@guandata/guanvis 0.1.23 → 0.1.24

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guanvis 0.1.24 - 2026-06-09
+
+- 新增 area title 和 card group 布局能力，支持在页面中组织分区标题和卡片分组。
+- `gen-layout-id` 支持生成 area title 相关布局 ID，便于构建复杂页面布局。
+- 增强布局 DSL、打包导出和页面布局校验，补充大量布局场景测试。
+
 ## @guandata/guanvis 0.1.23 - 2026-06-04
 
 - 新增指标卡片构建能力，支持基于指标配置生成图表卡片，并补充 `metric init` 和指标图表参考文档。

package/README.md

@@ -18,6 +18,8 @@ guanvis genid 5
 # 生成布局组件 ID
 guanvis gen-layout-id tab
 guanvis gen-layout-id panel 3 --length 8
+guanvis gen-layout-id areaTitle
+guanvis gen-layout-id cardGroup
 
 # 初始化：从 BI 获取数据集结构
 guanvis init <dsId> -d ./my_dashboard/
@@ -49,6 +51,12 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.24
+
+- 新增 area title 和 card group 布局能力，支持在页面中组织分区标题和卡片分组。
+- `gen-layout-id` 支持生成 area title 相关布局 ID，便于构建复杂页面布局。
+- 增强布局 DSL、打包导出和页面布局校验，补充大量布局场景测试。
+
 ### @guandata/guanvis 0.1.23
 
 - 新增指标卡片构建能力，支持基于指标配置生成图表卡片，并补充 `metric init` 和指标图表参考文档。
@@ -83,7 +91,7 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 ### 0.1.18
 
 - 新增 Tab 布局能力，支持通过 `createTab()` / `addPanel()` 组织同页多组可切换内容。
-- 新增 `gen-layout-id` 命令，用于生成 tab/panel 等布局组件 ID。
+- 新增 `gen-layout-id` 命令，用于生成布局组件 ID。
 - 增加 Tab 布局示例工程和文档说明，便于快速复用。
 - 增强筛选器默认值校验，提前发现不匹配的筛选值配置。
 

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -28,7 +28,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
-1. **工厂函数**：数据集图表用 `createCard()`；指标平台指标卡片用 `createMetricChart()`；筛选器/文本/图片/杜邦/Tab/页面用 `createSelector()` / `createTextCard()` / `createImageCard()` / `createDuPontChart()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`
+1. **工厂函数**：数据集图表用 `createCard()`；指标平台指标卡片用 `createMetricChart()`；筛选器/文本/图片/杜邦/Tab/页面用 `createSelector()` / `createTextCard()` / `createImageCard()` / `createDuPontChart()` / `createAreaTitle()` / `createCardGroup()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`
 2. **注册函数**：`registerCard(card.build())` / `registerMetricChart(card.build())` / `registerSelector(sel.build())` / `registerTextCard(text.build())` / `registerImageCard(image.build())` / `registerDuPontChart(dupont.build())` / `registerPage(page.build())`
 3. **字段引用**：单数据集用 `f("字段名")`，多数据集用 `field(DS, "字段名")`
 4. **zone maxCount**：`BASIC_COLUMN/BAR/LINE` metric=1；`GROUPED_*/STACKED_*` metric=∞；`KPI_CARD` metric=1；组合图 `*_WITH_LINE` row=1
@@ -48,7 +48,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 18. **设计规则**：`preview`/`pack`/`publish` 会自动应用内置设计规则；需要自定义静态卡片默认规则或主题已开放配置时，在工程目录新建 `design-rule.json`，不要手改 `themes/<themeId>.json`；详见 `references/theme.md`
 19. **图表选型**：用户说“指标卡片”时先区分语义：如果是数据集字段做单值/KPI，用 `SINGLE_VALUE` / `KPI_CARD`；如果是“用指标平台已有指标创建卡片”，必须先 `guanvis metric-init <metricId>`，再用 `createMetricChart()` + `metric()` / `metricDim()`，生成后端 `CARD_TYPE.METRIC_CHART`。复杂指标卡片参数先读 `references/metric-chart-reference.md`
 20. **杜邦分析图**：杜邦不是普通 `ChartType`，用 `createDuPontChart()` 创建 `LAYOUT` 卡片；节点通常放 `KPI_CARD` 子卡片，并通过 `.setRoot()` / `.addChild()` 组织树。页面布局只放杜邦父卡片，不单独放子卡片；筛选器 `linkToAll()` 会覆盖杜邦子卡片。
