用 OfficeCLI 从命令行批量生成 PPT 条形图：charts-bar 全特性实战指南

用 OfficeCLI 从命令行批量生成 PPT 条形图：charts-bar 全特性实战指南

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

OfficeCLI 是专为 AI 代理设计的命令行工具，可读取、编辑并自动化处理 Word、Excel 与 PowerPoint 文件。本指南以仓库中的examples/ppt/charts/charts-bar.md为核心，完整演示如何通过一条条officecli add ... --type chart命令，在幻灯片上生成bar / stackedBar / percentStackedBar / bar3d四类条形图，并覆盖标题、图例、数据标签、坐标轴、系列样式、参考线、误差线、预设主题与逐系列控制等全部图表能力。读完本文，你将掌握用纯命令行（或等价的 Python SDK 批量接口）从零构建一张包含 32 张条形图的 8 页演示文稿，并学会用set/query/get对已生成的图表做二次修改与回读校验。

示例文件与三种使用方式

charts-bar示例由三个相互配合的文件组成（均位于 examples/ppt/charts）：

• charts-bar.py — Python 脚本，通过officecli的Python SDK（pip install officecli-sdk）驱动命令生成演示文稿。脚本内部启动一个常驻（resident）进程，所有增删改操作以doc.batch(...)批量指令经命名管道传输，每个元素正是officecli batch列表中的{"command","parent","type","props"}字典；
• charts-bar.sh — 与 SDK 等价的纯 CLI 脚本，逐条调用officecli create / open / add / set / close / validate，产出完全一致的charts-bar.pptx；
• charts-bar.md — 本指南对应的说明文档，将每页幻灯片映射到它所演示的特性；
• charts-bar.pptx — 生成的 8 页演示文稿成品，每页 4 张图、共 32 张条形图。

重新生成演示文稿（CLI 脚本方式）：

cd examples/ppt/charts bash charts-bar.sh # → charts-bar.pptx

Python SDK 方式：

pip install officecli-sdk # 并将 officecli 二进制加入 PATH python3 charts-bar.py # → charts-bar.pptx

值得注意的细节：charts-bar.sh刻意没有使用set -e，与 SDK 端的doc.batch一样，它会容忍前向兼容的UNSUPPORTED props警告（officecli 以退出码 2 返回）并继续构建，从而保证整份文档完整产出。脚本底部用$CLI close "$FILE"收尾，并以$CLI validate "$FILE"做成品校验。

布局基础：每页 4 图的几何坐标

两张脚本共享同一套几何与数据定义（见 charts-bar.py 顶部）：

TL = {"x": "0.3in", "y": "1.05in", "width": "6.1in", "height": "3in"} # 左上 TR = {"x": "6.95in", "y": "1.05in", "width": "6.1in", "height": "3in"} # 右上 BL = {"x": "0.3in", "y": "4.25in", "width": "6.1in", "height": "3in"} # 左下 BR = {"x": "6.95in", "y": "4.25in", "width": "6.1in", "height": "3in"} # 右下

x/y/width/height支持in（英寸）等单位后缀，对应 PPTX 内部 EMU 坐标换算。数据格式统一为系列名:值1,值2,...，多系列用分号分隔：

D2="East:120,135,148,162;West:95,108,115,128" # 双系列 D3="East:120,135,148,162;South:95,108,115,128;West:80,90,98,110" # 三系列

Slide 1 — 基础变体：bar / stackedBar / percentStackedBar / bar3d

第一页用四张图对比四种核心类型，其中bar3d额外通过view3d="15,20,30"指定三维视角（绕 x / y 轴旋转角度与缩放）：

officecli add charts-bar.pptx /slide[1] --type chart \ --prop chartType=bar --prop title="bar" --prop legend=bottom \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" \ --prop x=0.3in --prop y=1.05in --prop width=6.1in --prop height=3in officecli add charts-bar.pptx /slide[1] --type chart \ --prop chartType=stackedBar --prop title="stackedBar" --prop legend=bottom \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;South:95,108,115,128;West:80,90,98,110" \ --prop x=6.95in --prop y=1.05in --prop width=6.1in --prop height=3in officecli add charts-bar.pptx /slide[1] --type chart \ --prop chartType=percentStackedBar --prop title="percentStackedBar" --prop legend=bottom \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;South:95,108,115,128;West:80,90,98,110" \ --prop x=0.3in --prop y=4.25in --prop width=6.1in --prop height=3in officecli add charts-bar.pptx /slide[1] --type chart \ --prop chartType=bar3d --prop title="bar3d" --prop legend=bottom \ --prop view3d="15,20,30" \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" \ --prop x=6.95in --prop y=4.25in --prop width=6.1in --prop height=3in

