@guandata/guanvis 0.1.34 → 0.1.36

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

@@ -7,6 +7,7 @@
 | `defineDataset(dsId, columns, options?)` | 定义数据集 schema（由 init 命令生成）。第一个数据集自动暴露为 `global.DS`（dsId 字符串）。`options.displayType` 指定数据集类型（如 `"EXCEL"`, `"DATAFLOW"`），确保看板页面正确显示数据集图标 |
 | `field(dsId, fieldName, overrides?)` | 从 schema 构造字段引用，`dsId` 是字符串。可叠加 aggrType/alias/numberFormat/sortType/granularity 等 |
 | `f(fieldName, overrides?)` | `field(DS, fieldName, overrides)` 的简写，仅适用于**单数据集**场景 |
+| `chartField(zone, index)` | 按最终数据区和位置引用图表字段，用于 `setAuxiliaryLine()` 的计算辅助线 |
 | `calcField(name, formula, opts?)` | 创建卡片级计算字段（公式中用 `[字段名]` 引用字段）。`opts`: `calculationType`/`fdType`/`numberFormat`/`advCalc`/`fieldFormat` 等 |
 | `filterField(dsId, fieldName, filterType, filterValue?, opts?)` | 创建筛选字段（带 filterType/filterValue），传给 `.addFilter()` 使用 |
 | `getDataset(dsId)` | 获取已定义的数据集对象（返回对象，**不要**传给 `field()` 和 `bindDataset()`） |

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

@@ -5,7 +5,7 @@
 | 方法 | 说明 |
 |------|------|
 | `createCard(chartType, name)` | 创建 Card（chartType 必须使用 `ChartType.XXX` 枚举） |
-| `.setId(cardId)` | **必填**。设置资源 ID（严格 24 位字母数字，格式与后端 RandUtil.uuid 一致），支持多次上传覆盖更新。通过 `guanvis genid` 生成；如果生成或填写的 ID 以数字开头，建议重新生成一组，避免 BI 前端 `querySelector("#<id>")` 报错 |
+| `.setId(cardId)` | **必填**。新建资源 ID 应通过 `guanvis genid` 生成；新建校验格式为 `^[a-z][a-z0-9]{23}$`。支持同 ID 重复上传覆盖更新；checkout/attach 的已有资源 ID 原样保留，不校验格式 |
 | `.bindDataset(dsId)` | 绑定数据集（必填，dsId 必须在 defineDataset 中注册） |
 | `.addRow(field)` | 添加行维度（X 轴） |
 | `.addColumn(field)` | 添加列维度（按维度分组着色，如按地区/类别分色）。仅 `STACKED_COLUMN`、`GROUPED_COLUMN`、`GROUPED_BAR` 等多指标图表支持 |
@@ -21,18 +21,27 @@
 | `.addTooltip(field)` / `.addFilter(field)` | 提示/筛选 |
 | `.addSort(field)` / `.addSplit(field)` / `.addSize(field)` | 排序/拆分/大小；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
-| `.setSplitSetting({ rows, columns })` | 拆分行列数（默认各 3），需配合 `.addSplit(field)` |
-| `.setColorByColors(preset_or_config)` | colorBy 渐变色。传 `ColorByPreset.RedGreen` 等预设名称，或 `{ startColor, endColor, middleColor?, steps? }` 自定义 hex 颜色 |
-| `.setShapeColorType(type)` | 图形填充方式。默认不调用为纯色；支持 `ShapeColorType.TransparentGradient`，仅用于前端已支持的柱/条类图表 |
-| `.setShowTitle(show)` | 是否显示卡片标题；隐藏标题用 `.setShowTitle(false)` |
-| `.setShowLegend(show, position)` | 图例 |
-| `.setDataLabel(config)` | 数据标签 |
-| `.setAxis(config)` | 轴配置（见下方 Axis Config 详解） |
-| `.setTableSetting(config)` / `.setPieSetting(config)` | 特殊图表设置 |
-| `.setThemeColor(tcId, colors)` | 主题颜色 |
+| `.setSplitSetting(config)` | 拆分图配置 |
+| `.setColorByColors(preset_or_config)` | 渐变色配置 |
+| `.setBarSetting(config)` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setShapeColorType(type)` | 图形填充配置 |
+| `.setLineSetting(config)` | 折线显示配置 |
+| `.setCardSetting(config)` | 卡片背景、主题跟随、内边距和内容间距 |
+| `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 卡片标题显隐和样式配置 |
+| `.setShowLegend(show, position?)` / `.setChartLegend(config)` | 图例配置 |
+| `.setDataLabel(config)` / `.setMetricAdditionalDataLabel(config)` | 数据标签配置 |
+| `.setAxis(config)` | 坐标轴配置 |
+| `.setTooltip(config)` | 工具提示配置 |
+| `.setTableSetting(config)` / `.setTableCellMerge(config)` | 表格行为、视觉样式与单元格配置 |
+| `.setPieSetting(config)` / `.setPieCenterText(config)` | 饼图配置 |
+| `.setGrandTotal(config)` | 表格总计与小计配置 |
+| `.setSummary(field, options?)` / `.setSummaryStyle(config)` | 汇总指标及样式配置 |
+| `.setSpecialValue(config)` | 特殊值显示配置 |
+| `.setDynamicParameterDefaultValue(param(dpId), value, options?)` | 卡片级动态参数默认值；数组按逗号连接，默认 `inheritParent: false` |
+| `.setThemeColor(tcId, colors?, options?)` | 主题色、颜色覆盖和分类/顺序色板配置 |
 | `.setLimit(count)` | 数据行数限制 |
