企业官网建设流程全解析

OfficeCLI 饼图自动化实战：用 charts-pie 示例掌握 PPT 饼图的 30+ 项可编程属性

【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具，可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源，仅包含一个二进制文件，无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI

本指南以 OfficeCLI 仓库自带的charts-pie演示（8 张幻灯片、每页 4 个图表、共 32 个饼图变体）为主线，系统讲解如何用officecliCLI 与 Python SDK 通过命令和属性参数，从零生成、定制并验证 PPT 饼图。读完本文，你将掌握饼图类型选择、扇区爆炸与起始角度、标题图例、数据标签、系列配色、背景修饰、预设主题以及图表的后期定位修改（set）等一整套可复现的自动化方案。

演示文件构成与重新生成

charts-pie演示由三个文件协同工作，位于 examples/ppt/charts 目录：

• charts-pie.py— Python 脚本，通过officecliPython SDK（pip install officecli-sdk）驱动命令生成演示文稿；
• charts-pie.sh— 与.py等价的纯 CLI 版本，逐条调用officecli add，两者产出相同的charts-pie.pptx；
• charts-pie.md— 当前文档，把每张幻灯片映射到它所演示的特性；
• charts-pie.pptx— 生成的成品（8 页 × 每页 4 图 = 32 个饼图）。

通过 CLI 重新生成的方式（Shell 版本）：

cd examples/ppt/charts ./charts-pie.sh # → 生成 charts-pie.pptx（脚本末尾还会执行 officecli validate）

Python 版本（SDK 方式）：

pip install officecli-sdk # 需要 officecli 二进制在 PATH 中 python3 charts-pie.py # → charts-pie.pptx

值得说明的是，两个脚本刻意不开启set -e：正如 charts-pie.sh 头部注释所写，它们容忍向前兼容的UNSUPPORTED props警告（officecli以退出码 2 返回），保证整份文档能完整构建出来。Python 版通过doc.batch(...)在一次往返中批量提交每条{"command","parent","type","props"}指令，与officecli batch列表中的条目一一对应；若未安装 SDK，脚本会自动回退到仓库内 sdk/python 目录的副本。

通用的四象限布局与数据源

每张幻灯片复用同一个"四象限"定位模板（见 charts-pie.py）：

所有图表共用同一份演示数据：4 个类别North,South,East,West，单一系列Share:30,25,28,17。在 CLI 中通过两个属性传入：

--prop categories="North,South,East,West" --prop data="Share:30,25,28,17"

categories是逗号分隔的类别标签，data是内联系列描述，格式为Name:1,2,3，多系列用分号分隔（如Sales:10,20,30;Cost:5,8,12）。按 schemas/help/_shared/chart.json 的定义，data仅能在添加（Add）时使用，创建后修改数据请改用 chart-series 元素上的set操作。

Slide 1 — 类型变体：pie / pie3d 与基础开关

第一页展示饼图最基本的四个属性组合：

# 标准饼图，自动为每个扇区配色 officecli add charts-pie.pptx /slide[1] --type chart \ --prop chartType=pie --prop title="pie" --prop legend=right \ --prop varyColors=true \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" \ --prop x=0.3in --prop y=1.05in --prop width=6.1in --prop height=3in # 3D 饼图，带 view3d 透视参数 officecli add charts-pie.pptx /slide[1] --type chart \ --prop chartType=pie3d --prop title="pie3d (view3d=20,20,30)" \ --prop view3d="20,20,30" --prop legend=right --prop varyColors=true \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" \ --prop x=6.95in --prop y=1.05in --prop width=6.1in --prop height=3in # 起始扇区从 90° 开始而不是 0° officecli add charts-pie.pptx /slide[1] --type chart \ --prop chartType=pie --prop title="firstSliceAngle=90" \ --prop firstSliceAngle=90 --prop legend=right \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" \ --prop x=0.3in --prop y=4.25in --prop width=6.1in --prop height=3in # 单一纯色（varyColors=false） officecli add charts-pie.pptx /slide[1] --type chart \ --prop chartType=pie --prop title="varyColors=false" \ --prop varyColors=false --prop legend=right \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" \ --prop x=6.95in --prop y=4.25in --prop width=6.1in --prop height=3in

Slide 1 覆盖的特性：chartType（pie/pie3d）、varyColors、firstSliceAngle（0–360°）、view3d。

关于这些属性，有几条值得注意的底层约束：

