@guandata/guanvis 0.1.37 → 0.1.38

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @guandata/guanvis 0.1.38 - 2026-08-13
+
+- 新增 `live` 系列命令和完整实时项目工作流，可对线上仪表板执行受控、可回溯的创建与维护操作。
+- 大幅扩展指标图、进度图、迷你图、地图、气泡图、雷达图、箱线图、热力图等专项图表属性，复杂看板的表达能力更完整。
+- 新增系统图标查询与引用能力，指标图等场景可直接使用 BI 环境中的图标资源。
+- 增强实时项目输入校验、已有仪表板附着、初始化、覆盖保护和任务诊断，减少误操作并提升问题定位效率。
+
 ## @guandata/guanvis 0.1.37 - 2026-08-07
 
 - 发布前新增字段 `fdId` 线上活性校验，提前发现无效字段绑定，降低发布失败风险。

package/README.md

@@ -54,6 +54,12 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.38
+
+- 新增 `live` 系列命令和完整实时项目工作流，可受控地创建与维护线上仪表板。
+- 扩展指标图、进度图、迷你图、地图、气泡图、雷达图、箱线图、热力图等专项图表属性。
+- 支持查询和引用 BI 环境中的系统图标，并增强输入校验、覆盖保护和任务诊断。
+
 ### @guandata/guanvis 0.1.37
 
 - 完善筛选器、页面布局和组合图配置，仪表板搭建更灵活。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"

package/skills/guanvis/SKILL.md

@@ -32,6 +32,28 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 - **资源包安全红线**：Agent 只编辑 DSL 源文件；资源包 ZIP 是 `guanvis pack/publish` 的派生产物，不手工生成、解包修改或重打包。`guanvis upload` 只允许上传 `guanvis pack` 原样生成的 ZIP。若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先停下来说明风险并确认方案，不要直接改 ZIP。
 - 发布后优先用 `guancli page get/card get` 回读结构与配置；`guanvis screenshot` 仅在明确需要视觉质量判断且模型支持图像理解时使用（额外消耗 token），不作默认闭环步骤。
 
+### 桌面端对话式实时构建
+
+桌面安全 Runtime 同时提供 `connected.guancli`、`connected.guanvis` 与右侧可见的 `browser` 时，使用 `guanvis live` 做无需持久化本地工程的对话式构建：
+
+1. 用 `connected.guancli` 查询数据集、页面与卡片，真实取数走 `card preview`；不要向用户索取 Token。
+2. 正式交付或需要任一完整能力时，把与普通工程完全相同的 `schema.js`、`card_*.js`、`selector_*.js`、`page.js`、主题/设计规则及二进制资产组成 version=1 JSON 内存工程，先调 `live project validate`，再把同一份 stdin 交给 `live project publish`。文本文件用 `content`；直接调用 CLI 时二进制用 `base64`，桌面安全 Runtime 中上传的图片或 xlsx 必须通过 `reference.list` 取得 ID，再用 `asset_refs:[{"reference_id":<id>,"path":"<工程内路径>"}]` 交给 Host 注入，模型不要读取或生成大段 base64。路径必须在工程内且大小写不能冲突。
+3. 只有需求严格落在 KPI、基础/分组/堆叠柱、基础折线、明细表且强调最低延迟时，才用 `live page/card` 批量建卡并一次 apply；不得用 P0 命令降级模拟筛选器、文本、图片、地图、自定义图表或复杂报表。
+4. publish/page create 返回页面 URL 后用 `browser.open` 在右侧打开；每次 publish/apply/patch/remove/delete 后 `browser.navigate(reload)`，再用 snapshot/screenshot 回读，并以 `guancli page get/card preview` 验证结构和真实数据。
+5. `live project` 复用普通 GuanVis 的完整 DSL、主题、设计规则、校验和 transfer 发布引擎；不允许宿主文件参数、绝对路径、`..` 或文件 URI。新建资源必须显式 setId，覆盖同 ID Page 仍需用户明确确认后使用 `--allow-overwrite`。
+6. `live card delete` 与 `live page remove-card` 仅在用户明确要求删除/移除时调用；前者删除实体，后者只移出布局。
+
+完整内存工程最小契约：
+
+```json
+{"version":1,"files":[
+  {"path":"schema.js","content":"defineDataset(...)"},
+  {"path":"card_01.js","content":"var card = createCard(...); registerCard(card.build());"},
+  {"path":"page.js","content":"var page = createPage(...); registerPage(page.build());"},
+  {"path":"assets/logo.png","base64":"..."}
+]}
+```
+
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
 **Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是"base JSON + 链式 DSL 操作 = 目标 JSON"，不修改 base JSON，重复执行产出相同 payload。zone 修改优先 `update*/patch*/add*/remove*/move*`（整 zone 重建的 `set*/clear*` 会触发 warning）；已有 selector 用 `.setSelectorSetting()` 修改筛选器配置，用 `.addLink()/.removeLink()/.clearLinks()` 修改联动，禁止借配置入口改变 selector 类型或重新绑定字段；自定义图表内容编辑仅限 SDK/ECHARTS_LITE（编辑 `charts/` 下反编译源文件），COMPLEX_REPORT/PLUGIN/PLUGIN_LITE/REPORT_FORM 调内容编辑 API 直接报错。发布前用 `guanvis diff <dir>` 或 preview 的 `changeSummary` 查看影响面；没有 DSL 操作覆盖的需求先扩展 DSL，不改 `.guanvis` JSON。完整操作语义（zone/筛选区/筛选栏画布互移等）见 `references/checkout-editing.md` §3。