-| `.setConditionalFormat(config)` / `.setAuxiliaryLine(config)` | 条件格式/辅助线 |
-| `.setMainViceStyle(config)` | 设置主副指标内容样式，配置见“数值组与主副指标组” |
+| `.setConditionalFormat(config)` / `.setAuxiliaryLine(config)` | 条件格式和辅助线配置 |
+| `.setMainViceStyle(config)` | 主副指标样式配置 |
 | `.linkTo(target, config)` | 图表卡片点击联动；`target` 可传布局 index 或 cardId，详细规则见本节 Card Linkage |
 | `registerDrillPath(parentCardIndex, drillCards, config?)` | 全局函数，声明固定路径下钻，详细规则见本节 Card Drill |
 | `.setRawSettings(key, value)` | 原始设置 |
@@ -150,10 +159,21 @@ attachCard(CARD_ID, BASE_PATH)
 | `.addDynamicRow(name, fields, options?)` / `.addDynamicColumn(name, fields, options?)` | 添加指标平台动态维度组 |
 | `.addDynamicMetric(name, fields, options?)` / `.addDynamicMetricAdditional(name, fields, options?)` | 添加指标平台动态指标组 |
 | `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
-| `.setShowTitle()` / `.setShowLegend()` / `.setDataLabel()` / `.setAxis()` / `.setTableSetting()` / `.setRawSettings()` | 常用图表设置，和普通 CardBuilder 一致 |
-| `.setProps(obj)` / `.setRawProps(key, value)` | 设置指标卡片 `meta.chartMain.props` |
+| `.setCardSetting()` | 卡片背景、主题跟随、内边距和内容间距 |
+| `.setShowTitle()` / `.setCardTitleStyle()` | 卡片标题显隐和样式配置 |
+| `.setShowLegend()` / `.setChartLegend()` | 图例配置 |
+| `.setDataLabel()` / `.setMetricAdditionalDataLabel()` | 数据标签配置 |
+| `.setAxis()` / `.setAuxiliaryLine()` / `.setTooltip()` | 坐标轴、辅助线和工具提示配置 |
+| `.setLineSetting()` | 折线显示配置 |
+| `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setPieSetting()` / `.setPieCenterText()` | 饼图配置 |
+| `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格行为、视觉样式与汇总配置 |
+| `.setSplitSetting()` / `.setShapeColorType()` | 拆分图和图形填充配置 |
+| `.setRawSettings()` | 原始设置 |
+| `.setProps(obj)` | 设置指标卡片 `meta.chartMain.props` |
 | `.setConfig(obj)` / `.setRawConfig(key, value)` | 设置指标卡片 `meta.chartMain.config` |
-| `.setSummary(obj)` | 设置指标卡片 `meta.summary` |
+| `.setSummary(metric(...), options?)` | 设置指标卡片 `meta.summary`；旧的原始对象签名继续兼容 |
+| `.setSummaryStyle(config)` / `.setSpecialValue(config)` | 汇总样式和特殊值配置 |
 | `.setColumns(columns)` | 设置指标卡片 `content.columns` / `dsInfo.columns` |
 | `.addMetricAdditional()` / `.addColorBy()` / `.addSize()` / `.addTooltip()` / `.addSplit()` | 添加副轴、颜色、大小、提示、拆分区域字段 |
 | `.build()` | 构建指标卡片 |
