企业官网建设流程全解析

• CLI
• AI 应用
• MCP 服务

本篇技术指南以 OfficeCLI 仓库中的examples/excel/pivot-tables.md及其配套的 pivot-tables.py、pivot-tables.sh、pivot-tables.xlsx 为核心，完整讲解如何用officecli add --type pivottable命令从纯命令行生成带完整渲染结果的 Excel 数据透视表。读完本文，你将掌握rows/cols/values/filters四大轴字段的写法、11 种值聚合函数、三种报表布局、日期分组、Top-N 过滤、计算字段、中文拼音排序等全部核心参数，并能用officecli query/get/view对生成结果做程序化检验。

一、三个文件如何协作：官方示例的结构

示例由三个文件协同完成，构成一个"文档讲解 + 脚本执行 + 成品检验"的闭环：

两个脚本产生等价的工作簿：.py版本启动一个常驻进程（resident），把 500 多个源数据单元格写入通过单次doc.batch(...)往返提交，每张数据透视表是经命名管道发送的一个add pivottable批处理项；每个批处理项与officecli batch列表中的{"command","parent","type","props"}字典完全相同。也就是说，理解了脚本里的一个 item，就同时理解了 CLI 命令与批处理 JSON 两种调用形态。

重新生成工作簿

cd examples/excel python3 pivot-tables.py # → 生成 pivot-tables.xlsx（19 个 sheet）

对应的 Bash 版执行./pivot-tables.sh [officecli]，脚本刻意不加set -e，这样即使出现前向兼容的UNSUPPORTED props警告（officecli 退出码 2），也能继续构建完整文档。

二、源数据设计

从 pivot-tables.py 可见源数据覆盖 4 个地区（North/South/East/West）、3 个品类（Electronics/Clothing/Food）、4 个季度、两个渠道（Online/Retail）与三级优先级（High/Medium/Low），日期字段以2025-01-15文本形式存储——这为后面的 2 级日期分组、双重页面筛选、Top-N 等所有演示提供了足够多样化的取值空间。

三、17 张数据透视表逐例拆解

以下每个小节对应 pivot-tables.xlsx 中的一个 sheet，命令可直接复制执行（先执行officecli create pivot-tables.xlsx与officecli open pivot-tables.xlsx进入常驻会话，或改用 batch 形态执行）。

3.1 Sheet「1-Sales Overview」—— 功能最全的旗舰示例

表格型（tabular）布局，2 级行层级（Region > Category）与季度列轴交叉；3 个值字段，其中 Cost 以行合计百分比显示；双页面筛选器可按 Channel 和 Priority 切片；外层行标签在每一行重复出现。

officecli add pivot-tables.xlsx "/1-Sales Overview" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region,Category \ --prop cols=Quarter \ --prop 'values=Sales:sum,Quantity:sum,Cost:sum:percent_of_row' \ --prop 'filters=Channel,Priority' \ --prop layout=tabular \ --prop repeatlabels=true \ --prop grandtotals=both \ --prop subtotals=on \ --prop sort=desc \ --prop style=PivotStyleDark2

要点：layout=tabular让每个行字段独占一列且标签与数据分行；repeatlabels=true对应 Excel「报表布局 → 重复所有项目标签」（OOXML 中写入fillDownLabelsDefault）；values中Cost:sum:percent_of_row的第三段是 showAs 显示模式。在源码 PivotTableHelper.cs 中，布局模式经PushLayoutMode解析为 compact/outline/tabular 三种并存入线程静态作用域，供几何计算与渲染器共用。

3.2 Sheet「2-Market Share」—— 列百分比市场份额

每个区域在各自品类内的份额以列百分比展示，outline 布局提供展开/折叠分组。

officecli add pivot-tables.xlsx "/2-Market Share" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region \ --prop cols=Category \ --prop 'values=Sales:sum:percent_of_col' \ --prop filters=Channel \ --prop layout=outline \ --prop grandtotals=both \ --prop style=PivotStyleMedium4

