@guandata/guanvis 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## @guandata/guanvis 0.1.19 - 2026-05-26
+
+- 筛选器默认值校验增强，日历筛选器会校验绑定字段类型，避免非日期字段误配日期默认值。
+- 增强来源动态字段、联动筛选器和默认值映射的校验，提前发现无法可靠发布的配置。
+- 补充相关测试覆盖和 builder 参考文档说明，提升复杂筛选器配置的可诊断性。
+
+## @guandata/guanvis 0.1.18 - 2026-05-25
+
+- 新增 Tab 布局能力，支持通过 `createTab()` / `addPanel()` 组织同页多组可切换内容。
+- 新增 `gen-layout-id` 命令，用于生成 tab/panel 等布局组件 ID。
+- 增加 Tab 布局示例工程和文档说明，便于快速复用。
+- 增强筛选器默认值校验，提前发现不匹配的筛选值配置。
+
 ## @guandata/guanvis 0.1.17 - 2026-05-21
 
 - 构建流程会将 npm 包版本注入到 `guanvis` 二进制，确保运行时版本信息与发布包一致。

package/README.md

@@ -15,6 +15,10 @@ guanvis install-skill
 # 生成资源 ID
 guanvis genid 5
 
+# 生成布局组件 ID
+guanvis gen-layout-id tab
+guanvis gen-layout-id panel 3 --length 8
+
 # 初始化：从 BI 获取数据集结构
 guanvis init <dsId> -d ./my_dashboard/
 
@@ -32,6 +36,13 @@ guanvis publish ./my_dashboard/
 
 ## 版本更新
 
