@guandata/guanvis 0.1.34 → 0.1.35

package/skills/guanvis/references/chart-properties.md

@@ -0,0 +1,1051 @@
+# 图表属性配置
+
+介绍图表属性配置的用法和参数。
+
+调用属性方法时会按实际支持范围校验图表类型；不支持的调用会产生 validation error。AttachedCard 会在读取基线卡片的图表类型后执行相同校验。
+
+标题、图例、数据标签、Tooltip、饼图中心文字和汇总指标共用字体样式校验：`fontFamily` 必须是非空字符串，`color` 必须是字符串或 `null`，`bold` / `italic` / `underline` 必须是 boolean。标题、图例、数据标签、Tooltip 和饼图中心文字的 `fontSize` 范围为 9–72；汇总指标为 12–72。
+
+## 卡片设置
+
+### `setCardSetting(config)`
+
+设置卡片背景、主题跟随、内边距和内容间距：
+
+```javascript
+.setCardSetting({
+    background: {
+        color: "#F5F6F7",
+        image: {
+            show: true,
+            uploadPath: "./assets/card-background.png",
+            renderType: ImageRenderType.FIT_TO_CONTENT
+        }
+    },
+    followTheme: false,
+    padding: {
+        top: 4,
+        right: 12,
+        bottom: 12,
+        left: 12
+    },
+    contentSpace: ContentSpaceSize.MIDDLE
+})
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `background` | object | 背景色和背景图片 |
+| `followTheme` | boolean | 是否跟随页面主题；传 `false` 后不再补齐该卡片的主题样式 |
+| `padding` | object | 四周内边距 |
+| `contentSpace` | `ContentSpaceSize` | 内容间距 |
+
+`background` 支持：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `color` | string / `null` | 背景色；`null` 清除显式背景色 |
+| `image` | object / `null` | 背景图片；`null` 清除并关闭背景图片 |
+
+`background.image` 支持：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `show` | boolean | 是否显示背景图片 |
+| `url` | string | 以 `http://` 或 `https://` 开头的图片链接；与 `uploadPath` 同时设置时优先使用 `url` |
+| `uploadPath` | string | 待上传的本地图片路径；没有 `url` 时生效，`pack`/`publish` 时作为 Card 附件上传 |
+| `renderType` | `ImageRenderType` | `RATIO`、`STRETCH` 或 `FIT_TO_CONTENT` |
+
+本地背景图支持 `jpg/jpeg/png/gif`，相对路径以 guanvis 工程目录为基准，`pack`/`publish` 时自动上传；`image: null` 会关闭并清空背景图。
+
+`padding` 支持 `top`、`right`、`bottom`、`left`，每项均为 `0`–`32` 的整数，单位为 px。`contentSpace` 可传 `ContentSpaceSize.SMALL`、`ContentSpaceSize.MIDDLE` 或 `ContentSpaceSize.LARGE`。
+
+该方法可用于 Card、MetricChart 和 `attachCard()`；重复调用或通过 `attachCard()` 修改时只合并显式传入的字段。
+
+## 卡片标题
+
+### `setCardTitleStyle(config)`
+
+设置卡片标题的文字和标题区域样式。标题显隐继续使用 `.setShowTitle(boolean)`：
+
+```javascript
+.setShowTitle(true)
+.setCardTitleStyle({
+    style: {
+        fontFamily: "sans-serif",
+        fontSize: 18,
+        color: "#1F2329",
+        bold: true,
+        italic: false,
+        underline: false,
+        textAlign: "left"
+    },
+    titleSetting: {
+        backgroundColor: "#FFFFFF",
+        height: 40,
+        showBgImage: false,
+        showIcon: true,
+        icon: {
+            url: "/guandata-store/images/title-icon.png",
+            sourceType: 3,
+            renderType: 3
+        },
+        topStrip: {
+            enabled: true,
+            width: 2,
+            backgroundColor: "#1456F0"
+        },
+        bottomStrip: {
+            enabled: false,
+            width: 2,
+            backgroundColor: "#DEE0E3"
+        }
+    }
+})
+```
+
+`style` 对应前端 `settings.style`：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `fontFamily` | string | 字体 |
+| `fontSize` | 9–72 | 字号 |
+| `color` | string / `null` | 字体颜色；`null` 使用默认颜色 |
+| `bold` / `italic` / `underline` | boolean | 字形 |
+| `textAlign` | `"left"` / `"center"` / `"right"` | 标题水平对齐 |
+
+新建 Card 或 MetricChart 时，只要传入 `style`，就会补齐前端标题默认值：`color: null`、`bold: true`、`italic: false`、`underline: false`、`fontSize: 14`、`fontFamily: "sans-serif"`。
+
+`titleSetting` 对应前端 `settings.titleSetting`：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `backgroundColor` | string / `null` | 标题区域背景色 |
+| `height` | 0–100 的整数 | 标题区域高度，单位 px |
+| `showBgImage` / `showIcon` | boolean | 是否显示背景图/图标 |
+| `bgImage` / `icon` | image object / `null` | 图片配置 |
+| `topStrip` / `bottomStrip` | strip object / `null` | 顶部/底部边框 |
+
+图片对象包含 `url`、`sourceType` 和 `renderType`。`sourceType`：`1` 链接、`2` 上传、`3` 素材；`renderType`：`1` 原比例、`2` 铺满、`3` 自适应。边框对象包含 `enabled`、`backgroundColor` 和 `width`，其中 `width` 可用 `2`、`4`、`6`、`8`。
+
+`attachCard()` 只增量合并显式传入的字段。例如只修改字号和底部边框开关时，不会覆盖线上标题颜色、背景和其它边框字段。
+
+## 汇总指标
+
+### `setSummary(field, options?)`
+
+设置卡片底部/侧边的汇总指标。普通数据集 Card 传 `f()` / `field()`，指标平台 MetricChart 传 `metric()`：
+
+```javascript
+createCard(ChartType.PIVOT_TABLE, "区域销售")
+    .addRow(f("区域"))
+    .addMetric(f("销售额"))
+    .setSummary(f("销售额"), {
+        aggrType: AggrType.AVG,
+        label: "平均销售额",
+        position: "bottom",
+        format: NumberFormat.number(1)
+    });
+
+createMetricChart(ChartType.PIVOT_TABLE, "销售指标")
+    .addMetric(metric("销售额"))
+    .setSummary(metric("销售额"), {
+        label: "销售额汇总",
+        position: "right"
+    });
+```
+
+普通 Card 的 `options`：
+
+| 字段 | 说明 |
+|---|---|
+| `aggrType` | 指标字段支持 `SUM` / `MIN` / `MAX` / `AVG` / `CNT` / `CNT_DISTINCT`；维度支持 `CNT` / `CNT_DISTINCT` / `MIN` / `MAX` |
+| `label` | 汇总指标显示名称；默认使用字段显示名 |
+| `position` | `"top"` / `"bottom"` / `"left"` / `"right"`，默认 `"bottom"` |
+| `format` | NumberFormat 格式对象 |
+
+聚合计算字段固定使用 `aggrType: "NUL"`，不能再套一层聚合。MetricChart 的汇总直接引用指标 ID，只支持 `label` 和 `position`。
+
+传 `null` 可关闭汇总指标：
+
+```javascript
+.setSummary(null)
+```
+
+为兼容已有 MetricChart 脚本，`.setSummary({ summaryType, ... })` 原始对象签名仍可使用；新代码优先传字段对象。
+
+前端不提供汇总指标的图表包括：`SOLID_GAUGE`、`SINGLE_VALUE`、`PROGRESS_BAR`、`PROGRESS_PIE`、`KPI_CARD`、`LIQUID_GAUGE`、`ACTIVITY_GAUGE`、`KPI_TREND` 和 `DATA_GRID`。
+
+### `setSummaryStyle(config)`
+
+设置汇总指标名称和值的样式：
+
+```javascript
+.setSummaryStyle({
+    showLabel: true,
+    label: { fontSize: 12, color: "#646A73" },
+    value: { fontSize: 20, bold: true, color: "#1F2329" }
+})
+```
+
+`label` / `value` 支持 `fontFamily`、`fontSize`（12–72）、`color`、`bold`、`italic`、`underline`。新建卡片会补齐前端默认样式；`attachCard()` 只增量修改显式传入的字段。
+
+## 特殊值
+
+### `setSpecialValue(config)`
+
+把 `NULL` 等特殊值显示为指定文本。支持 `PIVOT_TABLE`、`GROUPED_TABLE`、`SINGLE_VALUE` 和 `KPI_CARD`。
+
+```javascript
+.setSpecialValue({ specialValue: "--" })
+```
+
+也可直接传字符串：
+
+```javascript
+.setSpecialValue("--")
+```
+
+透视表额外支持隐藏对比中的空值行/列：
+
+```javascript
+.setSpecialValue({
+    specialValue: "--",
+    hideEmptyCol: true,
+    hideEmptyRow: false
+})
+```
+
+`hideEmptyCol` 和 `hideEmptyRow` 仅用于 `PIVOT_TABLE`；`attachCard()` 未显式传入的特殊值配置保持不变。
+
+## 动态参数默认值
+
+### `setDynamicParameterDefaultValue(parameter, value, options?)`
+
+设置普通数据集 Card 的卡片级参数默认值。参数必须来自项目的 `dynamic-parameters.js`，优先用 `param(dpId)` 引用：
+
+```javascript
+.setDynamicParameterDefaultValue(
+    param("aaaaaaaaaaaaaaaaaaaaaaaa"),
+    ["华东", "华南"]
+)
+```
+
+`value` 为数组时会与前端一致地保存为逗号分隔字符串。设置默认值意味着使用卡片级覆盖，因此 `inheritParent` 默认是 `false`；需要继续继承数据集/全局参数时显式传：
+
+```javascript
+.setDynamicParameterDefaultValue(
+    param("aaaaaaaaaaaaaaaaaaaaaaaa"),
+    "全国",
+    { inheritParent: true }
+)
+```
+
+同一参数被多个计算字段引用时，会更新该 `dpId` 的全部卡片参数记录。卡片没有实际引用该参数时构建会报错，不会静默写入无效配置。`attachCard()` 使用相同 API，并保留其它参数记录和未修改字段。
+
+## 图例
+
+### `setShowLegend(show, position?)`
+
+设置图例的显隐和主位置。
+
+
+| 参数         | 类型        | 说明     |
+| ---------- | --------- | ------ |
+| `show`     | boolean   | 是否显示图例 |
+| `position` | string，可选 | 图例位置   |
+
+
+```javascript
+.setShowLegend(true, "right")
+```
+
+`position` 可使用 `"top"`、`"bottom"`、`"left"`、`"right"`。
+
+传入 `position` 时会清除原有的交叉方向对齐位置。
+
+### `setChartLegend(config)`
+
+设置完整的图例属性。
+
+```javascript
+.setChartLegend({
+    showLegend: true,
+    legendPosition: "right",
+    legendCrossPosition: "top",
+    fontFamily: "sans-serif",
+    fontSize: 12,
+    color: "#343D50",
+    bold: false,
+    customLegend: {
+        pagination: true
+    }
+})
+```
+
+
+| 字段                              | 类型/取值                                                    | 说明            |
+| ------------------------------- | -------------------------------------------------------- | ------------- |
+| `showLegend`                    | boolean                                                  | 是否显示图例        |
+| `legendPosition`                | `"top"` / `"bottom"` / `"left"` / `"right"`              | 图例主位置         |
+| `legendCrossPosition`           | `"center"` / `"top"` / `"bottom"` / `"left"` / `"right"` | 图例在交叉方向上的对齐位置 |
+| `fontFamily`                    | string                                                   | 图例字体          |
+| `fontSize`                      | 9–72                                                    | 图例字号          |
+| `color`                         | string                                                   | 图例文字颜色        |
+| `bold` / `italic` / `underline` | boolean                                                  | 图例字形          |
+| `customLegend`                  | object                                                   | 图例扩展展示配置      |
+
+
+设置 `legendPosition` 且未同时设置 `legendCrossPosition` 时，会重置原有的交叉方向对齐位置。
+
+`customLegend` 可包含：
+
+
+| 字段                | 类型      | 说明                  |
+| ----------------- | ------- | ------------------- |
+| `pagination`      | boolean | 图例是否单行展示            |
+| `showNumber`      | boolean | 饼图图例显示数值            |
+| `showPercentage`  | boolean | 饼图图例显示百分比           |
+| `autoAlignment`   | boolean | 饼图图例数值右对齐           |
+| `legendItemWidth` | number  | 数值右对齐时的图例条目宽度，单位 px |
+
+
+`showNumber`、`showPercentage`、`autoAlignment` 和 `legendItemWidth` 用于 `PIE`。饼图存在拆分字段，或颜色字段不是与分类字段相同的明细字段时，不应用这些配置。
+
+在支持图例配置的图表中，`BASIC_LINE`、`BASIC_BAR`、`BASIC_COLUMN`、`BULLET_BAR`、`BULLET_COLUMN`、`BUTTERFLY`、`WORLD_MAP` 和 `BASIC_MAP` 不支持 `pagination`；其它支持图例配置的图表可以使用。图例位于上方或下方时显示为单行。
+
+不适用于当前图表类型或字段布局的 `customLegend` 字段不会写入卡片；新建 Card 和 MetricChart 时同时产生 validation warning。
+
+图例及 `customLegend` 的未知字段、错误类型、非法位置和小于 `1` 的 `legendItemWidth` 会产生 validation error。
+
+## 数据标签
+
+主图形和叠加图形的数据标签支持以下公共字段：
+
+
+| 字段                              | 类型      | 说明                  |
+| ------------------------------- | ------- | ------------------- |
+| `show`                          | boolean | 当前图形的数据标签开关         |
+| `showSeries`                    | boolean | 显示系列名               |
+| `showCategory`                  | boolean | 显示分类/维度值            |
+| `showNumber`                    | boolean | 显示数值                |
+| `position`                      | string  | 标签位置，例如 `"outside"` |
+| `fontSize`                      | 9–72    | 标签字号                |
+| `color`                         | string  | 标签颜色，如 `"#343d50"`  |
+| `bold` / `italic` / `underline` | boolean | 标签字形                |
+| `separator`                     | string  | 多项标签内容之间的分隔符        |
+| `textOutline`                   | boolean | 是否显示文字描边            |
+| `allowOverlap`                  | boolean | 是否允许标签重叠            |
+
+
+`show` 控制当前方法对应的图形；不传 `show` 时，只修改显式传入的字段。
+
+标签位置由图表方向决定，可用值为 `"outside"`、`"top"`、`"middle"`、`"bottom"`、`"left"`、`"center"`、`"right"`，并非每种图表都支持全部值。
+
+`separator` 可使用 `"comma"`、`"colon"`、`"semicolon"`、`"period"`、`"linefeed"`、`"space"`。
+
+### `setDataLabel(config)`
+
+设置主图形数据标签。
+
+除公共字段外，主图形还支持：
+
+
+| 字段                  | 类型                    | 说明                |
+| ------------------- | --------------------- | ----------------- |
+| `showPercentage`    | boolean               | 显示百分比             |
+| `showSubPercentage` | boolean               | 显示子级百分比           |
+| `showTotal`         | boolean               | 显示总计              |
+| `showSubTotal`      | boolean               | 显示小计              |
+| `showConnector`     | boolean               | 饼图标签连接线，仅用于 `PIE` |
+| `precision`         | `"0"` / `"1"` / `"2"` | 百分比小数位数           |
+
+
+标签内容字段按图表类型生效：
+
+
+| 图表                                                                                     | 可配置的标签内容                                                                                                 |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `PIE`                                                                                  | `showConnector`、`showCategory`、`showNumber`、`showPercentage`                                             |
+| `STACKED_COLUMN`、`STACKED_COLUMN_WITH_LINE`、`STACKED_COLUMN_WITH_SYMBOL`、`STACKED_BAR` | `showSeries`、`showCategory`、`showNumber`、`showPercentage`、`showTotal`                                    |
+| `PERCENT_STACKED_COLUMN`、`PERCENT_STACKED_BAR`                                         | `showSeries`、`showCategory`、`showNumber`、`showPercentage`                                                |
+| `STACKED_SPLIT_COLUMN`、`STACKED_SPLIT_BAR`                                             | `showSeries`、`showCategory`、`showNumber`、`showPercentage`、`showSubPercentage`、`showTotal`、`showSubTotal` |
+| `BUTTERFLY`、`BASIC_BUBBLE`、`BASIC_SCATTER_PLOT`、`BASIC_MAP`、`WORLD_MAP`                | `showCategory`、`showNumber`                                                                              |
+| 其它支持的图表                                                                                | `showSeries`、`showCategory`、`showNumber`                                                                 |
+
+
+`precision` 用于支持 `showPercentage` 的图表。
+
+旭日图的样式字段为 `separator` 和 `allowOverlap`；`BASIC_MAP`、`WORLD_MAP`、`BUBBLE_MAP`、`POINT_MAP` 的样式字段为字体样式、`separator` 和 `allowOverlap`。
+
+调用 `{ show: true }` 时默认打开以下字段：
+
+
+| 图表                       | 默认打开字段                                          |
+| ------------------------ | ----------------------------------------------- |
+| `PIE`                    | `showConnector`、`showCategory`、`showPercentage` |
+| `RISING_SUN`             | `showCategory`                                  |
+| `BASIC_BUBBLE`           | `showCategory`                                  |
+| `PERCENT_STACKED_COLUMN` | `showPercentage`                                |
+| 其它支持的图表                  | `showNumber`                                    |
+
+`PIE` 和 `RISING_SUN` 开启数据标签时，未显式设置 `separator` 会使用 `"colon"`。
+
+
+```javascript
+.setDataLabel({
+    show: true,
+    showCategory: true,
+    showNumber: true,
+    separator: "colon",
+    position: "outside",
+    fontSize: 12,
+    color: "#343d50",
+    bold: true,
+    textOutline: true
+})
+```
+
+`show: false` 会关闭主图形中决定标签显隐的字段，同时保留位置、字体、分隔符等样式配置。
+
+数据标签的未知字段、非 boolean 显隐值、非法 `position` / `precision` / `separator` 和不合法的字体样式会产生 validation error。
+
+### `setMetricAdditionalDataLabel(config)`
+
+使用公共字段设置叠加图形数据标签。
+
+```javascript
+.setDataLabel({
+    show: true,
+    showNumber: true
+})
+.setMetricAdditionalDataLabel({
+    show: true,
+    showNumber: true,
+    position: "top"
+})
+```
+
+两个方法的开关相互独立。`setDataLabel({ show: false })` 只关闭主图形标签；`setMetricAdditionalDataLabel({ show: false })` 只关闭叠加图形标签。
+
+## 坐标轴
+
+### `setAxis(config)`
+
+设置类目轴、基数值轴、主轴、副轴和缩略轴。`config` 可包含：
+
+- `categoryAxis`：X 类目轴。
+- `baseAxis`：X 数值轴，用于散点图、气泡图等。
+- `mainAxis`：Y 主轴。
+- `secondaryAxis`：Y 副轴，通常配合 `.addMetricAdditional()`。
+- `navigator`：缩略轴。
+
+```javascript
+.setAxis({
+    categoryAxis: {
+        visible: true,
+        showTitle: true,
+        title: "月份",
+        autoRotate: 45,
+        labelFontSize: 12,
+        showAxisLine: true
+    },
+    baseAxis: {
+        visible: true,
+        min: 0,
+        max: 100
+    },
+    mainAxis: {
+        visible: true,
+        showTitle: true,
+        title: "销售额",
+        min: 0,
+        max: 100000,
+        autoExtremes: false,
+        showGridLine: true,
+        labelFontSize: 11,
+        format: NumberFormat.currency("¥", 0)
+    },
+    secondaryAxis: {
+        visible: true,
+        showTitle: true,
+        title: "利润率"
+    },
+    navigator: {
+        showNavigator: true,
+        fixedValueAxis: true,
+        fixedOnRight: false
+    }
+})
+```
+
+
+| 属性                                             | 适用轴   | 说明                                                                                    |
+| ---------------------------------------------- | ----- | ------------------------------------------------------------------------------------- |
+| `visible`                                      | 所有    | 是否显示轴                                                                                 |
+| `showTitle`                                    | 所有    | 是否显示轴标题                                                                               |
+| `title`                                        | 所有    | 轴标题文字                                                                                 |
+| `titleFontSize` / `titleColor`                 | 所有    | 标题字号、颜色                                                                               |
+| `titleBold` / `titleItalic` / `titleUnderline` | 所有    | 标题字形                                                                                  |
+| `titlePosition`                                | 所有    | `"outside"` 或 `"top"`；是否生效取决于图表                                                       |
+| `labelFontSize` / `labelColor`                 | 所有    | 刻度标签字号、颜色                                                                             |
+| `labelBold` / `labelItalic` / `labelUnderline` | 所有    | 刻度标签字形                                                                                |
+| `unit`                                         | 数值轴   | 单位文字                                                                                  |
+| `min` / `max`                                  | 数值轴   | 固定轴范围                                                                                 |
+| `autoExtremes`                                 | 数值轴   | 是否自动计算范围                                                                              |
+| `showGridLine`                                 | 数值轴   | 是否显示网格线                                                                               |
+| `gridLineStyle`                                | 数值轴   | `{ lineType, lineWidth, lineColor }`；`lineType` 为 `"solid"` / `"dashed"` / `"dotted"` |
+| `reverseValue`                                 | 数值轴   | 是否反转轴方向                                                                               |
+| `tickInterval` / `autoTickInterval`            | 数值轴   | 刻度间隔及是否自动计算                                                                           |
+| `format`                                       | 数值轴   | NumberFormat 数值格式对象                                                                   |
+| `unifyAxisRange`                               | 主轴/副轴 | 自动统一双 Y 轴范围                                                                           |
+| `autoRotate`                                   | 类目轴   | 标签旋转角度，范围 `-90` 到 `90`                                                                |
+| `textLength`                                   | 类目轴   | 标签截断长度                                                                                |
+| `step`                                         | 类目轴   | 标签显示间隔                                                                                |
+| `isFixTop`                                     | 类目轴   | 将类目轴固定在顶部；仅部分图表生效                                                                     |
+| `showAxisLine`                                 | 类目轴   | 是否显示轴线                                                                                |
+| `axisLineStyle`                                | 类目轴   | `{ lineType, lineWidth, lineColor }`                                                  |
+| `showNavigator`                                | 缩略轴   | 是否显示缩略轴                                                                               |
+| `fixedValueAxis`                               | 缩略轴   | 是否固定数值轴范围                                                                             |
+| `fixedOnRight`                                 | 缩略轴   | 是否固定在右侧                                                                               |
+
+各轴会按图表结构校验：
+
+- `baseAxis` 只用于 `BASIC_SCATTER_PLOT` 和 `BASIC_BUBBLE`；这两类图表不使用 `categoryAxis`。
+- `secondaryAxis` 需要图表存在副轴；组合图还需要副轴数据区中存在字段。
+- `BOX_PLOT`、`RADAR_LINE` 和 `BUTTERFLY` 不使用 `navigator`。
+
+坐标轴会校验顶层和各轴的字段名、字段类型及前端范围，包括字号 `9`–`72`、`autoRotate` 的 `-90`–`90`、大于等于 `1` 的 `textLength` / `step`、正数 `tickInterval`，以及 `min <= max`。轴线和网格线宽度为 `1`–`5`，线型为 `solid`、`dashed` 或 `dotted`。
+
+`format` 可包含：
+
+
+| 字段                    | 类型      | 说明                              |
+| --------------------- | ------- | ------------------------------- |
+| `formatType`          | string  | `"NUMBER"`、`"CURRENCY"`、`"PERCENTAGE"` 或 `"ADVANCED"` |
+| `decimalPlaces`       | number / null | 小数位数；`NUMBER` 省略时使用自动精度，`CURRENCY` 和 `PERCENTAGE` 省略时默认为 `2` |
+| `useThousandsSeparator` | boolean | 是否使用千分位；`NUMBER` 和 `CURRENCY` 省略时默认为 `true` |
+| `prefixUnit`          | string  | 缩放单位，如 `"K"`、`"M"`、`"万"`、`"亿"` 或 `"auto"` |
+| `showPrefixUnit`      | boolean | 是否显示缩放单位                        |
+| `currencySymbol`      | string  | 货币符号                            |
+| `prefix` / `suffix`   | string  | 前缀和后缀                           |
+| `customFormat`        | string  | 高级数值格式表达式                       |
+| `divideDataBy`        | number  | 数值缩放除数                          |
+| `suffixSizePercent`   | number  | 后缀字号比例                          |
+
+
+优先使用 `NumberFormat.number()`、`NumberFormat.currency()`、`NumberFormat.percentage()` 和 `NumberFormat.auto()` 构造 `format`。构建 payload 时会把 `format` 转换为图表渲染使用的 `formatDefn`；如显式提供 `formatDefn`，则使用传入值。
+
+## 工具提示
+
+### `setTooltip(config)`
+
+设置工具提示的显隐、内容和样式。
+
+```javascript
+.setTooltip({ enabled: false })
+```
+
+
+| 字段                           | 类型                     | 说明                       |
+| ---------------------------- | ---------------------- | ------------------------ |
+| `enabled`                    | boolean                | 是否启用原生图表 Tooltip         |
+| `maxNumber`                  | number                 | 最大显示条目数，默认 `20`、最小 `1`   |
+| `onlyTooltipSeries`          | boolean                | 只展示显式放入 Tooltip zone 的字段 |
+| `hideTooltipColor`           | boolean                | 隐藏系列颜色标记；部分图表不支持         |
+| `hideTooltipTotal`           | boolean                | 隐藏 Tooltip 总计；仅支持总计的图表生效 |
+| `order`                      | `"metric"` / `"value"` | 按指标顺序或数值大小排序             |
+| `showNumber`                 | boolean                | 饼图 Tooltip 是否显示数值        |
+| `style.title` / `style.body` | object                 | 标题、正文的字体样式对象             |
+| `style.backgroundColor`      | string                 | Tooltip 背景色              |
+
+传入的字段会按图表类型校验，只写入该图表可配置的 Tooltip 属性。
+
+字体样式对象可包含 `fontFamily`、`fontSize`（9–72）、`color`、`bold`、`italic`、`underline`。新建时的默认值为：
+
+```javascript
+{
+    enabled: true,
+    maxNumber: 20,
+    onlyTooltipSeries: false,
+    hideTooltipColor: false,
+    hideTooltipTotal: false
+}
+```
+
+Tooltip 展示哪些数据字段由 `.addTooltip(field)` 控制；`setTooltip()` 只控制 Tooltip 属性，两者不要混淆。
+
+原生 Card Tooltip 不是 ECharts option。不要把自定义 ECharts 中的 `trigger: "axis"`、`formatter` 等字段传给 `setTooltip()`。
+
+## 饼图
+
+### `setPieSetting(config)`
+
+设置饼图和环图的展示方式。
+
+
+| 字段              | 类型      | 说明                                     |
+| --------------- | ------- | -------------------------------------- |
+| `showAsRing`    | boolean | 是否显示为环图                                |
+| `innerSize`     | number  | 环图空心占比，范围 `0` 到 `100`；不是 `innerRadius` |
+| `mergeOther`    | boolean | 是否合并小分类为“其它”                           |
+| `mergeSize`     | number  | 保留的维度数量，非负整数；其余合并为“其它”                 |
+| `mergeColor`    | string  | “其它”的颜色                                |
+| `size`          | number  | 自定义饼图直径占比，范围 `0` 到 `100`               |
+| `centerDisplay` | boolean | 是否启用中心区域展示能力                           |
+
+
+设置 `showAsRing` 时，如果没有提供有效的 `innerSize`，会使用默认空心占比 `70`。
+
+```javascript
+.setPieSetting({
+    showAsRing: true,
+    innerSize: 40,
+    mergeOther: true,
+    mergeSize: 5,
+    mergeColor: "#E9ECF1",
+    size: 75
+})
+```
+
+### `setPieCenterText(config)`
+
+设置饼图中心文本。
+
+```javascript
+.setPieCenterText({
+    showCenterText: true,
+    valueType: "percent",
+    valueFont: {
+        fontSize: 16,
+        bold: true
+    },
+    textFont: {
+        fontSize: 12,
+        color: "#646A73"
+    }
+})
+```
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `showCenterText` | boolean | 是否显示中心文本 |
+| `valueType` | `"percent"` / `"number"` | 中心值显示百分比或数值 |
+| `valueFont` | object | 中心值字体样式 |
+| `textFont` | object | 中心说明文字字体样式 |
+
+`valueFont` 和 `textFont` 可包含 `fontFamily`、`fontSize`（9–72）、`color`、`bold`、`italic`、`underline`。首次开启时会补齐中心值字号 `16` 和加粗样式；饼图包含多个指标时会关闭中心文本。
+
+## 表格
+
+### `setTableSetting(config)`
+
+设置表格的分页、对齐、换行、序号和分组展示。
+
+
+| 字段                              | 类型                   | 说明                                                                                        |
+| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
+| `pagination`                    | boolean              | 是否分页                                                                                      |
+| `pageSize`                      | number               | 每页行数；可选 `10` / `20` / `50` / `100` / `200`                                                |
+| `autoAlignment`                 | boolean              | 横向自动对齐                                                                                    |
+| `vAlign`                        | `"MIDDLE"` / `"TOP"` | 垂直居中或向上对齐                                                                                 |
+| `textWrap`                      | boolean              | `true` 自动换行，`false` 截断                                                                    |
+| `showHeaderSortingIcon`         | boolean              | 是否显示表头排序图标                                                                                |
+| `fixedHeaderInfo`               | object               | 固定表头；可包含 `{ X: boolean, Y: boolean }`                                                     |
+| `showLineNumber`                | boolean              | 是否显示行序号                                                                                   |
+| `accumulatedLineNumber`         | boolean              | 分页时连续累加编号                                                                                 |
+| `skipTotalRow`                  | boolean              | 行序号排除总计/小计；与连续累加编号互斥                                                                      |
+
+透视表还支持：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `lineNumberTitle` | string | 序号列标题 |
+| `lineNumberType` | string | `"basic"` / `"num"` / `"circle"` / `"flag"` / `"medal"` / `"card"` / `"fire"` / `"crown"` |
+| `lineNumberStyle` | object | 序号字体样式 |
+
+分组表还支持：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `treeDisplay` | boolean | 使用树形展示 |
+| `treeDisplayName` | string | 树形列名称 |
+| `isAutoShrinkGroupedTable` | boolean | 平铺展示无数据时隐藏列 |
+| `isDefaultExpandedGroupedTable` | boolean | 是否默认全部展开 |
+| `defaultExpandCols` | number | 默认展开列数 |
+
+
+表格属性会按以下规则同步关联字段：
+
+- `pagination: false` 会同时设置 `accumulatedLineNumber: false`。
+- `showLineNumber: false` 会同时设置 `skipTotalRow: false`。
+- `skipTotalRow: true` 与 `accumulatedLineNumber: true` 互斥，开启其中一项会关闭另一项。
+- `isDefaultExpandedGroupedTable: true` 会同时设置 `defaultExpandCols: 0`；设置大于 `0` 的 `defaultExpandCols` 会关闭默认全部展开。
+- `treeDisplay: true` 会把列总计位置设置为 `TOP`。
+
+`lineNumberStyle` 可包含 `fontFamily`、`fontSize`、`color`、`bold`、`italic`、`underline`、`strikeThrough`。
+
+```javascript
+.setTableSetting({
+    pagination: true,
+    pageSize: 20,
+    textWrap: true,
+    showLineNumber: true,
+    lineNumberTitle: "序号",
+    lineNumberType: "num"
+})
+```
+
+指标平台分组表示例：
+
+```javascript
+.setTableSetting({
+    fixedHeaderInfo: { X: false },
+    isDefaultExpandedGroupedTable: true,
+    defaultExpandCols: 0
+})
+```
+
+### `setTableCellMerge(config)`
+
+设置透视表单元格合并。
+
+```javascript
+.setTableCellMerge({
+    noMergeColumn: true,
+    noMergeRow: false
+})
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `noMergeColumn` | boolean | 是否不合并列区域的相同单元格 |
+| `noMergeRow` | boolean | 是否不合并行区域的相同单元格 |
+
+### `setGrandTotal(config)`
+
+设置整表总计及其样式。
+
+```javascript
+.setGrandTotal({
+    rowTotal: {
+        show: true,
+        position: GrandTotalPosition.RIGHT
+    },
+    columnTotal: {
+        show: true,
+        position: GrandTotalPosition.BOTTOM
+    },
+    subtotalStyle: {
+        alias: "小计",
+        showDetail: true,
+        fillColor: "#F5F7FA"
+    },
+    grandTotalStyle: {
+        alias: "总计",
+        bold: true
+    }
+})
+```
+
+
+| 字段                                                                | 类型/取值                               | 说明                                    |
+| ----------------------------------------------------------------- | ----------------------------------- | ------------------------------------- |
+| `rowTotal.show`                                                   | boolean                             | 显示横向的行总计                              |
+| `rowTotal.position`                                               | `GrandTotalPosition.LEFT` / `RIGHT` | 行总计位置；新建卡片只传 `show: true` 时默认 `RIGHT` |
+| `columnTotal.show`                                                | boolean                             | 显示纵向的列总计                              |
+| `columnTotal.position`                                            | `GrandTotalPosition.TOP` / `BOTTOM` | 列总计位置；新建透视表默认 `BOTTOM`，分组表默认 `TOP`    |
+| `subtotalStyle.alias`                                             | string                              | 小计别名                                  |
+| `subtotalStyle.showDetail`                                        | boolean                             | 是否显示为“小计（维度）”                         |
+| `subtotalStyle.fillColor`                                         | string                              | 小计填充色                                 |
+| `subtotalStyle.fontFamily` / `fontSize` / `color`                 | string / number / string            | 小计字体、字号和文字颜色                          |
+| `subtotalStyle.bold` / `italic` / `underline` / `strikeThrough`   | boolean                             | 小计字形                                  |
+| `grandTotalStyle.alias`                                           | string                              | 总计别名                                  |
+| `grandTotalStyle.fillColor`                                       | string                              | 总计填充色                                 |
+| `grandTotalStyle.fontFamily` / `fontSize` / `color`               | string / number / string            | 总计字体、字号和文字颜色                          |
+| `grandTotalStyle.bold` / `italic` / `underline` / `strikeThrough` | boolean                             | 总计字形                                  |
+
+
+AttachedCard 只修改显式传入的 `show`、`position` 和样式字段。例如只关闭列总计：
+
+```javascript
+attachCard(CARD_ID, BASE_PATH)
+    .setGrandTotal({ columnTotal: { show: false } });
+```
+
+开启行总计需要表格存在列字段，开启列总计需要表格存在行字段。
+
+字段级小计示例：
+
+```javascript
+createCard(ChartType.PIVOT_TABLE, "区域销售")
+    .addRow(f("区域", { hasSubTotal: true }))
+    .addMetric(f("销售额", {
+        aggrType: AggrType.SUM,
+        subtotalSetting: {
+            isDisplayed: true,
+            isAggrDsBased: true,
+            aggrType: "SUM"
+        }
+    }));
+
+createMetricChart(ChartType.GROUPED_TABLE, "指标表")
+    .addRow(metricDim("销售额", "区域", {
+        subtotalSetting: { isDisplayed: true }
+    }))
+    .addMetric(metric("销售额", {
+        subtotalSetting: {
+            isDisplayed: true,
+            isAggrDsBased: true,
+            aggrType: "SUM"
+        }
+    }));
+```
+
+修改已有卡片时使用字段 patch，不要整体替换 zone：
+
+```javascript
+attachCard(CARD_ID, BASE_PATH)
+    .updateRow("区域", { hasSubTotal: false })
+    .updateMetric("销售额", {
+        subtotalSetting: { isDisplayed: false }
+    });
+```
+
+`subtotalSetting.aggrType` 可使用 `"SUM"`、`"AVG"`、`"MAX"`、`"MIN"`。
+
+## 折线图
+
+### `setLineSetting(config)`
+
+设置折线图和面积图的线条、数据点与区域填充：
+
+```javascript
+.setLineSetting({
+    skipNulls: true,
+    showArea: true,
+    colorType: "gradient",
+    opacity: 60,
+    showPoint: true,
+    pointShape: "ring",
+    pointSize: 6,
+    showAsSpline: true,
+    lineStyle: "Solid_2"
+})
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `skipNulls` | boolean | 是否在空值处断开 |
+| `showArea` | boolean | 是否显示折线下方的区域填充 |
+| `colorType` | `"solid"` / `"gradient"` | 区域填充方式 |
+| `opacity` | number | 区域填充透明度，范围 `0`～`100` |
+| `showPoint` | boolean | 是否显示数据点 |
+| `pointShape` | `"default"` / `"dot"` / `"ring"` | 混合图形、实心圆或空心圆 |
+| `pointSize` | `5` / `6` / `8` | 数据点大小 |
+| `showAsSpline` | boolean | 是否显示为曲线 |
+| `lineStyle` | `"Solid_1"` / `"Solid_2"` / `"Solid_3"` / `"Dash_2"` | 细实线、中实线、粗实线或虚线 |
+| `secondSetting` | object | 多折线图次数值轴的折线显示配置，字段与主配置相同 |
+
+多折线图可以分别设置主数值轴和次数值轴：
+
+```javascript
+.setLineSetting({
+    lineStyle: "Solid_2",
+    secondSetting: {
+        showPoint: false,
+        lineStyle: "Dash_2"
+    }
+})
+```
+
+堆积面积图和百分比堆积面积图使用 `skipNulls`、`opacity`、`showPoint`、`pointShape`、`pointSize`、`showAsSpline` 和 `lineStyle`。
+
+## 图形填充
+
+### `setShapeColorType(type)`
+
+设置柱形、条形等图形的填充方式。
+
+```javascript
+.setShapeColorType(ShapeColorType.TransparentGradient)
+```
+
+
+| 枚举                                   | 后端值                      | 说明   |
+| ------------------------------------ | ------------------------ | ---- |
+| `ShapeColorType.Solid`               | `"solid"`                | 纯色   |
+| `ShapeColorType.TransparentGradient` | `"transparent_gradient"` | 透明渐变 |
+| `ShapeColorType.ColorGradient`       | `"color_gradient"`       | 彩色渐变 |
+
+
+它与 `.addColorBy()` / `.setColorByColors()` 的按指标值渐变着色不是同一能力。
+
+## 拆分图
+
+### `setSplitSetting(config)`
+
+设置拆分图的布局、标签和工具提示，必须配合 `.addSplit(field)`：
+
+```javascript
+.addSplit(f("区域"))
+.setSplitSetting({
+    rows: 2,
+    columns: 3,
+    syncY: true,
+    isolatedChartTooltip: true,
+    titleFormat: {
+        fontFamily: "sans-serif",
+        fontSize: 12,
+        color: "#343D50",
+        bold: false
+    }
+})
+```
+
+
+| 字段                     | 类型      | 说明                    |
+| ---------------------- | ------- | --------------------- |
+| `rows`                 | number  | 拆分布局行数，最小为 `1`          |
+| `columns`              | number  | 拆分布局列数，最小为 `1`          |
+| `splitRows`            | number  | 拆分布局行数，与 `rows` 等价，最小为 `1` |
+| `splitColumns`         | number  | 拆分布局列数，与 `columns` 等价，最小为 `1` |
+| `syncY`                | boolean | 是否统一拆分图的数值轴范围         |
+| `isolatedChartTooltip` | boolean | Tooltip 是否只显示当前拆分图的数据 |
+| `titleFormat`          | object  | 拆分标签字体样式              |
+
+
+`titleFormat` 可包含 `fontFamily`、`fontSize`、`color`、`bold`、`italic`、`underline`。不调用时默认 3 行 3 列。主轴或副轴同时设置固定最小值和最大值时，`syncY` 会设为 `true`。
+
+`syncY` 和 `isolatedChartTooltip` 必须是 boolean；`titleFormat` 使用公共字体样式校验。`rows` 与 `splitRows`、`columns` 与 `splitColumns` 同时传入时必须相等。没有调用 `.addSplit()` 时，构建会提示该配置不生效。
+
+## 辅助线
+
+### `setAuxiliaryLine(config)`
+
+设置数值轴辅助线和分组累计线：
+
+```javascript
+.setAuxiliaryLine({
+    mainAxis: [
+        { name: "目标线", color: "#FF0000", valueType: "FIXED", fixedValue: "50000" },
+        {
+            name: "销售额平均值",
+            color: "#0088FF",
+            valueType: "CALCULATED",
+            field: chartField("metric", 0),
+            calculatedValue: "AVG"
+        }
+    ],
+    secondaryAxis: [
+        { name: "基准线", color: "#00AA00", valueType: "FIXED", fixedValue: "0.3" }
+    ],
+    baseAxis: [
+        { name: "X 轴基准线", color: "#8B5CF6", valueType: "FIXED", fixedValue: "50" }
+    ],
+    groupTotal: {
+        show: true,
+        color: "#FF0000"
+    }
+})
+```
+
+
+顶层配置：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `mainAxis` | array | 主数值轴辅助线数组 |
+| `secondaryAxis` | array | 次数值轴辅助线数组 |
+| `baseAxis` | array | 基数值轴辅助线数组 |
+| `groupTotal` | object | 分组累计线配置 |
+
+`mainAxis`、`secondaryAxis` 和 `baseAxis` 数组中的辅助线项：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `name` | string | 辅助线名称，不能为空 |
+| `color` | string | 颜色，如 `"#FF0000"` |
+| `valueType` | `"FIXED"` / `"CALCULATED"` | 固定值辅助线或计算辅助线 |
+| `fixedValue` | number / string | 固定值，可传数字或数字字符串 |
+| `field` | object | 计算辅助线引用的图表字段，使用 `chartField(zone, index)` |
+| `calculatedValue` | string | 计算方式 |
+| `params` | array | 仅 `calculatedValue: "PERCENTILE"` 使用。第一个元素表示百分位比例，范围为 `0`～`1`；例如 `["0.9"]` 表示第 90 百分位，不传时使用 `["0.5"]` |
+
+`groupTotal` 用于分组、堆积和拆分堆积柱/条图：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `show` | boolean | 是否显示分组累计线 |
+| `color` | string | 分组累计线颜色，如 `"#FF0000"` |
+
+`chartField(zone, index)` 按最终数据区引用字段，`zone` 可使用 `"metric"` 或 `"metricAdditional"`，`index` 从 `0` 开始。构建时会自动写入字段的 `key`、ID、名称和类型；不要手写图表字段 key。
+
+辅助线顶层和数组项中的未知字段会产生 validation error；显式传入的 `color` 必须是非空字符串。
+
+图表字段的 `calculatedValue` 可使用 `"AVG"`、`"MED"`、`"PERCENTILE"`、`"MAX"`、`"MIN"`。
+
+普通 Card 还可以引用不在图表数据区中的数据集字段，此时直接提供 `fdId`、`fdName`、`fdType` 和 `chartFd: false`；计算方式可使用 `"AVG"`、`"MAX"`、`"MIN"`、`"SUM"`、`"CNT"`、`"CNT_DISTINCT"`、`"NUL"`。
+
+`valueType: "FIXED"` 会移除计算字段、聚合方式和参数；`valueType: "CALCULATED"` 会移除 `fixedValue`。AttachedCard 删除字段或改变字段所在数值轴后，会清理失效的计算辅助线。
+
+## 主题色
+
+编写 `setThemeColor()` 配置前，先检查项目根目录的 `theme-colors.js`。文件不存在时先生成快照：
+
+```bash
+guanvis theme-color sync -d <project>
+```
+
+`theme-colors.js` 是只读快照，项目内的多个页面和子目录共同使用这一份。从快照中选择真实 `tcId` 后，再编写 `setThemeColor(tcId)`；不要猜测或编造 `tcId`。主题色列表变化或切换 BI 环境后，重新执行 `theme-color sync`；快照会按实际选中的 profile、服务地址和 domain 校验当前环境，不一致时构建会提示刷新。
+
+`preview`、`diff`、`pack` 和 `publish` 会在快照缺失时自动生成，作为构建兜底。这个兜底不能替代配置前读取快照，因为编写 `setThemeColor(tcId)` 时已经需要确定可用的 `tcId`。
+
+也可以直接查看当前环境的主题色列表：
+
+```bash
+guanvis theme-color list -f json
+```
+
+### `setThemeColor(tcId, colors?, options?)`
+
+切换主题色、修改颜色覆盖或选择分类/顺序色板：
+
+```javascript
+.setThemeColor("<tcId>", [null, "#FF0000"], {
+    useSequentialPalette: true
+})
+```
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `tcId` | string / `null` | 非空字符串表示切换到快照中的指定主题；`null` 表示保留当前主题，当前没有主题时使用默认主题 |
+| `colors` | (string \| null)[] / `null`，可选 | 按位置设置颜色覆盖；字符串覆盖对应颜色，数组元素 `null` 使用色板原值；省略或传 `null` 时不修改，空数组清除全部覆盖 |
+| `options` | object / `null`，可选 | 色板模式配置；省略或传 `null` 时不显式修改 |
+
+`options` 支持以下属性：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `useSequentialPalette` | boolean / `null` | `true` 使用顺序色板，`false` 使用分类色板；传 `null` 时不显式修改 |
+
+只切换主题或同时修改颜色：
+
+```javascript
+.setThemeColor("<tcId>")
+.setThemeColor("<tcId>", [null, "#FF0000"])
+```
+
+只修改当前主题的颜色覆盖或色板模式时，`tcId` 传 `null`：
+
+```javascript
+.setThemeColor(null, [null, null, "rgba(230, 18, 47, 1)"])
+
+.setThemeColor(null, null, {
+    useSequentialPalette: false
+})
+```
+
+非空 `tcId` 必须使用主题色列表中的真实 ID。切换主题时会同步更新 `tcId`、`theme` 和色板模式；未显式传 `useSequentialPalette` 时，漏斗图在主题提供顺序色板时默认使用顺序色板，否则使用分类色板；其他图表默认使用分类色板。
+
+已有颜色覆盖会按位置保留，并根据最终所选色板的颜色槽数量补 `null` 或截断。显式传空 `colors` 数组会清除颜色覆盖。`useSequentialPalette: true` 只允许用于开启了顺序色板且包含顺序色板颜色的主题，否则产生 validation error。