特性覆盖：chartType（bar/stackedBar/percentStackedBar/bar3d）、categories、data、legend、view3d。

实现原理：在 ChartHelper.Builder.cs 中，bar3d（以及column3d）走C.Bar3DChart分支：先按kind决定BarDirectionValues.Bar/Column，再通过C.BarGrouping映射stacked与percentStacked（缺省为Clustered），并固定追加GapWidth = 150与三个轴引用（category / value /series 轴，因此 3D 条形图额外需要系列轴）。非 3D 的bar则走BuildBarChart(C.BarDirectionValues.Bar, ...)，共享同一套系列构造逻辑。chartType的完整枚举与别名在 schemas/help/pptx/chart.json 中定义：输入接受友好别名（如stackedArea、bar3D、percentStackedColumn），而Get回读会返回统一的base_modifier规范形式（如bar_stacked、bar_percentStacked、bar3d）。

Slide 2 — 3D 条形图几何形状：shape=box/cylinder/cone/pyramid

shape属性只对bar3d生效，用于控制三维条形的几何形态：

# shape= 控制 3D 条形几何（仅 bar3d） officecli add charts-bar.pptx /slide[2] --type chart \ --prop chartType=bar3d --prop shape=box --prop title="shape=box" \ --prop legend=none --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" officecli add charts-bar.pptx /slide[2] --type chart \ --prop chartType=bar3d --prop shape=cylinder --prop title="shape=cylinder" \ --prop legend=none --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" officecli add charts-bar.pptx /slide[2] --type chart \ --prop chartType=bar3d --prop shape=cone --prop title="shape=cone" \ --prop legend=none --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" officecli add charts-bar.pptx /slide[2] --type chart \ --prop chartType=bar3d --prop shape=pyramid --prop title="shape=pyramid" \ --prop legend=none --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128"

特性覆盖：shape（box/cylinder/cone/pyramid），仅用于bar3d。此类 3D 条形几何参数（shape、barshape、shape3d等）在构建器中作为 3D 图表的专用键处理（参见 ChartHelper.Builder.cs 附近的属性清单）。

Slide 3 — 标题与图例样式

第三页演示标题字体、图例位置、图例叠加与自动标题删除四类样式控制：

officecli add charts-bar.pptx /slide[3] --type chart \ --prop chartType=bar --prop title="Styled title" \ --prop title.font=Georgia --prop title.size=20 \ --prop title.color=4472C4 --prop title.bold=true \ --prop legend=bottom --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" officecli add charts-bar.pptx /slide[3] --type chart \ --prop chartType=bar --prop title="legend=top + legendFont" \ --prop legend=top --prop legendFont="10:333333:Calibri" \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" officecli add charts-bar.pptx /slide[3] --type chart \ --prop chartType=bar --prop title="legend.overlay=true" \ --prop legend=topRight --prop legend.overlay=true \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128" officecli add charts-bar.pptx /slide[3] --type chart \ --prop chartType=bar --prop autotitledeleted=true --prop legend=none \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128"

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

使用要点：legendFont采用字号:颜色:字体三段式紧凑语法（如10:333333:Calibri），与后文labelfont、axisfont保持一致；legend.overlay=true让图例叠加在绘图区之上而不挤压图表区域；autotitledeleted=true可删除随图表自动生成的标题占位（常用于图表本身已有视觉标题的场景）。

Slide 4 — 数据标签：dataLabels / labelPos / labelfont

数据标签支持多个内容的组合显示，以及四种标签位置：