+### 0.1.18
+
+- 新增 Tab 布局能力，支持通过 `createTab()` / `addPanel()` 组织同页多组可切换内容。
+- 新增 `gen-layout-id` 命令，用于生成 tab/panel 等布局组件 ID。
+- 增加 Tab 布局示例工程和文档说明，便于快速复用。
+- 增强筛选器默认值校验，提前发现不匹配的筛选值配置。
+
 ### 0.1.17
 
 - 构建流程会将 npm 包版本注入到 `guanvis` 二进制，确保运行时版本信息与发布包一致。

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -27,7 +27,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
-1. **工厂函数**：只用 `createCard()` / `createSelector()` / `createTextCard()` / `createPage()`，不要 `new XxxBuilder()`
+1. **工厂函数**：只用 `createCard()` / `createSelector()` / `createTextCard()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`
 2. **注册函数**：`registerCard(card.build())` / `registerSelector(sel.build())` / `registerTextCard(text.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
@@ -46,6 +46,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 17. **主题切换**：用户描述风格（深色科技风/科技蓝/蓝色简约等）→ 在工程目录里 `guanvis theme preference --keywords "..." --sync`（`[dir]` 可省，默认当前目录）；不要选择租户默认的“浅色”/“深色”主题，找不到合适主题时保持/清空偏好，让 preview/pack/publish 自动使用内置“简约”兜底。改版未提风格时 `.applied.json` 会自动继承上次主题，preview/pack/publish 不需要重复指定。**多子目录工程**：每个子目录是独立工程，主题要在子目录里配置 + preview/pack/publish 也必须 `cd` 进对应子目录运行（在根目录直接跑会被命令显式拒绝并给出 cd 提示）；详见 `references/theme.md`
 18. **设计规则**：`preview`/`pack`/`publish` 会自动应用内置设计规则；需要自定义静态卡片默认规则或主题已开放配置时，在工程目录新建 `design-rule.json`，不要手改 `themes/<themeId>.json`；详见 `references/theme.md`
 19. **图表选型**：创建指标卡时，若只有单指标优先用 `SINGLE_VALUE`；需展示对比指标时用 `KPI_CARD`，并调用 `.addCompare(...)`
+20. **tab 布局**：同一主题有多组互斥分析内容时可用 tab；少量卡片或需同时对照时优先平铺。用法见 `references/builder-reference.md`，示例见 `evals/tab_layout/`
 
 ## 何时使用
 
@@ -231,6 +232,10 @@ registerPage(p.build());
 guanvis genid       # 生成 1 个
 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 时自动收敛
+
 # 预览生成结果（JSON 输出到 stdout，含 payload 验证，用于调试）
 guanvis preview ./my_dashboard/
 
@@ -308,6 +313,7 @@ guanvis pack ./project
 |------|------|------|
 | 基础仪表板 | `evals/sales_dashboard/` | 普通卡片（柱状图、折线图、KPI、饼图）+ 筛选器 + 页面布局 |
 | 自定义图表 | `evals/custom_chart_echarts/` | ECharts Lite 自定义图表：柱状图 + 饼图，使用 `loadContent()` 文件模式 |
+| Tab 布局 | `evals/tab_layout/` | 单页面 tab 示例，含根布局指标卡、图表卡片、文本卡片、筛选器和 panel 内卡片布局 |
 
 生成脚本前先查阅对应示例中的文件结构和写法。
 
@@ -316,7 +322,7 @@ guanvis pack ./project
 | 场景 | 路径 | 读取时机 |
 |------|------|----------|
 | 字段、计算字段、NumberFormat、高级计算和卡片筛选器 API | `references/api-reference.md` | 编写字段、指标、公式或筛选条件时 |
-| Card/Page/Selector/Text/Image/CustomChart Builder API 与枚举 | `references/builder-reference.md` | 编写或修改 JS DSL builder 调用时 |
+| Card/Page/Tab/Selector/Text/Image/CustomChart Builder API 与枚举 | `references/builder-reference.md` | 编写或修改 JS DSL builder 调用时 |
 | zone 校验、图表选型、地图/拆分图、字段对象细节 | `references/validation-and-chart-patterns.md` | pack 报错、选型不确定或需要特殊图表行为时 |
 | 仪表板主题机制与 theme 命令排错 | `references/theme.md` | 用户指定视觉风格、改版继承主题或主题异常时 |
 | 在线同步、认证、ID 管理和硬约束 | `references/publish-and-constraints.md` | publish/upload、更新线上资源或确认生成边界时 |

package/skills/guanvis/evals/tab_layout/card_00_total_revenue.js

@@ -0,0 +1,6 @@
+var card = createCard(ChartType.SINGLE_VALUE, "总营收")
+    .setId("eeeeeeeeeeeeeeeeeeeeeeee")
+    .bindDataset(DS)
+    .addMetric(f("营收", { aggrType: AggrType.SUM, numberFormat: NumberFormat.currency("¥", 0) }));
+
+registerCard(card.build());

package/skills/guanvis/evals/tab_layout/card_01_revenue.js

@@ -0,0 +1,10 @@
+var card = createCard(ChartType.GROUPED_COLUMN, "区域产品营收")
+    .setId("aaaaaaaaaaaaaaaaaaaaaaaa")
+    .bindDataset(DS)
+    .addRow(f("区域"))
+    .addColumn(f("产品"))
+    .addMetric(f("营收", { aggrType: AggrType.SUM, numberFormat: NumberFormat.currency("¥", 0) }))
+    .setShowLegend(true, "right")
+    .setDataLabel({ show: true, showNumber: true });
+
+registerCard(card.build());

package/skills/guanvis/evals/tab_layout/card_02_trend.js

@@ -0,0 +1,9 @@
+var card = createCard(ChartType.MULTI_LINE, "月度营收成本趋势")
+    .setId("bbbbbbbbbbbbbbbbbbbbbbbb")
+    .bindDataset(DS)
+    .addRow(f("月份"))
+    .addMetric(f("营收", { aggrType: AggrType.SUM, numberFormat: NumberFormat.auto("万") }))
+    .addMetric(f("成本", { aggrType: AggrType.SUM, numberFormat: NumberFormat.auto("万") }))
+    .setShowLegend(true, "bottom");
+
+registerCard(card.build());

package/skills/guanvis/evals/tab_layout/card_03_story.js

@@ -0,0 +1,11 @@
+var text = createTextCard("Tab 使用说明")
+    .setId("cccccccccccccccccccccccc")
+    .addMarkdown(
+        "### Tab 布局示例\n\n" +
+        "- `createTab()` 创建容器\n" +
+        "- `addPanel(name, callback)` 创建页面上可切换的标签\n" +
+        "- panel 内通过 cardIndex 放置图表卡片或文本卡片\n\n" +
+        "> 筛选器仍然注册为 selector，自动进入页面筛选器区。"
+    );
+
+registerTextCard(text.build());

package/skills/guanvis/evals/tab_layout/page.js

@@ -0,0 +1,23 @@
+var salesTab = createTab("销售分析")
+    .setId("tab_AbCdEf")
+    .setLabelStyle(TabLabelStyle.CAPSULE)
+    .setAlignment(TabAlignment.CENTER)
+    .addPanel("区域分析", function(panel) {
+        panel
+            .setId("panel_GhIjKl")
+            .addRow([{ card: 1, w: 6 }, { card: 3, w: 6 }], 6);
+    })
+    .addPanel("趋势分析", function(panel) {
+        panel
+            .setId("panel_MnOpQr")
+            .addFullWidthCard(2, 7);
+    });
+
+var page = createPage("Tab Layout 示例")
+    .setId("pppppppppppppppppppppppp")
+    .setDescription("展示根布局指标卡、tab 容器、panel 内图表/文本卡片，以及 selector 仍进入筛选器区。")
+    .setCardMargin(8)
+    .addRow([{ card: 0, w: 4 }], 3)
+    .addTab(salesTab);
+
+registerPage(page.build());

package/skills/guanvis/evals/tab_layout/schema.js

@@ -0,0 +1,11 @@
+// Auto-generated by guanvis schema command
+// DO NOT EDIT — regenerate with: guanvis schema s9ded2338f43807b095fbb4f
+
+defineDataset("s9ded2338f43807b095fbb4f", [
+    { fdId: "jb16f22f6c1c21c3f6e8e293", name: "区域", fdType: "STRING", metaType: "DIM" },
+    { fdId: "o7093aaf2b2f32c9e964c41a", name: "产品", fdType: "STRING", metaType: "DIM" },
+    { fdId: "p2670dd6b74fc78c3e9c57ad", name: "月份", fdType: "DATE", metaType: "DIM" },
+    { fdId: "lb1c31b4dc86511a27049a98", name: "营收", fdType: "DOUBLE", metaType: "METRIC" },
+    { fdId: "aece10cd6806966be56f52ff", name: "成本", fdType: "DOUBLE", metaType: "METRIC" },
+    { fdId: "g1b16b52a16eb10c5e26d4bb", name: "数量", fdType: "INT", metaType: "METRIC" }
+], { displayType: "EXCEL" });

package/skills/guanvis/evals/tab_layout/selector_01_region.js

@@ -0,0 +1,8 @@
+var sel = createSelector("区域筛选")
+    .setId("ssssssssssssssssssssssss")
+    .bindField(f("区域"))
+    .setMultiSelect(true)
+    .linkToAll()
+    .build();
+
+registerSelector(sel);

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

@@ -115,7 +115,7 @@
 
 **布局单位**：
 1. 默认横向使用 12 列栅格；开启精细模式后使用 60 列栅格。
-2. 推荐通过 `.setFineMode(true)` 设置为精细模式，且必须在任何 `addRow()` / `placeCard()` 等放置卡片的工具方法之前调用。
+2. 推荐通过 `.setFineMode(true)` 设置为精细模式，且必须在任何 `addRow()` / `placeCard()` / `addTab()` 等布局方法之前调用。
 3. `addRow()` 及其快捷方法的 `height` 省略或为 0 时使用默认行高（普通 6，精细 18）。
 
 | 方法 | 说明 |
@@ -129,6 +129,7 @@
 | `.addThirdWidthCards(ci1, ci2, ci3, height?)` | 三等分 |
 | `.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 内容自动推导 |
 | `.setBackgroundColor(color)` | 页面背景色 |
 | `.setCardMargin(margin)` | 卡片间距 |
 | `.setFineMode(enabled)` | 开启/关闭精细模式 |