@@ -203,9 +225,13 @@ guanvis check-dataset-switch . --from <oldDs> --to <newDs> --mode full   # 详
 # 仪表板主题（详见 references/theme.md）
 guanvis theme preference --keywords "..." --sync   # 另有 --theme-id / --clear；theme list/show/sync
 
-# 单张图表主题色
+# 获取当前环境中可用的图表主题色
 guanvis theme-color list
 guanvis theme-color sync -d ./my_dashboard
+
+# 获取当前 BI 环境可用的图标
+guanvis icon list
+guanvis icon list --group default_line -f json
 ```
 
 **多子目录工程**：每个子目录是独立工程，preview/pack/publish/`theme *` 必须 `cd` 进各子目录分别执行、各出各的资源包；根目录直接运行时若任一子目录有 `themes/` 会拒绝执行并打印 cd 提示。

package/skills/guanvis/references/api-reference.md

@@ -4,7 +4,7 @@
 
 | 函数 | 说明 |
 |------|------|
-| `defineDataset(dsId, columns, options?)` | 定义数据集 schema（由 init 命令生成）。第一个数据集自动暴露为 `global.DS`（dsId 字符串）。`options.displayType` 指定数据集类型（如 `"EXCEL"`, `"DATAFLOW"`），确保看板页面正确显示数据集图标 |
+| `defineDataset(dsId, columns, options?)` | 定义数据集 schema（由 init 命令生成）。第一个数据集自动暴露为 `global.DS`（dsId 字符串）。`options.displayType` 指定数据集类型（如 `"EXCEL"`, `"DATAFLOW"`）；`options.sourceType` 保存数据源运行方式，用于直连能力限制等校验 |
 | `field(dsId, fieldName, overrides?)` | 从 schema 构造字段引用，`dsId` 是字符串。可叠加 aggrType/alias/numberFormat/sortType/granularity 等 |
 | `f(fieldName, overrides?)` | `field(DS, fieldName, overrides)` 的简写，仅适用于**单数据集**场景 |
 | `chartField(zone, index)` | 按最终数据区和位置引用图表字段，用于 `setAuxiliaryLine()` 的计算辅助线 |

package/skills/guanvis/references/builder-reference.md

@@ -25,8 +25,18 @@
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
 | `.setSplitSetting(config)` | 拆分图配置 |
 | `.setColorByColors(preset_or_config)` | 渐变色配置 |
-| `.setBarSetting(config)` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setBarSetting(config)` | 柱形图/条形图的柱体宽度、间距和圆角配置；帕累托图还支持数据点显隐 |
+| `.setStackSplitSetting(config)` | 分组堆积柱形图/条形图的堆积分组模式 |
 | `.setWaterfallSetting(config)` | 瀑布图的正负值颜色和累计值配置 |