@@ -183,7 +203,7 @@ var card = createCard(ChartType.BASIC_COLUMN, "区域销售额")
     .setShapeColorType(ShapeColorType.TransparentGradient);
 ```
 
-支持的图表：`BASIC_COLUMN`、`BASIC_BAR`、`GROUPED_COLUMN`、`GROUPED_BAR`、`GROUPED_COLUMN_WITH_LINE`、`GROUPED_COLUMN_WITH_SYMBOL`、`BULLET_BAR`。
+支持的图表：`BASIC_COLUMN`、`BULLET_COLUMN`、`BASIC_BAR`、`BULLET_BAR`、`GROUPED_COLUMN`、`GROUPED_BAR`、`GROUPED_COLUMN_WITH_LINE`、`GROUPED_COLUMN_WITH_SYMBOL`。
 
 多指标示例：
 
@@ -203,77 +223,9 @@ registerMetricChart(card.build());
 - `KPI_CARD`：展示主指标 + 对比指标，例如同比、环比、目标差异；使用时应同时配置 `.addMetric(...)` 和 `.addCompare(...)`。
 - 没有对比指标时优先用 `SINGLE_VALUE`，即使卡片放在看板顶部 KPI 区。
 
-#### Axis Config（`.setAxis(config)`）
+#### 图表属性配置
 
-`config` 对象可包含 `categoryAxis`（X 类目轴）、`mainAxis`（Y 主轴）、`secondaryAxis`（Y 副轴）：
-
-```javascript
-.setAxis({
-    categoryAxis: {
-        visible: true,
-        showTitle: true, title: "月份",
-        autoRotate: 45,
-        labelFontSize: 12,
-        showAxisLine: true
-    },
-    mainAxis: {
-        visible: true,
-        showTitle: true, title: "销售额",
-        min: 0, max: 100000,
-        autoExtremes: false,
-        showGridLine: true,
-        labelFontSize: 11
-    },
-    secondaryAxis: {
-        visible: true,
-        showTitle: true, title: "利润率",
-        labelFontSize: 11
-    }
-})
-```
-
-| 属性 | 适用轴 | 说明 |
-|------|--------|------|
-| `visible` | 所有 | 是否显示轴（`false` 隐藏轴） |
-| `showTitle` | 所有 | 是否显示轴标题 |
-| `title` | 所有 | 轴标题文字 |
-| `titleFontSize` / `titleColor` / `titleBold` | 所有 | 标题字体样式 |
-| `unit` | mainAxis/secondaryAxis | 单位（如"万元"），显示在标题旁 |
-| `min` / `max` | mainAxis/secondaryAxis | 固定轴范围（需 `autoExtremes: false`） |
-| `autoExtremes` | mainAxis/secondaryAxis | `true`（默认）自动计算范围 |
-| `showGridLine` | mainAxis/secondaryAxis | 是否显示网格线 |
-| `reverseValue` | mainAxis/secondaryAxis | 反转轴方向 |
-| `labelFontSize` / `labelColor` | 所有 | 刻度标签字体 |
-| `autoRotate` | categoryAxis | 标签旋转角度（0/45/90） |
-| `textLength` | categoryAxis | 标签截断字符长度 |
-| `step` | categoryAxis | 标签间隔（每 N 个显示一个） |
-| `showAxisLine` | categoryAxis | 是否显示轴线 |
-
-#### Auxiliary Line Config（`.setAuxiliaryLine(config)`）
-
-辅助线/参考线配置。`config` 对象按轴分组：
-
-```javascript
-.setAuxiliaryLine({
-    mainAxis: [
-        { name: "目标线", color: "#FF0000", valueType: "FIXED", fixedValue: "50000" },
-        { name: "平均值", color: "#0088FF", valueType: "CALCULATED", calculatedValue: "AVG" }
-    ],
-    secondaryAxis: [
-        { name: "基准线", color: "#00AA00", valueType: "FIXED", fixedValue: "0.3" }
-    ]
-})
-```
-
-每条辅助线的属性：
-
-| 属性 | 说明 |
-|------|------|
-| `name` | 辅助线名称（显示在图例中） |
-| `color` | 颜色（hex 字符串如 `"#FF0000"`） |
-| `valueType` | `"FIXED"`（固定值）或 `"CALCULATED"`（聚合计算） |
-| `fixedValue` | 当 `valueType="FIXED"` 时的固定数值（字符串格式） |
-| `calculatedValue` | 当 `valueType="CALCULATED"` 时的聚合类型：`"AVG"`（平均值）、`"MAX"`、`"MIN"`、`"MEDIAN"`、`"SUM"` |
+图表属性的字段、枚举、默认值和联动规则见 `references/chart-properties.md`。编写对应 setter 前必须先读该文档。
 
 #### Conditional Format Config（`.setConditionalFormat(config)`）
 
@@ -438,7 +390,7 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.removeLayoutItem(cardRef)` | 从当前 Page 根布局移除已放置的 card/selector/layout component；主要给动作级移动 API 使用 |
 | `.addFilterSelectorGroup(group)` | 添加一个筛选栏筛选器组 |
 | `.addFilterSelector(selectorId)` | 显式添加一个未分组的筛选栏 selector，并控制其与筛选器组的顺序 |