要点：percent_of_col把每个单元格转换为所在列的占比；layout=outline每个行字段独占一列但标签与数据同行。表中有 Channel 页面筛选器，Excel 中会在透视表上方留出筛选行（源码BuildLocation会为带筛选器的透视写入rowPageCount/colPageCount属性，保证筛选下拉框位置正确）。

3.3 Sheet「3-Product Deep Dive」—— 5 个值字段与合成 Values 轴

同一源列（Sales）上叠加三种聚合：sum、average、max。完全不设列轴——值字段自动变成列标题（Excel 注入合成 "Values" 列轴）。

officecli add pivot-tables.xlsx "/3-Product Deep Dive" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Category,Product \ --prop 'values=Sales:sum,Sales:average,Sales:max,Quantity:sum,Cost:sum' \ --prop filters=Region \ --prop layout=tabular \ --prop grandtotals=rows \ --prop subtotals=on \ --prop sort=desc \ --prop style=PivotStyleMedium9

要点：5 个values元组、无cols（合成 Values 轴）、grandtotals=rows（只保留底部合计行，隐藏最右合计列）。多值字段时表头会分成两行：首行是 "Values" 轴标题，次行是各值字段名——这一几何由ComputePivotGeometry与BuildLocation的firstHeaderRow/firstDataRow计算保证与 Excel 原生文件一致。

3.4 Sheet「4-Channel Analysis」—— 全局占比

销售额显示为占全表总计的百分比，揭示每个渠道在全部季度中的全球份额；无页面筛选器。

officecli add pivot-tables.xlsx "/4-Channel Analysis" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Channel \ --prop cols=Quarter \ --prop 'values=Sales:sum:percent_of_total,Quantity:sum' \ --prop layout=outline \ --prop grandtotals=both \ --prop style=PivotStyleLight21

要点：percent_of_total相对整个透视表的合计计算，与percent_of_row/percent_of_col是三种最常用的显示模式。values元组可以混用不同显示模式（这里第一个是percent_of_total，第二个保持normal）。

3.5 Sheet「5-Priority Matrix」—— 分组间空行

每个外层组（Priority）之后插入空行做视觉分隔；升序排序让 High 排在最前。

officecli add pivot-tables.xlsx "/5-Priority Matrix" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Priority,Region \ --prop cols=Category \ --prop 'values=Sales:sum,Cost:sum:percent_of_row' \ --prop filters=Channel \ --prop layout=tabular \ --prop blankrows=true \ --prop grandtotals=both \ --prop subtotals=on \ --prop sort=asc \ --prop style=PivotStyleDark6

要点：blankrows=true对应 Excel「报表布局 → 在每个项目后插入空行」（OOXML 写入insertBlankRow）。源码中PushInsertBlankRow把开关发布到线程静态作用域，几何计算按外层分组数追加空行高度。

3.6 Sheet「6-Compact 3-Level」—— 三级紧凑布局

Region > Category > Product 三级行层级以紧凑（compact）布局展示——所有标签共享一列、逐级缩进。

officecli add pivot-tables.xlsx "/6-Compact 3-Level" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region,Category,Product \ --prop 'values=Sales:sum,Quantity:sum' \ --prop filters=Priority \ --prop layout=compact \ --prop grandtotals=both \ --prop subtotals=on \ --prop sort=desc \ --prop style=PivotStyleMedium14

要点：layout=compact是 OfficeCLI 的默认布局。当任一侧轴字段达到 3 个及以上时，源码切换到通用的AxisTree递归树渲染（见 PivotTableHelper.cs 的 AxisNode 抽象），外层节点输出小计行、叶节点输出数据行，行/列两棵独立树同步遍历生成 2D 网格，这也是 3 级以上行层级在 Excel 中正确折叠/展开的底层保证。

3.7 Sheet「7-No Subtotals」—— 关闭小计的平铺视图