@@ -154,6 +155,55 @@
 
 注意：这里的高度建议是非精细模式下的页面生成建议，不覆盖 `addRow()` 在精细模式下省略高度时使用默认行高 `18` 的 API 行为。
 
+### Tab 布局
+
+tab 用于把页面中的卡片分到多个 panel。适合同一主题下多组互斥查看的分析内容；若卡片较少或需要同时对照，优先直接平铺。关键总览指标通常放在 tab 外，tab 内按实际分析主题组织 panel。支持通过 `page.addTab(tab)` 添加满宽 tab，暂不支持半宽 tab 或 tab 嵌套。
+
+| 方法 | 说明 |
+|------|------|
+| `createTab(name)` | 创建 tab 容器；`name` 用于脚本可读性，页面上显示的是各 panel 的 name |
+| `.setId(tabId)` | **必填**。设置 tab ID，必须以 `tab_` 开头且同一页面内唯一。建议用 `guanvis gen-layout-id tab` 生成 |
+| `.addPanel(name, callback)` | 添加 panel；callback 接收 `panel` 配置对象，必须在其中放入至少一张卡片 |
+| `.setLabelStyle(style)` | 设置标签样式：`TabLabelStyle.UNDERLINE`（默认）、`CARD`、`CAPSULE`、`TRAPEZOID` |
+| `.setAlignment(alignment)` | 设置标签对齐：`TabAlignment.LEFT`（默认）、`CENTER`、`RIGHT` |
+| `.setTabSize(size)` | 设置标签宽度：`TabSizeType.MAX_CONTENT`（默认）或 `FLEX` |
+| `panel.setId(panelId)` | **必填**。设置 panel ID，必须以 `panel_` 开头且同一页面内唯一。建议用 `guanvis gen-layout-id panel` 生成 |
+| `panel.addRow(specs, height?)` | 在 panel 内按行放置卡片，写法同 `PageBuilder.addRow()` |
+| `panel.addFullWidthCard(cardIndex, height?)` | 在 panel 内放一张满宽卡片 |
+| `panel.placeCard(cardIndex, x, y, w, h)` | 在 panel 内精确放置卡片 |
+
+**使用示例**：
+
+```javascript
+var salesTab = createTab("销售分析")
+    .setId("tab_AbCdEf")
+    .setLabelStyle(TabLabelStyle.CAPSULE)
+    .setAlignment(TabAlignment.CENTER)
+    .addPanel("区域分析", function(panel) {
+        panel
+            .setId("panel_GhIjKl")
+            .addRow([{ card: 0, w: 6 }, { card: 1, w: 6 }], 6);
+    })
+    .addPanel("趋势分析", function(panel) {
+        panel
+            .setId("panel_MnOpQr")
+            .addFullWidthCard(2, 8);
+    });
+
+var page = createPage("销售仪表板")
+    .setId("p184352b7a76776db5f534df")
+    .addTab(salesTab);
+
+registerPage(page.build());
+```
+
+注意：
+
+- tab 必须有 panel，panel 必须有卡片；不要创建空 tab 或空 panel。
+- panel 内放置非 selector 卡片（图表、文本、图片、自定义图表等）。selector 仍通过 `registerSelector()` 进入页面筛选器区。
+- panel 布局跟随页面精细模式：`page.setFineMode(true)` 后，panel 也使用 60 列栅格和精细模式默认行高。
+- 不需要手工设置 tab 高度；只有明确要固定高度时才给 `page.addTab(tab, height)` 传第二个参数。
+
 ### SelectorBuilder（筛选器）
 
 筛选器是特殊的卡片（`cdType=6`），放在页面顶部的筛选器面板中，可联动影响其他图表卡片。