-| `.setFilterPanelLayout(config)` | 配置筛选栏的布局相关属性；见下方“筛选栏布局” |
+| `.setFilterPanelLayout(config)` | 配置筛选栏布局和视觉样式；见下方“筛选栏布局与视觉” |
 | `.setFilterLayout(items)` | 整体设置快捷筛选区的 selector / filter selectorGroup ID 列表；checkout 场景会覆盖 base `filterLayout` |
 | `.clearFilterLayout()` | 清空快捷筛选区；常用于把已有快捷筛选器改成画布内普通筛选器卡片 |
 | `.addFilterLayoutItem(items)` | 向快捷筛选区追加 selector / filter selectorGroup ID，已存在则跳过 |
@@ -452,12 +404,47 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.setBackgroundColor(color)` | 页面背景色 |
 | `.setCardMargin(margin)` | 卡片间距 |
 | `.setFineMode(enabled)` | 开启/关闭精细模式 |
-| `.setDashboardTitle(enabled, options?: { title?: string })` | 开启/关闭仪表板标题；未传 `title` 时默认使用 Page 名称 |
+| `.setDashboardTitle(enabled, options?)` | 开启/关闭仪表板标题，并设置标题文字、字体、背景、图标、高度和下边距；未传 `title` 时默认使用 Page 名称 |
 | `.setExportView(enabled, config?)` | 开启/关闭导出视图；`config.mode` 决定使用分页方向还是单页宽度 |
 | `.setWidthAdaptive(enabled, width?)` | 开启/关闭宽度自适应；默认宽度 1280 |
-| `.setLayoutSetting(config)` | 原始 layout 配置 |
+| `.setLayoutSetting(config)` | 设置 `page.meta.layoutSetting`。多次调用深度合并 |
 | `.build()` | 构建 |
 
+`setDashboardTitle()` 的 `options`：
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 标题文字；省略时使用 Page 名称 |
+| `font` | 字体、字形和对齐设置，见下表 |
+| `backgroundColor` | 背景色 |
+| `backgroundImage` | 背景图片，使用通用图片对象 |
+| `icon` | 标题图标，使用通用图片对象 |
+| `contentHeight` | 背景高度，整数 120～400 |
+| `paddingBottom` | 背景下边距，整数 0～100 |
+
+`font` 字段：
+
+| 字段 | 规则 |
+|------|------|
+| `fontFamily` | 非空字符串 |
+| `fontSize` | 整数 1～72 |
+| `color` | 颜色字符串 |
+| `bold` | 布尔值 |
+| `italic` | 布尔值 |
+| `underline` | 布尔值 |
+| `strikeThrough` | 布尔值 |
+| `textAlign` | `left` / `center` / `right` |
+
+通用图片对象：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示图片 |
+| `url` | `http(s)` 外链或已有 `/guandata-store/...` 地址 |
+| `uploadPath` | 本地图片路径；pack/publish 时作为 Page 附件上传 |
+| `sourceType` | `ImageSourceType.OUTSIDE_LINK` / `LOCAL_IMAGE` |
+| `renderType` | `ImageRenderType.RATIO` / `STRETCH` / `FIT_TO_CONTENT` |
+
 #### 导出视图与宽度自适应
 
 ```javascript
@@ -482,7 +469,66 @@ page.setWidthAdaptive(true, 1600);
 
 `setWidthAdaptive(true, width)` 的 `width` 会先静默四舍五入，再校验是否位于 `800 ~ 4096`；缺失或非法时使用 1280。宽度自适应不能与 `layoutType: "responsive"` 同时开启，但可以与导出视图同时开启。
 
