@finebi/finebi-cli 1.5.0 → 1.6.0

package/skills/finebi-cli-agent/references/widget-dsl-styles.md

@@ -0,0 +1,413 @@
+# Widget DSL API：图表样式与视觉通道
+
+> Widget DSL API 总导航见 [widget-dsl-api.md](widget-dsl-api.md)。
+
+## 4.6 图表级视觉通道
+
+| DSL API                     | 业务含义     |
+|-----------------------------|----------|
+| `.color(dimRef)`            | 按维度着色。   |
+| `.color(measureRef)`        | 按连续指标着色。 |
+| `.size(measureRef)`         | 按指标控制大小。 |
+| `.label(dimRef)`            | 追加标签维度。  |
+| `.label(measureRef)`        | 追加标签指标。  |
+| `.tooltipField(dimRef)`     | 追加提示维度。  |
+| `.tooltipField(measureRef)` | 追加提示指标。  |
+| `.granularity(dimRef)`      | 追加细粒度维度。 |
+| `.granularity(measureRef)`  | 追加细粒度指标。 |
+
+## 4.6.1 图形大小
+
+| API | 语义与范围 |
+|---|---|
+| `SizeOptions.line().width(px)` | 普通折线线宽，有限数 `0.5–35px` |
+| `SizeOptions.interval().widthRatio(ratio)` | 普通柱形柱宽比例，有限数 `0–1` |
+| `.roundRadius(px)` | 柱形圆角，整数 `0–50px` |
+| `.gap(value)` | 柱间距 `small/middle/large`；仅 seriesColumn/stackColumn 图表级且存在绘图指标 |
+| `SizeOptions.box().widthRatio(ratio)` | 箱线宽度比例，有限数 `0–1`；图表级及 BOX Series |
+| `SizeOptions.sankey().nodeWidth(value)` | 桑基节点宽度，有限数 `0–100`，与原生滑块同值；仅图表级 |
+| `SizeOptions.funnel().widthRatio(ratio)` | 漏斗宽度比例，有限数 `0–1`；仅图表级 |
+| `SizeOptions.gauge().radiusRatio(ratio)` | 仪表图尺寸比例，有限数 `0–1`；仅图表级 |
+| `SizeOptions.gauge().radius(px)` | 仪表图像素尺寸，有限数 `1.00001–150`；仅图表级 |
+| `SizeOptions.pie().radiusRatio(ratio)` | 饼图、玫瑰图外半径比例，有限数 `0–1`；仅图表级 |
+| `SizeOptions.multiPie().radiusRatio(ratio)` | 多层饼图外半径比例，有限数 `0–1`；仅图表级 |
+| `.innerRadiusRatio(ratio)` | `SizeOptions.pie/multiPie` 的内径比例，有限数 `0–1`；`0` 为实心 |
+
+使用 `.sizeOptions(...)` 挂到图表或绘图 Series，Series 未声明的属性继承图表配置，显式 `0` 可覆盖父级。
+空 `SizeOptions` 工厂表示未声明，不重置；字段映射继续使用 `.size(measure)`。
+线宽适用 `partitionLine/seriesLine`；柱宽与圆角适用 `sliceColumn/stackColumn/seriesColumn/compareColumn`。
+柱宽比例不适用于双轴均含指标的像素布局；支持分类轴转置。柱间距不允许 Series 覆盖。雷达、面积、自定义组合图及地图不接受本入口，也不能与 RadarOptions 混用。
+仪表图编辑器入口为“图形属性 → 样式 → 大小”。仪表图无轴字段或存在纯维度轴时使用 `radiusRatio`，否则使用像素 `radius`（例如仅 `.y(measure)`）；单位与布局不符时报错。通过 `.pointer(measure)` 绑定指针而不放轴时使用比例。漏斗仅支持宽度配置，不提供固定高度 API。文本图形字号不在此入口范围内。
+饼图与玫瑰图使用 `.sizeOptions(SizeOptions.pie().radiusRatio(0.8).innerRadiusRatio(0.5))`；
+多层饼图使用 `.sizeOptions(SizeOptions.multiPie().radiusRatio(0.8).innerRadiusRatio(0.2))`。
+两项可独立省略；玫瑰图半径比例控制数据映射的最大半径，不替代 `.size(measure)` 字段映射。
+饼图家族不支持像素半径、逐 Series 大小、共用半径开关或起止/旋转角；扇区角度仍由指标占比决定。
+已有点图 `pointRadius` 与地图 `mapRadius` 保持各自入口。示例见 [折线](widget-dsl-api-examples.md#101-分区折线图)
+与 [柱形](widget-dsl-api-examples.md#102-多系列柱形图)。
+
+## 4.7 数值格式
+
+| DSL API                                                 | 业务含义         |
+|---------------------------------------------------------|--------------|
+| `.numberFormat(measureRef, NumberFormatModel.xxx(...))` | 设置指标展示格式。    |
+| `.numberFormat(dimRef, NumberFormatModel.xxx(...))`     | 设置明细数值列展示格式。 |
+
+数据条只能作用于分组表和交叉表中已追加的 `measureRef`，不适用于明细表或其他图表。
+当前只支持平台默认形态（数值保留、自动最小/最大值、平台默认颜色）。
+
+迷你图仅适用于分组表，一个组件最多一个。类型工厂为 `MiniChart.line/pie/interval`；
+排序为 `MiniChartSort.ASC/DESC/TARGET_ASC/TARGET_DESC`；过滤只使用
+`MiniChartFilter.textBelong/textNotBelong/dateBelong/dateNotBelong`。目标指标必须已追加，
+依赖维度不要求追加；迷你图样式使用平台默认值。
+
+## 4.7.1 警戒线与趋势线
+
+仅 `partitionLine/seriesLine/sliceColumn/stackColumn/seriesColumn/compareColumn/custom` 支持分析线。
+目标参数必须是绘图轴 Series 中实际绘制的同一个 `MeasureRef` 语义身份；
+`custom` 选择 Series 数量较多的一轴绘图，相等选 y；非绘图轴的 `bar(measure)` 不可绑定分析线。
+`MeasureRef` 包含来源、字段、聚合、别名和快速计算，不是显示名称，也不能用只出现在
+color/size/label/tooltip 等通道中的指标代替。
+
+```js
+const sales = from("销售表").sum("销售额");
+WidgetDsl.create("销售趋势").chart().seriesLine()
+  .x(from("销售表").dim("月份"))
+  .y(line(sales))
+  .warningLine(sales, WarningLine.fixed("目标", 100).solid()
+    .color("#E65251").showValue(false))
+  .warningLine(sales, WarningLine.average("平均"))
+  .trendLine(sales, TrendLine.linear("趋势").dashed()
+    .color("#A6A6A6").forecastForward(2).forecastBackward(1))
+  .build();
+```
+
+警戒线工厂：`WarningLine.fixed(name, value)`、`average(name)`、`minimum(name)`、
+`maximum(name)`；修饰器：`solid/dashed/color/showValue`。默认虚线、`#E65251`、显示值。
+趋势线工厂：`TrendLine.linear(name)`、`exponential(name)`、`logarithmic(name)`、
+`polynomial(name)`；修饰器：`solid/dashed/color/forecastForward/forecastBackward`。默认实线、
+`#A6A6A6`、预测 0。预测值不得为负，固定值必须有限，颜色只接受 `#RRGGBB`。
+
+不要生成任意警戒线公式、其他拟合类型或多项式阶数；当前 DSL 不支持这些能力。同一目标下
+警戒线名称不能重复，趋势线名称不能重复。
+
+## 4.7.2 值轴与双 y 轴
+
+入口：`.valueAxis(measureRef, ValueAxis.builder()...build())`。适用于
+`partitionLine/seriesLine/sliceColumn/stackColumn/seriesColumn/compareColumn/custom`，目标必须唯一对应
+实际 x/y 轴上的指标 Series，且来源、聚合、别名、快速计算与 Series 中的引用完全一致。
+
+| Builder 方法 | 语义与限制 |
+|---|---|
+| `side(ValueAxisSide.LEFT/RIGHT)` | 不声明时 LEFT；RIGHT 仅用于 POLY 区域。纵轴为左右，横轴实际显示为下/上 |
+| `range(ValueAxisRange.AUTO)` | 自动范围、分区共用范围 |
+| `range(ValueAxisRange.PER_PARTITION)` | 按维度动态范围；仅允许纵轴存在维度分区 |
+| `range(ValueAxisRange.CUSTOM)` | 自定义范围，未设置的边界仍由平台计算 |
+| `min(expr)/max(expr)/interval(expr)` | 设边界即推断 CUSTOM，与其他 range 冲突报错；常量须有限，常量间隔大于 0，常量 min 小于 max |
+| `showLabel(boolean)/labelRotation(int)` | 标签显示及 -90 到 90 度旋转 |
+| `labelFont(font)/titleFont(font)` | `AxisFont.automatic()` 或 `AxisFont.custom(family, size, color, bold, italic)`；正整数字号，颜色为 `#RRGGBB` 或空串（自动颜色） |
+| `reversed(boolean)/logarithmic(boolean)` | 逆序、十进制对数轴；不指定逆序保留对比图默认值 |
+| `showTitle(boolean)/title(text)/autoTitle()` | 标题显示、自定义非空标题或随指标名变化的自动标题 |
+
+边界表达式：`AxisValue.fixed(number)`、`AxisValue.min(measureRef)`、`max(measureRef)`、
+`average(measureRef)`，通过 `.add(expr)/subtract(expr)/multiply(expr)/divide(expr)` 组合。
+表达式引用只能来自同一实际轴；不接受任意公式文本。统计值按平台绘制数据计算，
+输入边界使用原始数值；例如展示百万单位，最大值仍写 `AxisValue.fixed(2000000)`。
+
+双 y 轴需要**纵轴区域指标聚合 POLY**，`sum/avg` 是字段汇总，不代表区域已聚合。
+`seriesColumn/seriesLine/stackColumn/custom` 使用 POLY；分区柱/分区折线和对比条形图的 PARALLEL 不允许 RIGHT。
+未声明侧别的指标归 LEFT。每侧共用一套轴属性，同属性不同值报错，不按声明顺序覆盖；
+同侧数字格式以平台选中的指标格式显示（左侧首指标、右侧末指标），建议同侧使用一致单位。
+
+合同金额/回款金额双轴、两侧百万单位：
+
+```js
+var contract = from("合同表").sum("合同金额");
+var received = from("合同表").sum("回款金额");
+WidgetDsl.create("合同与回款").chart().seriesColumn()
+  .x(from("合同表").dim("省份"))
+  .y(bar(contract)).y(bar(received))
+  .valueAxis(contract, ValueAxis.builder().title("合同金额（百万元）").build())
+  .valueAxis(received, ValueAxis.builder().side(ValueAxisSide.RIGHT)
+    .title("回款金额（百万元）").build())
+  .numberFormat(contract, NumberFormatModel.number(2, NumberFormatModelScale.MILLION, "元", true))
+  .numberFormat(received, NumberFormatModel.number(2, NumberFormatModelScale.MILLION, "元", true))
+  .build();
+```
+
+金额与比例双轴（比例字段约定原始值 `0.25` 表示 25%）：
+
+```js
+var amount = from("销售表").sum("销售额");
+var rate = from("销售表").avg("毛利率");
+WidgetDsl.create("金额与毛利率").chart().seriesLine()
+  .x(from("销售表").dim("月份"))
+  .y(line(amount)).y(line(rate))
+  .valueAxis(amount, ValueAxis.builder().title("销售额")
+    .max(AxisValue.max(amount).multiply(AxisValue.fixed(1.2))).build())
+  .valueAxis(rate, ValueAxis.builder().side(ValueAxisSide.RIGHT).title("毛利率")
+    .min(AxisValue.fixed(0)).max(AxisValue.fixed(1)).build())
+  .numberFormat(amount, NumberFormatModel.number(2))
+  .numberFormat(rate, NumberFormatModel.percentage(1, true))
+  .build();
+```
+
+省略属性沿用默认，显式 false 生效。回读输出有效轴的规范配置，可补出显式默认值；
+自动标题和字体保持自动语义。更新时保留所需 valueAxis 声明，移轴后同步调整同轴公式引用。
+有效公式或样式超出以上范围时导出明确报错，不能据此省略设置后替换保存。
+
+## 4.7.3 分类轴
+
+笛卡尔图表（含 `custom`）支持 `categoryAxis(DimRef, CategoryAxis.builder()...build())`，目标必须唯一位于 x/y 轴。
+同一目标不可重复声明；同字段不同日期粒度可分别设置。本期不包含钻取。
+
+| 方法 | 说明 |
+|---|---|
+| `showLabel(boolean)` | 标签显隐，显式 false 保留 |
+| `labelDisplay(CategoryAxisDisplay.AUTO/ALL/INTERVAL)` | 默认、全部、间隔显示；ALL 的平台值为 ellipsis |
+| `labelAutoWrap(boolean)` | 全部显示时换行；其他策略可保留该配置 |
+| `labelRotation(int)` | -90..90；AUTO 策略由平台决定实际方向 |
+| `autoInterval()` / `interval(int)` | 推导 INTERVAL；自定义间隔为非负整数，0 合法；与显式 AUTO/ALL 冲突时报错 |
+| `labelFont(AxisFont.automatic/custom)` | 自动字体继承主题，自定义字体沿用值轴签名 |
+| `labelAlign(CategoryAxisAlign.AUTO/LEFT/CENTER/RIGHT)` | 非 AUTO 仅支持纵向分类轴，且要求自定义 labelFont |
+| `showTitle(boolean)` / `title(String)` / `autoTitle()` | 显隐与文本独立；允许自定义空文本；自动标题使用当前维度显示名 |
+| `titleFont(AxisFont.automatic/custom)` | 标题字体 |
+
+未调用 categoryAxis 或使用空配置时，保留现有创建默认值（标签自动显示、标题隐藏）。
+只修改标题不会生成标签配置。分类轴按 placement 私有保存，允许与 valueAxis、numberFormat 同时使用。
+Widget 创建及 Dashboard 内嵌图表使用同一 DSL；更新通过导出完整 DSL 后修改配置并重建，省略配置不代表远端局部合并。
+
+```js
+var region = from("合同订单原表").dim("地区");
+var amount = from("合同订单原表").sum("购买金额");
+WidgetDsl.create("地区销售").chart().seriesColumn()
+  .x(region).y(bar(amount))
+  .categoryAxis(region, CategoryAxis.builder()
+    .showLabel(true).labelDisplay(CategoryAxisDisplay.ALL)
+    .labelAutoWrap(true).labelRotation(-45)
+    .showTitle(true).title("销售地区").build())
+  .build();
+```
+
+`interval(n)` 向平台原值传递 n，不做加减转换；具体抽样结果应以目标实例渲染为准。
+标签隐藏时保留旋转、字体及换行；非 INTERVAL 策略下的休眠间隔在导出时归一化。
+反读不静默丢弃未知策略或无法表达的有效字体/标题状态。
+
+## 4.7.4 表格指标属性
+
+分组表与交叉表支持指标 `.tableColor(target, config)`、`.tableShape(target, config)`；分组表、交叉表和明细表支持维度目标的同名重载。
+分组表/交叉表的指标 `target` 是已绑定且唯一的 MeasureRef，或 `TableTarget.ALL_MEASURES`。明细表的数值目标和判断字段均使用原始数值 DimRef；文本/日期列使用下方的维度配置重载。
+
+```js
+WidgetDsl.create("前三名标记").chart().table()
+    .dimension(from("订单").dim("地区"))
+    .measure(from("订单").sum("金额"))
+    .tableShape(from("订单").sum("金额"),
+        TableShape.by(quickCalculation(from("订单").sum("金额"), QuickCalculationType.RANK_DES))
+            .when(NumberRange.atMost(3), TableSymbol.of(TableShapeType.CROWN, "#D4AF37"))
+            .affectTotals(false))
+    .build();
+```
+
+| 配置 | DSL |
+|---|---|
+| 无判断指标的固定颜色 | `TableColor.fixed(CellColor.text("#FF0000").background("#FFFFFF"))` |
+| 绑定判断指标 | `TableColor.by(measure)` / `TableShape.by(measure)`；没有条件时仍保留绑定 |
+| 无判断指标的固定形状 | `TableShape.fixed(TableSymbol.of(TableShapeType.CROWN, "#D4AF37"))` |
+| 数值条件 | `.when(NumberRange.equalTo(1), style)`；也支持 `atLeast/above/atMost/below/between(min, closeMin, max, closeMax)/all` |
+| 颜色基础样式 | `TableColor.by(measure).otherwise(CellColor.text("#333333"))` |
+| 形状基础配置保留 | `TableShape.by(measure).baseStyle(TableSymbol.of(TableShapeType.CROWN, "#D4AF37"))`；条件未命中仍不显示符号，这不是兜底规则 |
+| 合计参与条件 | `.affectTotals(true)`，默认 false；不控制合计行显隐 |
+| 颜色应用整行 | `TableColor...applyToLine(true)`，默认 false；形状没有该开关 |
+
+颜色支持 `#RRGGBB`、`transparent` 或空串。形状使用 `TableShapeType` 的单个符号枚举（如 `CROWN/FACE_SMILE/CIRCLE_SOLID/NONE`），不接受组合预设 `GROUP_*`。
+规则按声明顺序保存，最后命中的规则生效；固定模式不能追加数值条件。每个目标每个通道只能声明一次。全部指标配置先应用，再由单指标配置覆盖，与声明先后无关。
+判断字段建立独立隐藏绑定，且不进入轴或自动加入过滤。分组表/交叉表允许独立聚合、已有计算字段和快速计算；明细表只接受原始数值 DimRef。排名不改变行排序；如需排序使用现有 `.sort(...)`。
+不提供属性专属过滤 API；需要过滤时使用组件 `.filter()`，遵循组件结果过滤与共享字段分组语义，不能承诺只改变标记、不改变行数。
+平均值差、不一致标志和极值标志由既有计算字段或数据集提供，表格属性只消费数值结果。
+
+明细表的数值字段使用 `TableColor/TableShape`，支持固定样式和数值区间条件；目标无需出现在 `col` 中，未展示时只保留配置，不自动增加展示列。重复展示同一字段时，配置应用到所有匹配列。判断源也可以是未展示的原始数值字段。`TableTarget.ALL_MEASURES` 只作用于可见数值列，隐藏目标配置单独保留。明细表不支持聚合、快速计算或计算字段作为属性判断源。
+
+```js
+WidgetDsl.create("明细金额标记").chart().detailTable()
+    .col(from("订单").dim("金额"))
+    .tableColor(from("订单").dim("金额"),
+        TableColor.by(from("订单").dim("金额"))
+            .when(NumberRange.below(0), CellColor.text("#FF0000")))
+    .tableShape(from("订单").dim("金额"),
+        TableShape.fixed(TableSymbol.of(TableShapeType.CROWN, "#D4AF37")))
+    .build();
+```
+
+#### 维度颜色、形状与组件钻取
+
+已绑定且唯一的 DimRef 可用 `tableColor(dim, TableDimensionColor.of()...)` 和
+`tableShape(dim, TableDimensionShape.of()...)`。`.otherwise(style)` 设置固定或未命中样式；
+`.when(TableCondition.xxx(...), style)` 按显示文本判断，最后命中规则生效，不过滤结果行。
+维度形状的 `otherwise` 是未命中兜底；颜色支持 `.applyToLine(true)`，默认 false。
+
+`TableCondition.in(["华东", null])` / `notIn([...])` 接受非空字符串列表（允许 null）；
+`contains/notContains/startsWith/endsWith/notStartsWith/notEndsWith` 接受一个非空字符串。
+日期与分组表/交叉表的数值维度也按格式化后的显示文本匹配；明细表的原始数值列使用上方数值属性。
+
+```js
+WidgetDsl.create("地区城市标记").chart().table()
+    .dimension(from("订单").dim("地区"))
+    .measure(from("订单").sum("金额"))
+    .tableColor(from("订单").dim("地区"), TableDimensionColor.of()
+        .when(TableCondition.in(["华东"]), CellColor.text("#FF0000")))
+    .tableDrill(TableDrill.of(from("订单").dim("地区"))
+        .initial(from("订单").dim("城市")).order(TableDrillOrder.FREE))
+    .tableShape(from("订单").dim("地区"), from("订单").dim("城市"),
+        TableDimensionShape.of()
+            .when(TableCondition.contains("南京"), TableSymbol.of(TableShapeType.CROWN, "#D4AF37")))
+    .build();
+```
+
+钻取需要主题中已存在以目标维度为根、至少两层的共享钻取目录。
+`TableDrill.of(root)` 默认初始根层级、`TableDrillOrder.FIXED`；`FREE` 允许自由钻取。
+三参数 `tableColor(root, level, config)` / `tableShape(root, level, config)` 分别配置目录层级；
+不必声明 `tableDrill` 即可设置层级样式。层级须属于该目录，支持 DimRef 分组，非根层级不支持别名。
+每个目标每层每通道只能声明一次；组件钻取设置每个目标只能声明一次。
+配置仅设置初始层级与顺序，不表示交互产生的钻取历史。
+
+## 4.8 排序
+
+
+| DSL API                                                     | 业务含义                |
+|-------------------------------------------------------------|---------------------|
+| `.sort(dimRef, SortOrder.ASC / SortOrder.DESC)`             | 按维度值方向排序。           |
+| `.sort(measureRef, SortOrder.ASC / SortOrder.DESC)`         | 按指标值方向排序。           |
+| `.sort(dimRef, ["A", "B", "C"])`                            | 维度自定义顺序，适合业务枚举排序。   |
+| `.sort(dimRef, measureRef, SortOrder.ASC / SortOrder.DESC)` | 维度按照某个指标结果排序，适合排行榜。 |
+
+## 4.9 组件内边距（图表与表格通用）
+
+在 chart 链上调用 padding(Padding.of()...build())，适用于全部图表（含指标卡）与三种表格。
+
+| Padding Builder 方法 | 含义 |
+|---|---|
+| top(n) / right(n) / bottom(n) / left(n) | 分别设置上、右、下、左 |
+| vertical(n) | 同时设置上下 |
+| horizontal(n) | 同时设置左右 |
+
+n 为非负整数像素，0 表示无内边距。未指定的边沿用平台默认；空 Builder 恢复默认。
+重复 padding 调用以最后整组为准，Builder 内按调用顺序覆盖各边。锁按钮仅为编辑联动，DSL 用成对赋值表达。
+
+```js
+WidgetDsl.create("销售额").chart().kpi()
+  .text(from("销售原表").sum("金额"))
+  .padding(Padding.of().vertical(0).horizontal(12).build())
+  .build();
+```
+
+分别设置四边可用 .padding(Padding.of().top(4).right(12).bottom(8).left(16).build())。
+通过 widget add/update --file 保存，widget dsl 回读；dashboard 内联定义同样支持。
+能力来源：[图形组件样式第八节](https://help.fanruan.com/finebi/doc-view-231.html)。
+
+## 4.10 组件网格线、轴线与分区线
+
+图表支持四个独立入口（表格不支持）：
+
+| 入口 | 组件样式面板配置 |
+|---|---|
+| `.horizontalGrid(config)` | 横向网格线 |
+| `.verticalGrid(config)` | 纵向网格线 |
+| `.axisLine(config)` | 轴线 |
+| `.sectionLine(config)` | 分区线 |
+
+`config` 使用 `ChartLine.builder()`，可选方法为 `enabled(boolean)`、
+`type(ChartLineType.SOLID/DASHED/DOTTED)`、`color(string)` 和 `width(int)`。
+宽度为非负整数；颜色支持空串（自动）、`transparent`、`#RGB`、`#RRGGBB`。
+未设置时启用、宽度 1、自动颜色；网格默认虚线，轴线和分区线默认实线。
+实际可见效果取决于图表类型与分区布局。关闭总网格线时，将横纵两个开关均设为 false。
+`DOTTED` 可保存和回读，但点线渲染依赖平台版本；仅实现 solid/dashed 的渲染器会显示为实线。
+
+在已有图表的 `.build()` 前追加：
+
+```js
+  .horizontalGrid(ChartLine.builder().enabled(true)
+    .type(ChartLineType.DOTTED).color("#D9D9D9").width(1).build())
+  .verticalGrid(ChartLine.builder().enabled(false).build())
+  .axisLine(ChartLine.builder().color("#666666").width(2).build())
+  .sectionLine(ChartLine.builder().enabled(false).build())
+```
+
+这些是组件样式，不是 `lineOptions` 的数据折线，也不是分析线。
+导出保留非默认配置及关闭状态下的样式；整份 DSL 更新时省略配置会恢复默认值。
+
+## 4.11 组件背景（图表与表格通用）
+
+所有图表与表格支持 `.titleBackground(WidgetBackground)` 和 `.widgetBackground(WidgetBackground)`。
+使用 `WidgetBackground.of()...build()`：
+
+| 方法 | 含义 |
+|---|---|
+| color("") / color("transparent") / color("#RGB" 或 "#RRGGBB") | 自动跟随主题 / 透明 / 自定义颜色 |
+| image(附件ID) | 自定义图片；先用 `dashboard upload-image` 上传，引用返回的 ID |
+| style(WidgetBackground.STYLE1…STYLE6) | 内置样式；标题 1–6，组件 1/2/3/5/6 |
+| borderRadius(0…6) | 组件颜色背景圆角，整数 |
+| borderSize(0…5) / borderColor(颜色) | 组件颜色背景的边框宽度和颜色 |
+
+标题 STYLE1–6：标题下横线、标题双横线、标题上横线、科幻标题装饰、商务标题装饰、清新标题装饰。
+组件 STYLE1/2/3/5/6：科幻大屏样式、数据大屏样式、科技感动态样式、指标卡样式、红色组件样式。
+颜色/图片/样式互斥，最后一次模式选择生效。标题、图片和内置样式不支持边框配置。
+省略整个背景或传 `WidgetBackground.of().build()` 恢复自动；显式圆角/宽度 0 会覆盖继承。
+自动继承要求颜色、边框色为空且圆角/宽度均未声明。图片只接受附件 ID；颜色回读为小写。
+
+```js
+WidgetDsl.create("柱状图背景").chart().sliceColumn()
+  .x(from("销售原表").dim("地区"))
+  .y(bar(from("销售原表").sum("金额")))
+  .titleBackground(WidgetBackground.of().color("").build())
+  .widgetBackground(WidgetBackground.of().style(WidgetBackground.STYLE2).build())
+  .build();
+```
+
+自定义组件颜色背景可替换为
+`.widgetBackground(WidgetBackground.of().color("#102040").borderRadius(4).borderSize(1).borderColor("#4488cc").build())`。
+通过现有 `widget add/update --file` 保存，`widget dsl` 回读；仪表板全局背景使用 `TemplateStyle`。
+能力范围参考：[表格背景](https://help.fanruan.com/finebi/doc-view-988.html)。
+
+## 5. SeriesModel
+
+`line(measureRef)` 和 `bar(measureRef)` 返回 `SeriesModel`，可以继续定义系列级视觉通道。
+
+```js
+line(from("销售表").sum("销售额"))
+bar(from("销售表").sum("销售额"))
+```
+
+| DSL API                              | 业务含义            |
+|--------------------------------------|-----------------|
+| `line(measureRef)`                   | 构造折线系列。         |
+| `bar(measureRef)`                    | 构造柱形系列。         |
+| `.color(dimRef / measureRef)`        | 系列级着色。          |
+| `.size(measureRef)`                  | 系列级大小控制。        |
+| `.label(dimRef / measureRef)`        | 系列标签内容。         |
+| `.tooltipField(dimRef / measureRef)` | 系列悬浮信息补充字段。     |
+| `.granularity(dimRef / measureRef)`  | 系列细粒度字段。        |
+| `.lineConnect(dimRef / measureRef)`  | 折线系列的连线维度或连线指标。 |
+| `.sizeOptions(SizeOptions...)` | 绘图 Series 大小外观，仅支持普通折线、柱形和 BOX；适用范围与继承规则见 [§4.6.1](#461-图形大小)。 |
+| `.lineOptions(LineOptions...)`     | 普通折线的连线样式；也可在图表级设置。 |
+
+流向地图使用图表级 `.chart().lineMap().lineConnect(measureRef)`，连线属性仅接受指标。
+`LINE_MAP` 的 basic 模板使用 `.lineConnect(from(tableName).sum(routeField))`，对连线字段求和。
+
+### 5.1 普通折线连线样式
+
+仅 `partitionLine/seriesLine` 支持图表级和绘图指标级 `lineOptions`：
+
+| API | 取值 / 语义 |
+|---|---|
+| `LineOptions.normal()/curve()/step()` | 折线 / 曲线 / 阶梯线 |
+| `LineOptions.defaults()` | 不指定属性，用于只覆盖单项；不重置已有配置 |
+| `.borderStyle(value)` | `solid` / `dashed` |
+| `.marker(value)` | `true` / `false`，显示/隐藏标记点 |
+| `.symbol(value)` | `circle/rect/triangle/circle_hollow/square_hollow/triangle_hollow` |
+| `.nullPattern(value)` | `continuous/disconnect/zero`，空值连续/断开/置零 |
+
+单指标只覆盖已声明属性，其他属性继承图表配置；显式 `false` 可以覆盖 `true`。
+未配置时保持默认折线、实线、无标记点、空值连续。雷达使用 `RadarOptions`，不能与 `LineOptions` 混用。
+面积、自定义组合图、流向地图和无对应绘图几何的非绘图轴指标不接受此配置。
+示例见 [普通折线连线样式](widget-dsl-api-examples.md#普通折线连线样式)。
+

package/skills/finebi-cli-agent/scripts/finebi-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": true,
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",

package/skills/finebi-cli-agent/scripts/finebi-cli/src/app.js

@@ -0,0 +1,189 @@
+import {cp, mkdir, readdir, readFile, stat, writeFile} from "node:fs/promises";
+import {dirname, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+
+import {cliError} from "./errors.js";
+import {failure, success} from "./output.js";
+
+const TEMPLATE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates", "web-app");
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu;
+
+export async function handleApp(args, context = {}) {
+  const action = args[0];
+  if (action === "create") return createApp(args.slice(1), context);
+  if (action === "inspect") return inspectApp(args.slice(1));
+  return invalid("app", "App command is required.", ["finebi-cli app create --name <name> --path <parent>", "finebi-cli app inspect --path <project>"]);
+}
+
+export async function createApp(args, context = {}) {
+  const options = parseOptions(args, "app.create");
+  if (!options.ok) return options.error;
+  const {name, path: parentPath} = options.value;
+  if (!name || name.length > 214 || !NAME_PATTERN.test(name) || WINDOWS_DEVICE_NAME.test(name)) {
+    return invalid("app.create", "name must be a simple lowercase npm name (letters, digits, and single hyphens).", ["finebi-cli app create --name sales-dashboard --path <parent>"]);
+  }
+  if (!parentPath) {
+    return invalid("app.create", "path must be an existing parent directory.");
+  }
+  const parent = resolve(parentPath);
+  const destination = resolve(parent, name);
+  if (dirname(destination) !== parent) {
+    return invalid("app.create", "name must stay inside the selected parent directory.");
+  }
+  try {
+    if (!(await stat(parent)).isDirectory()) return invalid("app.create", "path must point to a directory.");
+  } catch (error) {
+    return invalid("app.create", error.code === "ENOENT" ? `Parent directory does not exist: ${parent}` : `Cannot inspect parent directory: ${error.message}`);
+  }
+  try {
+    const templateRoot = context.templateRoot ? resolve(context.templateRoot) : TEMPLATE_ROOT;
+    const templatePackage = JSON.parse(await readFile(resolve(templateRoot, "package.json"), "utf8"));
+    const templateConfigPath = resolve(templateRoot, "public", "app-config.json");
+    let config = {schemaVersion: "1", title: name, basePath: "/webroot/decision", layout: "overview", dashboardId: "", maxRows: 1000, pageSize: 8, widgets: [], filters: []};
+    try {
+      config = JSON.parse(await readFile(templateConfigPath, "utf8"));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    try {
+      await mkdir(destination, {recursive: false});
+    } catch (error) {
+      return invalid("app.create", error.code === "EEXIST" ? `Destination already exists: ${destination}` : `Cannot create destination: ${error.message}`);
+    }
+    await copyTemplateContents(templateRoot, destination);
+    await mkdir(resolve(destination, "public"), {recursive: true});
+    await writeFile(resolve(destination, "package.json"), `${JSON.stringify({...templatePackage, name}, null, 2)}\n`, "utf8");
+    await writeFile(resolve(destination, "public", "app-config.json"), `${JSON.stringify({...config, templateVersion: templatePackage.version}, null, 2)}\n`, "utf8");
+    const lockPath = resolve(destination, "package-lock.json");
+    try {
+      const lock = JSON.parse(await readFile(lockPath, "utf8"));
+      lock.name = name;
+      if (lock.packages?.[""]) lock.packages[""].name = name;
+      await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    return success("app.create", {name, path: destination, templateVersion: templatePackage.version});
+  } catch (error) {
+    return invalid("app.create", `Could not create project: ${error.message}`);
+  }
+}
+
+async function copyTemplateContents(sourceRoot, destinationRoot, relativeDirectory = "") {
+  const sourceDirectory = resolve(sourceRoot, relativeDirectory);
+  const destinationDirectory = resolve(destinationRoot, relativeDirectory);
+  for (const entry of (await readdir(sourceDirectory, {withFileTypes: true})).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+    const relativePath = `${relativeDirectory}/${entry.name}`.replace(/^\//u, "");
+    if (!templatePathAllowed(relativePath)) continue;
+    const sourcePath = resolve(sourceDirectory, entry.name);
+    const destinationPath = resolve(destinationDirectory, entry.name);
+    if (entry.isDirectory()) {
+      await mkdir(destinationPath, {recursive: false});
+      await copyTemplateContents(sourceRoot, destinationRoot, relativePath);
+    } else if (entry.isFile()) {
+      await cp(sourcePath, destinationPath, {force: false, errorOnExist: true});
+    } else {
+      throw new Error(`Unsupported template entry: ${relativePath}`);
+    }
+  }
+}
+
+function templatePathAllowed(relative) {
+  const relativePath = relative.replaceAll("\\", "/");
+  const parts = relativePath.split("/").filter(Boolean);
+  const basename = parts.at(-1) || "";
+  return !parts.some(part => ["node_modules", "dist", "temp", ".git"].includes(part))
+    && basename !== ".env"
+    && (!basename.startsWith(".env.") || basename === ".env.example");
+}
+
+async function inspectApp(args) {
+  const options = parseOptions(args, "app.inspect");
+  if (!options.ok) return options.error;
+  const projectPath = options.value.path;
+  if (!projectPath) return invalid("app.inspect", "path must be a project directory.");
+  const project = resolve(projectPath);
+  try {
+    if (!(await stat(project)).isDirectory()) return invalid("app.inspect", "path must point to a project directory.");
+    const configPath = resolve(project, "public", "app-config.json");
+    const config = JSON.parse(await readFile(configPath, "utf8"));
+    const errors = await validateConfig(config);
+    if (errors.length) return failure("app.inspect", cliError("INVALID_ARGUMENT", {path: "public/app-config.json", message: errors.join(" ")}));
+    return success("app.inspect", {
+      path: project,
+      dashboardId: config.dashboardId,
+      widgets: config.widgets.length,
+      templateVersion: config.templateVersion || null,
+      remoteValidated: false,
+    });
+  } catch (error) {
+    return invalid("app.inspect", `Cannot read project configuration: ${error.message}`);
+  }
+}
+
+async function validateConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== "object" || Array.isArray(config)) return ["configuration must be a JSON object."];
+  const allowedConfigFields = new Set(["schemaVersion", "title", "basePath", "layout", "dashboardId", "maxRows", "pageSize", "widgets", "filters", "templateVersion"]);
+  for (const field of Object.keys(config)) if (!allowedConfigFields.has(field)) errors.push(`unsupported config field: ${field}.`);
+  if (config.schemaVersion !== "1") errors.push("schemaVersion must be \"1\".");
+  if (!nonEmptyString(config.title)) errors.push("title is required.");
+  if (!nonEmptyString(config.basePath) || !/^\/(?!\/)[\w/-]+$/.test(config.basePath)) errors.push("basePath must be a same-origin path.");
+  if (!["overview", "workbench"].includes(config.layout)) errors.push("layout must be overview or workbench.");
+  if (!Number.isInteger(config.maxRows) || config.maxRows < 1 || config.maxRows > 10000) errors.push("maxRows must be an integer from 1 to 10000.");
+  if (!Number.isInteger(config.pageSize) || config.pageSize < 1 || config.pageSize > 100) errors.push("pageSize must be an integer from 1 to 100.");
+  if (typeof config.dashboardId !== "string" || !config.dashboardId.trim()) {
+    if (Array.isArray(config.widgets) && config.widgets.length === 0) return ["project is not bound: dashboardId and widgets must be configured."];
+    errors.push("dashboardId is required.");
+  }
+  if (!Array.isArray(config.widgets) || config.widgets.length === 0) {
+    errors.push("widgets must be a non-empty array.");
+    return errors;
+  }
+  for (const [index, widget] of config.widgets.entries()) {
+    if (!widget || typeof widget !== "object") {
+      errors.push(`widgets[${index}] must be an object.`);
+      continue;
+    }
+    const allowedWidgetFields = new Set(["entryId", "name", "type", "datasetId", "categoryFieldId", "valueFieldId"]);
+    for (const field of Object.keys(widget)) if (!allowedWidgetFields.has(field)) errors.push(`widgets[${index}].${field} is unsupported.`);
+    for (const field of ["entryId", "name", "type"]) {
+      if (typeof widget[field] !== "string" || !widget[field].trim()) errors.push(`widgets[${index}].${field} is required.`);
+    }
+    if (!["table", "bar", "line", "pie", "kpi"].includes(widget.type)) errors.push(`widgets[${index}].type is unsupported.`);
+    if (widget.type && widget.type !== "table" && !nonEmptyString(widget.valueFieldId)) errors.push(`widgets[${index}].valueFieldId is required for ${widget.type}.`);
+    if (widget.type && !["table", "kpi"].includes(widget.type) && !nonEmptyString(widget.categoryFieldId)) errors.push(`widgets[${index}].categoryFieldId is required for ${widget.type}.`);
+    for (const field of ["datasetId", "categoryFieldId", "valueFieldId"]) {
+      if (widget[field] !== undefined && !nonEmptyString(widget[field])) errors.push(`widgets[${index}].${field} must be a non-empty string.`);
+    }
+  }
+  try {
+    const {validateFilterBindings} = await import("../templates/web-app/src/finebi/filters.js");
+    validateFilterBindings(config.filters);
+  } catch (error) {errors.push(error.message);}
+  return errors;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function parseOptions(args, command) {
+  const value = {};
+  for (let index = 0; index < args.length; index++) {
+    const option = args[index];
+    if (option === "--json") continue;
+    if (option !== "--name" && option !== "--path") return {ok: false, error: invalid(command, `Unsupported option: ${option}`)};
+    const key = option.slice(2);
+    const next = args[++index];
+    if (!next || next.startsWith("--")) return {ok: false, error: invalid(command, `${option} requires a value.`)};
+    if (value[key]) return {ok: false, error: invalid(command, `${option} must only be supplied once.`)};
+    value[key] = next;
+  }
+  return {ok: true, value};
+}
+
+function invalid(command, message, nextActions = []) {
+  return failure(command, cliError("INVALID_ARGUMENT", {path: command, message, nextActions}));
+}