officecli add charts-bar.pptx /slide[4] --type chart \ --prop chartType=bar --prop title="value @ outsideEnd" \ --prop dataLabels=value --prop labelPos=outsideEnd \ --prop labelfont="10:333333:Calibri" --prop legend=none \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180" officecli add charts-bar.pptx /slide[4] --type chart \ --prop chartType=bar --prop title="value,category @ insideEnd" \ --prop dataLabels="value,category" --prop labelPos=insideEnd \ --prop labelfont="9:FFFFFF:Calibri" --prop legend=none \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180" officecli add charts-bar.pptx /slide[4] --type chart \ --prop chartType=stackedBar --prop title="stacked + center labels" \ --prop dataLabels=value --prop labelPos=center \ --prop labelfont="9:FFFFFF:Calibri" --prop legend=bottom \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;South:95,108,115,128;West:80,90,98,110" officecli add charts-bar.pptx /slide[4] --type chart \ --prop chartType=bar --prop title="dataLabels=none" \ --prop dataLabels=none --prop legend=none \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180"

特性覆盖：dataLabels（value/category/percent/none，或逗号组合）、labelPos（outsideEnd/insideEnd/insideBase/center）、labelfont。

实战建议：value,category组合适合强调分类名与数值并存的场景；堆叠图（stackedBar）中标签放在center可清晰标注每段贡献值；白色标签（9:FFFFFF:Calibri）配合深色系列填充可获得高对比度。

Slide 5 — 坐标轴：缩放、标题、网格线、刻度与显示单位

坐标轴是条形图信息密度的关键。本页先演示 Add 阶段的一揽子轴属性，再演示创建后用chart-axis Set做增量修改：

officecli add charts-bar.pptx /slide[5] --type chart \ --prop chartType=bar --prop title="min/max + titles + numfmt" --prop legend=none \ --prop axismin=0 --prop axismax=200 --prop majorunit=50 --prop minorunit=10 \ --prop axistitle="Revenue" --prop cattitle="Quarter" \ --prop axisfont="10:333333:Calibri" --prop axisline="666666:1" \ --prop axisnumfmt="#,##0" \ --prop categories="Q1,Q2,Q3,Q4" --prop data="Rev:60,90,140,180" officecli add charts-bar.pptx /slide[5] --type chart \ --prop chartType=bar --prop title="gridlines + ticks" --prop legend=none \ --prop gridlines="E0E0E0:0.3" --prop minorGridlines="F0F0F0:0.25" \ --prop majorTickMark=out --prop minorTickMark=in --prop tickLabelPos=nextTo \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180" officecli add charts-bar.pptx /slide[5] --type chart \ --prop chartType=bar --prop title="labelrotation=-30" --prop legend=none \ --prop labelrotation=-30 \ --prop categories="January,February,March,April" \ --prop data="A:60,90,140,180" officecli add charts-bar.pptx /slide[5] --type chart \ --prop chartType=bar --prop title="dispunits=thousands" --prop legend=none \ --prop dispunits=thousands \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="Rev:120000,135000,148000,162000" # chart-axis Set：创建后二次修改数值轴 officecli set charts-bar.pptx "/slide[5]/chart[1]/axis[@role=value]" \ --prop title="Revenue" --prop format='$#,##0' \ --prop majorGridlines=true --prop max=200 --prop min=0

特性覆盖：axismin、axismax、majorunit、minorunit、axistitle、cattitle、axisfont、axisline、axisnumfmt、gridlines、minorGridlines、majorTickMark、minorTickMark、tickLabelPos、labelrotation、dispunits、chart-axis Set。

实现原理：轴属性分为两个阶段处理。Add 阶段的axismin/axismax等属于图表级快捷键（chart的 schema 明确注明 axis* 属性是Add-time only）；创建之后要修改轴，必须通过子元素 chart-axis（pathSegment 为axis，以role为键，取值category/value/value2/series）。在 ChartHelper.Axis.cs 中可以看到axismin/axismax这类旧键被翻译为面向主数值轴（role=value）的目标属性；labelrotation则会根据上下文路由到xaxis.labelrotation或yaxis.labelrotation（见 ChartHelper.Axis.cs），避免误写全部数值轴。dispunits=thousands让 12 万级别的数值以千为单位显示，配合axisnumfmt的数字格式（如#,##0、$#,##0）可显著提升大数可读性。

Slide 6 — 系列样式：颜色、渐变、透明度、轮廓、阴影与引导线