完全关闭小计后的平坦表格视图，只保留底部合计行。由于没有小计行承载外层标签，必须开启repeatlabels=true，否则外层标签会消失。

officecli add pivot-tables.xlsx "/7-No Subtotals" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region,Category \ --prop cols=Quarter \ --prop values=Sales:sum \ --prop layout=tabular \ --prop repeatlabels=true \ --prop grandtotals=cols \ --prop subtotals=off \ --prop sort=asc \ --prop style=PivotStyleLight1

要点：subtotals=off关闭所有外层小计行/列（OOXML 层面为defaultSubtotal=false），grandtotals=cols只显示右侧合计列。源码PushSubtotalsOptions仅接受 on/off（含 true/false/show/hide/yes/no/1/0 同义值），并会显式拒绝subtotals=auto之类的拼写错误——这类严格枚举校验可避免用户把拼写错误静默当成默认值。

3.8 Sheet「8-Date Grouping」—— 自动日期分组

从日期列自动分组：Date:year生成 "2024"、"2025" 年份桶，Date:quarter生成 "2024-Q1" 等季度子桶，走原生 Excel fieldGroup XML 实现。

officecli add pivot-tables.xlsx "/8-Date Grouping" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop 'rows=Date:year,Date:quarter' \ --prop 'values=Sales:sum,Cost:sum' \ --prop filters=Region \ --prop layout=outline \ --prop grandtotals=both \ --prop subtotals=on \ --prop style=PivotStyleMedium7

要点：rows中的字段名:year/:quarter语法（另支持:month→ "2024-01"、:day→ "2024-01-05"）会触发ApplyDateGrouping预处理器：为每个分组字段派生虚拟列，并在缓存定义中生成原生<fieldGroup>+<rangePr>+<groupItems>XML。源码注释特别强调：缺少这段 XML 时 Excel 会报"fieldGroup 形状不匹配"而拒绝渲染内层层级。日期分组与计算字段、Top-N、labelFilter 一样，都会强制使用独立缓存（sharedExistingCache = null），避免派生缓存字段污染与其他透视表共享的缓存结构。

3.9 Sheet「9-Top 5 Products」—— Top-N 裁剪

只保留销售额前 5 的产品，且完全隐藏合计行。

officecli add pivot-tables.xlsx "/9-Top 5 Products" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Product \ --prop 'values=Sales:sum,Quantity:sum,Cost:sum' \ --prop layout=tabular \ --prop grandtotals=none \ --prop topN=5 \ --prop sort=desc \ --prop style=PivotStyleDark1

要点：topN=5的底层实现是ApplyTopNFilter（PivotTableHelper.cs）：它按最外层行字段取值，用第一个值字段的聚合函数降序排名，只保留前 N 个键，并在缓存构建之前直接裁剪源数据行，从而让缓存、渲染单元格与合计三者保持步调一致。同时ApplyTopNPivotFilter会把<filter type="count">写入透视定义，Excel 刷新时能据此重新应用裁剪。注意其已知边界：仅支持最外层行字段、仅支持"最大 N 个"、多值字段时按第一个值字段排名、topN是 Add 时一次性生效（Set 忽略）。

3.10 Sheet「10-Ultimate」—— 全家桶

所有特性叠加在一张透视表里：tabular + 重复标签 + 分组空行 + 双筛选 + 混合聚合 + 仅行合计。

officecli add pivot-tables.xlsx "/10-Ultimate" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region,Category \ --prop cols=Quarter \ --prop 'values=Sales:sum,Quantity:average,Cost:sum:percent_of_row' \ --prop 'filters=Channel,Priority' \ --prop layout=tabular \ --prop repeatlabels=true \ --prop blankrows=true \ --prop grandtotals=rows \ --prop subtotals=on \ --prop sort=desc \ --prop style=PivotStyleDark11

