Charts (ChartView + subclasses)

dev.crossfly.ui.chart 模块有一个共享的渲染核心（ChartView，继承自 Component）和 8 个具体子类，它们是推荐的入口点——每一个都预配置了类型并暴露符合人体工学的流式方法：

类	类型	如何添加数据
`LineChart`	折线	`.withSeries(nome, valores[, cor])`
`AreaChart`	带填充面积的折线（继承 `LineChart`）	`.withSeries(...)` · `.areaOpacity(int)`
`BarChart`	分组柱状	`.withSeries(...)`
`StackedBarChart`	堆叠柱状	`.series(nome, valores[, cor])`
`StackedAreaChart`	堆叠面积（渐变）	`.series(...)` · `.areaOpacity(int)`
`PieChart`	饼图	`.slice(nome, valor[, cor])`
`DonutChart`	环形图	`.slice(...)` · `.hole(float)`
`ComboChart`	柱状 + 折线（次 Y 轴）	`.addBarSeries(...)` · `.addLineSeries(...)`

🟡 · 包： dev.crossfly.ui.chart · 继承： Component · 样式： ComponentStyle

⚠️ 2026 年重命名： 旧类 LineChartView/BarChartView/PieChartView/ DonutChartView/ComboChartView 已被重命名为 LineChart/BarChart/PieChart/ DonutChart/ComboChart（移除了 View 后缀）。此外，饼图/环形图现在使用 slice(...)（不再是 withSlice）。

何时使用

按类别的趋势（折线/面积）、量级（柱状）、随时间的构成（堆叠）、整体中的占比（饼图/环形图），或量级 + 比率同时呈现（组合图）。

何时不要使用

X 任意的 XY 散点、3D 或仪表盘 → 不支持。自由绘图 → whiteboard。

完整示例（复制、粘贴并运行）

在 CrossFly 中你只需编写一个 Window 类（主屏幕）——Main 和 launcher 是 平台样板代码。将 launcher 指向此类（classname 参数）并运行 gradlew :lwjgl3:run：

package com.exemplo;

import dev.crossfly.ui.*;          // Window, Component, LAY_FILL…
import dev.crossfly.ui.layout.*;   // VerticalLayout
import dev.crossfly.ui.chart.*;    // ChartView, LineChart…

/**
 * 主可执行界面。将启动器指向此类 (classname)
 * 并运行：gradlew :lwjgl3:run
 */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      LineChart line = new LineChart();
      line.withSeries("Revenue", new double[]{42, 55, 51, 68, 73, 88}, 0xFF42A5F5)
          .withSeries("Target",  new double[]{40, 50, 56, 60, 70, 82}, 0xFFAB47BC);
      line.title("Receita por mês");
      line.categories(new String[]{"Jan", "Feb", "Mar", "Apr", "May", "Jun"});
      line.smooth(true);            // Catmull-Rom
      line.yAxis(0, 100, 5);         // 固定的 Y 范围（或 autoYAxis()）

      add(LAY_FILL, line);
   }
}

下面的代码片段只展示核心部分（放进 onShow() 内的内容），以聚焦于该功能。要运行它们，请把核心部分放入上面的 MainWindow 骨架中。

基本用法（按子类——推荐）

LineChart line = new LineChart();
line.withSeries("Revenue", new double[]{42, 55, 51, 68, 73, 88}, 0xFF42A5F5)
    .withSeries("Target",  new double[]{40, 50, 56, 60, 70, 82}, 0xFFAB47BC);
line.title("Receita por mês");
line.categories(new String[]{"Jan", "Feb", "Mar", "Apr", "May", "Jun"});
line.smooth(true);                       // Catmull-Rom
line.yAxis(0, 100, 5);                    // 固定的 Y 范围（或 autoYAxis()）
add(LAY_FILL, line);

柱状与堆叠柱状

BarChart bar = new BarChart();
bar.withSeries("North", new double[]{120, 140, 138, 165}, 0xFF5C6BC0)
   .withSeries("South", new double[]{95, 110, 123, 131}, 0xFF26C6DA);
bar.title("Vendas trimestrais").categories(new String[]{"Q1", "Q2", "Q3", "Q4"});

StackedBarChart stacked = new StackedBarChart();
stacked.series("Direct",  new double[]{6.2, 13.7, 19.9, 8}, 0xFF1976D2)
       .series("Mail Ad", new double[]{18.2, 11, 8, 17.8}, 0xFF81C784);
stacked.yAxis(0, 100, 5);

