@guandata/guanvis 0.1.46 → 0.1.47

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @guandata/guanvis 0.1.47 - 2026-09-11
+
+- 交叉表新增跨视图 `filterBy` 逐格校验：横向父格缺少 `filterBy`、把 `filterBy` 写到横向展开的表头格、以及已用区域未从 A1 起步等形态会在 pack/publish 阶段明确报错并给出修正项，文档同时说明 `filterBy` 与 JOIN 虚拟视图两种交叉表形态的取舍。
+- `setSheetDefaults({ showGridLines })` 可关闭 Pro 报表网格线，并可通过 `decompile` 原样回读。
+- `setTableSetting` 的表格字号下限放宽到 9，便于还原密集的迁移报表区块。
+- `publish --allow-overwrite` 覆盖发布后会重置被替换页面的草稿，编辑器不再打开上一版本的卡片和脚本；原生卡片 bundle 自带的运行时标记不再被误判为未替换占位符。
+
 ## @guandata/guanvis 0.1.46 - 2026-09-09
 
 - 正式发布按系统和架构拆分的原生程序包，安装命令不变，下载量与磁盘占用显著降低。

package/README.md

@@ -57,6 +57,12 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.47
+
+- 交叉表新增跨视图 `filterBy` 逐格校验，违规形态在 pack/publish 阶段给出明确修正提示，文档同时说明与 JOIN 虚拟视图的取舍。
+- `setSheetDefaults({ showGridLines })` 可关闭 Pro 报表网格线，并可原样回读；表格字号下限放宽到 9。
+- `publish --allow-overwrite` 覆盖发布会重置被替换页面的草稿，避免编辑器打开上一版本内容。
+
 ### @guandata/guanvis 0.1.46
 
 - 正式启用按系统和架构拆分的原生程序包，安装命令不变，下载量与磁盘占用显著降低。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"
@@ -40,17 +40,16 @@
     "win32"
   ],
   "optionalDependencies": {
-    "@guandata/guanvis-darwin-arm64": "0.1.46",
-    "@guandata/guanvis-darwin-x64": "0.1.46",
-    "@guandata/guanvis-linux-x64": "0.1.46",
-    "@guandata/guanvis-linux-arm64": "0.1.46",
-    "@guandata/guanvis-win32-x64": "0.1.46"
+    "@guandata/guanvis-darwin-arm64": "0.1.47",
+    "@guandata/guanvis-darwin-x64": "0.1.47",
+    "@guandata/guanvis-linux-x64": "0.1.47",
+    "@guandata/guanvis-linux-arm64": "0.1.47",
+    "@guandata/guanvis-win32-x64": "0.1.47"
   },
   "engines": {
     "node": ">=14"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "registry": "https://registry.npmjs.org/"
   }
 }

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

@@ -1226,7 +1226,7 @@ Workbook API：
 
 绑定 `options` 支持 `expansion`、`fillMode`、`context`、`countPerPage`、`filter`、`filterBy`、`numberFormat` 和 `style`；维度额外支持 `group`、`sort`，度量额外支持 `aggregate`。未知 option 会直接校验失败，不再静默忽略。
 