-21. **tab 布局**：同一主题有多组互斥分析内容时可用 tab；少量卡片或需同时对照时优先平铺。用法见 `references/builder-reference.md`，示例见 `evals/tab_layout/`
+21. **布局组件**：支持了布局组件 `小标题(AreaTitle)`/ `卡片组(CardGroup)`/ `标签页(Tab)`， 目前布局组件只支持放在画布的根布局，不支持嵌套组合使用，用法见 `references/builder-reference.md`。
 22. **资源包禁止手改**：只改 DSL，不改 ZIP 内部文件；`upload` 只用于上传 `guanvis pack` 原样生成的包。批量重绑、迁移页面等需求先讨论方案。
 
 ## 何时使用
@@ -266,6 +266,8 @@ guanvis genid 5     # 生成 5 个
 # 生成布局组件 ID
 guanvis gen-layout-id tab                 # 生成 1 个 tab_ + 默认 6 位字母
 guanvis gen-layout-id panel 3 --length 8  # 生成 3 个 panel_ + 8 位字母；length 只计算下划线后的随机字母，超出 6~10 时自动收敛
+guanvis gen-layout-id areaTitle           # 生成 1 个 areaTitle_ + 默认 6 位字母
+guanvis gen-layout-id cardGroup           # 生成 1 个 cardGroup_ + 默认 6 位字母
 
 # 预览生成结果（JSON 输出到 stdout，含 payload 验证，用于调试）
 guanvis preview ./my_dashboard/

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

@@ -289,8 +289,10 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 
 **布局单位**：
 1. 默认横向使用 12 列栅格；开启精细模式后使用 60 列栅格。
-2. 推荐通过 `.setFineMode(true)` 设置为精细模式，且必须在任何 `addRow()` / `placeCard()` / `addTab()` 等布局方法之前调用。
+2. 推荐通过 `.setFineMode(true)` 设置为精细模式，且必须在任何 `addRow()` / `placeCard()` / `addTab()` / `addAreaTitle()` / `addCardGroup()` 等布局方法之前调用。
 3. `addRow()` 及其快捷方法的 `height` 省略或为 0 时使用默认行高（普通 6，精细 18）。
+4. 区域小标题用 `createAreaTitle(...).setId(...).build()` 定义，并通过 `page.addAreaTitle(title)` 放在 Page 根布局；不要放进 tab panel。
+5. 卡片组用 `createCardGroup(...).setId(...)` 定义，并通过 `page.addCardGroup(group)` 放在 Page 根布局。
 
 | 方法 | 说明 |
 |------|------|
@@ -304,6 +306,8 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.addQuarterWidthCards(ci1, ci2, ci3, ci4, height?)` | 四等分 |
 | `.placeCard(cardIndex, x, y, w, h)` | 精确放置 Card，`w/h` 必须大于 0， `x/y/w/h` 必须显式填写 |
 | `.addTab(tab, height?)` | 添加一个满宽 tab 容器；不传 height 时按第一个 panel 内容自动推导 |
+| `.addAreaTitle(areaTitle, height?)` | 添加一个满宽区域小标题|
+| `.addCardGroup(group, height?)` | 添加一个满宽卡片组；不传 height 时按标题和组内布局自动推导 |
 | `.setBackgroundColor(color)` | 页面背景色 |
 | `.setCardMargin(margin)` | 卡片间距 |
 | `.setFineMode(enabled)` | 开启/关闭精细模式 |
@@ -311,6 +315,66 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.setLayoutSetting(config)` | 原始 layout 配置 |
 | `.build()` | 构建 |
 