officecli add charts-bar.pptx /slide[6] --type chart \ --prop chartType=bar --prop title="colors + seriesoutline" --prop legend=bottom \ --prop colors="4472C4,ED7D31,A5A5A5" --prop seriesoutline="000000:0.5" \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;South:95,108,115,128;West:80,90,98,110" officecli add charts-bar.pptx /slide[6] --type chart \ --prop chartType=bar --prop title="gradient + seriesshadow" --prop legend=bottom \ --prop gradient="FF6600-FFCC00:90" --prop seriesshadow="000000-5-45-3-50" \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180" officecli add charts-bar.pptx /slide[6] --type chart \ --prop chartType=bar --prop title="transparency=30 + gradients" --prop legend=bottom \ --prop gradients="FF0000-0000FF;00FF00-FFFF00" --prop transparency=30 \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="A:60,90,140,180;B:40,70,100,130" # serlines — 从堆叠条形到图例的引导线（仅 stackedBar） officecli add charts-bar.pptx /slide[6] --type chart \ --prop chartType=stackedBar --prop title="stacked + serlines=true" \ --prop serlines=true --prop legend=bottom \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="East:120,135,148,162;West:95,108,115,128"

特性覆盖：colors、seriesoutline、gradient、seriesshadow、gradients、transparency、serlines（stackedBar 系列引导线）。

参数语法备忘：

• colors="4472C4,ED7D31,A5A5A5"— 逗号分隔的系列调色板，按系列顺序取用；
• gradient="FF6600-FFCC00:90"— 单系列双色渐变，起始色-结束色:角度；
• gradients="FF0000-0000FF;00FF00-FFFF00"— 分号分隔、逐系列指定渐变，可与transparency=30（百分比透明度）叠加；
• seriesshadow="000000-5-45-3-50"— 系列阴影的紧凑编码；
• seriesoutline="000000:0.5"— 系列描边颜色:线宽。

Slide 7 — 叠加元素：参考线、误差线、间距与数据表

officecli add charts-bar.pptx /slide[7] --type chart \ --prop chartType=bar --prop title="referenceline=100" --prop legend=none \ --prop referenceline="100:FF0000:Target" \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180" officecli add charts-bar.pptx /slide[7] --type chart \ --prop chartType=bar --prop title="errbars=fixedVal:10" --prop legend=none \ --prop errbars="fixedVal:10" \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180" officecli add charts-bar.pptx /slide[7] --type chart \ --prop chartType=bar --prop title="gapwidth=50 + overlap=20" --prop legend=bottom \ --prop gapwidth=50 --prop overlap=20 \ --prop categories="Q1,Q2,Q3,Q4" \ --prop data="A:60,90,140,180;B:50,75,110,150" officecli add charts-bar.pptx /slide[7] --type chart \ --prop chartType=bar --prop title="dataTable=true" --prop legend=bottom \ --prop dataTable=true \ --prop categories="Q1,Q2,Q3,Q4" --prop data="A:60,90,140,180"

特性覆盖：referenceline、errbars、gapwidth、overlap、dataTable。

语法备忘：

• referenceline="100:FF0000:Target"—数值:颜色:标签，用于标注目标线/阈值线；
• errbars="fixedVal:10"— 固定值误差线，误差带 ±10；
• gapwidth=50— 条形间隙宽度（百分比，值越小条形越粗）；
• overlap=20— 多系列条形的重叠百分比（正值重叠、负值分离）；
• dataTable=true— 在图表下方内嵌数据表。

从源码结构看，参考线等叠加元素在 Setter 阶段以分号连接的复合值解析（参见 ChartHelper.Advanced.cs），并在参考线超出坐标轴量程时产生referenceline_out_of_scale警告，便于在脚本中捕获并修正轴范围。

Slide 8 — 预设主题与逐系列控制

最后一页演示三套一键主题preset，以及 Add 阶段直接以seriesN.*逐系列指定名称、数值与颜色，再用chart-series Set事后改名改色：