-`context` 可写单父格 `A3`，也可写横纵双父格 `A4*B3`。父格必须是维度绑定：左父格与当前格同一行且纵向扩展，上父格与当前格同一列且横向扩展，最多各一个。相同数据视图的层级和交叉表只用 `context`；同时生成同源 `filterBy` 会形成嵌套 `LP(...)`，现在会在 pack 阶段拒绝。`filterBy` 仅用于跨数据视图映射，字段的 view 必须是当前绑定 view，引用的 cell 必须同时列在 `context` 中。`filter` 与 `filterBy` 不能并用。
+`context` 可写单父格 `A3`，也可写横纵双父格 `A4*B3`。父格必须是维度绑定：左父格与当前格同一行且纵向扩展，上父格与当前格同一列且横向扩展，最多各一个。相同数据视图的层级和交叉表只用 `context`；同时生成同源 `filterBy` 会形成嵌套 `LP(...)`，现在会在 pack 阶段拒绝。`filterBy` 仅用于跨数据视图映射，字段的 view 必须是当前绑定 view，引用的 cell 必须是 `context` 里的父格或父格的 `context` 祖先（多级表头可同时给年、月两个列键）。`filter` 与 `filterBy` 不能并用。**同一 Sheet 里 `filterBy` 与 `expansion: "horizontal"` 并存时按格校验**（pack 拒绝，规则与实测见 complex-report-pro-patterns.md §1）：带 `filterBy` 的格若挂在横向父格下，`filterBy` 必须包含该横向父格；同 Sheet 其它挂在横向父格下、自身不横向扩展的绑定/动态公式必须也带 `filterBy`，否则改用 `setDataSourceRelations` 虚拟视图 + `context`；`filterBy` 不能写在横向扩展格自身上；第 1 行与 A 列都要有格（标题放 A1），否则渲染器还原横向表头时错位。同一列里下方第二段带的顶层维度要显式 `context: "None"`，否则默认父格推断会把它挂到上一段的同列维度。
 
 聚合可用 `SUM/COUNT/AVERAGE/MAX/MIN/PRODUCT/STDDEV/STDDEVP/VAR/VARP`。`AVG` 是输入别名，会编译为 `AVERAGE`；`COUNTA` 不是 Pro 聚合函数，会在本地拒绝。`countPerPage` 只接受正整数或 `*`。分页模式最多设置一个 `countPerPage`，且只能放在没有 `context` 的顶层 `bindDimension` 上；放在嵌套子维度上会导致 Pro 分页器只合并部分祖先单元格，因此 `pack` 会直接拒绝。
 