• chartType是仅创建时生效的属性。按照 schemas/help/pptx/chart.json 的说明，创建后切换图表类型不被支持（各类型的系列、坐标轴 XML 结构差异太大），必须删除重建。输入时它很宽容，接受pie、pie3d等友好别名；而读取（Get）返回的是系统化记号，如pieOfPie、barOfPie。
• varyColors适用于单系列图表，让每个数据点拥有独立颜色（对应 OOXML 中的varyColors标志）。
• firstSliceAngle只对pie/doughnut生效（schema 中以appliesWhen: chartType=pie声明），以角度为单位，默认从 0°（正上方偏右）开始排布扇区。
• view3d的完整格式是rotX,rotY,perspective，尾部可以省略（也可以只传单个整数仅设置透视），命名键形式（如rotX=...）会被拒绝，见 schemas/help/_shared/chart.json 中view3d的定义。

Slide 2 — 扇区爆炸（Explosion）

爆炸效果把每个扇区沿半径方向推出一定百分比，适合强调占比结构：

for angle in 0 10 20 30; do officecli add charts-pie.pptx /slide[2] --type chart \ --prop chartType=pie --prop title="explosion=$angle" \ --prop explosion=$angle --prop legend=right \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" done

Slide 2 覆盖的特性：explosion（0–100，占饼图半径的百分比）。

从源码看，explosion的实现会落到每个数据点上：在 ChartHelper.SetterHelpers.cs 中，ApplyDataPointExplosion为指定数据点写入 OOXML 的dPt/Explosion元素（Explosion { Val = explosion }），且仅在explosion > 0时生成该节点。也就是说，值为 0 时不会产生冗余的 XML 节点，而explosion的别名explode同样被接受。该属性支持 Add 与 Set，创建后仍可修改。

Slide 3 — 标题与图例

标题和图例是饼图信息传达的"门面"，这一页覆盖四种组合：

# 标题字体样式：Georgia 20pt、蓝色 4472C4、加粗 officecli add charts-pie.pptx /slide[3] --type chart \ --prop chartType=pie --prop title="Styled title" \ --prop title.font=Georgia --prop title.size=20 \ --prop title.color=4472C4 --prop title.bold=true \ --prop legend=right --prop categories="North,South,East,West" \ --prop data="Share:30,25,28,17" # 图例置于底部 + 自定义图例字体 officecli add charts-pie.pptx /slide[3] --type chart \ --prop chartType=pie --prop title="legend=bottom + legendFont" \ --prop legend=bottom --prop legendFont="10:333333:Calibri" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 图例叠加在绘图区之上（不占用额外空间） officecli add charts-pie.pptx /slide[3] --type chart \ --prop chartType=pie --prop title="legend.overlay=true" \ --prop legend=topRight --prop legend.overlay=true \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 完全移除自动标题与图例 officecli add charts-pie.pptx /slide[3] --type chart \ --prop chartType=pie --prop autotitledeleted=true --prop legend=none \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17"

Slide 3 覆盖的特性：title.font、title.size、title.color、title.bold、legend（right/bottom/topRight/none）、legendFont、legend.overlay、autotitledeleted。

参数细节（依据 schemas/help/_shared/chart.json）：

• legend是枚举：true|false|none|top|bottom|left|right|topRight|tr，其中none/false隐藏图例；连字符与下划线变体（如top-right）同样被接受。
• legendFont与labelfont使用同一个复合格式size:color:fontname，任意段可省略，例如legendFont=9:808080只设置字号与颜色。读取时它被拆分为labelFont.size / labelFont.color / labelFont.bold / labelFont.name等独立键，便于 dump→replay 重建。
• legend.overlay=true让图例覆盖在绘图区之上而不是预留空间。
• title传none（不区分大小写）或空字符串时，添加阶段直接跳过标题元素创建；autotitledeleted=true则抑制自动生成的"Chart Title"占位符。
• 标题字体属性（title.font/size/color/bold）同时支持 Add 与 Set，创建后仍可调整。

Slide 4 — 数据标签与引导线

数据标签控制扇区上直接标注的内容：

# 只显示百分比 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartType=pie --prop title="dataLabels=percent" \ --prop dataLabels=percent --prop legend=right \ --prop labelfont="10:333333:Calibri" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 百分比 + 类别名，并为每个扇区绘制引导线 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartType=pie --prop title="percent,category + leaderlines" \ --prop dataLabels="percent,category" --prop leaderlines=true \ --prop legend=none --prop labelfont="10:333333:Calibri" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 同时显示数值、百分比、类别名 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartType=pie --prop title="all flags (value,percent,category)" \ --prop dataLabels="value,percent,category" --prop leaderlines=true \ --prop legend=none \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 不显示任何数据标签 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartType=pie --prop title="dataLabels=none" \ --prop dataLabels=none --prop legend=right \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17"