+### AreaTitleBuilder
+
+`areaTitle` 是 Page 根布局里的区域小标题，不是 Card，不绑定数据集，也不会生成 page-card relation。ID 必须以 `areaTitle_` 开头，建议用 `guanvis gen-layout-id areaTitle` 生成。
+
+| 方法 | 说明 |
+|------|------|
+| `createAreaTitle(name)` | 创建区域小标题，`name` 即为标题的内容，会被写入该组件的 style 中，必须要传 name |
+| `.setId(areaTitleId)` | **必填**。设置区域小标题 ID，必须以 `areaTitle_` 开头 |
+| `.setShowTitle(boolean)` | 是否显示标题 |
+| `.setFontSize(number)` | 字号 |
+| `.setColor(color)` | 字体颜色 |
+| `.setBold(boolean)` | 是否加粗 |
+| `.setTextAlign(alignment)` | 对齐方式, 支持 `left`, `center`, `right` |
+| `.setBackgroundColor(color)` | 背景色 |
+| `.setShowBgImage(boolean)` | 是否显示背景图 |
+| `.setShowIcon(boolean)` | 是否显示图标 |
+| `.build()` | 构建 areaTitle result |
+
+```javascript
+var salesTitle = createAreaTitle("销售概览")
+    .setId("areaTitle_AbCdEf")
+    .setFontSize(20)
+    .setBold(true)
+    .setTextAlign("left")
+    .build();
+
+var page = createPage("销售仪表板")
+    .setId("p184352b7a76776db5f534df")
+    .addAreaTitle(salesTitle)
+    .addFullWidthCard(0, 6);
+
+registerPage(page.build());
+```
+
+### CardGroupBuilder
+
+`cardGroup` 是一个布局容器，不是 Card，不绑定数据集，也不会生成独立 page-card relation。ID 必须以 `cardGroup_` 开头，建议用 `guanvis gen-layout-id cardGroup` 生成。卡片组目前只能放入根布局，暂不支持放入 tab panel、另一个卡片组或嵌套区域小标题。
+
+| 方法 | 说明 |
+|------|------|
+| `createCardGroup(name)` | 创建卡片组，`name` 写入分组标题 |
+| `.setId(cardGroupId)` | **必填**。设置卡片组 ID，必须以 `cardGroup_` 开头 |
+| `.setShowTitle(boolean)` | 是否显示标题，默认 `true` |
+| `.addRow(specs, height?)` | 在组内按行放置卡片，写法同 `PageBuilder.addRow()` |
+| `.addFullWidthCard(cardIndex, height?)` | 在组内放一张满宽卡片 |
+| `.placeCard(cardIndex, x, y, w, h)` | 在组内精确放置卡片 |
+
+```javascript
+var salesGroup = createCardGroup("销售概览")
+    .setId("cardGroup_AbCdEf")
+    .addRow([{ card: 0 }, { card: 1 }])
+    .addFullWidthCard(2);
+
+var page = createPage("销售仪表板")
+    .setId("p184352b7a76776db5f534df")
+    .addCardGroup(salesGroup);
+
+registerPage(page.build());
+```
+
 #### 页面密度尺寸建议
 
 以下尺寸建议以非精细模式的 12 列布局单位为基准，用于生成页面时选择页面卡片间距和常见卡片高度。精细模式目前只定义横向 60 列栅格与显式 `x/y/w/h` 放置规则，暂不提供独立的密度尺寸换算规则。
@@ -329,9 +393,9 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 
 注意：这里的高度建议是非精细模式下的页面生成建议，不覆盖 `addRow()` 在精细模式下省略高度时使用默认行高 `18` 的 API 行为。
 
-### Tab 布局
+### Tab Builder
 
-tab 用于把页面中的卡片分到多个 panel。适合同一主题下多组互斥查看的分析内容；若卡片较少或需要同时对照，优先直接平铺。关键总览指标通常放在 tab 外，tab 内按实际分析主题组织 panel。支持通过 `page.addTab(tab)` 添加满宽 tab，暂不支持半宽 tab 或 tab 嵌套。
+tab 用于把页面中的卡片分到多个 panel。适合同一主题下多组互斥查看的分析内容；若卡片较少或需要同时对照，优先直接平铺。关键总览指标通常放在 tab 外，tab 内按实际分析主题组织 panel。支持通过 `page.addTab(tab)` 添加满宽 tab，暂不支持半宽 tab 或 tab 嵌套。 示例可以参考 `evals/tab_layout/`。
 
 | 方法 | 说明 |
 |------|------|