@@ -1298,7 +1298,7 @@ checkout 得到的 `templates/<cdId>.xlsx` 可用 `guanvis report decompile <xls
 | `sheet.setRow(startCell, values, style?)` | 从 startCell 起横向批量写标量值，数组元素 `null` 跳过该格；style 应用到每个写入格。表头行一行写完 |
 | `sheet.setColumn(startCell, values, style?)` | 纵向批量写（固定科目列一次写完） |
 | `sheet.setColumnWidth(col, width)` | col 支持 `"B"` 或范围 `"B:D"`（整段同宽） |
-| `sheet.setSheetDefaults({ defaultColumnWidth?, defaultRowHeight?, defaultRowHidden? })` | 未显式设置宽高的行列默认值（编译时自动先于其他操作应用，脚本内位置不影响结果）；`defaultRowHidden: true` 使未显式声明的行默认隐藏（OOXML zeroHeight） |
+| `sheet.setSheetDefaults({ defaultColumnWidth?, defaultRowHeight?, defaultRowHidden?, showGridLines? })` | 未显式设置宽高的行列默认值（编译时自动先于其他操作应用，脚本内位置不影响结果）；`defaultRowHidden: true` 使未显式声明的行默认隐藏（OOXML zeroHeight）；`showGridLines: false` 隐藏工作表网格线（OOXML sheetView showGridLines="0"，无边框单元格之间不再画浅灰线，报表类版式常用；decompile 原样还原） |
 | `sheet.setHyperlink(cell, url, { tooltip?, display? })` | **静态格**超链接（标题/返回目录等固定格；dev29 实证 GcExcel 渲染保留）；`display` 为链接可见文本（格无自身值时用户看到的就是它）。超链不随模板扩展复制——扩展区行级链接用 `setDynamicFormula` + `HYPERLINK("url","文本")`（dev29 实证展开为 shared formula 每行可点） |
 
 样式对象在原有 `bold/italic/fontSize/fontColor/backgroundColor/horizontalAlignment/verticalAlignment/wrapText/numberFormat/borderColor/diagonalDown` 基础上新增（compile/decompile/setCellStyle 合并三端一致，roundtrip 有测试锁定）：

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

@@ -1168,7 +1168,7 @@ Tooltip 展示哪些数据字段由 `.addTooltip(field)` 控制；`setTooltip()`
 | `selectedColor` | string | 选中高亮色，可使用带透明度的 `rgba(...)` |
 | `colWidth` | integer，15–1000 | 表格列宽 |
 | `fontFamily` | 非空 string | 全表字体 |
-| `fontSize` | number，12–72 | 全表字号 |
+| `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 }`。

package/skills/guanvis/references/complex-report-pro-patterns.md

@@ -50,6 +50,17 @@ Pro 模板 = Excel 网格上放"模板格"。每个模板格要么绑定数据
 
 **同一数据视图内只写 `context`，绝不写 `filterBy`**（同源 filterBy 会编译成嵌套 `LP(...)`，后端 500；pack 已本地拒绝）。`filterBy` 仅用于跨数据视图父格映射，且 cell 必须同时出现在 `context` 中。
 
+**`filterBy` 与横向扩展同在一个 Sheet 时按格三条规则**（pack 已本地拒绝，报错前缀 `cross-view filterBy on a sheet with a horizontal expansion`）。原因：Sheet 上只要有一个 `filterBy`，Pro 后端就把整张 Sheet 切成"两遍渲染"——第一遍只做纵向扩展（横向扩展格先占位、带 filterBy 的格改成 lookup 且只保留左父格），第二遍才还原横向扩展并给 lookup 格补上父格；lookup 按列取值的键来自 `filterBy`，不来自 `context`。这些错误后端都不报，只出错数，所以本地必须硬拒绝：
+
+1. 带 `filterBy` 的格若 `context` 里有横向父格，`filterBy` 必须同时包含该横向父格（只给纵向键 → 每列重复同一个值）。
+2. 同一 Sheet 上，凡 `context`（含默认推断）挂在横向父格下、自身不是 `expansion: "horizontal"`、又没有 `filterBy` 的绑定或动态公式，一律拒绝（第一遍就被消费，不随列扩展，输出一个总量）。要么给它补含横向父格的 `filterBy`，要么整表改 §2.8 JOIN 虚拟视图 + 只写 `context`。
+3. `filterBy` 不能写在横向扩展格自身上（lookup 改写会丢掉它的 E=H），横向列头单独放一格，过滤放在值格。
+4. 第 1 行和 A 列都必须有格（值、模板或带样式的格），让工作表已用区域从 A1 开始：渲染器还原横向表头时按已用区域相对坐标定位，模板从 B 列或第 2 行起步时表头整体错位一格、占位符残留、查值全空。把标题放在 A1 即可；A 列纯留白时放一个空格值。
+
+满足规则的形态实测按列正确：三视图交叉表（行轴视图 / 列轴视图 / 度量视图）度量格 `context: "A3*B2"` + `filterBy: [{行键, A3}, {列键, B2}]`；两级列头（国家→是否已付）时 `filterBy` 可以额外带 `context` 祖先格 `B2`（`context` 每个方向只写最近父格，`filterBy` 允许写祖先），合并列头与空值列都正确。与 §2.8 JOIN 形态的取舍：filterBy 形态行/列成员各来自自己的视图、无交点为空，JOIN 形态是 INNER JOIN、关联不到的成员直接消失。
+
+**多段带的顶层锚点写 `context: "None"`**：同一列里第二段带的顶层维度（如第 7 行的 `A7`）会被默认父格推断挂到上一段的同列维度（`guanvis report inspect` 显示 `A3 (inherited)`），第二段就嵌进第一段的分组里；显式 `None` 才是独立的一段。
+
 ## 2. 结构模式配方
 
 每个配方给最小正确形态；完整可运行工程见 `evals/complex_report_pro/`（最小 Workbook DSL 工程）。
@@ -187,7 +198,7 @@ report.setDataSourceRelations([{
 }]);
 ```
 