-#### 筛选栏布局
+#### 页面布局与卡片视觉
+
+页面全局视觉配置直接写入 `layoutSetting`，不使用单独的 `setGlobalStyle()`：
+
+```javascript
+page.setLayoutSetting({
+    compact: true,
+    card: {
+        border: {
+            enabled: true,
+            width: 1,
+            color: "#D9D9D9",
+            radius: 6
+        },
+        boxShadow: {
+            enabled: true
+        }
+    },
+    page: {
+        background: {
+            image: {
+                enabled: true,
+                uploadPath: "./assets/page-background.png",
+                renderType: ImageRenderType.STRETCH
+            }
+        }
+    },
+    toolbarSettings: {
+        displayState: CardToolbarDisplayState.HIDDEN,
+        hiddenState: CardToolbarHiddenState.PARTIAL,
+        hiddenMenus: [
+            CardToolbarMenu.DATA_EXPLAIN,
+            CardToolbarMenu.INTRO
+        ]
+    }
+});
+```
+
+`setLayoutSetting()` 按自有属性递归稀疏合并，多次调用只覆盖相同叶子字段。例如先设置 `card.border.enabled`、再单独设置 `card.border.color`，两个值都会保留。未传字段不会被写成默认值：checkout Page 保留 base 中的同级配置，新建 Page 继续由主题和前端运行时补齐。
+
+只设置 `card.border.color` 是合法的，但不会自动开启边框；`enabled` 未设置时仍使用现有值或产品默认值 `false`。边框宽度范围为 `1 ~ 10`，圆角范围为 `0 ~ 20`，均接受范围内的有限数字。`card.boxShadow.enabled` 和 `compact` 必须为布尔值。
+
+页面背景图片位于 `page.background.image`：
+
+- `enabled`：是否显示背景图片；设为 `false` 只关闭显示，不清除已选择的图片。
+- `url`：外链或 BI 已上传图片地址。`http://...` / `https://...` 推断为 `ImageSourceType.OUTSIDE_LINK`；`/guandata-store/...` 是当前 BI 环境中已有的上传资源，推断为 `ImageSourceType.LOCAL_IMAGE`，直接引用而不会再次上传。跨环境迁移时优先使用 `uploadPath`，让图片随 Page 附件一起打包。
+- `uploadPath`：相对项目目录或绝对本地路径。`preview` 会校验文件，`pack` / `publish` 会作为 Page 附件上传并改写为稳定的 `/guandata-store/images/...` 地址。支持 jpg、jpeg、png、gif，并校验扩展名与真实文件类型一致。
+- `renderType`：`ImageRenderType.RATIO`、`STRETCH`、`FIT_TO_CONTENT`；选择新图片而未传时与当前产品一致，默认 `FIT_TO_CONTENT`。
+
+`url` 和 `uploadPath` 同时传入时优先使用 `url` 并产生 warning。新建 Page 只公开 `ImageSourceType.OUTSIDE_LINK`(1) 和 `LOCAL_IMAGE`(2)；checkout 未修改的历史来源值会原样保留。背景色仍可使用 `.setBackgroundColor()` 或设置 `layoutSetting.pageBackgroundColor`。
+
+工具栏配置与产品页面的“卡片工具栏”设置一致：
+
+- `displayState`：`CardToolbarDisplayState.DEFAULT` / `HIDDEN`。
+- `hiddenState`：隐藏工具栏时使用 `CardToolbarHiddenState.ALL` / `PARTIAL`；默认展示的新页面可以省略，checkout 从隐藏切回默认时必须显式传 `null`。
+- `hiddenMenus`：使用 `CardToolbarMenu` 中的公开菜单枚举；`ALL` 模式必须传空数组或省略。
+
+新建 Page 设置 `hiddenState` 或 `hiddenMenus` 时必须同时设置 `displayState`，设置 `displayState: HIDDEN` 时必须给出 `hiddenState`，避免产生前端无法生效的半完整组合。checkout 改变工具栏状态时按产品的整组更新语义填写关联字段：切回默认使用 `{ displayState: DEFAULT, hiddenState: null, hiddenMenus: [] }`，切换为全部隐藏时同时传 `hiddenMenus: []`。构建会在 base 深度合并后校验最终组合；未修改的历史配置和仅调整菜单的历史值仍可无损回写。
+
+#### 筛选栏布局与视觉
 
 ```javascript
 page.setFilterPanelLayout({
@@ -490,13 +536,45 @@ page.setFilterPanelLayout({
     spacing: FilterPanelSpacing.MIDDLE,
     padding: { top: 8, right: 12, bottom: 8, left: 12 },
     labelPosition: "top",
-    actionOrder: "right"
+    labelFont: { fontSize: 12, color: "#333333", bold: true },
+    controlStyle: FilterPanelControlStyle.OUTLINED,
+    controlFont: { fontSize: 12, color: "#222222", bold: false },
+    actionOrder: "right",
+    buttonColor: "#2E88FF",
+    buttonFont: { fontSize: 12, bold: true },
+    backgroundColor: "rgba(255, 255, 255, 0.9)",
+    backgroundImageEnabled: true,
+    backgroundImage: {
+        url: "https://example.com/filter-panel.png",
+        sourceType: ImageSourceType.OUTSIDE_LINK,
+        renderType: ImageRenderType.FIT_TO_CONTENT
+    }
 });
 ```
 
