@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,2101 @@
+# 图表属性配置
+
+介绍图表属性配置的用法和参数。
+
+调用属性方法时会按实际支持范围校验图表类型；不支持的调用会产生 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: true,
+        bgImage: {
+            uploadPath: "./assets/title-background.png",
+            renderType: ImageRenderType.STRETCH
+        },
+        showIcon: true,
+        icon: {
+            uploadPath: "./assets/title-icon.png"
+        },
+        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` | 图片配置；`null` 清除对应图片 |
+| `topStrip` / `bottomStrip` | strip object / `null` | 顶部/底部边框 |
+
+图片对象支持：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `url` | string | 外链、当前环境已有的上传图片地址或素材地址 |
+| `uploadPath` | string | 本地图片路径；没有 `url` 时生效，`pack`/`publish` 时作为 Card 附件上传 |
+| `sourceType` | `1` / `2` / `3` | 链接、上传或素材；使用 `uploadPath` 时固定为 `2`，不必传入 |
+| `renderType` | `1` / `2` / `3` | 原比例、铺满或自适应；本地图片省略时默认自适应 |
+
+本地标题背景图和 icon 支持 `jpg/jpeg/png/gif`，相对路径以 guanvis 工程目录为基准；`url` 和
+`uploadPath` 同时设置时优先使用 `url`，并产生 warning。边框对象包含 `enabled`、`backgroundColor`
+和 `width`，其中 `width` 可用 `2`、`4`、`6`、`8`。
+
+`attachCard()` 只增量合并显式传入的字段。例如只修改字号和底部边框开关时，不会覆盖线上标题颜色、背景和其它边框字段。
+
+## 图标
+
+### 获取可用图标
+
+可用图标来自当前 BI 环境的 `/api/icon-group/list`，不要猜测图标组或图标 ID。执行：
+
+```bash
+guanvis icon list
+guanvis icon list --group default_line -f json
+```
+
+输出中的 `GROUP_ID` 是图标组 ID，`ICON_IDS` 是该组可用的图标 ID。内置组通常包括
+`default_line`、`default_fill`、`default_combination`、`default_square` 和
+`default_portal`，但图标 ID、隐藏状态和租户自定义组必须以目标环境的查询结果为准。
+该命令用于获取全部可用图标，不限定具体图表类型。
+
+### 系统图标引用
+
+图表属性引用 BI 系统图标时，使用下列字段：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `groupId` | 非空字符串 | 系统图标组 ID，必须来自 `guanvis icon list` 的查询结果 |
+| `iconId` | 非空字符串 | 系统图标 ID，必须属于所选 `groupId` |
+| `colors` | `{ primary?, secondary?, tertiary? }` | 系统图标的颜色配置，每项为 string / `null` |
+
+只有 `groupId`、`iconId` 和 `colors` 与 BI 系统中的图标资源相关。图标的开关、大小、
+位置、对齐和间距属于具体图表的展示配置，分别在对应图表 API 中说明。图标引用不负责
+上传图标、创建素材或管理前端图标库。
+
+## 指标与进度
+
+本节说明指标类图表的专属属性。各 API 的适用图表和配置范围见对应小节；
+`attachCard()` 只深度合并显式传入的字段。
+
+### 共用文字样式
+
+下文的 `value`、`style`、`nameStyle` 和 `text` 文字样式对象使用相同字段：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `fontFamily` | 非空字符串 | 字体 |
+| `fontSize` | number / `null` | 指标卡为 `null`（自动）或 `9`～`1638`；对比指标卡为 `9`～`1638`；进度类为 `9`～`72`；多环进度图为 `12`～`72` |
+| `color` | string / `null` | 文字颜色；`null` 恢复主题默认色 |
+| `bold` / `italic` / `underline` | boolean | 加粗、斜体和下划线 |
+| `strikeThrough` | boolean | 删除线；只用于指标卡和对比指标卡 |
+
+### `setSingleValueSetting(config)`
+
+设置指标卡 `SINGLE_VALUE` 的对齐、数值、标签和图标：
+
+```javascript
+.setSingleValueSetting({
+    alignment: "center",
+    value: { fontSize: null, bold: true, color: "#1F2329" },
+    label: {
+        show: true,
+        style: { fontSize: 14, color: "#646A73" },
+        position: "mt",
+        alignment: "center",
+        maxWidth: 180
+    },
+    icon: {
+        show: true,
+        groupId: "default_line",
+        iconId: "bar_chart",
+        size: null,
+        position: "left",
+        alignment: "center",
+        margin: 10
+    }
+})
+```
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `alignment` | `"left"` / `"center"` / `"right"` | 整个指标卡对齐方式 |
+| `value` | 文字样式 | 数值样式 |
+| `label.show` | boolean | 是否显示标签 |
+| `label.style` | 文字样式 | 标签样式 |
+| `label.position` | `"mt"` / `"ml"` | 标签位于数值上方/左侧 |
+| `label.alignment` | `"left"` / `"center"` / `"right"` | 标签与数值的对齐方式 |
+| `label.maxWidth` | 0～999 的整数 | 标签最大宽度，单位 px |
+| `icon.show` | boolean | 是否显示指标装饰图标 |
+| `icon.groupId` | 非空字符串 | 系统图标组 ID，参考「图标」章节 |
+| `icon.iconId` | 非空字符串 | 系统图标 ID，参考「图标」章节 |
+| `icon.colors` | `{ primary?, secondary?, tertiary? }` | 系统图标颜色，参考「图标」章节 |
+| `icon.size` | `null` 或 9～1638 的整数 | 图标大小；`null` 表示自动 |
+| `icon.position` | `"tagLeft"` / `"left"` / `"top"` | 标签左侧、指标左侧或指标上方 |
+| `icon.alignment` | `"left"` / `"center"` / `"right"` / `"top"` / `"bottom"` | 图标与指标的对齐方式 |
+| `icon.margin` | 4～999 的整数 | 图标与指标间距，单位 px |
+
+`value.fontSize: null` 和 `label.style.fontSize: null` 表示字号自动。
+
+当 `icon.show: true` 时，最终 payload 会包含完整的基础图标配置：`show`、`groupId`、
+`iconId`、`size`、`position` 和 `margin`。新建指标卡缺少这些字段时默认补齐
+`default_line / bar_chart / null（自动） / left / 10`；`attachCard()` 优先保留线上已有的
+图标选择和颜色，只补齐缺失的基础字段。
+
+### `setKPISetting(config)`
+
+设置对比指标卡 `KPI_CARD` 的布局、主指标和对比指标：
+
+```javascript
+.setKPISetting({
+    layout: {
+        preset: "classic",
+        alignment: "left",
+        divider: { show: true, color: "#D0D3D6" }
+    },
+    main: {
+        value: { fontSize: 32, bold: true },
+        label: { show: true, style: { fontSize: 12 }, position: "ml" },
+        icon: { show: true, groupId: "default_line", iconId: "bar_chart" }
+    },
+    compare: {
+        value: { fontSize: 14 },
+        label: { style: { fontSize: 12 }, position: "cl" },
+        maxPerLine: 1,
+        iconStyle: "positiveGreenStyle1",
+        iconShowMap: { 0: false }
+    }
+})
+```
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `layout.preset` | `"classic"` / `"style1"`～`"style6"` | 快捷布局；同时设置主指标和对比指标的布局默认组合 |
+| `layout.alignment` | `"left"` / `"center"` / `"right"` | 整个指标块对齐方式 |
+| `layout.divider.show` | boolean | 是否显示分割线 |
+| `layout.divider.color` | string / `null` | 分割线颜色；`null` 恢复默认色 |
+| `main.value` | 文字样式 | 主指标数值 |
+| `main.label.show` | boolean | 是否显示主指标标签 |
+| `main.label.style` | 文字样式 | 主指标标签 |
+| `main.label.position` | `"mt"` / `"ml"` | 主标签位于数值上方/左侧 |
+| `main.label.alignment` | `"left"` / `"center"` / `"right"` | 主标签与数值对齐 |
+| `main.label.valueAlign` | `"follow"` / `"right"` / `"both_ends"` | 主标签与数值分布；允许在任意快捷布局中保存，具体生效条件见下表 |
+| `main.label.maxWidth` | 0～999 的整数 | 主标签最大宽度，单位 px |
+| `main.label.valueMargin` | 4～100 的整数 | 主标签与数值间距，单位 px |
+| `main.icon.show` | boolean | 是否显示主指标装饰图标 |
+| `main.icon.groupId` | 非空字符串 | 系统图标组 ID，参考「图标」章节 |
+| `main.icon.iconId` | 非空字符串 | 系统图标 ID，参考「图标」章节 |
+| `main.icon.colors` | `{ primary?, secondary?, tertiary? }` | 系统图标颜色，参考「图标」章节 |
+| `main.icon.size` | 9～1638 的整数 | 图标大小 |
+| `main.icon.position` | `"tagLeft"` / `"left"` / `"top"` | 标签左侧、指标左侧或指标上方 |
+| `main.icon.alignment` | `"left"` / `"center"` / `"right"` / `"top"` / `"bottom"` | 图标与指标的对齐方式 |
+| `main.icon.margin` | 4～999 的整数 | 图标与指标间距，单位 px |
+| `compare.value` | 文字样式 | 对比指标数值 |
+| `compare.label.style` | 文字样式 | 对比指标标签 |
+| `compare.label.position` | `"ct"` / `"cl"` | 对比标签位于数值上方/左侧 |
+| `compare.label.alignment` | `"left"` / `"center"` / `"right"` | 对比标签与数值对齐 |
+| `compare.label.valueAlign` | `"follow"` / `"right"` / `"both_ends"` | 对比标签与数值分布；允许保存，渲染效果受标签位置、布局结构和 `maxPerLine` 影响 |
+| `compare.label.maxWidth` | 0～999 的整数 | 对比标签最大宽度，单位 px |
+| `compare.label.valueMargin` | 4～100 的整数 | 对比标签与数值间距，单位 px |
+| `compare.maxPerLine` | 大于等于 1 的整数 | 对比指标每行最多显示几个 |
+| `compare.iconStyle` | `positiveRed` / `positiveGreen` / `positiveRedStyle1` / `positiveGreenStyle1` / `displayNull` | 涨跌图标样式；`displayNull` 不显示 |
+| `compare.iconShowMap` | `{ [index]: boolean }` | 按对比指标索引控制图标；payload 只保存值为 `false` 的项 |
+
+快捷布局与前端一致，会原子化写入下列默认组合：
+
+| `preset` | 主指标标签 | 对比指标位置 | 对比指标标签 | `maxPerLine` | 其它关键默认值 |
+|---|---|---|---|---:|---|
+| `classic` | 左侧 | 主指标下 | 左侧 | 1 | 主、对比指标 `valueAlign: "follow"` |
+| `style1` | 上方、居中 | 固定底部 | 左侧 | 2 | 显示分割线 |
+| `style2` | 上方、居中 | 固定底部 | 上方 | 2 | 显示分割线 |
+| `style3` | 上方、左对齐 | 主指标右侧 | 上方 | 9 | 主/对比指标跟随排列 |
+| `style4` | 左侧、左对齐 | 主指标下 | 左侧 | 2 | — |
+| `style5` | 左侧、左对齐 | 主指标下 | 上方 | 2 | — |
+| `style6` | 左侧、居中 | 主指标下 | 左侧 | 1 | 主指标 `valueAlign: "both_ends"` |
+
+切换快捷布局时会覆盖表中列出的布局字段，但保留数值字体、颜色、图标等无关样式；同一次
+`setKPISetting()` 中，`main`、`compare` 及 `layout` 的其它显式字段在预设之后应用，可覆盖
+预设值。
+
+`valueAlign` 的生效规则与前端渲染一致。前端代码中的 `isClassicKpi` 指的是下表中的
+Grid 结构，并不要求 `layout.preset` 必须为 `"classic"`；例如 `style6` 也属于 Grid 结构。
+
+| 当前结构 | `main.label.valueAlign` | `compare.label.valueAlign` |
+|---|---|---|
+| Grid：对比指标在主指标下、对比标签在左侧、`maxPerLine = 1` | 主标签在左侧时生效；`right`、`both_ends` 均使主数值靠右 | 生效；`right` 使对比数值靠右，`both_ends` 还会撑满整个 Grid |
+| 纵向：对比指标位于固定底部，或不满足 Grid 条件且不在主指标右侧 | 当前渲染器不读取，配置保留 | 标签在左侧且 `maxPerLine = 1` 时 `right` 生效；每行多个时由网格自动分布，`both_ends` 无特殊效果 |
+| 横向：对比指标在主指标右侧且不满足 Grid 条件 | 当前渲染器不读取，配置保留 | 标签在左侧且 `maxPerLine = 1` 时 `right` 生效；主/对比整体为两端分布时，运行时按 `right` 渲染 |
+
+这些是“当前是否产生视觉效果”的条件，不是 payload 合法性约束。GuanVis 会像前端一样保存
+合法枚举值，不会因为切换快捷布局、标签位置、整体分布方式或 `maxPerLine` 而清空另一个
+`valueAlign`，也不会因此报错；暂时不生效的值在以后切回适用结构时仍可恢复生效。
+`main.label.valueAlign: "both_ends"` 与 `compare.label.valueAlign` 可以同时存在，Grid 渲染器会
+合并处理，不会引起异常。`attachCard()` 同样保留线上已有值，只覆盖显式传入的字段。
+
+当 `main.icon.show: true` 时，最终 payload 会包含完整的基础图标配置：`show`、`groupId`、
+`iconId`、`size`、`position` 和 `margin`。新建对比指标卡缺少这些字段时默认补齐
+`default_line / bar_chart / 24 / left / 10`；`attachCard()` 优先保留线上已有的图标选择和
+颜色，只补齐缺失的基础字段。
+
+分割线沿用卡片现有的对比指标布局，仅在对比指标位于固定底部时可见；本节不开放对比指标位置配置。
+
+### 进度类共用数据标签
+
+`setProgressBarSetting()`、`setProgressPieSetting()`、`setLiquidGaugeSetting()` 和
+`setSolidGaugeSetting()` 的 `main` / `secondary` 使用下列字段；不适用某图表的字段会报错。
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `main.format` | `"percent"` / `"current"` | 主指标显示百分比或当前值 |
+| `main.precision` | `0` / `1` / `2` | 百分比小数位数 |
+| `main.value` | 文字样式 | 主指标数值样式 |
+| `main.valuePosition` | 见具体方法 | 主指标数值位置；仅进度条支持 |
+| `main.outline` | boolean | 主指标是否显示描边；仅进度条支持 |
+| `main.showName` | boolean | 是否显示数值名称 |
+| `main.name` | string | 数值名称 |
+| `main.nameStyle` | 文字样式 | 数值名称样式 |
+| `main.namePosition` | 见具体方法 | 数值名称位置；仅进度条支持 |
+| `secondary.showPercent` / `showCurrent` / `showTarget` | boolean | 次指标显示百分比、当前值和目标值 |
+| `secondary.percentName` | string | 次指标中的百分比名称 |
+| `secondary.precision` | `0` / `1` / `2` | 次指标百分比小数位数 |
+| `secondary.text` | 文字样式 | 次指标文本样式 |
+| `secondary.position` | 见具体方法 | 次指标位置 |
+| `secondary.alignment` | `"left"` / `"center"` | 次指标对齐方式；仅进度条支持 |
+
+### `setProgressBarSetting(config)`
+
+设置进度条 `PROGRESS_BAR` 的颜色、数据标签和图形显示：
+
+```javascript
+.setProgressBarSetting({
+    colors: {
+        mode: "gradient",
+        startColor: "#1456F0",
+        endColor: "#7AA2FF",
+        background: "#E8EAF0"
+    },
+    main: {
+        format: "percent",
+        precision: 1,
+        value: { fontSize: 28, bold: true },
+        valuePosition: "outer",
+        outline: true,
+        showName: true,
+        name: "完成率",
+        namePosition: "top"
+    },
+    secondary: {
+        showCurrent: true,
+        showTarget: true,
+        position: "bottom",
+        alignment: "left"
+    },
+    display: { mode: "custom", height: 28, borderRadius: 6 }
+})
+```
+
+| 分组 | 字段 | 类型/取值 | 说明 |
+|---|---|---|---|
+| `colors` | `mode` | `"interval"` / `"gradient"` | 分段或渐变 |
+| `colors` | `startColor` / `endColor` / `background` | string / `null` | 起始色、结束色和底色 |
+| `colors` | `intervals` | 区间数组 | 分段颜色，结构见下表 |
+| `main` | `valuePosition` | `"inner"` / `"right"` / `"outer"` | 数值在内部、右侧或外部 |
+| `main` | `namePosition` | `"left"` / `"top"` / `"bottom"` | 数值名称位置；外部数值会强制显示名称，左侧名称会调整为上方 |
+| `secondary` | `position` | `"top"` / `"bottom"` | 次指标位置 |
+| `display` | `mode` | `"default"` / `"custom"` | 配置方式 |
+| `display` | `height` | 1～64 的整数 | 进度条高度，单位 px |
+| `display` | `borderRadius` | 0～32 的整数 | 进度条圆角，单位 px |
+
+### `setProgressPieSetting(config)`
+
+设置圆形进度条 `PROGRESS_PIE` 的颜色、数据标签和图形显示：
+
+```javascript
+.setProgressPieSetting({
+    colors: {
+        mode: "interval",
+        intervals: [
+            { type: "less_than", min: 0, color: "#F54A45" },
+            { type: "more_than", min: 0, color: "#34C724" }
+        ],
+        background: "#E8EAF0"
+    },
+    main: { format: "current", value: { fontSize: 30 }, showName: true },
+    secondary: { showPercent: true, showTarget: true, position: "inner" },
+    display: { showTicks: true, wide: true, startAngle: 90 }
+})
+```
+
+| 分组 | 字段 | 类型/取值 | 说明 |
+|---|---|---|---|
+| `colors` | `mode` | `"interval"` / `"gradient"` | 分段或渐变 |
+| `colors` | `startColor` / `endColor` / `background` | string / `null` | 起始色、结束色和底色 |
+| `colors` | `intervals` | 区间数组 | 分段颜色 |
+| `secondary` | `position` | `"top"` / `"bottom"` / `"left"` / `"right"` / `"inner"` | 次指标位置 |
+| `display` | `showTicks` | boolean | 显示刻度 |
+| `display` | `wide` | boolean | 宽幅显示 |
+| `display` | `startAngle` | 0～360 的整数 | 起始角度 |
+
+进度条和圆形进度条的 `intervals` 结构：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `type` | `"interval"` / `"more_than"` / `"less_than"` | 闭区间、大于阈值或小于阈值；默认 `interval` |
+| `min` | -100～100 的整数 | 区间下界；`more_than` / `less_than` 时作为阈值 |
+| `max` | -100～100 的整数 | `interval` 的区间上界，且不得小于 `min` |
+| `color` | 非空字符串 | 区间颜色 |
+
+### `setActivityGaugeSetting(config)`
+
+设置多环进度图 `ACTIVITY_GAUGE`。色板继续使用 `.setThemeColor()`，本方法补充底色和数据标签：
+
+```javascript
+.setActivityGaugeSetting({
+    background: "#E8EAF0",
+    labels: {
+        showSeries: true,
+        showCategory: false,
+        showPercentage: true,
+        precision: 2,
+        count: 5,
+        valueFont: { fontFamily: "Arial", fontSize: 16 },
+        text: { fontSize: 14, color: "#646A73", bold: true }
+    }
+})
+```
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `background` | string / `null` | 环形底色 |
+| `labels.show` | boolean | 一次开启/关闭系列名称、类别名称和百分比 |
+| `labels.showSeries` / `showCategory` / `showPercentage` | boolean | 分别显示系列名称、类别名称和百分比 |
+| `labels.precision` | `0` / `1` / `2` | 百分比小数位数 |
+| `labels.count` | 1～25 的整数 | 标签数量 |
+| `labels.valueFont.fontFamily` | 非空字符串 | 数值字体 |
+| `labels.valueFont.fontSize` | `null` 或 12～72 | 数值字号；`null` 表示自动 |
+| `labels.text` | 文字样式 | 标签文本样式，字号范围 12～72 |
+
+### `setLiquidGaugeSetting(config)`
+
+设置流体进度图 `LIQUID_GAUGE` 的外环颜色和数据标签：
+
+```javascript
+.setLiquidGaugeSetting({
+    outerColor: "#1456F0",
+    main: { format: "percent", precision: 1, showName: true, name: "完成率" },
+    secondary: { showCurrent: true, showTarget: true, position: "bottom" }
+})
+```
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `outerColor` | string / `null` | 外环颜色 |
+| `main` | 进度类共用主指标 | 主指标数据格式、精度、数值和数值名称 |
+| `secondary` | 进度类共用次指标 | 次指标内容、文本和位置 |
+| `secondary.position` | `"top"` / `"bottom"` / `"left"` / `"right"` / `"inner"` | 次指标位置 |
+
+### `setSolidGaugeSetting(config)`
+
+设置填充仪表板 `SOLID_GAUGE` 的颜色、图形显示和数据标签：
+
+```javascript
+.setSolidGaugeSetting({
+    colors: {
+        intervals: [
+            { min: 0, max: 80, color: "#F5B942" },
+            { type: "more_than", min: 80, color: "#34C724" }
+        ],
+        background: "#E8EAF0",
+        targetLine: "#111111"
+    },
+    display: { startAngle: -100, endAngle: 100, max: 120 },
+    main: { format: "current", showName: true, name: "销售额" },
+    secondary: { showPercent: true, showTarget: true, position: "right" }
+})
+```
+
+| 分组 | 字段 | 类型/取值 | 说明 |
+|---|---|---|---|
+| `colors` | `intervals` | 区间数组 | 数值分段颜色；结构同上，但上下界必须是大于等于 0 的整数且无固定上限 |
+| `colors` | `background` | string / `null` | 底色 |
+| `colors` | `targetLine` | string / `null` | 目标线颜色 |
+| `display` | `startAngle` | -120～0 的整数 | 起始角度 |
+| `display` | `endAngle` | 0～120 的整数 | 结束角度 |
+| `display` | `max` | 有限数字 / `null` | 最大值；`null` 使用自动最大值 |
+| `main` | 进度类共用主指标 | 主指标数据格式、精度、数值和数值名称 |
+| `secondary` | 进度类共用次指标 | 次指标内容、文本和位置 |
+| `secondary.position` | `"top"` / `"bottom"` / `"left"` / `"right"` | 次指标位置 |
+
+## 汇总指标
+
+### `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 })` 只关闭叠加图形标签。
+
+### `setTreemapDataLabel(config)`
+
+设置矩形树图 `TREE_MAP` 第一层和第二层独立数据标签：
+
+```javascript
+.setTreemapDataLabel({
+    first: {
+        show: true,
+        showSeries: true,
+        showCategory: true,
+        showNumber: true,
+        separator: "linefeed",
+        fontSize: 14,
+        color: "#FFFFFF",
+        bold: true
+    },
+    second: {
+        show: true,
+        showCategory: true,
+        showNumber: true,
+        separator: "space",
+        fontSize: 12,
+        color: "#FFFFFF"
+    }
+})
+```
+
+顶层配置：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `first` | object | 第一层数据标签配置 |
+| `second` | object | 第二层数据标签配置 |
+
+`first` 和 `second` 支持相同的属性：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `show` | boolean | 当前层数据标签开关 |
+| `showSeries` | boolean | 显示系列名称 |
+| `showCategory` | boolean | 显示类别名称 |
+| `showNumber` | boolean | 显示数值 |
+| `separator` | `"comma"` / `"colon"` / `"semicolon"` / `"period"` / `"linefeed"` / `"space"` | 标签内容分隔符 |
+| `fontSize` | 9–72 | 字号 |
+| `color` | string / `null` | 文字颜色；`null` 使用图表默认颜色 |
+| `bold` / `italic` / `underline` | boolean | 粗体、斜体和下划线 |
+
+`show: true` 按 BI 前端的开启动作补入当前层默认配置：第一层为 `fontSize: 14`、白色、显示类别名称，第二层为 `fontSize: 12`、白色、显示类别名称；同一次调用显式传入的字段会覆盖这些默认值。`show: false` 会把当前层的 `showSeries`、`showCategory`、`showNumber` 全部设为 `false`，但保留分隔符和文字样式。
+
+多次调用以及 `attachCard()` 都只合并本次涉及的层和属性，另一层及未识别的线上历史字段保持不变。
+
+### `setFunnelDataLabel(config)`
+
+设置漏斗图 `FUNNEL` 和水平漏斗图 `HORIZONTAL_FUNNEL` 的数值、最后一个数值、类别和转化率标签：
+
+```javascript
+.setFunnelDataLabel({
+    number: {
+        show: true,
+        fontSize: 14,
+        color: "#FFFFFF",
+        textOutline: true
+    },
+    lastNumber: {
+        fontSize: 14,
+        bold: true,
+        textOutline: true
+    },
+    category: {
+        show: true,
+        fontSize: 11,
+        color: "#343D50",
+        textOutline: false
+    },
+    conversionRate: {
+        show: true,
+        fontSize: 11,
+        color: "#343D50",
+        textOutline: true
+    }
+})
+```
+
+| 字段 | 是否支持 `show` | 说明 |
+|---|---|---|
+| `number` | 是 | 各漏斗阶段的数值标签；其开关同时控制最后一个数值 |
+| `lastNumber` | 否 | 最后一个数值的独立文字样式；显隐由 `number.show` 控制 |
+| `category` | 是 | 类别标签 |
+| `conversionRate` | 是 | 转化率标签 |
+
+四个标签对象的文字样式属性：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `fontSize` | 9–72 | 字号 |
+| `color` | string / `null` | 文字颜色；省略时使用当前主题的默认颜色 |
+| `bold` / `italic` / `underline` | boolean | 粗体、斜体和下划线 |
+| `textOutline` | boolean | 当前标签独立的文字描边开关 |
+
+`number`、`category`、`conversionRate` 还支持 `show: boolean`。不传 `show` 时只修改样式；不调用本方法时，BI 前端默认显示数值、类别和转化率。由于前端共用 `showNumber` 开关，最后一个数值不能独立隐藏或显示。
+
+多次调用以及 `attachCard()` 都是字段级合并：例如只修改 `category.color` 不会覆盖数值、转化率或类别的其它样式，也会保留未识别的线上历史字段。
+
+## 坐标轴
+
+### `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)`
+
+设置透视表、分组表、明细表、树状表和滚动表的行为与视觉样式。行为字段继续写入 `props.miscPivotTableSetting`；视觉样式按分组写入真实前端属性：
+
+- `appearance` → `props.pivot_appearance`
+- `headers` → `props.pivot_headers`
+- `data` → `props.pivot_data`
+
+视觉分组使用嵌套字段合并。只设置视觉样式时不会清空已有行为配置；编辑已有卡片时也只深合并显式传入的视觉字段。
+
+| 图表类型 | 视觉能力 | 行为限制 |
+|---|---|---|
+| `PIVOT_TABLE` | 支持下表全部视觉字段 | 支持透视表序号配置 |
+| `GROUPED_TABLE` | 支持下表全部视觉字段 | 支持分组展示与展开配置 |
+| `DETAIL_TABLE` | 支持下表全部视觉字段 | `vAlign` 仅支持 `"MIDDLE"` |
+| `LAYER_TREE_TABLE` | 支持下表全部视觉字段 | 不支持分页、累计行号和跳过总计行；支持展开配置 |
+| `SCROLL_TABLE` | 使用下文所列的滚动表视觉字段 | 支持数字/字母换行及行号样式；不支持分页、累计行号、跳过总计行和 `textWrap`；`vAlign` 仅支持 `"MIDDLE"` |
+
+#### 主题及样式：`appearance`
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `theme` | `"classic"` / `"compact"` | 经典或极简主题 |
+| `colorType` | `"grey"` / `"ocean"` / `"laker"` / `"spring"` / `"autumn"` | 表格色系 |
+| `banding` | `{ enabled: boolean, colors: string[] }` | 斑马纹开关与非空颜色数组 |
+| `border` | `{ enabled: boolean, colors: string[] }` | 外边框开关与非空颜色数组 |
+| `divider` | `{ colors: string[] }` | 行列分隔线非空颜色数组 |
+| `backgroundColor` | string | 表格背景色 |
+| `selectedColor` | string | 选中高亮色，可使用带透明度的 `rgba(...)` |
+| `colWidth` | integer，15–1000 | 表格列宽 |
+| `fontFamily` | 非空 string | 全表字体 |
+| `fontSize` | number，9–72 | 全表字号（BI 面板只提供 12 起，表格本身按给定值渲染；紧凑的迁移报表块常用 10） |
+| `cellPadding` | `"SMALL"` / `"MIDDLE"` / `"LARGE"` | 单元格内间距 |
+
+滚动表的 `appearance` 仅支持 `colorType`、`banding`、`divider`、`backgroundColor`、`colWidth` 和 `cellPadding`。其中 `colorType` 可选 `"grey"` / `"light-blue"` / `"purple"` / `"lake-blue"` / `"green"` / `"yellow"`，`divider` 使用 `{ row: boolean, column: boolean, color: string }`。
+
+#### 表头设置：`headers`
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `columnEnabled` | boolean | 是否显示列表头；仅滚动表支持配置 |
+| `colHeaderHeight` | integer，18–500 | 列表头行高 |
+| `columnStyle` | object | 列表头背景与文字样式 |
+| `colHeaderAlignment` | `"center"` / `"left"` / `"right"` / `"followField"` | 列表头对齐方式 |
+| `rowSize` | integer，0–100 | 行表头列数；滚动表不支持配置 |
+| `rowStyle` | object | 行表头背景与文字样式；额外支持 `showFillColor`；滚动表不支持配置 |
+
+#### 数据行样式：`data`
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `rowHeight` | integer，18–500 | 数据行行高 |
+| `hoverColor` | string | 鼠标悬停背景色 |
+| `style` | object | 数据区文字样式 |
+
+`columnStyle`、`rowStyle` 和 `data.style` 可包含 `fontFamily`、`fontSize`（12–72）、`color`、`bold`、`italic`、`underline`、`strikeThrough`。`columnStyle` / `rowStyle` 还支持 `fillColor`，`rowStyle` 额外支持 `showFillColor: boolean`。
+
+```javascript
+.setTableSetting({
+    appearance: {
+        theme: "compact",
+        colorType: "ocean",
+        banding: { enabled: true, colors: ["#F5F7FA"] },
+        border: { enabled: true, colors: ["#D9DEE8"] },
+        divider: { colors: ["#E4E7F0"] },
+        backgroundColor: "#FFFFFF",
+        selectedColor: "rgba(22, 93, 255, 0.1)",
+        colWidth: 120,
+        fontFamily: "Arial",
+        fontSize: 12,
+        cellPadding: "MIDDLE"
+    },
+    headers: {
+        colHeaderHeight: 36,
+        columnStyle: { fillColor: "#EDF2FA", color: "#21272A", bold: true },
+        colHeaderAlignment: "followField",
+        rowSize: 1,
+        rowStyle: { showFillColor: true, fillColor: "#F1F6FB", color: "#343D50" }
+    },
+    data: {
+        rowHeight: 32,
+        hoverColor: "#F5F5F5",
+        style: { color: "#21272A", fontSize: 12 }
+    }
+})
+```
+
+#### 行为配置
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `pagination` | boolean | 是否分页 |
+| `pageSize` | number | 每页行数；可选 `10` / `20` / `50` / `100` / `200` |
+| `autoAlignment` | boolean | 横向自动对齐 |
+| `vAlign` | `"MIDDLE"` / `"TOP"` | 垂直居中或向上对齐；明细表、滚动表不支持 `"TOP"` |
+| `textWrap` | boolean | `true` 自动换行，`false` 截断；滚动表不支持 |
+| `wordBreak` | boolean | 数字/字母是否自动换行；仅滚动表支持 |
+| `showHeaderSortingIcon` | boolean | 是否显示表头排序图标 |
+| `fixedHeaderInfo` | object | 固定表头；通常可包含 `{ X: boolean, Y: boolean }`；滚动表仅支持 `{ X: false }` |
+| `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 | 默认展开列数 |
+
+树状表支持其中的 `isDefaultExpandedGroupedTable` 和 `defaultExpandCols`。
+
+
+表格属性会按以下规则同步关联字段：
+
+- 对支持累计行号的表格，`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
+})
+```
+
+### 表格迷你图
+
+迷你图只支持透视表 `PIVOT_TABLE`。字段开关和可视化样式是两层配置：
+
+- `setMiniChart(selector, config)` 把指定数值字段设置为迷你图，写入 `zoneData.metric[].miniChart`；
+- `setMiniChartSetting(selector, config)` 设置该字段的迷你图样式，按最终字段 `key` 写入 `props.miniChart[key]`。
+
+`selector` 可传数值字段的名称/`fdId`/`key` 字符串、metric zone 中从 `0` 开始的索引，
+或字段对象。GuanVis 会解析最终字段 key，不要手写 `props.miniChart` 的 key。
+
+```javascript
+createCard(ChartType.PIVOT_TABLE, "月度销售")
+    .addRow(f("区域"))
+    .addMetric(f("销售额"))
+    .setMiniChart("销售额", {
+        chartType: MiniChartType.LINE,
+        dimension: f("月份", {
+            filterType: FilterType.IN,
+            filterValue: ["2026-01", "2026-02"]
+        }),
+        ordering: MiniChartSort.ASC
+    })
+    .setMiniChartSetting("销售额", {
+        color: "#1456F0",
+        skipNulls: true,
+        showPoint: false,
+        lineStyle: "Solid_2",
+        width: 180,
+        height: 60,
+        limit: 12,
+        axes: { categoryAxis: { visible: false } },
+        dataLabels: { metric: { showSeries: false, showNumber: true, allowOverlap: true } },
+        chartLegend: { showLegend: false }
+    });
+```
+
+`setMiniChart()` 配置：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `chartType` | `MiniChartType.LINE` / `COLUMN` / `PIE` / `PROGRESS` | 单线图、单柱图、饼图或进度条 |
+| `dimension` | `f()` / `field()` / `metricDim()` 字段 | 单线图、单柱图和饼图必填；不能使用聚合字段；进度条不支持 |
+| `ordering` | `MiniChartSort.ASC` / `DESC` | 维度升序或降序；省略时为 `ASC` |
+
+`dimension` 可携带 `filterType`、`filterValue`、`filterLevel` 和
+`fieldFilterSettings`，用于迷你图维度筛选。进度条不构建维度数据，因此最终 `rows` 固定为空数组。
+
+字段配置限制与前端一致：
+
+| 限制 | GuanVis 行为 |
+|---|---|
+| 图表类型不是 `PIVOT_TABLE` | validation error |
+| column zone 存在非 MPH 的对比字段 | validation error；必须先移除对比字段 |
+| 开启自由钻取 | validation error |
+| 直连数据库、Web Service 或服务器直连文件数据集 | schema/base 中有 `sourceType` 时 validation error |
+| 动态数值字段（含 `dzId`） | validation error |
+| 主副指标组内字段 | validation error |
+| 字段已有高级计算 | 与前端确认切换后的结果一致：开启迷你图时清除 `advCalc` / `secondAdvCalc` |
+
+知识反馈/分析结果存储、LOD 受限字段和“每张表最多几个迷你图”的上限依赖当前 BI
+运行时上下文或管理员参数，离线 `pack` 无法可靠推断；目标环境仍会执行自己的运行时限制，
+GuanVis 不硬编码可能随环境变化的数量上限。
+
+调用 `setMiniChart(selector, null)` 会关闭该字段的迷你图并删除对应样式；切换
+`chartType` 会清除旧类型样式，避免把折线属性带入饼图或进度条。必须先调用
+`setMiniChart()` 开启字段，再调用 `setMiniChartSetting()`。
+
+#### `setMiniChartSetting(selector, config)`
+
+公共尺寸属性：
+
+| 字段 | 适用类型 | 类型/范围 | 说明 |
+|---|---|---|---|
+| `width` | 全部 | 折线/柱形/饼图 50–1000；进度条 50–300 | 单元格宽度，px |
+| `height` | 全部 | 折线/柱形/饼图 30–500；进度条 30–100 | 单元格高度，px |
+| `limit` | 折线/柱形/饼图 | 大于等于 0 的整数 | 显示维度值数量；实际最大值由 BI 管理员参数决定 |
+
+单线图属性：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `color` | string / `null` | 线条颜色；`null` 使用主题色 |
+| `skipNulls` | boolean | 是否在空值处断开 |
+| `showArea` | boolean | 是否显示覆盖区域 |
+| `opacity` | 0–100 的整数 | 覆盖区域透明度 |
+| `colorType` | `"solid"` / `"gradient"` | 覆盖区域纯色或渐变 |
+| `showPoint` | boolean | 是否显示数据点 |
+| `showAsSpline` | boolean | 是否使用曲线 |
+| `lineStyle` | `"Solid_1"` / `"Solid_2"` / `"Solid_3"` / `"Dash_2"` | 线型 |
+| `axes` / `dataLabels` / `chartLegend` | object | 预览坐标轴、数据标签和图例，结构见下表 |
+
+单柱图属性：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `color` | string / `null` | 柱体颜色；`null` 使用主题色 |
+| `colorType` | `"solid"` / `"transparent_gradient"` / `"color_gradient"` | 柱体填充方式 |
+| `gapBetweenGroup` / `gapInGroup` | 0–100 的整数 | 分组间/组内间距百分比 |
+| `axes` / `dataLabels` / `chartLegend` | object | 预览坐标轴、数据标签和图例，结构见下表 |
+
+饼图属性：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `theme` | object | `{ tcId?, theme?, colors?, useSequentialPalette? }` 主题及颜色配置 |
+| `dataLabels` | object | 预览数据标签 |
+| `chartLegend` | object | 预览图例 |
+| `centerTextSetting` | object | 中心文本；支持 `showCenterText`、`valueType`、`valueFont`、`textFont` |
+
+进度条属性：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `intervalColors` | 非空数组 | 可用历史颜色字符串，或 `{ color, interval, type }`；`type` 为 `interval` / `more_than` / `less_than` |
+| `background` | string / `null` | 进度条底色 |
+| `showDataLabel` | boolean | 是否显示数值 |
+| `mainFontSize` | `null` / `"auto"` / 9–72 | 数值字号；`null` 或 `"auto"` 为自动 |
+| `mainLabelValueColor` | string / `null` | 数值颜色 |
+| `mainBold` / `mainItalic` / `mainUnderline` | boolean | 数值字形 |
+
+预览公共对象使用前端的原生层级：
+
+| 对象 | 支持字段 |
+|---|---|
+| `axes.categoryAxis` / `axes.mainAxis` | `visible`、标题字段、标签字体字段、轴线字段；迷你图面板不开放单位、范围、网格线、格式和导航器 |
+| `dataLabels.metric` | `showCategory`、`showSeries`、`showNumber`、`showPercentage`、`allowOverlap`、`position`、`fontSize`、`color`、`bold`、`italic`、`underline`、`textOutline`、`separator`；`showSeries` 用于兼容或关闭已有系列标签，布尔字段均会校验类型 |
+| `chartLegend` | `showLegend`、`legendPosition`、`legendCrossPosition`、字体字段及 `customLegend` |
+
+重复调用会深度合并显式字段；`setMiniChartSetting(selector, null)` 只删除该字段的样式，
+不关闭字段迷你图。本 API 同时支持普通 Card、MetricChart 和 `attachCard()`。
+
+### `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`。
+
+## 组合图
+
+### `setComboSetting(config)`
+
+设置组合图的显示方式、折线或符号样式。
+
+通用属性：
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `swapYShape` | boolean | 是否交换主图形和叠加图形 |
+
+折线组合图支持 `GROUPED_COLUMN_WITH_LINE` 和 `STACKED_COLUMN_WITH_LINE`：
+
+```javascript
+.setComboSetting({
+    swapYShape: true,
+    line: {
+        skipNulls: true,
+        showPoint: true,
+        pointShape: "ring",
+        pointSize: 6,
+        showAsSpline: true,
+        lineStyle: "Solid_2"
+    }
+})
+```
+
+`line` 支持的属性：
+
+| 属性 | 类型/取值 | 说明 |
+|---|---|---|
+| `skipNulls` | boolean | 是否在空值处断开 |
+| `showPoint` | boolean | 是否显示数据点 |
+| `pointShape` | `"default"` / `"dot"` / `"ring"` | 混合图形、实心圆或空心圆 |
+| `pointSize` | `5` / `6` / `8` | 数据点大小 |
+| `showAsSpline` | boolean | 是否显示为曲线 |
+| `lineStyle` | `"Solid_1"` / `"Solid_2"` / `"Solid_3"` / `"Dash_2"` | 细实线、中实线、粗实线或虚线 |
+
+符号组合图支持 `GROUPED_COLUMN_WITH_SYMBOL` 和 `STACKED_COLUMN_WITH_SYMBOL`：
+
+```javascript
+.setComboSetting({
+    symbol: {
+        symbols: ["circle", "diamond", "square", "triangle", "triangle-down"],
+        symbolSize: 8
+    }
+})
+```
+
+`symbol` 支持的属性：
+
+| 属性 | 类型/取值 | 说明 |
+|---|---|---|
+| `symbols` | 1～20 个 string | 可使用 `circle`、`diamond`、`square`、`triangle`、`triangle-down` 或有效的 `http(s)` 图片地址 |
+| `symbolSize` | 4～20 的整数 | 符号大小 |
+
+`swapYShape` 可以单独设置，也可以与 `line` 或 `symbol` 一起设置；`line` 与 `symbol` 不能同时配置。`attachCard()` 只修改显式传入的字段。
+
+## 瀑布图
+
+### `setWaterfallSetting(config)`
+
+设置 `WATERFALL_COLUMN` 的正负值颜色和累计值：
+
+```javascript
+.setWaterfallSetting({
+    upColor: "#FD7F76",
+    downColor: "#69BFA8",
+    showSum: true,
+    sumName: "累计值",
+    sumColor: "#4379CE"
+})
+```
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `upColor` | 非空 string / `null` | 正值颜色；`null` 使用默认颜色 |
+| `downColor` | 非空 string / `null` | 负值颜色；`null` 使用默认颜色 |
+| `showSum` | boolean | 是否显示累计值 |
+| `sumName` | 非空 string / `null` | 累计值名称；`null` 使用“累计值” |
+| `sumColor` | 非空 string / `null` | 累计值颜色；`null` 使用默认颜色 |
+
+该方法支持普通卡片、指标卡片和 `attachCard()`；多次调用或 attach 更新都只合并显式传入的属性。配置颜色指标时，正负值颜色由颜色指标决定；累计值配置仍然生效。
+
+## 地图
+
+### `setMapSetting(config)`
+
+设置世界地图、中国行政地图、气泡行政地图和符号行政地图的专属属性。配置写入
+`props.highmapSetting`：
+
+```javascript
+createCard(ChartType.BASIC_MAP, "浙江城市销售")
+    .addRow(f("城市"))
+    .addMetric(f("销售额"))
+    .setMapSetting({
+        showNullAsZero: true,
+        region: MapRegion.CITY,
+        province: { name: "浙江省", code: "330000" },
+        city: { name: "杭州市", code: "330100" },
+        underColor: "#E6E8EA",
+        borderColor: "#617282",
+        hoverColor: "#BADA55"
+    });
+```
+
+支持的属性：
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `showNullAsZero` | boolean | 是否把 `NULL` 数值显示为 `0` |
+| `region` | `MapRegion.COUNTRY` / `PROVINCE` / `CITY` / `AUTO` | 全国、省级、市级或自动地图范围；不适用于世界地图 |
+| `province` | `{ name, code }` / `null` | 省级显示内容；`name`、`code` 均为非空字符串，`null` 清除选择 |
+| `city` | `{ name, code }` / `null` | 市级显示内容；`name`、`code` 均为非空字符串，`null` 清除选择 |
+| `customRegion` | 非空 string / `null` | BI 中已有的自定义大区 `mapId`；`null` 关闭大区显示 |
+| `underColor` | 非空 string | 地图底色 |
+| `borderColor` | 非空 string | 地图边框颜色 |
+| `hoverColor` | 非空 string | 地图区域悬停背景色；只用于世界地图和中国行政地图 |
+| `symbol` | `MapSymbol` / http(s) URL | 符号行政地图的符号形状或自定义图片链接 |
+| `symbolSize` | 4～20 的整数 | 符号行政地图的符号大小，单位 px |
+
+各地图实际支持范围：
+
+| 图表 | Null 显示为 0 | 范围/显示内容/大区 | 底色/边框 | 悬停色 | 符号样式 |
+|---|---:|---:|---:|---:|---:|
+| `WORLD_MAP` | ✓ | — | ✓ | ✓ | — |
+| `BASIC_MAP` | ✓ | ✓ | ✓ | ✓ | — |
+| `BUBBLE_MAP` | ✓ | ✓ | ✓ | — | — |
+| `POINT_MAP` | ✓ | ✓ | ✓ | — | ✓ |
+
+`MapRegion` 的后端值依次为 `1`、`2`、`3`、`4`。切换 `region` 时会与前端一致地清除
+原有 `province` 和 `city`；同一次调用显式传入的新 `province` / `city` 会在清除之后写入。
+`province` 仅在省级或市级范围中生效，`city` 仅在市级范围中生效。
+
+`customRegion` 必须引用目标 BI 环境中已经存在的自定义大区 `mapId`，不要猜测或用名称代替。
+设置后渲染器优先使用自定义大区，`region`、`province` 和 `city` 会保留但暂不生效；清除
+`customRegion` 后可继续恢复生效。
+
+`MapSymbol` 支持 `CIRCLE`、`DIAMOND`、`SQUARE`、`TRIANGLE`、`TRIANGLE_DOWN`；也可直接
+传入有效的 `http://` 或 `https://` 图片地址。重复调用及 `attachCard()` 均只深度合并显式字段，
+未修改颜色、区域设置和线上历史字段保持不变。
+
+## 气泡图
+
+### `setBubbleSetting(config)`
+
+设置普通气泡图 `BASIC_BUBBLE` 和气泡行政地图 `BUBBLE_MAP` 的气泡半径范围，配置写入
+`props.bubbleSetting`：
+
+```javascript
+.setBubbleSetting({
+    minScale: 0.4,
+    maxScale: 1.8
+})
+```
+
+| 字段 | 类型/范围 | 说明 |
+|---|---|---|
+| `minScale` | 0～1 的有限数字 | 最小值侧的气泡半径缩放；越小，小值气泡越大 |
+| `maxScale` | 1～2 的有限数字 | 最大值侧的气泡半径缩放；越大，大值气泡越小 |
+
+前端滑块默认对应 `minScale: 1`、`maxScale: 1`。两个值分别参与气泡数据范围的最小值和
+最大值换算，并不是直接的像素半径。重复调用或 `attachCard()` 只合并本次传入的字段。
+
+## 雷达图
+
+### `setRadarSetting(config)`
+
+设置雷达图 `RADAR_LINE` 的图形显示属性，配置写入 `props.miscRadarSetting`：
+
+```javascript
+.setRadarSetting({
+    drawByMetric: true,
+    showAsSpline: true,
+    showPoint: true,
+    showSolidFill: true,
+    opacity: 40
+})
+```
+
+| 属性 | 类型/范围 | 默认值 | 说明 |
+|---|---|---:|---|
+| `drawByMetric` | boolean | `false` | 是否按度量排列 |
+| `showAsSpline` | boolean | `false` | 是否显示为曲线 |
+| `showPoint` | boolean | `true` | 是否显示数据点 |
+| `showSolidFill` | boolean | `false` | 是否显示填充色 |
+| `opacity` | 0～100 的有限数字 | `30` | 填充色饱和度；仅在 `showSolidFill: true` 时生效 |
+
+关闭填充色不会清除 `opacity`，再次开启时继续使用原值。新建卡片首次调用会补齐表中默认值；
+重复调用或 `attachCard()` 只合并显式传入的属性。
+
+## 箱线图
+
+### `setBoxPlotSetting(config)`
+
+设置箱线图 `BOX_PLOT` 的数据点和箱体颜色，配置写入 `props.boxPlotSetting`：
+
+```javascript
+.setBoxPlotSetting({
+    showAll: true,
+    fillColor: "#C7E1FF",
+    dataPointColor: "#3472AB",
+    lineColor: "#617282"
+})
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `showAll` | boolean | `false` | 是否显示所有数据点；关闭时仅显示异常值 |
+| `fillColor` | 非空 string | `"#C7E1FF"` | 箱体填充色 |
+| `dataPointColor` | 非空 string | `"#3472AB"` | 数据点颜色 |
+| `lineColor` | 非空 string | `"#617282"` | 箱体边框、中位线和范围线颜色 |
+
+新建卡片首次调用会补齐表中默认值，保证箱线图颜色配置完整；重复调用或 `attachCard()`
+只合并显式传入的属性。
+
+## 热力图
+
+### `setHeatMapSetting(config)`
+
+设置热力图 `HEAT_MAP` 的渐变色、网格色和数值标签，配置写入 `props.heatMapSetting`：
+
+```javascript
+.setHeatMapSetting({
+    startColor: "#EEEEEE",
+    endColor: "#4379CE",
+    gridColor: "#FFFFFF",
+    dataLabel: true
+})
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `startColor` | 非空 string / `null` | `"#EEEEEE"` | 渐变起始颜色；`null` 使用前端默认色 |
+| `endColor` | 非空 string / `null` | `"#4379ce"` | 渐变结束颜色；`null` 使用前端默认色 |
+| `gridColor` | 非空 string / `null` | `"#ffffff"` | 网格颜色；`null` 使用前端默认色 |
+| `dataLabel` | boolean | `false` | 是否显示数值标签 |
+
+新建卡片首次调用会补齐表中默认值；重复调用或 `attachCard()` 只合并显式传入的属性。
+
+## 柱形图与条形图
+
+### `setBarSetting(config)`
+
+设置柱形图和条形图的柱体宽度、分组间距、组内间距和圆角；帕累托图还可以设置是否显示数据点：
+
+```javascript
+.setBarSetting({
+    barWidth: 35,
+    barBorderRadius: 4
+})
+```
+
+也可以使用间距模式：
+
+```javascript
+.setBarSetting({
+    gapBetweenGroup: 40,
+    gapInGroup: 20,
+    barBorderRadius: 2
+})
+```
+
+| 字段 | 类型/范围 | 说明 |
+|---|---|---|
+| `barWidth` | 1–100 的整数 | 柱体宽度百分比 |
+| `gapBetweenGroup` | 0–100 的整数 | 分组间距百分比 |
+| `gapInGroup` | 0–100 的整数 | 分组内柱体间距百分比 |
+| `barBorderRadius` | 0–40 的整数 | 柱体圆角，单位 px |
+| `showPoint` | boolean | 是否显示帕累托曲线的数据点；仅 `PARETO` 支持 |
+
+`barWidth` 与 `gapBetweenGroup` / `gapInGroup` 是两种互斥的配置方式，不能在同一次调用中同时设置。调用 `barWidth` 时自动使用宽度模式；调用任一间距字段时自动切换到间距模式并清除已有 `barWidth`。`barBorderRadius` 可以与任一模式组合，也可以单独修改；新建图表仅在该图表的前端默认矩阵本来使用宽度模式时补充 `useBarWidth: true`，不会把其它柱图强制切换模式。
+
+该方法支持以下柱形图和条形图：
+
+- 柱形图：`BASIC_COLUMN`、`GROUPED_COLUMN`、`STACKED_COLUMN`、`STACKED_SPLIT_COLUMN`、`PERCENT_STACKED_COLUMN`、`GROUPED_COLUMN_WITH_LINE`、`STACKED_COLUMN_WITH_LINE`、`GROUPED_COLUMN_WITH_SYMBOL`、`STACKED_COLUMN_WITH_SYMBOL`、`BULLET_COLUMN`、`WATERFALL_COLUMN`、`PARETO`
+- 条形图：`BASIC_BAR`、`GROUPED_BAR`、`STACKED_BAR`、`STACKED_SPLIT_BAR`、`PERCENT_STACKED_BAR`、`BULLET_BAR`、`BUTTERFLY`
+
+蝴蝶图没有组内柱体间距配置，因此不支持 `gapInGroup`。`showPoint` 只对 `PARETO` 开放，其它柱形图或条形图传入该字段会产生 validation error。`attachCard()` 使用相同的图表类型和字段校验，并只合并显式传入的配置；切换到间距模式时保留未修改的颜色、圆角和未知历史字段。
+
+### `setStackSplitSetting(config)`
+
+设置分组堆积柱形图或条形图的堆积分组方式。配置独立写入
+`props.stackSplitSetting`，不会修改 `miscBarSetting` 中的柱宽、间距、圆角或其它历史字段。
+
+```javascript
+createCard(ChartType.STACKED_SPLIT_COLUMN, "渠道收入结构")
+    .addRow(f("月份"))
+    .addColumn(f("渠道"))
+    .addMetric(f("收入"))
+    .addMetric(f("利润"))
+    .setStackSplitSetting({ mode: "SPLIT_BY_METRICS" });
+```
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `mode` | `"SPLIT_NONE"` | 无分组，所有系列使用同一个堆积组 |
+| `mode` | `"SPLIT_BY_METRICS"` | 按度量分组；相同度量在不同对比项下堆积为一组，需要多个度量才产生分组效果 |
+| `mode` | `"SPLIT_BY_ATTR"` | 按对比分组；相同对比字段取值下的多个度量堆积为一组，需要 `column` 对比字段才产生分组效果 |
+| `mode` | `"SPLIT_INTERLACED"` | 按系列顺序交替分为两组 |
+| `mode` | `"SPLIT_EVEN"` | 按系列顺序将前半部分和后半部分均匀分为两组 |
+
+本方法只支持 `STACKED_SPLIT_COLUMN` 和 `STACKED_SPLIT_BAR`，普通堆积图、分组图及其它
+柱形图不支持。前端常量中的 `SPLIT_MANUAL` 是未来能力占位，当前属性面板没有开放，
+GuanVis 也不接受。按度量或按对比分组缺少对应字段时，前端保留配置但当前渲染不产生
+分组效果，因此 GuanVis 不会自动清除或报错。重复调用以及 `attachCard()` 都只覆盖 `mode`，
+并保留 `stackSplitSetting` 中未识别的历史字段。
+
+## 帕累托图
+
+### `setParetoSetting(config)`
+
+设置 `PARETO` 的累计曲线名称和百分比精度：
+
+```javascript
+createCard(ChartType.PARETO, "销售额帕累托图")
+    .addRow(f("客户"))
+    .addMetric(f("销售额"))
+    .setBarSetting({ showPoint: true })
+    .setParetoSetting({
+        curveName: "累计占比",
+        precision: 2
+    });
+```
+
+| 字段 | 类型/范围 | 说明 |
+|---|---|---|
+| `curveName` | 非空 string / `null` | 累计曲线名称；`null` 使用前端默认名称 |
+| `precision` | 0–6 的整数 | 累计百分比的小数位数 |
+
+设置 `precision` 时会写入完整的百分比格式配置，包括 `divideDataBy: 100`、`formatType: "PERCENTAGE"` 和对应的 `decimalPlaces`。该方法只支持 `PARETO`，可用于普通卡片、指标卡片和 `attachCard()`；重复调用或 attach 更新只覆盖显式传入的属性，并保留其它历史字段。
+
+## 图形填充
+
+### `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。