+| `.setParetoSetting(config)` | 帕累托图的累计曲线名称和百分比精度配置 |
+| `.setMapSetting(config)` | 地图专属属性配置 |
+| `.setBubbleSetting(config)` | 气泡半径配置 |
+| `.setRadarSetting(config)` | 雷达图显示配置 |
+| `.setBoxPlotSetting(config)` | 箱线图配置 |
+| `.setHeatMapSetting(config)` | 热力图配置 |
+| `.setSingleValueSetting(config)` / `.setKPISetting(config)` | 指标卡、对比指标卡配置 |
+| `.setProgressBarSetting(config)` / `.setProgressPieSetting(config)` | 进度条、进度环配置 |
+| `.setActivityGaugeSetting(config)` / `.setLiquidGaugeSetting(config)` / `.setSolidGaugeSetting(config)` | 活动仪表盘、水波图、实心仪表盘配置 |
 | `.setShapeColorType(type)` | 图形填充配置 |
 | `.setLineSetting(config)` | 折线显示配置 |
 | `.setComboSetting(config)` | 组合图的显示方式、折线或符号样式配置 |
@@ -34,9 +44,11 @@
 | `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 卡片标题显隐和样式配置 |
 | `.setShowLegend(show, position?)` / `.setChartLegend(config)` | 图例配置 |
 | `.setDataLabel(config)` / `.setMetricAdditionalDataLabel(config)` | 数据标签配置 |
+| `.setTreemapDataLabel(config)` / `.setFunnelDataLabel(config)` | 矩形树图分层数据标签、漏斗图各类数据标签配置 |
 | `.setAxis(config)` | 坐标轴配置 |
 | `.setTooltip(config)` | 工具提示配置 |
 | `.setTableSetting(config)` / `.setTableCellMerge(config)` | 表格行为、视觉样式与单元格配置 |
+| `.setMiniChart(selector, config)` / `.setMiniChartSetting(selector, config)` | 设置透视表数值字段的迷你图类型、维度及字段 key 对应样式 |
 | `.setPieSetting(config)` / `.setPieCenterText(config)` | 饼图配置 |
 | `.setGrandTotal(config)` | 表格总计与小计配置 |
 | `.setSummary(field, options?)` / `.setSummaryStyle(config)` | 汇总指标及样式配置 |
@@ -167,13 +179,25 @@ attachCard(CARD_ID, BASE_PATH)
 | `.setShowTitle()` / `.setCardTitleStyle()` | 卡片标题显隐和样式配置 |
 | `.setShowLegend()` / `.setChartLegend()` | 图例配置 |
 | `.setDataLabel()` / `.setMetricAdditionalDataLabel()` | 数据标签配置 |
+| `.setTreemapDataLabel()` / `.setFunnelDataLabel()` | 矩形树图分层数据标签、漏斗图各类数据标签配置 |
 | `.setAxis()` / `.setAuxiliaryLine()` / `.setTooltip()` | 坐标轴、辅助线和工具提示配置 |
 | `.setLineSetting()` | 折线显示配置 |
 | `.setComboSetting()` | 组合图的显示方式、折线或符号样式配置 |
-| `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置；帕累托图还支持数据点显隐 |
+| `.setStackSplitSetting()` | 分组堆积柱形图/条形图的堆积分组模式 |
 | `.setWaterfallSetting()` | 瀑布图的正负值颜色和累计值配置 |