Slide 4 覆盖的特性：dataLabels（percent/category/value/none 或任意组合）、leaderlines、labelfont。

根据 schema 说明：

• dataLabels的取值：none隐藏；否则是标志位逗号列表——value、percent、category、series、all（也接受seriesName/categoryName/percentage/values等别名）。位置值（outsideEnd/center/insideEnd/insideBase/top/bottom/left/right/bestFit）会隐式启用showVal并作为dLblPos应用。
• 位置值对饼图有限制：按 schemas/help/_shared/chart.json 中labelPos的定义，pie/pie3D 仅允许ctr/inEnd/inBase/bestFit（严格遵循 OOXMLST_DLblPosPie枚举），其他 token 会被拒绝。
• leaderlines=true仅在饼图/圆环图中生效，为数据标签到扇区绘制连接引导线。
• labelfont使用size:color:fontname复合格式，本页演示统一使用10:333333:Calibri（10pt、深灰 333333、Calibri 字体）。

Slide 5 — 系列样式：调色板、渐变、阴影、描边与透明度

这一页演示如何批量美化学区外观：

# 显式调色板：四个扇区依次使用指定颜色 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartType=pie --prop title="colors= explicit palette" --prop legend=right \ --prop colors="4472C4,ED7D31,A5A5A5,70AD47" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 渐变填充 + 系列阴影 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartType=pie --prop title="gradient + seriesshadow" --prop legend=right \ --prop gradient="FF6600-FFCC00" --prop seriesshadow="000000-5-45-3-50" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 白色描边，宽度 2 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartType=pie --prop title="seriesoutline white" --prop legend=right \ --prop seriesoutline="FFFFFF:2" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 扇区 30% 透明 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartType=pie --prop title="transparency=30" --prop legend=right \ --prop transparency=30 \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17"

Slide 5 覆盖的特性：colors、gradient、seriesshadow、seriesoutline、transparency。

参数格式（依据 schemas/help/_shared/chart.json）：

• colors：逗号分隔、按位置对应各系列的填充色（第 1 个颜色 → 系列 1）。创建后不可修改（add-only，set: false），若要逐点改色请用 per-series 的点属性（如series{N}.point{M}.color）。
• gradient：格式c1-c2[-c3][:angle]，角度为度数；若图表没有系列会直接报错。
• seriesshadow：格式COLOR-BLUR-ANGLE-DIST-OPACITY，例如000000-5-45-3-50表示黑色、模糊 5、角度 45°、距离 3、不透明度 50%；传none移除。
• seriesoutline：格式color、color:width或color:width:dash（也接受-分隔符），none移除。
• transparency：0–100 的百分比，它是opacity/alpha的反义（transparency=30≡opacity=70）。

Slide 6 — 起始角度全范围巡览

将第一扇区起始角遍历 0/90/180/270，直观对比四个方向：

for ang in 0 90 180 270; do officecli add charts-pie.pptx /slide[6] --type chart \ --prop chartType=pie --prop title="firstSliceAngle=$ang" \ --prop firstSliceAngle=$ang --prop legend=right --prop varyColors=true \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" done

Slide 6 覆盖的特性：firstSliceAngle（0/90/180/270 度——全范围调研）。这一页与 Slide 1 的第三个图（firstSliceAngle=90）共同验证了该属性在整个 0–360° 范围内的行为，适合在选型时快速预览"哪个起始角度最顺眼"。

Slide 7 — 图表背景与边框

控制绘图区、图表区的填充与描边：

# 图表区暖色填充 + 黑色细边框 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartType=pie --prop title="chartareafill + chartborder" --prop legend=right \ --prop chartareafill=FFF8E7 --prop chartborder="000000:1" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 圆角 + 蓝色边框 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartType=pie --prop title="roundedcorners=true" --prop legend=right \ --prop roundedcorners=true --prop chartborder="4472C4:2" \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 绘图区无填充 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartType=pie --prop title="plotFill=none" --prop legend=right \ --prop plotFill=none \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 图表区无填充 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartType=pie --prop title="chartareafill=none" --prop legend=right \ --prop chartareafill=none \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17"

Slide 7 覆盖的特性：chartareafill（hex 或 none）、plotFill（hex 或 none）、chartborder、roundedcorners。

需要区分两个区域：chartareafill作用于整个图表区域背景，plotFill只作用于绘图区（扇区所在的坐标区）。两者都支持纯色、渐变（c1-c2[:angle]）或none。chartborder与plotborder使用相同的线格式：color、color:width、color:width:dash或none。roundedcorners在 schemas/help/_shared/chart.docx-pptx.json 中定义，用于圆化图表区域的外角。