-所有字段均可选，多次调用按字段增量合并。
+所有字段均可选，多次调用按字段增量合并；`labelFont`、`controlFont` 和 `buttonFont` 也只覆盖显式传入的字体子字段。省略字段表示保留现值，显式传 `null` 表示删除该覆盖值并恢复产品/主题默认；字体对象的单个子字段也可传 `null`。例如 `{ backgroundColor: null, controlFont: { color: null } }` 会清除背景色和控件文字颜色覆盖。
 
-`padding` 支持 `top/right/bottom/left` 和`0 ~ 32`内的整数；非数字、`NaN`、`Infinity` 等非法值会产生 warning 并丢弃。
+补充规则：
+
+| 对象/字段 | 规则 |
+|-----------|------|
+| `padding` | 支持 `top`、`right`、`bottom`、`left`，值为整数 0～32；非法值产生 warning 并丢弃 |
+| `labelFont` | 支持 `fontFamily`、`fontSize`、`color`、`bold`、`italic`、`underline`；字号为整数 9～20 |
+| `controlFont` | 支持 `fontFamily`、`fontSize`、`color`、`bold`、`italic` |
+| `buttonFont` | 支持 `fontFamily`、`fontSize`、`bold`、`italic`、`underline`；文字颜色由产品固定 |
+| `buttonColor` | 按钮强调色 |
+
+`backgroundImage`：
+
+| 项目 | 规则 |
+|------|------|
+| 完整对象 | 新建 Page 最终必须包含 `url`、`sourceType`、`renderType` |
+| 稀疏更新 | 完整设置后可只修改单个字段；checkout 与 base 合并后的对象必须完整 |
+| `url` | 非空字符串；本地图片使用已有 BI 资源路径 |
+| `sourceType` | `ImageSourceType.OUTSIDE_LINK` / `LOCAL_IMAGE` |
+| `renderType` | `ImageRenderType.RATIO` / `STRETCH` / `FIT_TO_CONTENT` |
+| 关闭显示 | 设置 `backgroundImageEnabled: false` |
+| 恢复默认 | 同时将 `backgroundImageEnabled`、`backgroundImage` 设为 `null` |
 
 | 字段 | 可选值 | 写入 `page.meta.filterLayoutSettings` |
 |------|--------|----------------------------------------|