面积与堆叠面积

AreaChart area = new AreaChart();
area.withSeries("Load", new double[]{180, 260, 210, 300, 280}, 0xFF26C6DA);
area.areaOpacity(110);                    // 填充的 alpha 0–255

StackedAreaChart sarea = new StackedAreaChart();
sarea.series("Line 1", new double[]{140, 232, 101, 264}, 0xFF6DDB92)
     .series("Line 2", new double[]{120, 282, 111, 234}, 0xFF00D4FF);
sarea.areaOpacity(210);
sarea.decimals = 0;                        // 用于微调的公有字段

饼图与环形图

PieChart pie = new PieChart();
pie.slice("Organic", 38, 0xFF42A5F5)
   .slice("Paid",    24, 0xFFAB47BC)
   .slice("Social",  20, 0xFF26A69A);
pie.title("Fontes de tráfego");

DonutChart donut = new DonutChart();
donut.slice("Organic", 38).slice("Paid", 24).slice("Social", 20)
     .hole(0.58f);                          // 孔的半径 [0..0.95]

组合图（柱状 + 折线于次轴）

ComboChart combo = new ComboChart();
combo.addBarSeries("Sessions",     new double[]{1000, 1250, 1180, 1340}, 0xFF90CAF9)
     .addLineSeries("Conversion %", new double[]{2.8, 3.1, 2.9, 3.4}, 0xFF1E88E5);  // 右侧 Y 轴
combo.title("Conversão x Sessões").yAxis(0, 1600, 8);

数据模型

ChartView.Series（笛卡尔）：new Series(nome, double[] valores[, cor])；流式方法 .line() / .bar() 设置 renderMode（用于组合图）。
ChartView.PieSlice（径向）：new PieSlice(nome, double valor[, cor])。
颜色 0 = 自动（调色板 DEFAULT_COLORS，9 种颜色）。要固定颜色，请使用带 alpha 的 ARGB（0xFF…）。

配置（公有字段 + 流式方法）

成员	类型	默认值	作用
`title(String)` · `categories(String[])`	流式	—	标题 / X 轴标签
`yAxis(min, max, steps)` · `autoYAxis()`	流式	自动	Y 轴范围
`smooth(bool)` / `smoothLines`	流式/字段	`false`	Catmull-Rom 插值
`area(bool)` / `showArea`	流式/字段	`false`	填充折线下方的面积
`areaOpacity(int)` / `areaAlpha`	流式/字段	`0x55`	填充的 alpha（0–255）
`showLegend`/`showGrid`/`showTitle`/`showPoints`/`showValues`	字段	`true`	显示标志
`decimals`	字段	`2`	标签/工具提示中的小数位数
`axisColor`/`axisTextColor`/`legendTextColor`/`gridColor`	字段	主题	颜色（ARGB）
`pointRadius`/`lineThickness`/`barInnerGap`/`splineSteps`	字段	—	绘制的精细调整
`donutHoleRatio` / `hole(float)`	字段/流式	`0.56`	环形图的孔
`enableHoverSelection`/`enableInteractionAnimations`	字段	`true`	悬停选择 / 高亮动画

在流式方法之外修改公有字段后，请调用 repaint()。

回调与状态

onAction(Action) 在选择改变（点/柱/扇区）时触发——通过 runActions()。读取 selectedSeries+selectedIndex（笛卡尔）或 selectedSlice（径向）；-1 = 无。
交互通过 onTouchUp（选择最近的）和 onHover（高亮光标下的）实现。没有 onClick。

样式

与任何 Component 一样：chart.getStyle().backColor(...)/borderColor(...)；使用 .copy() 来派生而不改变共享的样式：

chart.style(chart.getStyle().copy().backColor(0xFFFFFFFF).borderColor(0xFFE0E0E0));

最佳实践

优先使用具体子类（LineChart、BarChart……）而非裸的 ChartView——流式方法更清晰。
笛卡尔使用 series/withSeries；径向使用 slices/slice——不要在同一类型中混用。
固定 yAxis(min,max,steps) 以获得稳定的坐标轴（自动模式会包含零，可能“压平”）。

常见错误

使用旧名称 LineChartView/PieChartView……（已重命名）或 withSlice（现在是 slice）。
传入颜色 0x00… 却期望得到黑色：0 是“自动”，而 alpha 00 是不可见的——请使用 0xFF000000。
期望 onClick：交互是通过由选择/悬停触发的 onAction 实现的。

另见

ui/ · cookbook/ · whiteboard