要点：repeatlabels=true+blankrows=true+ 双filters+ 混合聚合 +grandtotals=rows全部同时生效，是验证各参数正交组合的最佳回归样例——这正是官方示例把 10 号位置留给它的原因，可用于在 CI 中核对多特性叠加时几何与渲染不冲突。

3.11 Sheet「11-Chinese Locale」—— 中文区域排序

中文数据按拼音序排序（华北 < 华东 < 华南 < 西南），并自定义合计标签。证明字段名、筛选值与标题均可承载非 ASCII 文本。

officecli add pivot-tables.xlsx "/11-Chinese Locale" --type pivottable \ --prop source=CNData!A1:C13 \ --prop rows=地区,品类 \ --prop values=销售额:sum \ --prop layout=tabular \ --prop grandtotals=both \ --prop subtotals=on \ --prop sort=locale \ --prop grandTotalCaption=合计 \ --prop style=PivotStyleMedium2

要点：sort=locale使用zh-CN 区域性比较器做拼音排序。源码在 PivotTableHelper.cs 中明确：比较器硬编码为 zh-CN 而非CurrentCulture，否则在非中文进程区域（如 CI 上的 en-US）下 CJK 字符串会静默退化为序数比较，使 locale 模式与 asc 无法区分。grandTotalCaption=合计覆盖默认的 "Grand Total" 文案。

3.12 Sheet「12-Position + Aggregates」—— 锚点定位与冷门聚合

把透视表锚定在 D2 单元格（默认自动放置）；演示 count、min、product、countNums 四种不常用的聚合，以及aggregate=avg作为省略聚合时的默认值。

officecli add pivot-tables.xlsx "/12-Position + Aggregates" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop position=D2 \ --prop rows=Category \ --prop 'values=Sales:count,Quantity:min,Quantity:product,Sales:countNums' \ --prop aggregate=avg \ --prop layout=tabular \ --prop grandtotals=both \ --prop style=PivotStyleLight16

要点：position=D2覆盖默认的"源数据之后自动放置"；aggregate=avg是当某个值元组省略聚合段（如只写Sales）时套用的默认聚合，Add 与 Set 两条路径均支持该aggregate=位置参数覆盖。聚合函数全集见 pivottable.json 的 values 说明：sum, avg, count, max, min, product, stdev, stdevp, var, varp, countNums。注意页面筛选器存在时源码会自动把锚点下移，为筛选行留出filterCount + 1行的头部空间。

3.13 Sheet「13-Calculated Field」—— 计算字段与行级标签过滤

用户自定义公式字段（Margin = Sales - Cost、Tax = Sales * 0.1）自动作为数据字段加入——无需在values=中列出。预缓存的labelFilter只保留 Region 以 "N" 开头的行。

officecli add pivot-tables.xlsx "/13-Calculated Field" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop 'calculatedField1=Margin:=Sales-Cost' \ --prop 'calculatedField2=Tax:=Sales*0.1' \ --prop rows=Region \ --prop values=Sales:sum \ --prop 'labelFilter=Region:beginsWith:N' \ --prop layout=tabular \ --prop grandtotals=both \ --prop style=PivotStyleMedium3

要点：calculatedFieldN=名称:=公式（数字编号变体在源码中经正则去尾后归一到calculatedfield键）由ApplyCalculatedFields把 cacheField / pivotField / dataField 三元组追加进定义，公式存于 cacheField 上由 Excel 显示时实时计算，底层列不写入 sheetData。labelFilter=字段:类型:值支持contains / doesNotContain / beginsWith / endsWith / equals / notEquals六种类型（schema 中扩展列出 greaterThan/lessThan/between 等比较型），其 V2 行为是三分支执行：解析出结构化 spec、渲染路径裁剪非匹配行、同时在透视定义中写入<filter type="captionBeginsWith">使 Excel 刷新后仍保留过滤；缓存始终基于全量源数据构建，因此刷新可以重新求值。

3.14 Sheet「14-Statistical」—— 方差与独立 showDataAs