@@ -504,9 +582,17 @@ page.setFilterPanelLayout({
 | `spacing` | `FilterPanelSpacing.SMALL` / `MIDDLE` / `LARGE` | `selPadding` |
 | `padding` | `{ top?, right?, bottom?, left? }` | `paddingValue` |
 | `labelPosition` | `"top"` / `"left"` | `selName.position` |
+| `labelFont` | 字体对象 | `selName.font` |
+| `controlStyle` | `FilterPanelControlStyle.BORDERLESS` / `OUTLINED` / `FILLED` | `selStyle.variant` |
+| `controlFont` | 字体对象 | `selStyle.font` |
 | `actionOrder` | `"left"` / `"right"` | `opStyle.order` |
+| `buttonColor` | 非空颜色字符串 | `button` |
+| `buttonFont` | 字体对象 | `opStyle.font` |
+| `backgroundColor` | 非空颜色字符串 | `background` |
+| `backgroundImageEnabled` | `true` / `false` | `backgroundImageEnabled` |
+| `backgroundImage` | `{ url, sourceType, renderType }` | `backgroundImage` |
 
-该方法只覆盖上述布局字段。checkout 会在 `.guanvis/base/page.json` 保留完整线上配置，pack/publish 时在此基础上合并布局补丁，因此颜色、字体和背景不会丢失；新页面的视觉字段由主题补齐。
+该方法只覆盖表中字段。checkout 会把这些布局和视觉字段重新生成到 `page.js`，同时在 `.guanvis/base/page.json` 保留完整线上配置；pack/publish 在基线上稀疏合并显式补丁，未知历史字段不会丢失。新页面未显式设置的视觉字段仍由主题补齐。
 
 ### AreaTitleBuilder
 
@@ -525,6 +611,9 @@ page.setFilterPanelLayout({
 | `.setBackgroundColor(color)` | 背景色 |
 | `.setShowBgImage(boolean)` | 是否显示背景图 |
 | `.setShowIcon(boolean)` | 是否显示图标 |
+| `.setFontStyle(style)` | 稀疏设置字体、字形和对齐方式 |
+| `.setBackgroundImage(image)` | 设置背景图片；支持外链、已有 Store 地址或本地 `uploadPath` |
+| `.setIcon(image)` | 设置图标图片；图片规则同上 |
 | `.build()` | 构建 areaTitle result |
 
 ```javascript
@@ -553,12 +642,42 @@ registerPage(page.build());
 | `.setId(cardGroupId)` | **必填**。设置卡片组 ID，必须以 `cardGroup_` 开头 |
 | `.setRawStyle(style)` | checkout 保留线上 style 用；新建工程优先用 `.setShowTitle()` 等语义化方法 |
 | `.setShowTitle(boolean)` | 是否显示标题，默认 `true` |
+| `.setTitleStyle(config)` | 设置标题字体、背景/图标及上下边框 |
+| `.setBackgroundStyle({ color?, image? })` | 设置卡片组自身背景色和背景图 |
+| `.setCardSpacing(type, value?)` | 设置组内卡片间距；type 使用 `LayoutMarginType.NONE/SPACE/DIVIDE` |
+| `.setDividingLineStyle({ color? })` | 设置分割线颜色；分割线模式由 `.setCardSpacing(LayoutMarginType.DIVIDE)` 开启 |
 | `.addRow(specs, height?)` | 在组内按行放置卡片，写法同 `PageBuilder.addRow()` |
 | `.addFullWidthCard(cardRef, height?)` | 在组内放一张满宽卡片 |
 | `.placeCard(cardRef, x, y, w, h)` | 在组内精确放置卡片 |
 
 卡片组内布局方法同 `PageBuilder`，使用 `cardRef`。
 
+`setTitleStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示标题 |
+| `font` | 标题字体、字形和对齐 |
+| `backgroundColor` | 标题背景色 |
+| `backgroundImage` | 标题背景图 |
+| `icon` | 标题图标 |
+| `topStrip` | 顶部边框设置 |
+| `bottomStrip` | 底部边框设置 |
+
+`topStrip`、`bottomStrip`：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示边框 |
+| `width` | 2 / 4 / 6 / 8 |
+| `backgroundColor` | 边框颜色 |
+
+`setDividingLineStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `color` | 分割线颜色 |
+
 ```javascript
 var salesGroup = createCardGroup("销售概览")
     .setId("cardGroup_AbCdEf")
@@ -656,11 +775,37 @@ tab 用于把页面中的卡片分到多个 panel。适合同一主题下多组
 | `.setLabelStyle(style)` | 设置标签样式：`TabLabelStyle.UNDERLINE`（默认）、`CARD`、`CAPSULE`、`TRAPEZOID` |
 | `.setAlignment(alignment)` | 设置标签对齐：`TabAlignment.LEFT`（默认）、`CENTER`、`RIGHT` |
 | `.setTabSize(size)` | 设置标签宽度：`TabSizeType.MAX_CONTENT`（默认）或 `FLEX` |
+| `.setTitleStyle(config)` | 设置 Tab 总标题及其字体、位置、背景和图标 |
+| `.setSelectedTextStyle(style)` / `.setUnselectedTextStyle(style)` | 设置选中/未选中页签文字样式 |
+| `.setTabColor(color)` | 设置非下划线页签的主体颜色 |
+| `.setBackgroundStyle({ color?, image? })` | 设置页签栏背景色和背景图 |
 | `panel.setId(panelId)` | **必填**。设置 panel ID，必须以 `panel_` 开头且同一页面内唯一。建议用 `guanvis gen-layout-id panel` 生成 |
+| `panel.setPanelStyle(config)` | 设置当前 panel 的背景、卡片间距和分割线颜色 |
 | `panel.addRow(specs, height?)` | 在 panel 内按行放置卡片，写法同 `PageBuilder.addRow()` |
 | `panel.addFullWidthCard(cardRef, height?)` | 在 panel 内放一张满宽卡片 |
 | `panel.placeCard(cardRef, x, y, w, h)` | 在 panel 内精确放置卡片 |
 
+Tab 的 `setTitleStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示总标题 |
+| `title` | 总标题文字 |
+| `position` | `TabTitlePosition.TOP` / `TabTitlePosition.LEFT` |
+| `font` | 标题字体、字形和对齐 |
+| `backgroundColor` | 标题背景色 |
+| `backgroundImage` | 标题背景图 |
+| `icon` | 标题图标 |
+
+`panel.setPanelStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `backgroundColor` | panel 背景色 |
+| `backgroundImage` | panel 背景图 |
+| `margin` | `{ type, value }`；`type: LayoutMarginType.DIVIDE` 开启分割线模式，`SPACE` 的 value 为整数 1～20 |
+| `dividingLineColor` | 分割线颜色 |
+
 **使用示例**：
 
 ```javascript
@@ -1570,6 +1715,8 @@ project/
 | `FieldType` | `STRING`, `INT`, `LONG`, `DOUBLE`, `FLOAT`, `DATE`, `BOOL`, `DECIMAL` | 字段数据类型 |
 | `SortOrder` | `ASC`, `DESC` | 排序方向 |
 | `Granularity` | `NONE`, `YEAR`, `QUARTER`, `MONTH`, `WEEK`, `DAYOFWEEK`, `DAY`, `HOUR`, `MINUTE`, `SECOND` | 日期粒度 |
+| `GrandTotalPosition` | `LEFT`, `RIGHT`, `TOP`, `BOTTOM` | 表格总计位置；行总计用左右，列总计用上下 |
+| `ContentSpaceSize` | `SMALL`, `MIDDLE`, `LARGE` | 卡片内容间距 |
 | `DynamicFieldOrder` | `PRESET`, `CLICK` | 动态字段默认顺序；`PRESET` 按候选顺序，`CLICK` 按用户选择顺序 |
 | `FilterType` | `IN`, `NOT_IN`, `GT`, `GE`, `LT`, `LE`, `EQ`, `NE`, `BT`（区间）, `CONTAINS`, `NOT_CONTAINS`, `STARTSWITH`, `ENDSWITH`, `IS_NULL`, `NOT_NULL` | 筛选条件类型 |
 | `FilterLevel` | `DETAIL`（明细）, `AGGREGATION`（聚合）, `RESULT`（结果） | 筛选级别 |
@@ -1577,6 +1724,8 @@ project/
 | `SelectorType` | `DS_ELEMENTS`（默认）, `DS_INTERVAL`, `CALENDAR`, `TIME_MACRO` | 筛选器类型 |
 | `SelectorDisplay` | `SEARCH_LIST`（单选下拉）, `SEARCH_BOX`（多选下拉）, `CHECKBOX`（复选框）, `RADIO`（单选框）, `BUTTON_GROUP`（按钮组） | 筛选器展示类型，不设置时根据 multiSelect 自动推断 |
 | `SelectorDefaultType` | `FIRST_PICK`, `FIXED_VALUE`, `ALL`（默认，全部/不筛选） | 筛选器默认值类型 |
+| `TabTitlePosition` | `TOP`, `LEFT` | Tab 总标题位置 |
+| `LayoutMarginType` | `NONE`, `SPACE`, `DIVIDE` | Tab panel 与卡片组的卡片间距模式 |
 | `CardType` | `CHART`(0), `TEXT`(1), `IFRAME`(2), `PICTURE`(4), `SELECTOR`(6), `LAYOUT`(9) | 卡片类型（内部使用，通常不需要直接引用） |
 | `ImageSourceType` | `OUTSIDE_LINK`(1), `LOCAL_IMAGE`(2) | 图片来源类型 |
 | `ImageRenderType` | `RATIO`(1，原比例), `STRETCH`(2，拉伸填满), `FIT_TO_CONTENT`(3，自适应内容) | 图片渲染模式 |