-`leftId/rightId/viewId` 写数据视图别名，字段写显示名，pack 自动翻译成子卡 ID/zone key；同组 relations 必须连成连通图。JOIN 键是 METRIC 型 ID 时在子视图用 `AggrType.MAX` 带出。模板只能引用该组 `selectedCols` 输出的字段。
+`leftId/rightId/viewId` 写数据视图别名，字段写显示名，pack 自动翻译成子卡 ID/zone key；同组 relations 必须连成连通图。JOIN 键是 METRIC 型 ID 时在子视图用 `AggrType.MAX` 带出。模板只能引用该组 `selectedCols` 输出的字段；`name` 非空即输出列别名（不同视图的同名字段用 `订单_雇员ID` 这类别名区分，模板按别名引用）。虚拟视图是行级明细：只有度量的视图要在 `addRow` 里放关联键（METRIC 键先加 STRING 计算字段），否则 DATA_GRID 聚成一行、JOIN 只剩一条。"行轴、列轴、度量来自不同数据视图的交叉表"有两种形态：度量格 `filterBy` 同时带行键和列键（§1 三条规则，行/列成员各来自自己的视图、无交点为空），或本节 JOIN 虚拟视图；当 Sheet 上还有其它挂在横向父格下、无法加 `filterBy` 的格（例如列头下方按列的计数行、动态公式）时只能走 JOIN。JOIN 的代价是 INNER JOIN 关联不到的成员不出现、空交点为空白、展开顺序以关联结果为准。
 
 ### 2.9 条件格式 / 冻结 / 图片
 
@@ -313,6 +324,11 @@ pack/publish 阶段（本地校验，改 DSL 即可）：
 | `subtotal parent ... must be a setContextText cell` / `must be on the same row to the left` | `bindSubtotal` 没挂同行左侧标签 | 按 §2.3 三件套补 `setContextText`，值与标签同行 |
 | `redundantly filters the same view ... use context only` | 同数据视图写了 `filterBy` | 删掉 filterBy，同源层级/交叉只写 `context` |
 | `filter and filterBy cannot be combined` | 两者并用 | 只留一个 |
+| `cross-view filterBy on a sheet with a horizontal expansion: filterBy on cell X must include its horizontal parent Y` | 带 `filterBy` 的格挂在横向父格下，但 `filterBy` 只给了纵向键 | 在 `filterBy` 里补 `{ field: 列键字段, cell: Y }`（§1 规则 1） |
+| `cross-view filterBy on a sheet with a horizontal expansion: cell X (...) hangs off horizontal parent Y without a filterBy` | Sheet 上有 `filterBy`，而 X 只用 `context`（或默认推断）挂在横向父格下 | 给 X 补含 Y 的 `filterBy`；无法补（同视图计数行、动态公式）时整表改 §2.8 JOIN 虚拟视图 + 只写 `context` |
+| `cross-view filterBy on a sheet with a horizontal expansion: filterBy on cell X cannot be combined with expansion "horizontal" on the same cell` | 把 `filterBy` 写在了横向扩展的列头格上 | 列头格只保留 `expansion: "horizontal"`，过滤放到值格 |
+| `cross-view filterBy on a sheet with a horizontal expansion: row 1 and column A must both hold a cell` | 模板从 B 列或第 2 行起步，已用区域不从 A1 开始 | 标题放 A1，或 `setValue("A1", " ")` 放一个空格值（§1 规则 4） |
+| `filterBy[i] cell X must also be listed in context (or be a context ancestor of a listed parent)` | `filterBy` 引用的格既不是 `context` 父格，也不是父格的 `context` 祖先 | 多级表头按祖先链写（`context: "A4*B2"` 可带 `B2` 的父格 `B1`），其它格不能当过滤键 |
 | `unknown option "context"`（出现在 bindGrandTotal 上） | `bindGrandTotal` 传了 context | 删 context；总计只支持 `aggregate/numberFormat/style` |
 | `unsupported aggregate "COUNTA"; supported aggregates: ...` | 聚合不在白名单 | 换 `SUM/COUNT/AVERAGE/MAX/MIN/PRODUCT/STDDEV/STDDEVP/VAR/VARP`；`AVG` 会自动规范化为 `AVERAGE` |
 | `pagination requires exactly one worksheet` / `countPerPage ... must use a top-level dimension without context` / `pagination cannot be combined with filter` | 分页约束违规 | 见 §2.7：单 Sheet、去掉 filter/filterBy、countPerPage 移到顶层维度 |