+| `.setParetoSetting()` | 帕累托图的累计曲线名称和百分比精度配置 |
+| `.setMapSetting()` | 地图专属属性配置 |
+| `.setBubbleSetting()` | 气泡半径配置 |
+| `.setRadarSetting()` | 雷达图显示配置 |
+| `.setBoxPlotSetting()` | 箱线图配置 |
+| `.setHeatMapSetting()` | 热力图配置 |
+| `.setSingleValueSetting()` / `.setKPISetting()` | 指标卡、对比指标卡配置 |
+| `.setProgressBarSetting()` / `.setProgressPieSetting()` | 进度条、进度环配置 |
+| `.setActivityGaugeSetting()` / `.setLiquidGaugeSetting()` / `.setSolidGaugeSetting()` | 活动仪表盘、水波图、实心仪表盘配置 |
 | `.setPieSetting()` / `.setPieCenterText()` | 饼图配置 |
 | `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格行为、视觉样式与汇总配置 |
+| `.setMiniChart()` / `.setMiniChartSetting()` | 设置透视表数值字段的迷你图和样式；支持已有 MetricChart 增量编辑 |
 | `.setSplitSetting()` / `.setShapeColorType()` | 拆分图和图形填充配置 |
 | `.setRawSettings()` | 原始设置 |
 | `.setProps(obj)` | 设置指标卡片 `meta.chartMain.props` |
@@ -1773,6 +1797,10 @@ project/
 | `AggrType` | `SUM`, `AVG`, `COUNT`(=CNT), `COUNT_DISTINCT`(=CNT_DISTINCT), `MIN`, `MAX` | 聚合类型 |
 | `FieldType` | `STRING`, `INT`, `LONG`, `DOUBLE`, `FLOAT`, `DATE`, `BOOL`, `DECIMAL` | 字段数据类型 |
 | `SortOrder` | `ASC`, `DESC` | 排序方向 |
+| `MiniChartType` | `LINE`, `COLUMN`, `PIE`, `PROGRESS` | 透视表字段迷你图类型 |
+| `MiniChartSort` | `ASC`, `DESC` | 迷你图维度排序方向 |
+| `MapRegion` | `COUNTRY`, `PROVINCE`, `CITY`, `AUTO` | 中国行政类地图的显示范围 |
+| `MapSymbol` | `CIRCLE`, `DIAMOND`, `SQUARE`, `TRIANGLE`, `TRIANGLE_DOWN` | 符号行政地图的内置符号 |
 | `Granularity` | `NONE`, `YEAR`, `QUARTER`, `MONTH`, `WEEK`, `DAYOFWEEK`, `DAY`, `HOUR`, `MINUTE`, `SECOND` | 日期粒度 |
 | `GrandTotalPosition` | `LEFT`, `RIGHT`, `TOP`, `BOTTOM` | 表格总计位置；行总计用左右，列总计用上下 |
 | `ContentSpaceSize` | `SMALL`, `MIDDLE`, `LARGE` | 卡片内容间距 |

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

@@ -130,6 +130,389 @@
 
 `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?)`
@@ -428,6 +811,109 @@ createMetricChart(ChartType.PIVOT_TABLE, "销售指标")
 
 两个方法的开关相互独立。`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)`
@@ -793,6 +1279,137 @@ Tooltip 展示哪些数据字段由 `.addTooltip(field)` 控制；`setTooltip()`
 })
 ```
 
+### 表格迷你图
+
+迷你图只支持透视表 `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)`
 
 设置透视表单元格合并。
@@ -1033,11 +1650,167 @@ attachCard(CARD_ID, BASE_PATH)
 
 该方法支持普通卡片、指标卡片和 `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({
@@ -1062,6 +1835,7 @@ attachCard(CARD_ID, BASE_PATH)
 | `gapBetweenGroup` | 0–100 的整数 | 分组间距百分比 |
 | `gapInGroup` | 0–100 的整数 | 分组内柱体间距百分比 |
 | `barBorderRadius` | 0–40 的整数 | 柱体圆角，单位 px |
+| `showPoint` | boolean | 是否显示帕累托曲线的数据点；仅 `PARETO` 支持 |
 
 `barWidth` 与 `gapBetweenGroup` / `gapInGroup` 是两种互斥的配置方式，不能在同一次调用中同时设置。调用 `barWidth` 时自动使用宽度模式；调用任一间距字段时自动切换到间距模式并清除已有 `barWidth`。`barBorderRadius` 可以与任一模式组合，也可以单独修改；新建图表仅在该图表的前端默认矩阵本来使用宽度模式时补充 `useBarWidth: true`，不会把其它柱图强制切换模式。
 
@@ -1070,7 +1844,59 @@ attachCard(CARD_ID, BASE_PATH)
 - 柱形图：`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`。`attachCard()` 使用相同的图表类型和字段校验，并只合并显式传入的配置；切换到间距模式时保留未修改的颜色、圆角和未知历史字段。
+蝴蝶图没有组内柱体间距配置，因此不支持 `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 更新只覆盖显式传入的属性，并保留其它历史字段。
 
 ## 图形填充
 

package/skills/guanvis/references/metric-chart-reference.md

@@ -116,7 +116,7 @@ registerMetricChart(card.build());
 | `subtotalSetting.aggrType` | 小计聚合方式 |
 | `advCalc` | 高级计算，如排名、占比 |
 | `filter` | 指标业务限定 |
