@finebi/finebi-cli 1.5.0 → 1.6.1

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

@@ -2,1377 +2,13 @@
 
 这份文档只列当前文本 DSL 可以直接使用的 Widget API，以及各 API 的业务含义。本语句面同时是
 `widget dsl --id <widgetId>` 回读命令的输出面（平台 Bean 反向翻译的 DSL 文本，见 docs/commands/）。
-
-## 1. 根入口
-
-### 分组表、交叉表合计行列
-
-`table()` 支持 `totalRows(config)`；`crossTable()` 还支持 `totalColumns(config)`。
-配置以 `TableTotal.rows()` / `TableTotal.columns()` 构建：
-
-| 方法 | 语义 |
-|---|---|
-| `position(TotalPosition.TOP/BOTTOM)` | 合计行位置，总合计与组内合计共用；默认 BOTTOM |
-| `position(TotalPosition.LEFT/RIGHT)` | 合计列位置；默认 RIGHT |
-| `grand(boolean)` | 总合计显隐，默认 true |
-| `subtotal(boolean)` | 组内合计显隐，默认 false，与总合计独立 |
-| `fields([DimRef, ...])` | 需要小计的已声明维度，默认空；必须属于对应行/列轴；隐藏小计时也保留选择 |
-| `grandStyle(TotalStyle)` / `subtotalStyle(TotalStyle)` | 总合计/组内合计的显示名称、字体、背景色 |
-| `build()` | 生成不可变配置 |
-
-`TotalStyle.builder().name("总合计").background("#FF0000").build()`：空名称使用平台默认标题，空背景色跟随风格。
-字体默认自动；`autoFont()` 显式恢复自动。自定义字体使用
-`font(TotalFont.builder().family("Arial").size(14).color("#FFFFFF").bold(true).italic(false).underline(true).build())`。
-字号必须为正整数；未指定字体名/字号/颜色时继承平台表身或主题样式，粗体/斜体/下划线默认 false。
-
-`totalBy(MeasureRef, TotalCalculation.X)` 仅作用于已声明的表格指标，支持
-`AUTO`、`SUM`、`AVERAGE`、`MAX`、`MIN`、`MEDIAN`、`VARIANCE`、`STANDARD_DEVIATION`、`HIDE`。
-`AUTO` 按指标汇总方式计算明细数据，其他计算方式对分组后的结果再次计算；`HIDE` 隐藏该指标合计。
-合计方式独立于指标原有 `sum/avg/...` 聚合，不通过修改指标聚合表达。
-
-```javascript
-WidgetDsl.create("地区合计").chart().table()
-  .dimension(from("销售明细").dim("省份"))
-  .dimension(from("销售明细").dim("城市"))
-  .measure(from("销售明细").sum("合同金额"))
-  .totalRows(TableTotal.rows().position(TotalPosition.TOP).subtotal(true)
-    .fields([from("销售明细").dim("省份")])
-    .grandStyle(TotalStyle.builder().name("总合计").background("#FF0000").build())
-    .subtotalStyle(TotalStyle.builder().name("省份合计").background("#FFA500").build())
-    .build())
-  .totalBy(from("销售明细").sum("合同金额"), TotalCalculation.SUM)
-  .build();
-```
-
-合计配置为完整值对象，未填写的项采用上述默认值；未声明任何合计配置时保持组件构建默认行为。
-合计能力不适用于明细表与图表；指标名称占位不属于可选小计维度。
-同一字段/分组在多个位置复用同一内部维度时，共享小计选择，不能表达互相冲突的选择。
-参考：[FineBI 合计行/列样式](https://help.fanruan.com/finebi/doc-view-1697.html)。
-
-自定义组合图模板：`finebi-cli widget template --chart-type custom --scenario basic`。
-x/y 轴可为空，可放维度或 `bar/point/heatMap/square/area/line/pie/text/map/funnel/gauge/box/sankey(measure)` 指标系列，也可混排；无最少指标数要求，支持转置。
-绘图轴取指标更多的一轴，数量相同时取 y 轴。非绘图轴指标用不带独立图形或堆积配置的 `bar(measure)` 表示。
-图表级五通道由全部系列继承，系列同名通道覆盖；多指标默认自动按指标名称着色。
-`.stacked(true)` 仅用于组合图系列，默认不堆积。值轴沿用 `valueAxis` API。
-
-```javascript
-WidgetDsl.create("组合图")
-  .chart().custom()
-  .x(from("销售明细").dim("销售日期"))
-  .y(bar(from("销售明细").sum("毛利额")).stacked(true))
-  .y(bar(from("销售明细").sum("商品单价")).stacked(true))
-  .y(line(from("销售明细").sum("销售金额")))
-  .build();
-```
-
-`area(measure)` 可与柱形或折线混合；`lineConnect(field)` 仅放在线/面积系列，
-其字段不能与分类轴相同。自定义图表属于内置组合图，不接收 ECharts 配置或任意渲染代码。
-
-专用通道通过系列 fluent 方法配置，随 `widget dsl` 回读保留：
-
-| 图形 | 专用方法 |
-|---|---|
-| `point(m)` | `.symbol(field)` |
-| `heatMap(m)` | `.heatColor(measure)` |
-| `pie(m)` | `.pieAngle(measure)` |
-| `text(m)` | `.textField(field)`，可多次调用 |
-| `gauge(m)` | `.gaugePointer(measure)`（可多次）、`.gaugeMax(measure)`、`.gaugeType(GaugeType.POINT_GAUGE)` |
-| `sankey(m)` | `.sankeyStart(field).sankeyEnd(field)` |
-
-其余图形使用公共通道。专用通道只适用于表中图形；除文本与指针外每个专用通道最多一个字段。
-仪表盘默认 `GaugeType.SLOT_GAUGE`，还支持 `RING_GAUGE/POINT_GAUGE/SEMI_POINT_GAUGE/V_THERMOMETER_GAUGE/H_THERMOMETER_GAUGE`。
-自定义图表中的 `box(m)` 不要求基础箱型图入口的轴布局，但不支持 `.stacked(true)`。
-
-`widget template` 的 `basic` 支持的图表包括 `seriesLine`、`ROSE`、`MULTI_PIE`、`bubble`。`seriesLine` 使用 `dimensionField` 分类轴、指标求和折线和 `seriesField` 颜色；`ROSE` 使用 `dimensionField` 分类，数值字段 `measureField` 求和后同时绑定角度与半径；`MULTI_PIE` 使用 `dimensionField` 颜色、指标求和大小和必填 `granularityField` 粒度，不配置 x/y 或 tooltip；`bubble` 使用 `dimensionField` 颜色分组和 `measureField` 求和大小，不配置 x/y。公共变量为 `widgetName`、`tableName`、数值字段 `measureField`，变量按 JSON 字面量替换。
-
-`LINE basic` 使用 `dateField`（DATE/DATE_TIME，默认年月日）和两个不同的数值字段 `measureField1`、`measureField2`，分别以 `sum` 绘制上下分区折线。多指标自动按指标名称着色并生成图例；颜色由转换器绑定到各指标图形，不在“全部”卡片显式绑定。`widgetName`、`tableName` 为公共变量；仍编译为 `sliceLine`，既有输入别名保持兼容。
-
-基础箱型图使用 `.chart().box()` 和 `box(指标)`：
-
-```js
-WidgetDsl.create("各省城市销量分布")
-  .chart().box()
-  .x(from("销量表").dim("省份"))
-  .y(box(from("销量表").sum("销量"))
-    .granularity(from("销量表").dim("城市"))
-    .color(from("销量表").dim("省份")))
-  .build()
-```
-
-`box(measure)` 表达绘图指标，不是预计算的五个统计值。上例按城市汇总销量，再计算各省城市销量的分布。
-支持交换 x/y 的横向布局，以及省略分类轴、只配置细粒度的整体分布。恰好一个 BOX 指标，指标轴不能混入维度；
-分类轴或有效颜色、细粒度、提示通道至少有一个真实维度。自动指标名称不算真实维度。
-支持图表级及 Series 级 `color`、`granularity`、`tooltipField`，Series 非空配置覆盖图表级配置；
-复用现有字段绑定 `size`，不新增固定箱宽设置。标签、连线与混合 mark 不支持。
-没有细粒度时不自动补字段，箱体可能退化；异常点组合图、异常点开关和统计参数不在当前支持范围内。
-箱体及箱须由 FineBI 原生计算，箱宽和透明度采用原生默认值。字段和表名必须替换成已核实的资源。
-
-```js
-WidgetDsl.create("组件名")
-```
-
-业务含义：
-
-- 新建一个单组件 Builder。
-- 组件名是后续保存、挂载到仪表板、联动和跳转时使用的业务名。
-
-## 2. 字段与指标工厂
-
-文本字段先通过 `geographic-role set` 设置国家/省份/城市/区县角色，再在组件中使用
-`from("客户维度表").dim("省份").longitude()` 或 `.latitude()`。方向不能与其他维度分组叠加，
-`widget dsl` 回读会保留方向。数值经纬度角色在字段级设置，组件仍用普通指标引用及显式聚合。
-`measureID("配置ID").measure()` 表示不附聚合的计算字段，用于字段角色配置；组件展示计算指标仍用 `.sum()`。
-完整的字段角色 DSL、匹配流程和组件引用示例见 §2.6。地理角色不包含自定义图片；字段角色设置和地图组件创建是独立操作。
-
-物理字段使用 source-scoped 写法，模型指标集字段使用 model-scoped 写法：
-
-```js
-from("销售表").dim("地区")
-from("销售表").sum("销售额")
-from("销售表").measure("销售额")
-from("销售表").count()
-model("销售指标集").dataset("订单明细").dim("地区")
-model("销售指标集").metrics().sum("销售额")
-quickCalculation(from("销售表").sum("销售额"), QuickCalculationType.RANK_ASC)
-
-// 标准分析主题移动计算：作用于指标聚合结果集
-windowCalculation(
-    from("销售表").sum("销售额"),
-    WindowCalculationModel.of(0, 0, 0,
-        WindowCalculationModel.row(
-            WindowCalculationModel.preceding(1), WindowCalculationModel.following(0))))
-```
-
-`windowCalculation(measure, configuration)` 是全局函数；`WindowCalculationModel` 是窗口配置命名空间。
-仅标准分析主题可使用移动计算；自助分析主题会在保存前报错，此限制同样适用于记录数和隐藏通道。
-组件形态需与设计器可达面一致，否则报错：组件至少要有一个维度；`calculateType` 组内要求
-表格某一轴（行/列）或图表多于一个维度；图表方向只能是 `0`（向下，设计器仅提供「默认」）；
-表格方向按行/列区维度开放——`1` 向右需要列维度，`2`/`3` 组合方向要求行、列维度都有，
-且至少要有一个维度。上述例子计算前一行与当前行的合计。计算作用于组件聚合后的结果行；
-窗口顺序取决于组件排序，按日期移动时应使用日期维度并核对排序与出数。
-原指标可另放一列，逐行核对窗口计算值。
-
-| `WindowCalculationModel.of` 参数 | 可用值 |
-|---|---|
-| `function` | `0` 求和、`1` 平均、`2` 最大、`3` 最小、`4` 方差、`5` 标准差 |
-| `calculateType` | `0` 全表、`1` 组内 |
-| `direction` | `0` 向下、`1` 向右、`2` 先向下后向右、`3` 先向右后向下 |
-| `frame` | `WindowCalculationModel.row(start, end)`，仅支持按行窗口 |
-
-边界使用 `WindowCalculationModel.first()` / `.last()` / `.preceding(n)` / `.following(n)`；
-`n` 为非负整数，`preceding(0)` 和 `following(0)` 均表示当前行，起点不能在终点之后。
-模型字段沿用 `model("模型").dataset("表").sum("金额")`，计算字段沿用 `measureID("配置ID").sum()`，
-记录数沿用 `from("表").count()`；包装移动计算保留字段来源和别名。
-使用专用 `windowCalculation(...)` 传入完整配置，不能用裸 `quickCalculation(..., QuickCalculationType.WINDOW_CALCULATION)`。
-回读 DSL 保留函数、范围、方向和边界；不支持的范围窗口会明确报错。
-同一组件内，同一实际字段和聚合方式只能使用一套窗口配置；相同配置可重复引用，
-不同配置会报冲突（包括记录数及隐藏通道）。需要并列不同窗口时，使用独立复制字段；
-排序、数字格式、分析线和值轴的目标引用须携带与指标一致的完整窗口配置。
-
-`from("名称")` 与 `model("名称")` 是不同字段身份，即使同名也不能互换。模型名和字段名必须来自
-已确认的当前主题模型证据；模型级只提供指标，模型表字段和模型计算字段分别进入 `dataset(...)` 与 `calculated()` 子命名空间。
-模型表字段必须写数据集限定符 `model("模型").dataset("数据集").dim/sum(...)`；模型计算字段使用 `model("模型").calculated().dim/sum(...)`。同一作用域内字段展示名重复时返回 `BLOCKED`，不能猜测来源。
-
-### 2.1 维度字段
-
-| DSL API | 业务含义 |
-|---|---|
-| `from("来源表").dim("字段名")` | 默认分组维度，用于地区、月份、产品、客户、订单号等分组或分类信息。 |
-| `from("来源表").dim("字段名", null, "别名")` | 使用默认分组并指定展示名。 |
-| `from("来源表").dim("字段名", grouping)` | 使用日期、文本或数值自定义分组。 |
-| `from("来源表").dim("字段名", grouping, "别名")` | 同时指定分组和展示名。 |
-| `measureID("配置 ID").dim()` | 已保存计算字段使用默认分组。 |
-| `measureID("配置 ID").dim(grouping)` | 已保存计算字段使用与字段类型兼容的显式分组；不支持别名。 |
-| `....hidden()` | 关闭展示字段：维度仍绑定进轴、保留槽位，查看态不展示（`used=false`）；可叠加在上述任意维度形态之后，与分组/别名/经纬度组合。 |
-
-分组使用以下稳定语法：
-
-物理数值字段作维度时，主题 measure 池里必须先有该字段的**已注册副本**（`finebi-cli measure copy --subject-id <S> --field-id <F> --as dimension`，副本名为“原显示名 + 递增序号”，例如“购买的产品1”）。组件命令只复用已注册副本、不隐式注册：缺副本时 `widget add/update/data` 报 `UNSUPPORTED_FEATURE`，`nextActions` 直接给出该 copy 命令，执行后重跑组件命令即可。DSL 始终引用原字段名；导出通过副本的 `source` 还原原字段引用，并保留组件显示别名与分组。
-
-```js
-// 日期：默认 YEAR_MONTH_DAY 应省略 grouping；非默认粒度显式声明
-DimensionGrouping.dateGranularity("YEAR_MONTH")
-
-// 数值维度·相同值为一组：每个原始值自成一组（设计器数值维度菜单的「相同值为一组」）
-DimensionGrouping.numberSameValues()
-
-// 数值维度·区间分组：连续边界，至少两个有限数且严格递增；整数、长整数、小数都可直接写
-DimensionGrouping.numberIntervals(0, 100, 500)
-
-// 文本维度：值必须是非 null 字符串，同一原始值只能属于一个命名组
-DimensionGrouping.textGroups([
-  DimensionGrouping.textGroup("华东", ["上海", "江苏"]),
-  DimensionGrouping.textGroup("华南", ["广东", "广西"])
-], "其他")
-```
-
-`textGroups(groups)` 可省略其他组名。数值维度两种分组择一：`numberSameValues()`（相同值为一组，
-落 `group.type=ID_GROUP`）与 `numberIntervals(...)`（区间分组，落 `group.type=NUMBER_GROUP` + 区间负载）；
-转维度副本（`TRANSFORM_FROM_NUMBER`）不写 grouping 时默认**区间分组**（与设计器默认一致），明细表的原始
-数值列默认相同值为一组。默认日期 YMD、文本相同值分组和明细表裸数值相同值分组都不要
-显式生成 grouping。`widget dsl` 的规范化输出会保留分组/值顺序，数值边界使用无指数十进制，
-并把 `-0.0` 写成 `0.0`。reader 会消费的文本 CUSTOM_GROUP / 数值 NUMBER_GROUP direct holder
-必须完整恢复，否则返回错误，不会退化成普通维度。reader 不消费的 direct holder（无匹配维度的
-孤立载荷、默认文本 ID_GROUP / 默认日期 YMD 维度旁的 stray customGroup）会作为 warning 返回；
-`cal[*]` 嵌套 customGroup 始终 warning。
-
-`.hidden()` 对应设计器"展示字段"开关，回读保留（输出为维度表达式末尾的 `.hidden()` 后缀）。
-仅视图轴绑定的维度生效：filter 字段、钻取层级、迷你图依赖、KPI 通道等非展示面引用带
-`.hidden()` 会报错或无效果（KPI 通道维度明确拒绝）。同一字段在同一组件内多处引用须保持
-一致 hidden 状态，否则保存报错——明细表例外：同字段多列按列独立生效，可一列隐藏一列展示；
-分类轴（`categoryAxis`）目标引用须重复携带一致的 `.hidden()` 后缀才能命中轴上维度。
-指标名维度（`metricNameInRow/InCol` 与自动指标名）不支持隐藏，设计器侧关闭时回读会以
-warning 留痕。
-
-### 2.2 聚合指标
-
-| DSL API                                    | 业务含义                                  |
-|--------------------------------------------|---------------------------------------|
-| `from("来源表").sum("字段名")`                   | 求和指标，适合销售额、利润、数量等可累计数据。               |
-| `from("来源表").sum("字段名", "别名")`             | 求和指标，并指定展示名，适合同字段多次使用时区分口径。           |
-| `from("来源表").avg("字段名")`                   | 平均值指标，适合客单价、平均折扣率等场景。                 |
-| `from("来源表").avg("字段名", "别名")`             | 平均值指标，并指定展示名。                         |
-| `from("来源表").max("字段名")`                   | 最大值指标，适合峰值展示。                         |
-| `from("来源表").max("字段名", "别名")`             | 最大值指标，并指定展示名。                         |
-| `from("来源表").min("字段名")`                   | 最小值指标，适合谷值展示。                         |
-| `from("来源表").min("字段名", "别名")`             | 最小值指标，并指定展示名。                         |
-| `from("来源表").measure("字段名")`               | 原值指标，不做聚合，仅适合在非明细表过滤中表达“按字段原始值参与计算”。 |
-| `from("来源表").measure("字段名", "聚合方式", "别名")` | 自定义聚合指标，适合平台支持但没有 sugar 方法的聚合方式。      |
-| `from("来源表").countDistinct("字段名")`          | 字段去重计数（如去重客户数）。只支持文本/日期字段，且该字段须先用 `measure transform --as measure` 转成指标形态。 |
-| `from("来源表").countDistinct("字段名", "别名")`    | 字段去重计数，并指定展示名。            |
-| `measureID("配置 ID").countDistinct()`           | 已保存计算字段按配置 ID 去重计数；形态要求同上，且公式不得引用聚合形态字段（平台会再包一层去重计数而报聚合嵌套聚合，组件命令直接拒绝）。           |
-
-主题内已保存的计算字段作为组件指标时必须使用 `measureID("配置 ID").sum()`；作为维度时使用
-`measureID("配置 ID").dim()`；显式数值区间可写为
-`measureID("配置 ID").dim(DimensionGrouping.numberIntervals(0, 100, 500))`。数值计算字段生成指标转维度字段，
-文本和日期计算字段直接绑定；grouping 与字段类型不兼容时保存失败。计算字段的配置 ID 必须属于当前主题，
-不能用实际 `fieldId` 或名称替代；配置 ID 从 `measure search/info` 响应条目的 `measureId` 字段获取
-（条目的 `id` 是实际字段 ID，不能填进 `measureID()`）。
-
-### 2.3 记录数
-
-| DSL API                         | 业务含义                  |
-|---------------------------------|-----------------------|
-| `from("来源表").count()`          | 当前分组范围内的记录数；存在唯一分组维度时按该维度统计，否则统计总行数。          |
-| `from("来源表").count("别名")`     | 当前分组范围内的记录数，并指定展示名。 |
-
-模型级指标必须进入 `metrics()` 子命名空间；模型指标集不提供根级维度或记录数。按字段去重计数的
-指标（`countDistinct`）见 §2.2，不属于记录数。
-
-### 2.4 快速计算
-
-| DSL API                                                                        | 业务含义                            |
-|--------------------------------------------------------------------------------|---------------------------------|
-| `quickCalculation(measureRef, QuickCalculationType.xxx)`                       | 基于已有指标派生快速计算指标，如排名、占比、累计、同比、环比。 |
-| `quickCalculation(measureRef, QuickCalculationType.xxx, secondaryCalculation)` | 在快速计算基础上显式指定二次计算开关。             |
-
-常见业务语义：
-
-- `QuickCalculationType.RANK_ASC`、`QuickCalculationType.RANK_DES`：排名
-- `QuickCalculationType.CURRENT_TARGET_PERCENT`：当前值占比
-- `QuickCalculationType.SUM_OF_ABOVE`：累计值
-- `QuickCalculationType.YEAR_ON_YEAR_*`：同比
-- `QuickCalculationType.MONTH_ON_MONTH_*`：环比
-
-### 2.5 主题共享钻取目录
-
-主题共享钻取目录使用独立命令 `drill-directory update --subject-id <id> --file <directory.js>`：
-
-```javascript
-DrillDirectoryModel.builder("地区")
-    .levels([from("销售原表").dim("省"), from("销售原表").dim("市")])
-    .build()
-```
-
-解散用 `DrillDirectoryModel.builder("地区").dissolve().build()`，保留原字段及其他配置。`drill-directory dsl --subject-id <id> --name "地区"` 回读目录。层级至少一个，必须为同引擎维度且无分组/别名；支持物理 `from`、模型数据集 `model(...).dataset(...).dim(...)` 和已保存计算维度 `measureID(...).dim()`。同名不同层级或字段属于其他目录时拒绝写入。目录独立于组件 DSL，普通多行维度不等于创建目录。
-
-### 2.6 地理角色字段与经纬度引用
-
-地理角色是当前主题内已有字段的共享语义配置，不创建物理字段。先用独立的
-`GeographicRole(...)` DSL 配置字段，再用 `WidgetDsl.create(...)` 引用；不要把 `.level()`、
-`.within()` 或 `.role()` 接到 Widget Builder 或 `dim(...)` 后，也不要在组件保存时隐式修改共享字段。
-
-| 字段类型 / 用途 | DSL 写法 |
-|---|---|
-| 文本国家、省份、城市、区县 | `GeographicRole(from("表").dim("字段")).level(NATION / PROVINCE / CITY / DISTRICT)`，四个常量择一 |
-| 限定文本角色的上级区域 | `.within(NATION, "国家完整路径")`，更细范围可追加 `.within(PROVINCE, "省份完整路径")`、`.within(CITY, "城市完整路径")` |
-| 自动匹配 | `.autoMatch()`；没有人工覆盖的值继续按平台规则动态匹配 |
-| 人工修正某个原始值 | `.match("原始值", "目标区域完整路径")` |
-| 禁止某个原始值参与匹配 | `.unmatch("原始值")`，不能写成 `.match("原始值", null)` |
-| 数值经度 / 纬度 | `GeographicRole(from("表").measure("字段")).role(LONGITUDE / LATITUDE)`，两个常量择一 |
-| 清除已有角色 | `GeographicRole(from("表").dim("字段")).clear().build()`；数值字段目标使用 `.measure("字段")` |
-
-每份字段角色 DSL 以 `.build()` 结束。文本 `.level(...)`、数值 `.role(...)`、`.clear()` 三种模式互斥；
-数值角色不能附加 `within/autoMatch/match/unmatch`。同一级 `within` 或同一原始值的人工覆盖不能重复声明。
-`within` 必须是目标层级的祖先，多个范围必须处于同一祖先链；`match` 的目标必须符合角色层级与范围。
-
-**文本省份示例**（保存为独立的 `province-role.dsl`）：
-
-```js
-GeographicRole(from("客户维度表").dim("省份"))
-  .level(PROVINCE)
-  .within(NATION, "assets/map/geographic/world/中国")
-  .autoMatch()
-  .match("江苏", "assets/map/geographic/world/中国/江苏省")
-  .unmatch("未知")
-  .build();
-```
-
-表名、字段名和区域路径都必须替换为当前环境已核实的资源。先查询 `geographic-role catalog --level NATION`，
-再用返回的国家完整路径查询 `geographic-role catalog --level PROVINCE --parent-path <国家完整路径>`；
-城市、区县同理逐级查询。不要仅凭中文名称拼接路径。国家角色用 `.level(NATION).autoMatch()`，无需国家范围；
-省份及更细角色省略 `within` 时，仅在平台目录含唯一国家时自动选取。城市、区县可以只限定国家，不强制填满每一级。
-
-按以下顺序使用命令（参数编码以当前 capability 和动态 `--help` 为准）：
-
-1. 修改已有角色前，执行 `geographic-role dsl --subject-id <主题ID> --field-id <字段ID>` 读取完整配置。
-2. 用 `geographic-role match --subject-id <主题ID> --file <角色DSL路径> --values '["上海","江苏","未知"]'` 预览匹配，不保存。
-3. 用 `geographic-role set --subject-id <主题ID> --file <角色DSL路径>` 保存；该操作整份替换这个字段的地理配置，必须保留仍需要的人工覆盖。
-4. 用 `geographic-role info` / `geographic-role dsl`，携带 `--subject-id` 和返回的 `fieldId` 回读核对。
-
-`match` 只检查显式提供的 1..200 个值，`complete=true` 不表示扫描了整列。
-人工覆盖是稀疏配置：未出现的原始值继续自动匹配，`unmatch` 禁止该值匹配；`autoMatch()` 不会把预览结果固化为人工映射。
-取消角色也可使用 `geographic-role clear --subject-id <主题ID> --field-id <字段ID>`，保留字段；
-仍有组件经纬度引用时会拒绝清除并返回依赖组件 ID。
-
-**数值经纬度示例**（每行分别保存为一份角色 DSL）：
-
-```js
-GeographicRole(from("门店表").measure("经度")).role(LONGITUDE).build();
-GeographicRole(from("门店表").measure("纬度")).role(LATITUDE).build();
-```
-
-角色目标使用不带聚合的 `.measure(...)`；组件展示数值坐标时仍使用普通指标引用及符合业务粒度的显式聚合。
-主题计算字段目标使用 `measureID("配置ID").dim()` 或 `.measure()`；模型字段沿用
-`model("模型").dataset("数据集").dim()/measure()` 等已有作用域。配置只保存到当前主题，不修改业务模型源定义。
-命令回读区分源 `fieldId` 和配置 `measureId`，计算字段引用不能把二者混用。
-
-**组件引用示例**（字段角色已保存后，作为独立的 Widget DSL）：
-
-```js
-WidgetDsl.create("省份坐标引用").chart().table()
-  .dimension(from("客户维度表").dim("省份").longitude())
-  .dimension(from("客户维度表").dim("省份").latitude())
-  .build();
-```
-
-同一文本地理字段通过 `.longitude()` / `.latitude()` 派生两个坐标方向；
-裸 `.dim("省份")` 仍表示原始省份分组。方向不能与日期分组、文本自定义分组或数值区间分组叠加。
-`widget info` 的 slot 以 `coordinate=LONGITUDE/LATITUDE` 表达方向，`widget dsl` 回读保留这两个方法。
-地图组件也可将这两个引用分别绑定到 `.x(...)` / `.y(...)`；创建图表本身不能替代上述字段角色配置。
-
-## 3. 组件 Builder
-
-| DSL API                   | 业务含义                            |
-|---------------------------|---------------------------------|
-| `.chart()`                | 进入图表上下文，定义图表类型、编码槽位、视觉通道、排序和格式。 |
-| `.filter()`               | 进入过滤上下文，给当前组件附加查询过滤条件。          |
-| `.color()`                | 进入组件配色上下文，定义整体色板或业务值到颜色的映射。     |
-| `.addDimension(dimRef)`   | 直接把维度追加到组件的维度区，适合简单表格或快速补充分组字段。 |
-| `.addMeasure(measureRef)` | 直接把指标追加到组件的指标区。                 |
-| `.build()`                | 冻结当前定义，生成不可变 `WidgetModel`。     |
-| `.buildWidget()`          | `build()` 的兼容别名。                |
-
-## 4. 图表上下文
-
-### 4.1 图表类型
-
-| DSL API            | 业务含义                        |
-|--------------------|-----------------------------|
-| `.custom()` | 自定义组合图，支持多种指标 Series；约束和示例见 §1。 |
-| `.box()` | 基础箱型图，使用 box 指标及 granularity 明细粒度；约束和示例见 §1。 |
-| `.partitionLine()` | 分区折线图，常用于单指标随时间或分类变化的趋势分析。  |
-| `.rangeArea()` | 范围面积图，x 维度、y 两个 AREA 序列，依次为下界和差值；自动堆积并隐藏底层。 |
-| `.radar()` | 折线雷达图，LINE Series 共享绘图区，支持雷达形状和标记点。 |
-| `.seriesLine()`    | 多系列折线图，常用于按产品、渠道等系列展开的趋势对比。 |
-| `.sliceColumn()`   | 分区柱形图，常用于相同维度下多个指标的分区对比。      |
-| `.stackColumn()`   | 堆积柱形图，常用于展示组成结构和总量。         |
-| `.seriesColumn()`  | 多系列柱形图，常用于并列比较多个系列的数值。      |
-| `.compareColumn()` | 对比条形图，常用于横向排名或类目对比。         |
-| `.waterFall()` | 瀑布图：至少一个 x 分类维度、一个 y 指标和一个 size 指标，使用普通字段引用。 |
-| `.point()` | 散点图：x/y 各一个字段，至少一轴为指标；`granularity` 区分点。 |
-| `.bubble()` | 聚合气泡图：一个大小指标，至少一个轴或图形通道维度；允许 x/y 多指标轴，指标图形共享通道配置；基础模板采用空轴。 |
-| `.rectTree()` | 矩形树图：可选 x/y 字段、大小指标与分组维度；允许空图形，原生排列，不配置排序。 |
-| `.wordCloud()` | 词云：text 文本、size 大小、color 颜色；支持 textSize(number)，字段数量不强制限制。 |
-| `.heat()` | 热力区域图（`HEAT` / `heat`）：x/y 各至少一个维度，指标绑定 color 或 size，使用普通字段引用。 |
-| `.areaMap()` | 区域地图（`AREA_MAP` / `areaMap`），地理维度定位区域，color 表达指标。 |
-| `.pointMap()` | 点地图（`POINT_MAP` / `pointMap`），经纬度定位，size 表达点大小。 |
-| `.lineMap()` | 流向地图（`LINE_MAP` / `lineMap`），经纬度定位，lineConnect 指标确定连线。 |
-| `.heatMap()` | 地理热力图（`HEAT_MAP` / `heatMap`），经纬度定位，heatColor 表达热度。 |
-| `.sankey()` | 桑基图：sankeyStart/sankeyEnd 接维度，size 接指标，showNodeName 控制节点名称；不限制数量。 |
-| `.funnel()` | 漏斗图：可选 x/y 维度，size 单/多指标，支持阶段排序、转化率及汇总值标签。 |
-| `.pie()`           | 饼图，适合看份额占比。多指标时用 `.metricNameInCol()` 代替 `.x(...)`（指标名作扇区分类，反读同轨还原）。                 |
-| `.rose()`          | 玫瑰图，适合在占比基础上同时强调量值差异。多指标同饼图；`.size(指标)` 可多次声明（与各指标逐位绑定半径，省略则自动绑定）。       |
-| `.multiPie()`      | 多层饼图，适合看层级结构或多层占比关系。        |
-| `.kpi()`           | KPI 指标卡，适合看单个核心指标。          |
-| `.gauge()`         | 仪表盘组件，适合表达目标进度、达成率或区间型指标。 |
-| `.table()`         | 分组表，适合按维度查看聚合结果。            |
-| `.crossTable()`    | 交叉表，适合行列维度交叉分析。             |
-| `.detailTable()`   | 明细表，适合逐行查看原始数据。             |
-
-### 4.2 通用图表编码
-
-适用图表：`pie`、`gauge`
-
-| DSL API          | 业务含义           |
-|------------------|----------------|
-| `.x(dimRef)`     | 横轴、类别轴或角度轴放维度。 |
-| `.x(measureRef)` | 横轴放指标。         |
-| `.y(dimRef)`     | 纵轴、半径轴放维度。     |
-| `.y(measureRef)` | 纵轴放指标。         |
-
-GAUGE 可在通用 `x/y` 编码之外声明仪表盘外观和目标值：
-
-| DSL API | 业务含义 |
-|---|---|
-| `.gaugeType(GaugeType.POINT_GAUGE)` | 选择仪表盘类型；也可使用 `.ringGauge()`、`.pointGauge()`、`.semiPointGauge()`、`.verticalThermometerGauge()`、`.horizontalThermometerGauge()`、`.slotGauge()`。 |
-| `.pointer(measureRef)` | 追加独立指针，不占纵轴；圆形/半圆可连续调用设置多个指针，其余类型仅一个。不能与 `.y()`、横轴指标或字段级图形覆盖混用；可用 `.x(dimRef)` 分面。 |
-| `.target(100)` | 设置常量目标值，必须为正数。 |
-| `.target(measureRef)` | 使用指标字段作为目标值。 |
-| `.gaugeStyle("standard")` | 设置仪表盘样式。 |
-| `.gaugeScale("bold")` | 设置刻度样式。 |
-| `.gaugeRoundRadius(true)` / `.roundRadius(true)` | 设置圆角开关。 |
-| `.gaugeColor("point", "#1677ff")` | 设置专属颜色；名称支持 `point`、`tick`、`tickSlot`、`hub`、`hubBackground`、`background`。 |
-
-Gauge 的 `.maxValue()`、`.maxField()`、`.gaugeMaxValue()` 保留兼容；模板和反编译输出统一使用 `.target()`。
-
-Gauge 是仪表盘图表，Dashboard 是页面容器。多个指针使用连续 `.pointer(...)`，不要将多个
-指标放入 `.y()` 当作同一仪表的多个指针。比例数据为 0～1 时用 `.target(1)` 和
-`NumberFormatModel.percentage(1, true)`；格式设置不会把 0～100 的值归一化。
-
-### 4.2.1 瀑布图编码
-
-`waterFall` 用 x 分类维度、y 位置指标、size 变化量绘制矩形块。一个 y 指标和一个 size 指标为必填。
-累计值由已保存字段或显式快速计算提供；分类顺序决定累计顺序，应按业务指定排序。
-
-```js
-WidgetDsl.create("收支瀑布")
-    .chart().waterFall()
-    .x(from("收支表").dim("阶段"))
-    .y(quickCalculation(from("收支表").sum("变化量"), QuickCalculationType.SUM_OF_ABOVE))
-    .size(from("收支表").sum("变化量"))
-    .sort(from("收支表").dim("阶段"), ["收入", "成本", "税费"])
-    .build();
-```
-
-可使用 `color`、`label`、`tooltipField`、`granularity`、过滤及数字格式。多个分类维度可连续调用
-`x`。指标直接用 `MeasureRef`；Series、多纵轴、专属轴设置和分析线超出当前瀑布图能力。
-模板入口为 `finebi-cli widget template --chart-type waterFall --scenario basic`。
-
-### 4.2.2 散点图编码
-
-每轴一个 `DimRef` 或 `MeasureRef`，至少一轴为指标。日期可作维度轴；`granularity` 决定
-点的明细粒度，不指定时按其他维度聚合。示例对应官方身高体重图：
-
-```js
-var source = from("身高体重分布");
-var height = source.sum("身高");
-var weight = source.sum("体重");
-WidgetDsl.create("身高体重散点图")
-    .chart().point()
-    .x(height).y(weight)
-    .granularity(source.dim("序号"))
-    .color(source.dim("性别"))
-    .pointColor("女", "#FF0000").pointColor("男", "#0000FF")
-    .pointRadius(5)
-    .valueAxis(height, ValueAxis.builder()
-        .min(AxisValue.min(height).subtract(AxisValue.fixed(5)))
-        .max(AxisValue.max(height).add(AxisValue.fixed(5))).build())
-    .build();
-```
-
-`size(MeasureRef)` 可按数值改变点大小；`pointRadius` 为正有限半径，省略时使用平台默认。
-`pointColor(value, color)` 需要已绑定颜色维度，颜色为 `#RRGGBB`。支持标签、提示、过滤、
-排序、两轴与通道指标的 `numberFormat`、`valueAxis` 和 `categoryAxis`。
-Series、多字段轴、图形覆盖、分析线及自定义符号不在此入口范围内。
-模板：`finebi-cli widget template --chart-type point --scenario basic`。
-
-### 4.2.3 聚合气泡图编码
-
-聚合气泡图示例（对应官方地区录取人数场景）：
-
-```javascript
-WidgetDsl.create("各地区录取人数")
-    .chart().bubble()
-    .color(from("各省招生人数表").dim("地区"))
-    .size(from("各省招生人数表").sum("实际录取"))
-    .label(from("各省招生人数表").dim("地区"))
-    .build();
-```
-
-模板：`finebi-cli widget template --chart-type bubble --scenario basic`。
-第二个指标可绑定 `color`，此时用 `granularity(dim)` 确定气泡分组。允许 x/y 字段并完整回读，
-轴字段会影响原生显示效果，聚合气泡优先使用上面的空轴样例。支持五个图形通道、
-`pointRadius`、`pointColor`、过滤和通道指标数值格式；暂不支持图例开关及条件注释。
-
-### 4.2.4a 漏斗图编码
-
-```javascript
-WidgetDsl.create("阶段转化")
-    .chart().funnel()
-    .color(from("漏斗数据").dim("步骤"))
-    .size(from("漏斗数据").sum("人数"))
-    .label(from("漏斗数据").dim("步骤"))
-    .label(from("漏斗数据").sum("人数"))
-    .showConversionRate(true)
-    .sort(from("漏斗数据").dim("步骤"), from("漏斗数据").sum("人数"), SortOrder.DESC)
-    .build();
-
-WidgetDsl.create("多指标漏斗")
-    .chart().funnel()
-    .size(from("漏斗数据").sum("查看商品"))
-    .size(from("漏斗数据").sum("购买商品"))
-    .colorMetricName().labelMetricName().showMeasureSum(true)
-    .build();
-```
-
-模板：`finebi-cli widget template --chart-type funnel --scenario basic`。
-单指标需要阶段维度，带轴示例可将步骤放在 `.y(dim)`，同时 `.color(measure)` 按指标渐变着色。
-多指标用连续 `.size(measure)` 保留顺序，配 `.colorMetricName()` 或 `.granularityMetricName()`；
-这三个指标名称入口只用于多指标。颜色字段与指标名称颜色互斥。
-转化率及汇总值标签默认关闭，可显式传 false 关闭。复用 label/tooltipField/granularity、
-sort、filter、numberFormat；轴只接受维度。图例开关、漏斗宽高和自定义配色方案暂无 DSL 入口。
-
-### 4.2.4 矩形树图编码
-
-```javascript
-WidgetDsl.create("部门小组人数")
-    .chart().rectTree()
-    .color(from("示例数据").dim("部门"))
-    .size(from("示例数据").sum("人数"))
-    .label(from("示例数据").dim("小组"))
-    .build();
-```
-
-模板：`finebi-cli widget template --chart-type rectTree --scenario basic`。
-模板变量为 `widgetName`、`tableName`、`dimensionField`、`measureField`、`labelField`，按 JSON 字面量替换。
-大小可选，配置时最多一个指标；不强制分组维度或图形。标签维度也参与细分，
-可用 `granularity(dim)` 追加细粒度。颜色最多一个字段，可使用第二个指标。
-支持可选 x/y 字段、`tooltipField`、过滤和通道指标 `numberFormat`。不使用 Series、图形覆盖或轴设置，
-不配置排序，布局由 FineBI 原生处理；配色方案、图例与标签样式暂不支持。
-矩形过小时原生渲染器可能隐藏标签。
-
-### 4.2.5 热力区域图编码
-
-使用 `.chart().heat()`，x/y 均不能为空且只能绑定维度；指标放到图形通道，不使用
-`square(measure)` 或其他 Series。`color` 最多绑定一个字段，`size` 最多绑定一个指标。
-热度通常用聚合指标的颜色表达；需要同时表达方块大小时绑定 `size`。
-
-`HEAT` 是热力区域图，不要求配置地理角色；`HEAT_MAP` / `.chart().heatMap()` 是地理热力图，
-组合图的 `heatMap(measure)` 则是系列图形，不能替代 `.chart().heat()`。
-热力区域图的 DSL 使用 `.color(measure)`，由适配器映射为原生 `heatColor` 通道；
-内部图形为 `heatMap`，颜色与大小使用独立字段 placement，`entire` 不绑定业务字段。
-DSL 不使用 `.heatColor()`、`radius` 或 `symbol`，也不配置 `valueAxis`、`categoryAxis`、
-警戒线、趋势线、`rows` 或系列图形覆盖。
-
-基础模板：`finebi-cli widget template --chart-type HEAT --scenario basic`。以下示例沿用模板的颜色与大小绑定：
-
-```javascript
-WidgetDsl.create("地区产品销售热力图").chart().heat()
-  .x(from("销售明细").dim("地区"))
-  .y(from("销售明细").dim("产品"))
-  .color(from("销售明细").sum("销售额"))
-  .size(from("销售明细").sum("销售额"))
-  .build();
-```
-
-### 4.2.6 地图编码
-
-四类地图均要求 x 恰好一个经度字段、y 恰好一个纬度字段，不使用 Series。
-维度需要先配置地理角色，再通过 `.longitude()` / `.latitude()` 引用（见 §2.6）。
-区域地图使用同一地理维度的两个方向；其余地图也允许带匹配地理角色的经纬度指标。
-
-| 类型 | 图形通道约束 | 基础模板命令 |
-|---|---|---|
-| 区域地图 | color 最多一个字段，不使用 size | `finebi-cli widget template --chart-type AREA_MAP --scenario basic` |
-| 点地图 | color 最多一个字段、size 最多一个指标；支持 symbol、shape 和 radius | `finebi-cli widget template --chart-type POINT_MAP --scenario basic` |
-| 流向地图 | 必须有 lineConnect，绑定指标；可使用 color 和 size | `finebi-cli widget template --chart-type LINE_MAP --scenario basic` |
-| 地理热力图 | heatColor 最多一个指标，可使用 size 和 radius；不使用 color | `finebi-cli widget template --chart-type HEAT_MAP --scenario basic` |
-
-地图不配置 `rows`、系列图形覆盖、`valueAxis`、`categoryAxis`、警戒线、趋势线或表格属性。
-例如，对已配置地理角色的省份维度生成区域地图：
-
-```javascript
-WidgetDsl.create("省份销售地图").chart().areaMap()
-  .x(from("销售明细").dim("省份").longitude())
-  .y(from("销售明细").dim("省份").latitude())
-  .color(from("销售明细").sum("销售额"))
-  .build();
-```
-
-### 4.2.7 折线雷达图
-
-`.chart().radar()` 使用 LINE Series 和共享绘图区。默认圆形、无标记点，
-多指标按指标名称自动配色，显式颜色绑定优先。完整配置至少需要一个维度和一个 LINE Series，
-指标只能位于一个轴；允许双轴均空的编辑骨架。
-
-`.radarOptions(RadarOptions.polygon().marker(true).symbol("triangle"))` 设置多边形与三角标记。
-`RadarOptions.circle()/polygon()/disabled()` 及 `enabled(boolean)/marker(boolean)/symbol(string)` 返回不可变配置。
-标记值限 `circle/rect/triangle/circle_hollow/square_hollow/triangle_hollow`。
-选项也可用于 `partitionLine/seriesLine`，保留其图表身份和轴布局；原生 radar 不能禁用开关。
-若已配置其他类型的专用图形属性，切换图表类型后调用 `radarOptions` 会明确报错，保留原图形配置。
-雷达样式与 `lineConnect` 字段绑定独立；反向导出保留配置，无法表达的逐指标样式差异明确报错。
-模板获取与完整示例见 [折线雷达图示例](widget-dsl-api-examples.md#折线雷达图)。
-
-### 4.2.8 范围面积图
-
-获取 `widget template --chart-type rangeArea --scenario basic` 后替换表名、分类维度、`lowerField`、`spanField` 和 `upperField`。`spanField` 必须预先准备为上界减下界；第二个绘图指标不可直接填上界，`upperField` 仅用于第二条系列的标签。
-
-```javascript
-WidgetDsl.create("温度范围")
-    .chart().rangeArea()
-    .x(from("天气数据").dim("月份"))
-    .y(area(from("天气数据").sum("最低温度")).label(from("天气数据").sum("最低温度")))
-    .y(area(from("天气数据").sum("温差")).label(from("天气数据").sum("最高温度")))
-    .build();
-```
-
-若温差是 `calculated-field add` 创建的已保存计算字段，将对应引用换成 `measureID(返回的配置ID).sum()`。不得用 `from(...)` 伪造其物理字段身份。FineBI 支持两个正数之间的范围；先核实源数据与差值，再验收绘图边界。当前固定底层透明度 0、可见面积 0.4，下述兼容范围之外的透明度/渐变在反向导出时会报错；不提供自定义区间样式、分析线和值轴/分类轴样式。
-
-范围面积图反向读取兼容原生空颜色槽及 `entire.color.opacity = 0`（也接受 CLI 默认的 0.4）。两条绘图序列仍要求透明度分别为 0、0.4；导出后按 CLI 默认装配时，entire 归一为 0.4，未指定颜色字段则按统一多指标规则补指标名称。
-
-### 4.3 KPI 指标卡编码
-
-| DSL API            | 业务含义                         |
-|--------------------|------------------------------|
-| `.text(measureRef)` | 追加 KPI 主指标到 `KpiGraphicModel.text`。 |
-
-规则：
-
-- KPI 至少需要一个 `.text(...)`
-- 多个主指标按声明顺序追加多个 `.text(...)`
-- KPI 的 `cols`、`rows`、`values` 必须为空，不要使用 `.x(...)` 或 `.y(...)`
-
-### 4.4 折线图与柱形图编码
-
-适用图表：`partitionLine`、`seriesLine`、`sliceColumn`、`stackColumn`、`seriesColumn`、`compareColumn`
-
-| DSL API           | 业务含义            |
-|-------------------|-----------------|
-| `.x(dimRef)`      | 把维度放到类目轴。       |
-| `.x(seriesModel)` | 把折线或柱形系列放到 X 轴。 |
-| `.y(dimRef)`      | 把维度放到类目轴。       |
-| `.y(seriesModel)` | 把折线或柱形系列放到 Y 轴。 |
-
-系列工厂：
-
-| DSL API            | 业务含义    |
-|--------------------|---------|
-| `line(measureRef)` | 构造折线系列。 |
-| `bar(measureRef)`  | 构造柱形系列。 |
-
-### 4.5 表格编码
-
-#### 分组表
-
-| DSL API                | 业务含义    |
-|------------------------|---------|
-| `.dimension(dimRef)`   | 追加分组维度。 |
-| `.measure(measureRef)` | 追加聚合指标。 |
-| `.dataBar(measureRef)` | 为已追加指标启用平台默认数据条。 |
-| `.miniChart(measureRef, MiniChart.xxx(dimRef)...)` | 为已追加指标配置唯一迷你图；依赖维度可以不在分析区。 |
-
-#### 交叉表
-
-| DSL API                | 业务含义          |
-|------------------------|---------------|
-| `.row(dimRef)`         | 追加行维度。        |
-| `.col(dimRef)`         | 追加列维度。        |
-| `.measure(measureRef)` | 追加交叉指标。       |
-| `.dataBar(measureRef)` | 为已追加指标启用平台默认数据条。 |
-| `.metricNameInRow()`   | 把“指标名称”放到行维度。 |
-| `.metricNameInCol()`   | 把“指标名称”放到列维度。 |
-
-#### 明细表
-
-| DSL API        | 业务含义                         |
-|----------------|------------------------------|
-| `.col(dimRef)` | 追加明细列。明细表的原始列统一走 `col(...)`。 |
-
-#### 表格字体（组件样式）
-
-`table()/crossTable()/detailTable()` 支持 `.tableFont(WidgetTableFont)`。组件字体用
-`WidgetTableFont.of()`；仪表板主题的 `TemplateStyle.tableFont(TableFont)` 是另一作用域。
-使用现有 `widget add --subject-id <主题ID> --file <文件>` 或 `widget update --id <组件ID> --file <文件>` 保存，`widget dsl` 回读同一配置。
-
-`WidgetTableFont.auto()` 恢复自动；`of().header(TableTextFont).body(TableTextFont).build()`
-选择自定义。表头/表身均支持 `family(string)/size(int)/color(string)/bold(boolean)/italic(boolean)/underline(boolean)`。
-字号仅允许 12、13、14、16、18、20、22、24、26、28、30、32、34、36、38、40、64、128；字体传 CSS 字体族（如黑体 `SimHei`、宋体 `SimSun`、`Arial`；空字符串表示默认字体族）。
-表头用 `align(TableFontAlign.LEFT/CENTER/RIGHT)`；表身分别用 `dimensionAlign(...)` 和 `measureAlign(...)`。
-未声明属性继承主题；显式 `false` 覆盖主题；空颜色等同未声明。自动模式回读可省略。
-非表格组件、越界字号、表头使用表身对齐或表身使用单槽对齐均拒绝。
-
-```js
-WidgetDsl.create("地区金额")
-  .chart().table()
-  .dimension(from("销售原表").dim("地区"))
-  .measure(from("销售原表").sum("金额"))
-  .tableFont(WidgetTableFont.of()
-    .header(TableTextFont.of().family("SimHei").size(16).bold(true)
-      .color("#333333").align(TableFontAlign.CENTER).build())
-    .body(TableTextFont.of().family("SimHei").size(14).bold(false)
-      .dimensionAlign(TableFontAlign.CENTER).measureAlign(TableFontAlign.LEFT).build())
-    .build())
-  .build();
-```
-
-能力范围参考：[表格字体](https://help.fanruan.com/finebi/doc-view-1694.html)。
-
-#### 表格行高（组件样式）
-
-`table()/crossTable()/detailTable()` 支持 `.tableRowHeight(TableRowHeight)`：
-
-| 方法 | 含义 |
-|---|---|
-| headerHeight(px) / bodyHeight(px) | 表头 / 表身高度，16–200 整数像素，默认 32 |
-| headerWrap(boolean) / bodyWrap(boolean) | 表头 / 表身自动换行，默认 false |
-
-开启换行后，行高表示最大适应高度，内容在此高度内自动换行；PC 和移动端共用组件配置。
-未声明项保持默认值，重复 tableRowHeight 调用以最后一组为准；空 Builder 恢复默认。
-
-```javascript
-WidgetDsl.create("订单明细").chart().detailTable()
-  .col(from("订单表").dim("商品名称"))
-  .tableRowHeight(TableRowHeight.of()
-    .headerHeight(48).headerWrap(true)
-    .bodyHeight(100).bodyWrap(true).build())
-  .build();
-```
-
-可用于 widget add/update 及 dashboard 中的组件定义，widget dsl 反向导出保留有效设置。
-能力范围参考：[表格行高](https://help.fanruan.com/finebi/doc-view-1695.html)。
-
-#### 表格格式（组件样式）
-
-`table()/crossTable()/detailTable()` 支持 `.tableFormat(TableFormat.of()...build())`。
-
-| 方法 | 用法与范围 |
-|---|---|
-| pageRows(n) | 每页 1–1000 行；分组/交叉表默认 20，明细表默认 100；明细表 ≥50 列时最多 100 行 |
-| pageColumns(n) | 交叉表每页 1–1000 列，默认 7 |
-| sequence(boolean) | 显示序号，默认关闭 |
-| rowInfo(boolean) | 明细表显示行数信息，默认开启 |
-| totalRows(boolean) / totalPages(boolean) | 显示总行数/总页数，支持显式关闭；省略则继承平台查看态规则；不是合计行；仅标准分析主题可声明，显式 true 时对应行/列展开须为 DISABLED |
-| rowExpansion(TableExpansion.DISABLED / COLLAPSED / EXPANDED) | 分组/交叉表禁止展开收起交互（全部展开）/允许交互且初始收起/允许交互且初始展开 |
-| columnExpansion(TableExpansion.DISABLED / COLLAPSED / EXPANDED) | 交叉表列维度展开规则，同上 |
-| freezeDimensions(boolean) | 分组/交叉表冻结维度，默认开启 |
-| frozenColumns(n) | 明细表冻结前 1–10 列；0 关闭冻结，默认 1 |
-
-未声明展开配置时使用 DSL 默认的可交互、初始收起；迷你图固定禁止行展开交互。
-总行数/总页数配置入口属于 7.0.13+ 标准分析主题：自助分析主题下显式声明这两个开关中任一
-会报错（设计器不显示该开关组）；标准分析主题下显式 true 要求对应行/列展开为
-`TableExpansion.DISABLED`（交叉表行/列按钮任一开启即报错），显式 false 与省略等价始终放行。
-这两个布尔值省略时保留继承，显式 false 会关闭显示。宽度适应时前端不执行冻结。
-重复 tableFormat 以最后整组为准，空 Builder 恢复默认；不适用的表格专属选项直接报错。
-
-**新建默认与设计器系统参数**：CLI 新建组件固定展开收起可交互、初始收起与总合计开启；标准分析
-主题下设计器**新建**表格会按系统参数 `standardAnalysisSupportExpandCollapse` /
-`standardAnalysisSelectGrandTotal`（默认均为 false）改写为「隐藏展开按钮、关闭总合计」。需要与
-设计器新建同款默认形态时显式声明：`.tableFormat(...rowExpansion(TableExpansion.DISABLED)
-.totalRows(false).totalPages(false)...)`（交叉表另加 `.columnExpansion(TableExpansion.DISABLED)`），
-并加 `.totalRows(TableTotal.rows().grand(false).build())`（交叉表列合计用
-`.totalColumns(TableTotal.columns().grand(false).build())`）；这些值都不是省略默认，回读与重放稳定。
-配方适用于分组表/交叉表；明细表不适用 `rowExpansion` 与合计配置，只需 `.tableFormat(...)`
-声明 `totalRows(false)` 与 `totalPages(false)`。
-
-```javascript
-WidgetDsl.create("交叉表格式").chart().crossTable()
-  .row(from("订单表").dim("地区"))
-  .col(from("订单表").dim("商品"))
-  .measure(from("订单表").sum("金额"))
-  .tableFormat(TableFormat.of().pageRows(7).pageColumns(4).sequence(true)
-    .rowExpansion(TableExpansion.DISABLED).columnExpansion(TableExpansion.DISABLED)
-    .totalRows(true).totalPages(true).freezeDimensions(true).build())
-  .build();
-
-WidgetDsl.create("明细表格式").chart().detailTable()
-  .col(from("订单表").dim("商品"))
-  .tableFormat(TableFormat.of().pageRows(50).sequence(true)
-    .rowInfo(true).frozenColumns(4).build())
-  .build();
-```
-
-适用于 widget add/update 和 dashboard 组件定义，widget dsl 导出保留有效配置。
-功能参考：[表格格式](https://help.fanruan.com/finebi/doc-view-990.html)。
-
-#### 表格风格（组件样式）
-
-`table()/crossTable()/detailTable()` 支持 `.tableStyle(TableStyle.of()...build())`。
-
-| 方法 | 含义 |
-|---|---|
-| form(TableForm.MULTI_COLUMN / TREE / LIST) | 多列 / 树状 / 列表；只适用于分组表和交叉表，默认多列 |
-| style(TableStyle.STYLE1 / STYLE2 / STYLE3) | 风格 1 / 2 / 3；省略时继承仪表板主题 |
-| themeColor(color) | 具体颜色（如 "#FF8800"）、"transparent" 透明、"" 自动继承主题 |
-| adaptive(TableAdaptive.STANDARD / FIT_WIDTH) | 标准适应（默认，自动计算列宽）/ 宽度适应（宽度方向显示全部列）；三种表格均支持 |
-
-明细表不允许 form，包括 MULTI_COLUMN。未声明属性保留默认或主题继承；
-重复 tableStyle 以最后整组为准，空 Builder 恢复默认多列及主题继承。
-恢复标准适应用 `adaptive(TableAdaptive.STANDARD)`；反读时标准适应归一为省略。
-
-```javascript
-WidgetDsl.create("地区金额").chart().table()
-  .dimension(from("订单表").dim("地区"))
-  .measure(from("订单表").sum("金额"))
-  .tableStyle(TableStyle.of()
-    .form(TableForm.MULTI_COLUMN)
-    .style(TableStyle.STYLE2)
-    .adaptive(TableAdaptive.FIT_WIDTH)
-    .themeColor("#FF8800").build())
-  .build();
-```
-
-可用于 widget add/update 和 dashboard 组件定义；widget dsl 反向导出保留有效配置。
-仪表板全局表格主题仍使用 TemplateStyle.tableStyle/tableThemeColor。
-能力范围参考：[风格](https://help.fanruan.com/finebi/doc-view-1696.html)。
-
-### 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#普通折线连线样式)。
-
-## 6. 过滤上下文
-
-过滤固定采用 `field(...)+算子` 的链式写法：
-
-```js
-filter().field(from("销售表").dim("地区")).eq("华东")
-```
-
-| DSL API                        | 业务含义            |
-|--------------------------------|-----------------|
-| `.field(fieldRef)`             | 指定当前过滤目标字段。     |
-| `.eq(value)` / `.ne(value)` | 文本、数值、日期等于 / 不等于。 |
-| `.gt(value)` / `.gte(value)` / `.lt(value)` / `.lte(value)` | 数值大于 / 大于等于 / 小于 / 小于等于。 |
-| `.in(values)` / `.notIn(values)` | 文本枚举属于 / 不属于；日期显示文本也可按枚举匹配。 |
-| `.contains(value)` / `.notContains(value)` | 文本或日期显示文本包含 / 不包含。 |
-| `.startsWith(value)` / `.notStartsWith(value)` | 文本或日期显示文本前缀正 / 反匹配。 |
-| `.endsWith(value)` / `.notEndsWith(value)` | 文本或日期显示文本后缀正 / 反匹配。 |
-| `.between(from, to)` / `.notBetween(from, to)` | 数值或日期区间 / 区间外；数值默认包含两端。 |
-| `.between(from, to, includeFrom, includeTo)` / `.notBetween(from, to, includeFrom, includeTo)` | 数值区间的开闭边界；两个标记均为 boolean。 |
-| `.before(value)` / `.after(value)` | 日期早于 / 晚于。 |
-| `.isNull()` / `.notNull()` | 文本、数值、日期为空 / 不为空。 |
-| `.topN(value)` / `.bottomN(value)` | 文本、数值、日期最大 / 最小 N 个；N 为正整数或数值参数。日期可用 `.latest(value)` / `.earliest(value)`，导出归一为 topN/bottomN。 |
-| `.condition(WidgetFilter.anyOf([...]))` / `.condition(WidgetFilter.allOf([...]))` | 同一字段、分组和层级内的 OR / AND 条件树，可嵌套；子条件使用 WidgetFilter 的同名算子工厂。 |
-| `.closeRange(includeMin, includeMax)` | 数值区间端点开闭，紧跟 between 之前声明；与四参数 between 等价，重复声明的边界须一致。省略 = 全闭；回读保留开闭语义。 |
-
-数值参数过滤：先用 `widget-parameter info --subject-id ...` 查询当前主题参数，再使用
-`.filter().field(from("门店销售数据统计").sum("销售额")).topN(parameter("排名数量"))`。
-等值过滤使用 `.eq(parameter("数值阈值"))`，最小 N 个使用 `.bottomN(parameter("排名数量"))`。
-数值 eq/ne/gt/gte/lt/lte 与所有类型的 topN/bottomN 使用 number 参数；文本 in/notIn 和六种文本匹配使用 string 参数。
-日期 eq/ne/before/after 使用 date 参数，整段日期参数通过 `.between(parameter("时间段"))` / `.notBetween(parameter("时间段"))` 传入。
-日期显示文本匹配使用 string 参数。参数按当前主题名称解析，不用默认值替代；不接受参数与常量混合区间或参数列表。
-仪表板数值控件通过 `bindWidgetParameter("排名数量")` 绑定同名参数，修改控件值即可动态改变过滤值。
-参考：[数值参数参与过滤](https://help.fanruan.com/finebi/doc-view-1064.html)。
-
-日期点与区间端点接受已有 `DynamicDate` 值；需要工作日偏移、明确粒度或时钟时使用 `FilterDate`：
-
-```js
-.filter().field(from("销售表").sum("销售额")).gte(1000)
-.filter().field(from("销售表").dim("地区"))
-.condition(WidgetFilter.anyOf([WidgetFilter.eq("华东"), WidgetFilter.startsWith("华南")]))
-.filter().field(from("销售表").dim("日期"))
-.between(DynamicDate.beginOf(DynamicDate.MONTH, -1), DynamicDate.endOf(DynamicDate.MONTH, -1))
-.filter().field(from("销售表").dim("日期"))
-.before(FilterDate.offset(DynamicDate.today()).time("18:00:00").build())
-```
-
-`FilterDate.offset(DynamicDate...)` 或 `FilterDate.workdays(-3)` 返回 Builder，可设置
-`.group(FilterDate.YEAR/QUARTER/MONTH/WEEK/DAY/HOUR/MINUTE/SECOND/WORKDAY/AUTO)`，
-`.currentTime()` 或 `.time("HH:mm:ss")` 后 `.build()`。工作日依赖服务器工作日日历；
-currentTime 在查询时取当前时钟，time 为固定整秒时刻；`.time("")` 拒绝空字符串，需要当前时钟时使用 `.currentTime()`。动态区间两端可以分别使用静态或动态值。
-
-条件树不跨字段或计算层级；多次 `.filter()` 之间仍为 AND，根 AND 导出可展开为多条条件。
-日期文本匹配受字段日期粒度与引擎限制，保存时拒绝 Direct 引擎的包含和前后缀匹配（含参数和嵌套条件）。
-本文组件过滤能力不扩展控件候选值过滤或动态字段值 `where` 的接口。
-
-层级在字段与算子之间设置，例如：
-
-```js
-.filter().field(from("销售表").dim("地区"))
-.level(FilterLevel.FOURTH).eq("华东")
-```
-
-| FilterLevel | 自助分析主题 | 标准分析主题 |
-|---|---|---|
-| AUTO（默认） | 按字段及计算自动决定 | 按字段及计算自动决定 |
-| FIRST | 明细过滤 | 前置过滤 |
-| SECOND | DEF 新增列过滤 | 明细过滤 |
-| THIRD | 聚合计算过滤 | 聚合计算过滤 |
-| FOURTH | 快速计算过滤 | 快速计算过滤 |
-
-未声明 `.level(...)` 时按设计器面板的默认落值写入（两主题不同）：
-维度自身过滤与未聚合指标过滤在标准主题恒第二层、自助主题第一层（top/bottom N 时第二层）；
-聚合指标过滤第三层、top/bottom N 时第四层；公式过滤引用指标时第二层、否则第一层。
-**明细表**过滤走独立编辑器，默认标准主题 22（固定明细档）、非标准主题第一层。已知差异
-（前端有、本实现暂未镜像，可用显式 `.level(...)` 覆盖）：自助主题「数值维度/维度依赖聚合指标」
-项前端固定第二层、本实现落第一层。带快速计算的聚合指标过滤前端默认第四层、标准化路径
-不可声明（`.filter()` 的字段不接受携带快速计算）。
-普通维度进入分析区且依赖分组时可调整到四层；不在分析区时仅支持 FIRST/SECOND。
-自助主题的 DEF/WINDOW/FIXED 维度进入分析区后只允许 SECOND，维度依赖指标过滤允许 SECOND/THIRD/FOURTH。
-标准主题的聚合输出维度和分析区内依赖指标过滤仅允许 SECOND；新增列维度仅允许 FIRST/SECOND。
-聚合指标不支持手动调整；标准主题的未聚合指标（`.measure("字段")`）可选 FIRST/SECOND。
-明细表仅支持 FIRST/SECOND。普通算子和 `.formula(...)` 均支持层级；每条条件提交后重置为 AUTO，
-同一字段分组的条件须使用一致层级。层级不会替字段添加聚合或快速计算。
-
-参考：[自助分析层级](https://help.fanruan.com/finebi/doc-view-2405.html)、
-[维度调整规则](https://help.fanruan.com/finebi/doc-view-1609.html)、
-[标准分析层级](https://help.fanruan.com/finebi/doc-view-2777.html)。
-
-## 7. 配色上下文
-
-| DSL API                 | 业务含义          |
-|-------------------------|---------------|
-| `.byField(fieldRef)`    | 按某个字段自动拆分颜色。  |
-| `.palette(["#E65251", "#3478F6"])` | 按顺序设置分类色板，必须是非空 `#RRGGBB` 数组。 |
-| `.mapping({"值":"#颜色"})` | 为具体业务值指定固定颜色。 |
-
-先在图表上下文用 `.color(DimRef)` 绑定分类字段，再用 `.color().palette([...])` / `.mapping({...})` 配色。
-饼图、玫瑰图使用 x 分类，多指标图也可使用自动指标名称分类。mapping 键是显示分类值或指标显示名。
-只写 mapping 时，按映射声明顺序形成备用色板；先 palette 再 mapping 可为未列出的分类保留独立备用色板。
-再次 palette 会清除映射，再次 mapping 替换映射并保留当前色板；`.palette("名称")` 不是有效语法。
-
-支持柱形／折线各家族、custom、radar、box、rangeArea、pie、rose、gauge、areaMap、pointMap、lineMap。
-每个实际图形必须有维度颜色槽；指标渐变、多系列各自不同色板不在此入口范围。
-表格使用 tableColor；point/bubble 使用已有 colors；其他图表的适用范围按各图表节。
-DSL 回读保留分类绑定、色板和映射，自动主题色不输出显式 palette；无法保真的配色明确报错。
-完整例子见 [§10.12 组件配色](widget-dsl-api-examples.md#1012-组件配色)。
-
-## 8. 数值格式工厂
-
-```js
-NumberFormatModel.auto()
-NumberFormatModel.auto(2, NumberFormatModelScale.THOUSAND, null, true)
-NumberFormatModel.number(2)
-NumberFormatModel.number(2, NumberFormatModelScale.TEN_THOUSAND, "元", true)
-NumberFormatModel.percentage(1, true)
-```
-
-| DSL API                                                             | 业务含义               |
-|---------------------------------------------------------------------|--------------------|
-| `NumberFormatModel.auto()`                                          | 使用平台自动格式。          |
-| `NumberFormatModel.auto(decimalPlaces, scale, unit, useGrouping)` | 自动精度并保留缩放、单位和千分位配置；decimalPlaces 可为 null，保存面板值但不强制固定小数位。 |
-| `NumberFormatModel.number(decimalPlaces)`                           | 普通数值格式。            |
-| `NumberFormatModel.number(decimalPlaces, scale, unit, useGrouping)` | 带缩放、单位和千分位控制的数值格式。 |
-| `NumberFormatModel.percentage(decimalPlaces, useGrouping)`          | 百分比格式。             |
-
-`scale` 同时决定缩放与数量级单位，`unit` 是追加的单位文本。例如 `TEN_THOUSAND` + `"元"`
-显示“万元”；只显示“万”时使用 `null`，不要重复填写 `"万"`。`number(2, ...)` 固定两位小数；
-带参数的 `auto(...)` 保留自动精度。只有完全默认的 `auto()` 在回读时归一为未设置。
-
-## 9. 可用枚举
-
-| 枚举                       | 可用值                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `SortOrder`              | `SortOrder.ASC`, `SortOrder.DESC`, `SortOrder.asc`, `SortOrder.desc`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `QuickCalculationType`   | `QuickCalculationType.NONE`, `QuickCalculationType.CURRENT_TARGET_PERCENT`, `QuickCalculationType.CURRENT_TARGET_PERCENT_IN_GROUP`, `QuickCalculationType.RANK_ASC`, `QuickCalculationType.RANK_DES`, `QuickCalculationType.RANK_IN_GROUP_ASC`, `QuickCalculationType.RANK_IN_GROUP_DES`, `QuickCalculationType.SUM_OF_ABOVE`, `QuickCalculationType.SUM_OF_ABOVE_IN_GROUP`, `QuickCalculationType.SUM_OF_ALL_SUM`, `QuickCalculationType.SUM_OF_ALL_AVG`, `QuickCalculationType.SUM_OF_ALL_MAX`, `QuickCalculationType.SUM_OF_ALL_MIN`, `QuickCalculationType.SUM_OF_ALL_IN_GROUP_SUM`, `QuickCalculationType.SUM_OF_ALL_IN_GROUP_AVG`, `QuickCalculationType.SUM_OF_ALL_IN_GROUP_MAX`, `QuickCalculationType.SUM_OF_ALL_IN_GROUP_MIN`, `QuickCalculationType.YEAR_ON_YEAR_VALUE_YEAR`, `QuickCalculationType.YEAR_ON_YEAR_VALUE_QUARTER`, `QuickCalculationType.YEAR_ON_YEAR_VALUE_MONTH`, `QuickCalculationType.YEAR_ON_YEAR_VALUE_WEEK`, `QuickCalculationType.YEAR_ON_YEAR_DIFFERENCE_YEAR`, `QuickCalculationType.YEAR_ON_YEAR_DIFFERENCE_QUARTER`, `QuickCalculationType.YEAR_ON_YEAR_DIFFERENCE_MONTH`, `QuickCalculationType.YEAR_ON_YEAR_DIFFERENCE_WEEK`, `QuickCalculationType.YEAR_ON_YEAR_RATE_YEAR`, `QuickCalculationType.YEAR_ON_YEAR_RATE_QUARTER`, `QuickCalculationType.YEAR_ON_YEAR_RATE_MONTH`, `QuickCalculationType.YEAR_ON_YEAR_RATE_WEEK`, `QuickCalculationType.MONTH_ON_MONTH_VALUE`, `QuickCalculationType.MONTH_ON_MONTH_DIFFERENCE`, `QuickCalculationType.MONTH_ON_MONTH_RATE` |
-| `NumberFormatModelStyle` | `NumberFormatModelStyle.AUTO`, `NumberFormatModelStyle.NUMBER`, `NumberFormatModelStyle.PERCENTAGE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `NumberFormatModelScale` | `NumberFormatModelScale.NORMAL`, `NumberFormatModelScale.THOUSAND`, `NumberFormatModelScale.TEN_THOUSAND`, `NumberFormatModelScale.MILLION`, `NumberFormatModelScale.HUNDRED_MILLION`, `NumberFormatModelScale.BILLION`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-
-## 10. 推荐写法示例
-
-> §10 全部示例已外置到 [`widget-dsl-api-examples.md`](widget-dsl-api-examples.md)（纯追加式增长的大段示例与 §1-§9 的 API 面分离维护）。
+API 面拆分为下表文件，按需读取当前组件涉及的文件，不一次加载全部；章节编号沿用拆分前原编号
+（§4 分布在编码与样式两个文件）。
+
+| 文件 | 章节 | 何时读取 |
+| --- | --- | --- |
+| [widget-dsl-core.md](widget-dsl-core.md) | §1-§3 根入口、字段与指标工厂、组件 Builder | 写任何组件前必读 |
+| [widget-dsl-encodings.md](widget-dsl-encodings.md) | §4.1-§4.5 图表类型、通用与特殊图表编码、KPI 指标卡、折线柱形、表格编码 | 配置图表类型与通道编码时 |
+| [widget-dsl-styles.md](widget-dsl-styles.md) | §4.6-§4.11 视觉通道、数值格式、警戒线趋势线、值轴双 y 轴、分类轴、表格指标属性、排序、内边距、网格线、背景；§5 SeriesModel 连线样式 | 调整样式、视觉通道、轴或排序时 |
+| [widget-dsl-contexts.md](widget-dsl-contexts.md) | §6 过滤上下文、§7 配色上下文、§8 数值格式工厂、§9 可用枚举 | 配置过滤、配色、数值格式或查枚举时 |
+| [widget-dsl-api-examples.md](widget-dsl-api-examples.md) | 推荐写法示例（大段示例与 API 面分离维护） | 需要可运行的推荐写法时 |