officecli add charts-bar.pptx /slide[8] --type chart \ --prop chartType=bar --prop preset=minimal --prop title="preset=minimal" \ --prop legend=bottom --prop categories="Q1,Q2,Q3,Q4" \ --prop data="A:60,90,140,180;B:50,75,110,150" officecli add charts-bar.pptx /slide[8] --type chart \ --prop chartType=bar --prop preset=dark --prop title="preset=dark" \ --prop legend=bottom --prop categories="Q1,Q2,Q3,Q4" \ --prop data="A:60,90,140,180;B:50,75,110,150" officecli add charts-bar.pptx /slide[8] --type chart \ --prop chartType=bar --prop preset=corporate --prop title="preset=corporate" \ --prop legend=bottom --prop categories="Q1,Q2,Q3,Q4" \ --prop data="A:60,90,140,180;B:50,75,110,150" officecli add charts-bar.pptx /slide[8] --type chart \ --prop chartType=bar --prop title="seriesN.* Add + chart-series Set" \ --prop legend=bottom --prop categories="Q1,Q2,Q3,Q4" \ --prop series1.name="Product A" --prop series1.values="60,90,140,180" \ --prop series1.color=4472C4 \ --prop series2.name="Product B" --prop series2.values="50,75,110,150" \ --prop series2.color=ED7D31 officecli set charts-bar.pptx "/slide[8]/chart[4]/series[1]" \ --prop name="Renamed" --prop color=C00000

特性覆盖：preset（minimal/dark/corporate）、series1.name/series1.values/series1.color、chart-series Set。

实现原理：预设主题的注册表在 ChartPresets.cs：minimal/dark/corporate之外还支持magazine、dashboard、colorful、monochrome等更多预设。其中dark预设专门为深色幻灯片设计——深色背景、高亮数据、白色文字（参见 ChartPresets.cs 的注释）。seriesN.*点号前缀属性在 Add 阶段即按系列索引组装系列数据；创建之后则通过/slide[N]/chart[N]/series[N]路径走 chart-series 元素的 Set 流程做增量修改，两条路径互为补充。

完整特性覆盖表

检查生成结果：query / get 回读

演示文稿生成后，可以用 OfficeCLI 的查询与回读命令验证图表结构、位置与轴配置是否与预期一致：

# 列出全部图表节点 officecli query charts-bar.pptx chart # 回读单张图表（含标题、类型、系列、位置） officecli get charts-bar.pptx "/slide[1]/chart[1]" officecli get charts-bar.pptx "/slide[2]/chart[1]" # 回读数值轴配置 officecli get charts-bar.pptx "/slide[5]/chart[1]/axis[@role=value]"

这套get/query能力在 PowerPointHandler.Chart.cs 的ChartToNode中实现：图表节点从 GraphicFrame 的Transform读取x/y/width/height（EMU 转可读单位），通过ChartReference找到对应的ChartPart并读取标题、系列与数值，同时记录zorder（形状树中的堆叠次序），保证 dump→replay 时图层顺序不丢失。

小结

通过charts-bar这一个示例，你可以完整掌握 OfficeCLI 生成 PowerPoint 条形图的全部能力闭环：

1. 类型选择—bar/stackedBar/percentStackedBar/bar3d，配合shape与view3d定制 3D 形态；
2. 文本与图例—title.*、legend位置、legendFont、legend.overlay、autotitledeleted；
3. 数据标签—dataLabels组合、labelPos四种位置、labelfont；
4. 坐标轴— 缩放/单位/标题/字体/网格线/刻度/旋转的 Add 期配置，以及chart-axis Set的事后修改；
5. 系列视觉—colors、gradient(s)、transparency、seriesoutline、seriesshadow、serlines；
6. 叠加与布局—referenceline、errbars、gapwidth、overlap、dataTable；
7. 批量与增量—preset一键主题、seriesN.*逐系列装配、chart-series Set二次调整；
8. 验证—query/get回读整棵图表树。

无论是把上述命令逐条喂给脚本化的 AI 代理，还是用pip install officecli-sdk通过 sdk/python 的doc.batch(...)一次提交整页图表，都能在完全脱离 Office 图形界面的前提下，以可复现、可审查的方式批量产出专业的条形图幻灯片。更多整体流程可参考 skills/officecli-pptx/SKILL.md 与其余图表示例（charts-line、charts-column、charts-combo 等）做进一步对比学习。

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