-| `miniChart` | 表格内迷你图 |
+| `miniChart` | 表格内迷你图的前端字段配置；不要直接手写，使用 `.setMiniChart()`，样式使用 `.setMiniChartSetting()` |
 | `formula` / `formulaField` | 复合/原子拆分公式 |
 | `parentFdName` / `granularity` | 日期派生字段信息 |
 | `key` / `subZoneId` / `dzId` | 字段实例 key / 子区域 / 动态字段 |
@@ -179,15 +179,23 @@ registerMetricChart(card.build());
 | `.setSpecialValue(config)` | 设置特殊值显示；仅支持前端开放该属性的图表类型 |
 | `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 设置卡片标题显隐与样式 |
 | `.setColumns(columns)` | 设置 `content.columns` 与 dsInfo.columns |
-| `.setTableSetting(obj)` | 设置表格行为与视觉样式；详细字段见 `chart-properties.md` |
+| `.setTableSetting(obj)` | 设置表格行为与视觉样式 |
 | `.setTableCellMerge(obj)` | 设置透视表单元格合并 |
 | `.setPieSetting(obj)` / `.setPieCenterText(obj)` | 设置饼图属性 |
+| `.setTreemapDataLabel(obj)` / `.setFunnelDataLabel(obj)` | 设置矩形树图分层数据标签、漏斗图各类数据标签 |
 | `.setSplitSetting(obj)` | 设置拆分图属性 |
-| `.setBarSetting(obj)` | 设置柱形图/条形图的柱体宽度、间距和圆角；详细字段见 `chart-properties.md` |
-| `.setWaterfallSetting(obj)` | 设置瀑布图的正负值颜色和累计值；详细字段见 `chart-properties.md` |
+| `.setBarSetting(obj)` | 设置柱形图/条形图的柱体宽度、间距和圆角；帕累托图还支持数据点显隐 |
+| `.setStackSplitSetting(obj)` | 设置分组堆积柱形图/条形图的堆积分组模式 |
+| `.setWaterfallSetting(obj)` | 设置瀑布图的正负值颜色和累计值 |
+| `.setParetoSetting(obj)` | 设置帕累托图的累计曲线名称和百分比精度 |
+| `.setMapSetting(obj)` | 设置地图专属属性 |
+| `.setBubbleSetting(obj)` | 设置气泡半径 |
+| `.setRadarSetting(obj)` | 设置雷达图显示属性 |
+| `.setBoxPlotSetting(obj)` | 设置箱线图属性 |
+| `.setHeatMapSetting(obj)` | 设置热力图属性 |
 | `.setShapeColorType(type)` | 设置图形填充 |
 | `.setLineSetting(obj)` | 设置折线显示 |
-| `.setComboSetting(obj)` | 设置组合图的显示方式、折线或符号样式；详细字段见 `chart-properties.md` |
+| `.setComboSetting(obj)` | 设置组合图的显示方式、折线或符号样式 |
 | `.setAuxiliaryLine(obj)` | 设置辅助线 |
 | `.setGrandTotal(obj)` | 设置透视表/分组表行列总计及样式；字段小计通过 `metricDim()` / `metric()` overrides 配置 |
 | `.setFreeDrill(enabled, position)` | 设置 `config.freeDrillConfig` |

package/skills/guanvis/references/theme.md

@@ -85,8 +85,8 @@ AI 选择主题时不要把租户主题列表里的默认“浅色”/“深色
 
 `design-rule.json` 只用于两类配置：
 
-- `componentDefaults`：卡片静态默认规则，例如 `SINGLE_VALUE` 单指标卡、`KPI_CARD` 对比指标卡的默认布局与样式。指标卡/对比指标卡布局类配置只通过这里统一配置，不放进 `themePatch`，也不提供单张卡片 props 透出。
-- `themePatch`：仅用于主题已开放的主题配置，例如页面背景、标题样式、主题色等；不要把指标卡布局类配置放进 `themePatch`。
+- `componentDefaults`：卡片静态默认规则，用于统一项目内同类卡片的默认布局与样式，不属于主题覆盖。
+- `themePatch`：仅用于主题已开放的配置，例如页面背景、标题样式、主题色等；卡片自身的专属属性不放在这里。
 
 数据格式不放在 `design-rule.json` 里，数值/百分比格式由字段类型与图表区域规则自动处理。