补全聚合函数集：样本方差var与总体方差varP。showDataAs=running_total作为独立属性（区别于字段:聚合:模式元组）设置，作为所有值字段的默认显示方式。

officecli add pivot-tables.xlsx "/14-Statistical" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region \ --prop cols=Quarter \ --prop 'values=Sales:var,Sales:varP,Sales:sum' \ --prop showDataAs=running_total \ --prop layout=tabular \ --prop grandtotals=both \ --prop style=PivotStyleLight10

要点：showDataAs的合法取值（见 pivottable.json）为normal, percentOfTotal, percentOfRow, percentOfCol, runningTotal；percentOfParent / rankAscending / rankDescending / index / difference / percentDifference 等暂未支持，传入未知 token 会抛出校验异常而非静默忽略。它既能写进单个values元组的第三段，也能以独立--prop showDataAs=形式对全部值字段生效。

3.15 Sheet「15-Independent Totals」—— 行/列合计独立开关

行合计与列合计可以独立开关（区别于合并语义的grandtotals=both/rows/cols/none）。defaultSubtotal=true给每个 pivotField 打上默认小计标记。sort=locale-desc反转拼音顺序（西南 > 华南 > 华东 > 华北）。

officecli add pivot-tables.xlsx "/15-Independent Totals" --type pivottable \ --prop source=CNData!A1:C13 \ --prop rows=地区 \ --prop cols=品类 \ --prop values=销售额:sum \ --prop rowGrandTotals=true \ --prop colGrandTotals=false \ --prop defaultSubtotal=true \ --prop layout=outline \ --prop subtotals=on \ --prop sort=locale-desc \ --prop style=PivotStyleMedium11

要点：rowGrandTotals/colGrandTotals细粒度布尔键在PushGrandTotalsOptions中于主键grandTotals之后解析并覆盖之。源码注释记录了一段重要的历史修正：CLI 层rowGrandTotals实际映射到 OOXML 的colGrandTotals（最右合计列），colGrandTotals映射到 OOXML 的rowGrandTotals（底部合计行）——属性读写层会做名称交换以匹配 Excel UI 语义，理解这个映射有助于排查自定义 XML 时的困惑。

3.16 Sheet「16-Style Flags」—— 五个样式旗标

pivotTableStyleInfo的全部五个旗标全部接上：行/列斑马纹、行/列标题强调、末列高亮——与 Excel「数据透视表样式」功能区中的五个复选框一一对应。

officecli add pivot-tables.xlsx "/16-Style Flags" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region,Category \ --prop cols=Quarter \ --prop values=Sales:sum \ --prop showRowStripes=true \ --prop showColStripes=true \ --prop showRowHeaders=true \ --prop showColHeaders=true \ --prop showLastColumn=true \ --prop layout=tabular \ --prop grandtotals=both \ --prop style=PivotStyleMedium17

要点：五个布尔旗标showRowStripes / showColStripes / showRowHeaders / showColHeaders / showLastColumn经ApplyPivotStyleInfoProps叠加到<pivotTableStyleInfo>上，Add 与 Set 共用同一套校验。源码还提供了用户向别名：bandedRows→showRowStripes、bandedCols/bandedColumns→showColStripes（Excel 功能区叫法），以及showColumnStripes/showColumnHeaders的 col/column 拼写归一。

3.17 Sheet「17-Display Toggles」—— 显示开关

showDrill=false隐藏每个字段上的 +/- 展开折叠按钮；mergeLabels=true合并并居中重复的外层轴项目单元格（写入<pivotTableDefinition mergeItem="1">）。

officecli add pivot-tables.xlsx "/17-Display Toggles" --type pivottable \ --prop source=Sheet1!A1:J51 \ --prop rows=Region,Category \ --prop values=Sales:sum \ --prop showDrill=false \ --prop mergeLabels=true \ --prop layout=outline \ --prop grandtotals=both \ --prop subtotals=on \ --prop style=PivotStyleLight19

