@finebi/finebi-cli 1.4.0 → 1.6.0

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

@@ -0,0 +1,457 @@
+# Widget DSL API：图表类型与编码
+
+> Widget DSL API 总导航见 [widget-dsl-api.md](widget-dsl-api.md)。
+
+## 4. 图表上下文
+
+### 4.1 图表类型
+
+| DSL API            | 业务含义                        |
+|--------------------|-----------------------------|
+| `.custom()` | 自定义组合图，支持多种指标 Series；约束和示例见 [§1](widget-dsl-core.md#1-根入口)。 |
+| `.box()` | 基础箱型图，使用 box 指标及 granularity 明细粒度；约束和示例见 [§1](widget-dsl-core.md#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](widget-dsl-core.md#26-地理角色字段与经纬度引用)）。
+区域地图使用同一地理维度的两个方向；其余地图也允许带匹配地理角色的经纬度指标。
+
+| 类型 | 图形通道约束 | 基础模板命令 |
+|---|---|---|
+| 区域地图 | 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)。
+