Slide 8 — 预设主题与逐系列 Set 修改

最后一页把前面学到的能力收尾：用预设一键换肤，再用set对既有图表做定点修改。

# 三个预设主题 for p in minimal dark corporate; do officecli add charts-pie.pptx /slide[8] --type chart \ --prop chartType=pie --prop preset=$p --prop title="preset=$p" \ --prop legend=right \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" done # 第四个图表，创建后修改其系列 officecli add charts-pie.pptx /slide[8] --type chart \ --prop chartType=pie --prop title="chart-series Set name+color" --prop legend=right \ --prop categories="North,South,East,West" --prop data="Share:30,25,28,17" # 创建后修改系列名称与颜色（后置修改） officecli set charts-pie.pptx "/slide[8]/chart[4]/series[1]" \ --prop name="Renamed Share" --prop color=C00000

Slide 8 覆盖的特性：preset（minimal/dark/corporate）、chart-series 元素的set（name=/color=）。

关于preset，其完整取值在 src/officecli/Core/Chart/ChartPresets.cs 中维护：minimal、dark、corporate、magazine、dashboard、colorful、monochrome（别名mono）。每个预设是一组命名样式捆绑（例如dark使用深色背景、明亮数据色与白色文字，适合深色幻灯片）。preset同样支持 Add 与 Set，创建后仍可整体换肤。

最后一个set命令展示了位置式路径的定点修改：/slide[8]/chart[4]/series[1]表示第 8 页第 4 个图表的第 1 个系列。chart 元素的位置式路径为/slide[N]/chart[N]（另有稳定形式/slide[N]/chart[@id=ID]），chart-series 以series段挂在 chart 之下，基数 1..n（见 schemas/help/pptx/chart.json 的 children 定义）。修改后该系列名称变为 "Renamed Share"、颜色变为C00000。

完整特性覆盖一览

下表汇总了本演示 8 页幻灯片覆盖的全部饼图特性，可作为自动化选型的速查表：

检查与验证生成的图表

生成之后，可以用officecli的读取类命令核对产物，这既是验证，也是了解文档对象模型（DOM）路径的好方式：

# 列出文档中全部 chart 元素 officecli query charts-pie.pptx chart # 读取第 1 页第 1 个图表的完整属性（含 title.* 等回读键） officecli get charts-pie.pptx "/slide[1]/chart[1]" # 读取第 2 页第 2 个图表的属性 officecli get charts-pie.pptx "/slide[2]/chart[2]" # 读取第 8 页第 4 个图表第 1 个系列（验证 set 的结果） officecli get charts-pie.pptx "/slide[8]/chart[4]/series[1]"

从演示到生产的几个实践要点

• 一次批量、一个常住进程：Python SDK 版在with officecli.create(FILE, "--force") as doc:中启动一个常住进程，所有 slide/shape/chart 通过命名管道以doc.batch(...)往返提交，避免每个图表都启动一次二进制。CLI 版则按create → open → add... → close → validate的流程执行，.sh脚本末尾的officecli validate用于整体校验生成结果。
• 属性即契约：饼图相关属性的类型、别名、适用范围与读写时机都以 schemas/help/_shared/chart.json 和 schemas/help/pptx/chart.json 为权威定义，新增chartType值必须同步修改处理器与 schema（仓库以契约测试保证二者等价）。据此可以推断：凡是 schema 中标明set: true的属性（如explosion、title.*、legend、dataLabels、preset、chartareafill等）都支持创建后修改，而chartType、data、colors等属于 Add-time only，需要重建或改用系列级set。
• 样式函数落在哪一层：explosion等按数据点生效的属性最终落到 OOXML 的dPt节点（ChartHelper.SetterHelpers.cs 中的ApplyDataPointExplosion），并遵循严格的 schema 顺序（如 CT_PieSer：idx, order, tx?, spPr?, explosion?, dPt*, dLbls?, cat?, val?, extLst?）；这意味着自动生成的 XML 始终可被 PowerPoint 与 WPS 正常解析，而非手写字符串拼接。

至此，从"类型选择"到"主题预设"再到"后置修改"，8 页 32 图已经覆盖了 OfficeCLI 饼图能力的主干路径。你可以把charts-pie.py/charts-pie.sh当作模板，替换categories与data即为真实业务数据，替换象限坐标即为任意版式布局——整条流水线完全由命令与属性驱动，天然适合嵌入 Agent 工作流与 CI 自动化。

【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具，可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源，仅包含一个二进制文件，无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI