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 SDKpip install officecli-sdk驱动命令生成演示文稿charts-pie.sh— 与.py等价的纯 CLI 版本逐条调用officecli add两者产出相同的charts-pie.pptxcharts-pie.md— 当前文档把每张幻灯片映射到它所演示的特性charts-pie.pptx— 生成的成品8 页 × 每页 4 图 32 个饼图。通过 CLI 重新生成的方式Shell 版本cd examples/ppt/charts ./charts-pie.sh # → 生成 charts-pie.pptx脚本末尾还会执行 officecli validatePython 版本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象限xywidthheight左上 TL0.3in1.05in6.1in3in右上 TR6.95in1.05in6.1in3in左下 BL0.3in4.25in6.1in3in右下 BR6.95in4.25in6.1in3in所有图表共用同一份演示数据4 个类别North,South,East,West单一系列Share:30,25,28,17。在 CLI 中通过两个属性传入--prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17categories是逗号分隔的类别标签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 chartTypepie --prop titlepie --prop legendright \ --prop varyColorstrue \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 \ --prop x0.3in --prop y1.05in --prop width6.1in --prop height3in # 3D 饼图带 view3d 透视参数 officecli add charts-pie.pptx /slide[1] --type chart \ --prop chartTypepie3d --prop titlepie3d (view3d20,20,30) \ --prop view3d20,20,30 --prop legendright --prop varyColorstrue \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 \ --prop x6.95in --prop y1.05in --prop width6.1in --prop height3in # 起始扇区从 90° 开始而不是 0° officecli add charts-pie.pptx /slide[1] --type chart \ --prop chartTypepie --prop titlefirstSliceAngle90 \ --prop firstSliceAngle90 --prop legendright \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 \ --prop x0.3in --prop y4.25in --prop width6.1in --prop height3in # 单一纯色varyColorsfalse officecli add charts-pie.pptx /slide[1] --type chart \ --prop chartTypepie --prop titlevaryColorsfalse \ --prop varyColorsfalse --prop legendright \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 \ --prop x6.95in --prop y4.25in --prop width6.1in --prop height3inSlide 1 覆盖的特性chartTypepie/pie3d、varyColors、firstSliceAngle0–360°、view3d。关于这些属性有几条值得注意的底层约束chartType是仅创建时生效的属性。按照 schemas/help/pptx/chart.json 的说明创建后切换图表类型不被支持各类型的系列、坐标轴 XML 结构差异太大必须删除重建。输入时它很宽容接受pie、pie3d等友好别名而读取Get返回的是系统化记号如pieOfPie、barOfPie。varyColors适用于单系列图表让每个数据点拥有独立颜色对应 OOXML 中的varyColors标志。firstSliceAngle只对pie/doughnut生效schema 中以appliesWhen: chartTypepie声明以角度为单位默认从 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 chartTypepie --prop titleexplosion$angle \ --prop explosion$angle --prop legendright \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 doneSlide 2 覆盖的特性explosion0–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 chartTypepie --prop titleStyled title \ --prop title.fontGeorgia --prop title.size20 \ --prop title.color4472C4 --prop title.boldtrue \ --prop legendright --prop categoriesNorth,South,East,West \ --prop dataShare:30,25,28,17 # 图例置于底部 自定义图例字体 officecli add charts-pie.pptx /slide[3] --type chart \ --prop chartTypepie --prop titlelegendbottom legendFont \ --prop legendbottom --prop legendFont10:333333:Calibri \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 图例叠加在绘图区之上不占用额外空间 officecli add charts-pie.pptx /slide[3] --type chart \ --prop chartTypepie --prop titlelegend.overlaytrue \ --prop legendtopRight --prop legend.overlaytrue \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 完全移除自动标题与图例 officecli add charts-pie.pptx /slide[3] --type chart \ --prop chartTypepie --prop autotitledeletedtrue --prop legendnone \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17Slide 3 覆盖的特性title.font、title.size、title.color、title.bold、legendright/bottom/topRight/none、legendFont、legend.overlay、autotitledeleted。参数细节依据 schemas/help/_shared/chart.jsonlegend是枚举true|false|none|top|bottom|left|right|topRight|tr其中none/false隐藏图例连字符与下划线变体如top-right同样被接受。legendFont与labelfont使用同一个复合格式size:color:fontname任意段可省略例如legendFont9:808080只设置字号与颜色。读取时它被拆分为labelFont.size / labelFont.color / labelFont.bold / labelFont.name等独立键便于 dump→replay 重建。legend.overlaytrue让图例覆盖在绘图区之上而不是预留空间。title传none不区分大小写或空字符串时添加阶段直接跳过标题元素创建autotitledeletedtrue则抑制自动生成的Chart Title占位符。标题字体属性title.font/size/color/bold同时支持 Add 与 Set创建后仍可调整。Slide 4 — 数据标签与引导线数据标签控制扇区上直接标注的内容# 只显示百分比 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartTypepie --prop titledataLabelspercent \ --prop dataLabelspercent --prop legendright \ --prop labelfont10:333333:Calibri \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 百分比 类别名并为每个扇区绘制引导线 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartTypepie --prop titlepercent,category leaderlines \ --prop dataLabelspercent,category --prop leaderlinestrue \ --prop legendnone --prop labelfont10:333333:Calibri \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 同时显示数值、百分比、类别名 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartTypepie --prop titleall flags (value,percent,category) \ --prop dataLabelsvalue,percent,category --prop leaderlinestrue \ --prop legendnone \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 不显示任何数据标签 officecli add charts-pie.pptx /slide[4] --type chart \ --prop chartTypepie --prop titledataLabelsnone \ --prop dataLabelsnone --prop legendright \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17Slide 4 覆盖的特性dataLabelspercent/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 会被拒绝。leaderlinestrue仅在饼图/圆环图中生效为数据标签到扇区绘制连接引导线。labelfont使用size:color:fontname复合格式本页演示统一使用10:333333:Calibri10pt、深灰 333333、Calibri 字体。Slide 5 — 系列样式调色板、渐变、阴影、描边与透明度这一页演示如何批量美化学区外观# 显式调色板四个扇区依次使用指定颜色 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartTypepie --prop titlecolors explicit palette --prop legendright \ --prop colors4472C4,ED7D31,A5A5A5,70AD47 \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 渐变填充 系列阴影 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartTypepie --prop titlegradient seriesshadow --prop legendright \ --prop gradientFF6600-FFCC00 --prop seriesshadow000000-5-45-3-50 \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 白色描边宽度 2 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartTypepie --prop titleseriesoutline white --prop legendright \ --prop seriesoutlineFFFFFF:2 \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 扇区 30% 透明 officecli add charts-pie.pptx /slide[5] --type chart \ --prop chartTypepie --prop titletransparency30 --prop legendright \ --prop transparency30 \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17Slide 5 覆盖的特性colors、gradient、seriesshadow、seriesoutline、transparency。参数格式依据 schemas/help/_shared/chart.jsoncolors逗号分隔、按位置对应各系列的填充色第 1 个颜色 → 系列 1。创建后不可修改add-onlyset: 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移除。transparency0–100 的百分比它是opacity/alpha的反义transparency30≡opacity70。Slide 6 — 起始角度全范围巡览将第一扇区起始角遍历 0/90/180/270直观对比四个方向for ang in 0 90 180 270; do officecli add charts-pie.pptx /slide[6] --type chart \ --prop chartTypepie --prop titlefirstSliceAngle$ang \ --prop firstSliceAngle$ang --prop legendright --prop varyColorstrue \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 doneSlide 6 覆盖的特性firstSliceAngle0/90/180/270 度——全范围调研。这一页与 Slide 1 的第三个图firstSliceAngle90共同验证了该属性在整个 0–360° 范围内的行为适合在选型时快速预览哪个起始角度最顺眼。Slide 7 — 图表背景与边框控制绘图区、图表区的填充与描边# 图表区暖色填充 黑色细边框 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartTypepie --prop titlechartareafill chartborder --prop legendright \ --prop chartareafillFFF8E7 --prop chartborder000000:1 \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 圆角 蓝色边框 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartTypepie --prop titleroundedcornerstrue --prop legendright \ --prop roundedcornerstrue --prop chartborder4472C4:2 \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 绘图区无填充 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartTypepie --prop titleplotFillnone --prop legendright \ --prop plotFillnone \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 图表区无填充 officecli add charts-pie.pptx /slide[7] --type chart \ --prop chartTypepie --prop titlechartareafillnone --prop legendright \ --prop chartareafillnone \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17Slide 7 覆盖的特性chartareafillhex 或 none、plotFillhex 或 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 chartTypepie --prop preset$p --prop titlepreset$p \ --prop legendright \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 done # 第四个图表创建后修改其系列 officecli add charts-pie.pptx /slide[8] --type chart \ --prop chartTypepie --prop titlechart-series Set namecolor --prop legendright \ --prop categoriesNorth,South,East,West --prop dataShare:30,25,28,17 # 创建后修改系列名称与颜色后置修改 officecli set charts-pie.pptx /slide[8]/chart[4]/series[1] \ --prop nameRenamed Share --prop colorC00000Slide 8 覆盖的特性presetminimal/dark/corporate、chart-series 元素的setname/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[idID]chart-series 以series段挂在 chart 之下基数 1..n见 schemas/help/pptx/chart.json 的 children 定义。修改后该系列名称变为 Renamed Share、颜色变为C00000。完整特性覆盖一览下表汇总了本演示 8 页幻灯片覆盖的全部饼图特性可作为自动化选型的速查表FeatureSlide图表类型pie, pie3d1varyColors1firstSliceAngle0–3601, 6view3dpie3d1explosion0–100%2标题样式title.font/size/color/bold3图例right/bottom/topRight/none、legendFont、legend.overlay3autotitledeleted3dataLabelspercent/category/value/none 组合4leaderlines4labelfont4colors调色板5gradient、seriesshadow、seriesoutline、transparency5chartareafill、plotFill、chartborder、roundedcorners7presetminimal/dark/corporate8chart-series Setname/color8检查与验证生成的图表生成之后可以用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_PieSeridx, 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考