@finebi/finebi-cli 1.2.0 → 1.3.0

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

@@ -0,0 +1,457 @@
+# Widget DSL 推荐写法示例（`widget-dsl-api.md` §10）
+
+> 本文件是 [`widget-dsl-api.md`](widget-dsl-api.md) §10 的独立分册：可运行的推荐写法示例。
+> §1-§9（根入口 / 字段工厂 / Builder / 图表上下文 / SeriesModel / 过滤 / 配色 / 数值格式 / 枚举）留在主册。
+
+### 10.1 分区折线图
+
+```js
+WidgetDsl.create("月度趋势")
+    .chart().partitionLine()
+    .x(from("销售表").dim("月份"))
+    .y(line(from("销售表").sum("销售额"))
+        .tooltipField(from("销售表").sum("利润")))
+    .sort(from("销售表").dim("月份"), SortOrder.ASC)
+    .build()
+```
+
+适用场景：按月份看销售额走势，并在 tooltip 中补充利润。
+
+### 10.2 多系列柱形图
+
+```js
+WidgetDsl.create("访问指标对比")
+    .chart().seriesColumn()
+    .x(from("访问统计事实表").dim("统计日期"))
+    .y(bar(from("访问统计事实表").sum("浏览量")))
+    .y(bar(from("访问统计事实表").sum("访问次数")))
+    .build()
+```
+
+适用场景：按日期并列比较两个不同指标，转换器自动按指标名称着色。参考[多系列柱形图](https://help.fanruan.com/finebi/doc-view-199.html)。
+
+`sliceColumn basic` 使用分类维度和年月分组日期作为横轴，将两个不同的求和指标分区展示。参考[分区柱形图](https://help.fanruan.com/finebi/doc-view-197.html)。
+
+### 10.3 饼图
+
+```js
+WidgetDsl.create("区域占比")
+    .chart().pie()
+    .x(from("销售表").dim("地区"))
+    .y(from("销售表").sum("销售额"))
+    .label(from("销售表").sum("销售额"))
+    .build()
+```
+
+适用场景：看各地区销售额占比。
+
+### 10.4 玫瑰图
+
+```js
+WidgetDsl.create("品类贡献")
+    .chart().rose()
+    .x(from("销售表").dim("品类"))
+    .y(from("销售表").sum("销售额"))
+    .build()
+```
+
+适用场景：既看占比，也看不同品类的量值差异。
+
+### 10.5 多层饼图
+
+```js
+WidgetDsl.create("大区品牌销售结构")
+    .chart().multiPie()
+    .color(from("销售表").dim("大区"))
+    .size(from("销售表").sum("销售额"))
+    .granularity(from("销售表").dim("大区"))
+    .granularity(from("销售表").dim("品牌描述"))
+    .build()
+```
+
+适用场景：内圈按大区着色，外圈展示各大区下的品牌销售额。细粒度按父→子顺序包含两个维度，大小使用销售额求和。参考[多层饼图](https://help.fanruan.com/finebi/doc-view-274.html)。
+
+### 10.6 KPI 指标卡
+
+```js
+WidgetDsl.create("销售指标卡")
+    .chart().kpi()
+    .text(from("销售表").sum("销售额"))
+    .tooltipField(from("销售表").avg("客单价"))
+    .build()
+```
+
+适用场景：突出展示一个核心指标，并补充辅助信息。
+
+### 10.7 仪表盘
+
+```js
+WidgetDsl.create("达成率")
+    .chart().ringGauge()
+    .x(from("销售表").dim("目标类型"))
+    .y(from("销售表").avg("达成率"))
+    .target(100)
+    .gaugeStyle("standard")
+    .gaugeScale("bold")
+    .roundRadius(true)
+    .gaugeColor("point", "#1677ff")
+    .numberFormat(from("销售表").avg("达成率"), NumberFormatModel.percentage(1, true))
+    .build()
+```
+
+适用场景：查看目标完成率或评分进度。
+
+### 10.8 分组表
+
+```js
+WidgetDsl.create("区域销售表")
+    .chart().table()
+    .dimension(from("销售表").dim("地区"))
+    .dimension(from("销售表").dim("产品"))
+    .measure(from("销售表").sum("销售额"))
+    .dataBar(from("销售表").sum("销售额"))
+    .miniChart(from("销售表").sum("销售额"),
+        MiniChart.line(from("销售表").dim("月份"))
+            .sort(MiniChartSort.TARGET_DESC)
+            .filter(MiniChartFilter.textBelong(["1月", "2月", null])))
+    .measure(quickCalculation(from("销售表").sum("销售额"), QuickCalculationType.RANK_ASC))
+    .build()
+```
+
+适用场景：看分组结果，并附带组内排名。
+
+### 10.9 交叉表
+
+```js
+WidgetDsl.create("月度交叉分析")
+    .chart().crossTable()
+    .row(from("销售表").dim("地区"))
+    .col(from("销售表").dim("月份"))
+    .measure(from("销售表").sum("销售额"))
+    .measure(from("销售表").sum("利润"))
+    .dataBar(from("销售表").sum("销售额"))
+    .metricNameInCol()
+    .build()
+```
+
+适用场景：按地区和月份交叉查看多指标结果。
+
+### 10.10 明细表
+
+```js
+WidgetDsl.create("订单明细")
+    .chart().detailTable()
+    .col(from("订单表").dim("订单号"))
+    .col(from("订单表").dim("产品"))
+    .col(from("订单表").dim("销售额"))
+    .numberFormat(from("订单表").dim("销售额"), NumberFormatModel.number(2, NumberFormatModelScale.TEN_THOUSAND, "元", false))
+    .build()
+```
+
+适用场景：查看原始订单行数据。
+
+### 10.11 原值过滤
+
+```js
+WidgetDsl.create("高客单订单")
+    .chart().table()
+    .dimension(from("订单表").dim("地区"))
+    .measure(from("订单表").sum("销售额"))
+    .filter().field(from("订单表").measure("销售额")).between(1000, 5000)
+    .build()
+```
+
+适用场景：先用原始字段值做过滤，再看聚合结果。
+
+### 10.12 组件配色
+
+```js
+WidgetDsl.create("区域占比配色")
+    .chart().pie()
+    .x(from("销售表").dim("地区"))
+    .y(from("销售表").sum("销售额"))
+    .color()
+    .palette(["#E65251", "#3478F6", "#36A675"])
+    .build()
+```
+
+适用场景：统一套用固定色板。
+
+按分类固定颜色时，先绑定颜色字段：
+
+```js
+WidgetDsl.create("地区销售配色")
+    .chart().sliceColumn()
+    .x(from("销售表").dim("地区"))
+    .y(bar(from("销售表").sum("销售额")))
+    .color(from("销售表").dim("地区"))
+    .color().palette(["#E65251", "#3478F6"])
+    .mapping({"华东": "#36A675", "华南": "#3478F6"})
+    .build()
+```
+
+华东固定绿色、华南固定蓝色，其他分类使用声明的色板；分类排序改变不影响已映射的颜色。
+
+### 10.13 折线连线字段
+
+```js
+WidgetDsl.create("月度趋势对比")
+    .chart().seriesLine()
+    .x(from("销售表").dim("月份"))
+    .y(line(from("销售表").sum("销售额"))
+        .color(from("销售表").dim("渠道"))
+        .lineConnect(from("销售表").dim("周")))
+    .build()
+```
+
+适用场景：多系列折线既按渠道拆线，又要求折线按周连续连接。
+
+**约束（2026-08-26 真机实证）**：`lineConnect` 字段必须与类目轴（`.x(...)` / `.y(...)` 的维度）**不同**——同字段时平台渲染报 `Duplicate key DimensionHyperOrder`，编译期直接 fail-loud。
+
+#### 普通折线连线样式
+
+```js
+WidgetDsl.create("月度趋势样式")
+    .chart().seriesLine()
+    .x(from("销售表").dim("月份"))
+    .lineOptions(LineOptions.curve()
+        .borderStyle("dashed")
+        .marker(true)
+        .symbol("circle")
+        .nullPattern("disconnect"))
+    .y(line(from("销售表").sum("销售额")))
+    .y(line(from("销售表").sum("利润"))
+        .lineOptions(LineOptions.defaults().marker(false)))
+    .build()
+```
+
+两条曲线使用虚线、空值断开；销售额显示圆形标记，利润只覆盖标记开关。
+字段连线顺序仍由 `.lineConnect(field)` 声明，样式不会替换字段绑定。
+
+### 10.14 记录数指标
+
+```js
+WidgetDsl.create("区域订单量")
+    .chart().table()
+    .dimension(from("订单表").dim("地区"))
+    .measure(from("订单表").count("订单数"))
+    .build()
+```
+
+`count()` / `count(alias)` 表示来源表总行数。需要显式指定记录数依赖维度时使用：
+
+```js
+WidgetDsl.create("地区订单量")
+    .chart().table()
+    .dimension(from("订单表").dim("地区"))
+    .dimension(from("订单表").dim("产品"))
+    .measure(count(from("订单表").dim("地区"), "地区订单数"))
+    .build()
+```
+
+适用场景：组件存在多个维度，但记录数需要明确依赖其中一个维度。
+
+### 10.15 字段去重计数
+
+```js
+WidgetDsl.create("各区域客户数")
+    .chart().table()
+    .dimension(from("订单表").dim("地区"))
+    .measure(from("订单表").countDistinct("客户名称", "客户数"))
+    .build()
+```
+
+适用场景：按地区统计去重客户数。`countDistinct` 只支持文本/日期字段（含其计算字段变体，
+计算字段写 `measureID("配置 ID").countDistinct()`），且该字段须先转成指标形态——
+`widget add/update/data` 缺该形态时报 `UNSUPPORTED_FEATURE`，按 `nextActions` 执行
+`measure transform --subject-id <主题 ID> --field-id <字段 ID> --as measure` 后重跑即可；
+计算字段变体的公式引用聚合形态字段时同样被拒绝（平台取数校验会再包一层去重计数，报聚合嵌套聚合）。
+数值字段、模型字段不支持；明细表不接受指标引用。
+
+### 10.16 自定义维度顺序
+
+```js
+WidgetDsl.create("区域销售排序")
+    .chart().table()
+    .dimension(from("销售表").dim("地区"))
+    .measure(from("销售表").sum("销售额"))
+    .sort(from("销售表").dim("地区"), ["华北", "华东", "华南", "西部"])
+    .build()
+```
+
+适用场景：地区、阶段、等级这类业务枚举不适合按字典序展示。
+
+### 10.17 按指标结果排序
+
+```js
+WidgetDsl.create("地区销售排行榜")
+    .chart().table()
+    .dimension(from("销售表").dim("地区"))
+    .measure(from("销售表").sum("销售额"))
+    .sort(from("销售表").dim("地区"), from("销售表").sum("销售额"), SortOrder.DESC)
+    .build()
+```
+
+适用场景：排行榜、Top 区域、Top 产品这类“维度按指标值排序”的场景。
+
+### 10.18 交叉表指标名称在行轴
+
+```js
+WidgetDsl.create("区域指标对比")
+    .chart().crossTable()
+    .row(from("销售表").dim("地区"))
+    .metricNameInRow()
+    .col(from("销售表").dim("月份"))
+    .measure(from("销售表").sum("销售额"))
+    .measure(from("销售表").sum("利润"))
+    .build()
+```
+
+适用场景：希望把“销售额、利润”等指标名称竖向展开，便于逐行比对。
+
+### 10.19 直接追加维度和指标
+
+```js
+WidgetDsl.create("快速分组表")
+    .chart().table()
+    .addDimension(from("销售表").dim("地区"))
+    .addMeasure(from("销售表").sum("销售额"))
+    .build()
+```
+
+适用场景：快速生成简单分组表，不需要区分更多表格槽位。
+
+### 10.20 多值过滤与非空过滤
+
+```js
+WidgetDsl.create("有效订单")
+    .chart().detailTable()
+    .col(from("订单表").dim("订单号"))
+    .col(from("订单表").dim("地区"))
+    .filter().field(from("订单表").dim("地区")).in(["华东", "华南"])
+    .filter().field(from("订单表").dim("客户ID")).notNull()
+    .build()
+```
+
+适用场景：先筛一组业务值，再排除关键字段为空的脏数据。
+
+### 10.21 自定义聚合指标
+
+```js
+WidgetDsl.create("中位销售额")
+    .chart().kpi()
+    .text(from("销售表").measure("销售额", "MEDIAN", "销售额中位数"))
+    .build()
+```
+
+适用场景：平台支持某种聚合方式，但当前 DSL 没有专门的 sugar 方法。
+
+### 10.22 快速计算二次开关
+
+```js
+WidgetDsl.create("累计销售额")
+    .chart().table()
+    .dimension(from("销售表").dim("月份"))
+    .measure(
+        quickCalculation(
+            from("销售表").sum("销售额"),
+            QuickCalculationType.SUM_OF_ABOVE,
+            false
+        )
+    )
+    .build()
+```
+
+适用场景：需要显式指定快速计算的 secondaryCalculation 开关。
+
+### 10.23 业务值固定配色
+
+```js
+WidgetDsl.create("区域颜色固定")
+    .chart().pie()
+    .x(from("销售表").dim("地区"))
+    .y(from("销售表").sum("销售额"))
+    .color()
+    .mapping({
+        "华东": "#0B6E4F",
+        "华南": "#D98E04",
+        "华北": "#8C1C13"
+    })
+    .build()
+```
+
+适用场景：要求同一业务值在所有图表中保持固定品牌色或区域色。
+
+### 10.24 KPI 指标卡
+
+```js
+WidgetDsl.create("销售总额")
+    .chart().kpi()
+    .text(from("销售表").sum("销售额"))
+    .build()
+```
+
+### 10.25 模型指标集
+
+```js
+WidgetDsl.create("模型销售概览")
+    .chart().gauge()
+    .x(model("销售指标集").dataset("订单明细").dim("地区"))
+    .y(model("销售指标集").metrics().sum("销售额"))
+    .build()
+```
+
+模型表字段和模型计算字段按字段类型使用各自子命名空间的 `dim/sum/...` 形态；模型指标支持
+`sum/avg/max/min/measure`、alias 和快速计算。纯模型组件不需要物理表来源。缺少精确模型名或字段名证据时返回 `BLOCKED`，不要把模型名
+当作 `sourceTableName`。
+
+### 词云
+
+使用 `finebi-cli widget template --chart-type wordCloud --scenario basic` 获取模板。一个维度与一个指标是模板示范，DSL 允许空配置与多字段。文本栏使用 `text(field)`，标签栏使用 `label(field)`。
+
+```javascript
+WidgetDsl.create("搜索词云")
+    .chart().wordCloud()
+    .text(from("搜索词汇统计表").dim("搜索词"))
+    .size(from("搜索词汇统计表").sum("搜索次数"))
+    .color(from("搜索词汇统计表").sum("搜索次数"))
+    .textSize(36)
+    .build();
+```
+### 自定义同环比
+
+使用 `customPeriod(measure, CustomPeriodModel)` 创建期间指标；支持 `value`、`compare`、`period`、`relative`。
+
+### 桑基图
+
+`sankeyStart`、`sankeyEnd`、`size` 和 `color` 重复调用会追加字段；均可省略，不强制数量。
+起终点接受 DimRef，size 接受 MeasureRef。节点名称默认关闭，`showNodeName(true)` 开启。
+
+```javascript
+WidgetDsl.create("门店流量")
+    .chart().sankey()
+    .sankeyStart(from("订单").dim("产品名称"))
+    .sankeyEnd(from("订单").dim("门店名称"))
+    .size(from("订单").sum("订单金额"))
+    .color(from("订单").dim("产品名称"))
+    .showNodeName(true)
+    .build();
+```
+
+模板：`finebi-cli widget template --chart-type sankey --scenario basic`。
+多阶段数据用 source/target 边表示，中间节点同时出现于起点和终点；不新增层级槽位。
+
+### 折线雷达图
+
+使用 `finebi-cli widget template --chart-type radar --scenario basic` 获取模板，按响应中的变量元数据
+替换组件名、表名、分类维度及两个不同的数值字段；变量值按 JSON 字面量编码。
+API 与配置边界见 [雷达图编码](widget-dsl-api.md#427-折线雷达图)。
+
+```javascript
+WidgetDsl.create("手机参数对比").chart().radar()
+    .x(from("手机参数对比").dim("特征"))
+    .y(line(from("手机参数对比").sum("手机A")))
+    .y(line(from("手机参数对比").sum("手机B")))
+    .radarOptions(RadarOptions.polygon().marker(true).symbol("triangle"))
+    .build();
+```