@@ -173,6 +223,7 @@
 | `.setDefaultType(type)` | 默认值类型：`SelectorDefaultType.FIRST_PICK`（默认）、`FIXED_VALUE` 或 `ALL` |
 | `.setDefaultAll()` | 设置默认"全部"（不筛选），等价于 `setDefaultType(SelectorDefaultType.ALL)` |
 | `.setDefaultValue(values, displayValues?)` | 设置固定默认值，自动切换为 FIXED_VALUE 类型 |
+| `.setDefaultDateRange(start, end, displayValues?)` | 设置 `CALENDAR` 日期区间默认值，自动切换为 FIXED_VALUE；比手写数组更不容易漏填区间端点 |
 | `.setFirstPickLink(bool)` | FIRST_PICK 模式下是否联动刷新（默认 false） |
 | `.setDisplayType(type)` | 展示类型（仅 `DS_ELEMENTS` 使用）：`SelectorDisplay.SEARCH_LIST`（单选下拉）、`SEARCH_BOX`（多选下拉）、`CHECKBOX`（复选框）、`RADIO`（单选框）、`BUTTON_GROUP`（按钮组）。不设置时根据 multiSelect 自动选择。`DS_INTERVAL` 类型不需要此设置 |
 | `.setShowSelectAll(bool)` | 是否显示"全选"（默认 true） |
@@ -207,6 +258,21 @@ registerSelector(sel);
 // 也可设置 .setFilterType("EQ") 单值等于，或 "GT"/"LT" 等比较
 ```
 
+```javascript
+// selector_03_date.js — 日期范围（CALENDAR）
+var sel = createSelector("日期筛选")
+    .setId("abc123def456abc123def456")
+    .setSelectorType(SelectorType.CALENDAR)
+    .bindField(f("订单日期"))
+    .setDefaultDateRange("2026-01-01", "2026-01-31")
+    .linkToAll()
+    .build();
+registerSelector(sel);
+// CALENDAR 默认 filterType="BT"（区间），固定默认值必须是 2 个日期值。
+// 支持 "2026-01-15"、"2026-01"、"2026-Q1"、"2026-W03"、"2026" 等格式。
+// 同一个默认值数组必须使用同一粒度；未显式 setGranularity 时会从默认值格式推断粒度。
+```
+
 ```javascript
 // selector_03_timemacro.js — 快捷日期（TIME_MACRO）
 var sel = createSelector("快捷日期")