要点：showDrill=false在源码中反转语义写入每个 pivotField 的showDropDowns=false（OOXML 默认 true，仅当用户显式关掉时才写出）；mergeLabels=true设置MergeItem属性。这两个参数均为 Add 时一次性生效，Set 忽略。本示例不设列轴，值字段自动变为列头，与 3.3 节同类但只含单值字段，用于对照验证多值/单值两种表头形态。

四、参数全景表：一张表看懂所有 --prop

以下取自 schemas/help/xlsx/pivottable.json，Add 路径全部可用：

键名宽容度：源码维护一张别名表（_pivotKeyAliases），row/rowField/rowFields→rows，col/column/columns/...→cols，columngrandtotals→colgrandtotals等，大小写不敏感，任意拼写风格都能归一。未识别键会触发UNSUPPORTED props警告（Add 写 stderr，Set 进入返回值），而不是静默丢弃。同时，日期分组/计算字段/Top-N/labelFilter 四类透视强制使用独立缓存，普通源透视则共享缓存（与 Excel"一个源一个缓存"的契约一致，刷新会传播到同源兄弟透视）。

五、检查生成的成品

数据透视表生成后，可以用三个命令做程序化检验（对应 pivot-tables.md 末尾）：

# 列出工作簿中所有数据透视表 officecli query pivot-tables.xlsx pivottable # 获取某张透视表的细节（含 rows/cols/values/dataField{N}/location 等只读回读字段） officecli get pivot-tables.xlsx "/1-Sales Overview/pivottable[1]" # 以纯文本方式查看渲染后的透视区域 officecli view pivot-tables.xlsx text --sheet "1-Sales Overview"

get的回读字段来自 pivottable.json 的只读部分：cacheId（缓存索引）、fieldCount/dataFieldCount、dataField{N}（打包为name:aggFunc:fieldIdx，name 反映 Excel 存储的 "Sum of ..." 前缀）、dataField{N}.showAs、location（渲染单元格范围）、collapsedFields、sortByField等。officecli view html则可用于透视结果的视觉检查。

需要说明的一个实现细节：OfficeCLI 会把透视的聚合结果直接渲染成目标 sheet 的<sheetData>字面单元格（见 PivotTableHelper.cs 中RenderPivotIntoSheet的注释）——这与 Excel 的行为一致（Excel 打开时也是直接读取渲染单元格而非从缓存重算），因此生成的文件在任意第三方解析器下都是自包含、可读的，即使不做刷新也能看到完整数据。RefreshPivotCellsForView还负责在 HTML/视图渲染前从缓存重新物化单元格，保证旧文件或仅定义文件的透视也能被正确展示。

六、延伸阅读

• 完整可运行脚本：pivot-tables.py（SDK 批量形态）与 pivot-tables.sh（CLI 逐条形态）
• 参数 Schema：schemas/help/xlsx/pivottable.json；命令行内可用officecli help xlsx pivottable查看
• 核心实现：src/officecli/Core/PivotTableHelper.cs（含缓存构建、日期分组、Top-N、标签过滤、几何计算与 6 个渲染路径，其余逻辑拆分在PivotTableHelper.Cache.cs/PivotTableHelper.Parse.cs/PivotTableHelper.Set.cs/PivotTableHelper.Render.cs等文件中）
• Excel 使用指引：skills/officecli-xlsx/SKILL.md（透视表 + 切片器组合用法）；示例总览见 examples/README.md
• 数据透视表常与切片器搭配使用，可参考同目录 slicers.md 示例

从命令行构造一张"Excel 打开即见、刷新仍正确"的数据透视表，本质是对缓存、定义、渲染三者一致性的把控。17 个示例从双轴、双筛选、多聚合的旗舰配置，到拼音排序、计算字段、独立合计开关的边界特性，完整覆盖了officecli add --type pivottable的实用面——直接把示例命令改改source与字段名，就是一份可立即投入生产的数据透视表生成模板。

• CLI
• AI 应用
• MCP 服务