OfficeCLI Excel 基础图表实战指南：用 `officecli add --type chart` 生成列、条、折线与面积图

OfficeCLI Excel 基础图表实战指南用officecli add --type chart生成列、条、折线与面积图【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI本指南以 OfficeCLI 仓库中的基础图表展示示例examples/excel/charts/charts-basic.md为核心系统讲解如何用一行officecli add ... --type chart命令在 xlsx 工作簿中创建柱状、条形、折线、面积四大图表家族的 14 种变体并覆盖数据源绑定、坐标轴、图例、数据标签、参考线、渐变、阴影与三维透视等 60 个属性。读完本文你将掌握 OfficeCLI 面向 AI 代理设计的图表声明式语法能直接复制命令生成可被 Excel 打开的成品工作簿并理解这些属性在源码中的解析与落盘原理。示例整体结构三文件协作28 个图表一次生成该示例由三个文件协同工作位于 examples/excel/charts/charts-basic.py— Python 脚本调用officecli命令生成工作簿。每条图表命令都以可复制的 shell 命令形式写在注释中再由脚本执行它驱动的是officecli Python SDKpip install officecli-sdk一个常驻进程启动后每个单元格写入和每个图表都通过命名管道named pipe按工作表批量batch投递最终产物与 CLI 版本等价charts-basic.sh— CLI 孪生脚本逐条执行officecli add --type chart刻意不加set -e以便容忍前向兼容的UNSUPPORTED props警告officecli 退出码 2并继续构建完整文档charts-basic.xlsx— 生成的成品工作簿包含8 个工作表1 个数据表 7 个图表工作表共 28 个图表用 Excel 打开即可看到渲染结果charts-basic.md— 本文所基于的说明文档把每个工作表映射到它演示的功能点。重新生成工作簿只需两步cd examples/excel python3 charts-basic.py # 或 bash charts/charts-basic.sh # → charts/charts-basic.xlsx共享源数据Sheet1 的 12 个月区域销售数据所有图表共用Sheet1作为数据源12 个月的区域销售数据East、South、North、West 四个区域。数据布局为 A1:E13第一行为表头Month, East, South, North, West第 213 行为 JanDec 各月四个区域的数值。以.sh版本为例表头写入方式如下officecli set $FILE /Sheet1/A1 --prop textMonth --prop boldtrue officecli set $FILE /Sheet1/B1 --prop textEast --prop boldtrue # ... 其余表头与 12×4 行数据同理 officecli set $FILE /Sheet1/A2 --prop textJan ; officecli set $FILE /Sheet1/B2 --prop text120 ; ...这一数据块支撑了后续所有dataRangeSheet1!A1:E13形式的图表引用也可以被 charts.md 中更高级的组合图、散点图、股票图等示例复用。命令模型一条add声明一个图表在深入各工作表之前先理解 OfficeCLI 的图表添加模型。核心命令形态为officecli add workbook.xlsx 父路径/工作表名 --type chart \ --prop chartType类型 \ --prop 属性1值 --prop 属性2值 ...从源码 src/officecli/Handlers/Excel/ExcelHandler.Add.Chart.cs 可以看出chartType未指定时默认值为columncharttype与type两个键均可识别不区分大小写。dataRange别名range会被ParseDataRangeForChart解析为系列与分类数据并生成带单元格引用的系列没有dataRange时则支持三种内联数据形式dataEast:198;South:158;North:142;West:180— 直接内联单系列series1H1:663,598,528,661、series2H2:...— 命名的多系列series1.nameEastseries1.valuesSheet1!B2:B13series1.categoriesSheet1!A2:A13— 点分语法引用单元格区域会被自动限定为Sheet1!形式并回填字面量缓存保证 Excel 在重算前即可渲染。x/y/width/height控制图表在工作表中的锚定位置单位单元格数量默认width8、height15源码同时支持anchorD2:J18单元格区域锚定方式且当两者同时提供时anchor优先并给出警告。未知的chartType会在创建任何部件之前被 ChartHelper.ParseChartType 校验并抛错避免留下孤儿 Drawing 部件而诸如 funnel、treemap 等扩展cx类型则走 ChartExBuilder 分支。成功添加后返回路径形如/工作表名/chart[N]。Python SDK 批处理形态SDK 版本把上述命令改写为结构一致的字典每个条目就是officecli batch列表里的一员见 charts-basic.pydef add_sheet(name): return {command: add, parent: /, type: sheet, props: {name: name}} def chart(sheet, **props): return {command: add, parent: f/{sheet}, type: chart, props: props} with officecli.create(FILE, --force) as doc: doc.batch([...]) # 每个工作表一个 batch按工作表聚合发送 doc.send({command: save})运行前提pip install officecli-sdk且officecli二进制在 PATH 中脚本会优先使用已安装的 SDK否则回退到仓库内 sdk/python 的副本。Sheet 1列图家族column / columnStacked / columnPercentStacked / column3d第一个工作表演示列图的四种变体覆盖坐标轴标题、字体、网格线、自定义配色、数据标签、柱间隙、图例位置、绘图区填充与三维透视# 基础簇状列图坐标轴标题 坐标轴字体 officecli add data.xlsx /Sheet --type chart \ --prop chartTypecolumn \ --prop titleRegional Sales \ --prop dataRangeSheet1!A1:E13 \ --prop catTitleMonth --prop axisTitleSales \ --prop axisfont9:58626E:Arial \ --prop gridlinesD9D9D9:0.5:dot # 堆叠列图自定义颜色、数据标签、间隙控制、系列描边 officecli add data.xlsx /Sheet --type chart \ --prop chartTypecolumnStacked \ --prop colors2E75B6,70AD47,FFC000,C00000 \ --prop dataLabelstrue --prop labelPoscenter \ --prop gapwidth60 \ --prop series.outlineFFFFFF-0.5 # 100% 堆叠列图图例位置 绘图区填充 officecli add data.xlsx /Sheet --type chart \ --prop chartTypecolumnPercentStacked \ --prop legendbottom --prop legendfont9:8B949E \ --prop plotFillF5F5F5 # 3D 列图透视 标题样式 officecli add data.xlsx /Sheet --type chart \ --prop chartTypecolumn3d \ --prop view3d15,20,30 \ --prop title.fontCalibri --prop title.size16 \ --prop title.color1F4E79 --prop title.boldtrue本表涉及属性column、columnStacked、columnPercentStacked、column3d、dataRange、catTitle、axisTitle、axisfont、gridlines、colors、dataLabels、labelPos、gapwidth、series.outline、legend、legendfont、plotFill、view3d、title.font/size/color/bold。值得注意的格式细节axisfont9:58626E:Arial依次为字号、十六进制颜色、字体名gridlinesD9D9D9:0.5:dot依次为颜色、线宽、线型view3d15,20,30依次为绕 X 轴旋转角、绕 Y 轴旋转角、透视系数。Sheet 2条形图家族bar / barStacked / barPercentStacked / bar3d第二张表演示横向条形图的四种变体重点展示内联数据、命名系列、参考线与坐标轴线# 横向条形图内联数据 间隙控制 officecli add data.xlsx /Sheet --type chart \ --prop chartTypebar \ --prop dataEast:198;South:158;North:142;West:180 \ --prop gapwidth80 \ --prop dataLabelstrue --prop labelPosoutsideEnd # 堆叠条形图命名系列 重叠控制 officecli add data.xlsx /Sheet --type chart \ --prop chartTypebarStacked \ --prop series1H1:663,598,528,661 \ --prop series2H2:833,718,669,868 \ --prop gapwidth50 --prop overlap0 # 100% 堆叠条形图参考线 轴线 # 注意barPercentStacked 的值轴是 0-1显示为 0%-100%所以 50% 线要写成 0.5 # referenceLine 格式value | value:color | value:color:label | value:color:width:dash # | value:color:label:dash | value:color:width:dash:label # 线宽单位为磅默认 1.5pt。例如 0.5:FF0000:2:dash 画一条 2pt 的虚线 officecli add data.xlsx /Sheet --type chart \ --prop chartTypebarPercentStacked \ --prop referenceLine0.5:FF0000:Target:dash \ --prop axisLine333333:1:solid \ --prop catAxisLine333333:1:solid # 3D 条形图图表区填充 预设样式 officecli add data.xlsx /Sheet --type chart \ --prop chartTypebar3d \ --prop view3d10,30,20 \ --prop chartFillF2F2F2 \ --prop style3本表涉及属性bar、barStacked、barPercentStacked、bar3d、内联data、命名series、gapwidth、overlap、labelPosoutsideEnd、referenceLine、axisLine、catAxisLine、chartFill、style。这里最易踩坑的是 100% 堆叠图的参考线值轴以 01 表示 0%100%因此 50% 线必须写0.5而非50脚本注释中特别强调了这一点。referenceLine支持最多六段式语法value:color:width:dash:label线宽以磅为单位。axisLine与catAxisLine分别控制数值轴与分类轴的轴线颜色、粗细与线型。Sheet 3折线图家族line / lineStacked折线图演示了标记点、平滑曲线、系列阴影、刻度线、数据表等能力其中第一个图展示了点分语法的单元格区域引用# 折线图单元格区域系列点分语法 标记点 officecli add data.xlsx /Sheet --type chart \ --prop chartTypeline \ --prop series1.nameEast \ --prop series1.valuesSheet1!B2:B13 \ --prop series1.categoriesSheet1!A2:A13 \ --prop showMarkerstrue --prop markercircle:6:2E75B6 \ --prop gridlinesD9D9D9:0.5:dot \ --prop minorGridlinesEEEEEE:0.3:dot # 平滑折线系列阴影 officecli add data.xlsx /Sheet --type chart \ --prop chartTypeline \ --prop smoothtrue --prop lineWidth2.5 \ --prop gridlinesnone \ --prop series.shadow000000-4-315-2-40 # 堆叠折线刻度标记 officecli add data.xlsx /Sheet --type chart \ --prop chartTypelineStacked \ --prop majorTickMarkoutside --prop tickLabelPoslow # 虚线折线数据表 隐藏图例 officecli add data.xlsx /Sheet --type chart \ --prop chartTypeline \ --prop lineDashdash --prop lineWidth1.5 \ --prop dataTabletrue --prop legendnone本表涉及属性series1.name/values/categories单元格区域、showMarkers、marker样式:尺寸:颜色、smooth、lineWidth、lineDash、gridlines、minorGridlines、series.shadow、lineStacked、majorTickMark、tickLabelPos、dataTable、legendnone。格式要点markercircle:6:2E75B6依次为标记形状、大小磅、颜色series.shadow000000-4-315-2-40依次为颜色、模糊半径、角度、距离、透明度lineDash取值包括solid/dot/dash/dashdot/longdash。minorGridlines允许为主网格线再叠加一套次要网格线如EEEEEE:0.3:dot。legendnone隐藏图例配合dataTabletrue在图表下方显示数据表。Sheet 4面积图家族area / areaStacked / areaPercentStacked / area3d面积图演示透明度、渐变填充、圆角、轴可见性与三维透视# 面积图透明度 渐变 officecli add data.xlsx /Sheet --type chart \ --prop chartTypearea \ --prop transparency40 \ --prop gradient4472C4-BDD7EE:90 # 堆叠面积图绘图区填充 圆角 officecli add data.xlsx /Sheet --type chart \ --prop chartTypeareaStacked \ --prop plotFillF5F5F5 --prop roundedCornerstrue # 100% 堆叠面积图轴可见性控制 officecli add data.xlsx /Sheet --type chart \ --prop chartTypeareaPercentStacked \ --prop axisVisibletrue --prop axisLine999999:0.5:solid # 3D 面积图透视 officecli add data.xlsx /Sheet --type chart \ --prop chartTypearea3d \ --prop view3d20,25,15本表涉及属性area、areaStacked、areaPercentStacked、area3d、transparency、gradient、plotFill、roundedCorners、axisVisible、axisLine。格式要点gradient4472C4-BDD7EE:90依次为起始色、结束色以-分隔、渐变角度度transparency取 0100数值越大越透明。Sheet 5样式与格式化Styling第五张表把所有样式属性集中到一个完整定制的列图上并附加双 Y 轴、逐点配色、负值反转与自定义标签文本# 完全定制的图表标题效果、图例、坐标轴字体、系列效果 officecli add data.xlsx /Sheet --type chart \ --prop title.fontGeorgia --prop title.size18 \ --prop title.color1F4E79 --prop title.boldtrue \ --prop title.shadow000000-3-315-2-30 \ --prop legendfont10:444444:Helvetica --prop legendright \ --prop axisfont9:58626E:Arial \ --prop series.outlineFFFFFF-0.5 \ --prop series.shadow000000-3-315-2-25 \ --prop roundedCornerstrue --prop referenceLine160:FF0000:1:dash # 双 Y 轴次坐标轴 officecli add data.xlsx /Sheet --type chart \ --prop secondaryAxis2 # 逐点配色 负值反转 officecli add data.xlsx /Sheet --type chart \ --prop point1.color70AD47 --prop point3.colorFF0000 \ --prop invertIfNegtrue # 渐变绘图区填充 自定义数据标签文本 officecli add data.xlsx /Sheet --type chart \ --prop plotFillE8F0FE-FFFFFF:90 \ --prop markerdiamond:8:4472C4 \ --prop dataLabels.numFmt#,##0 \ --prop dataLabel3.textPeak!本表涉及属性title.shadow、secondaryAxis、point{N}.color、invertIfNeg、plotFill渐变、dataLabels.numFmt、dataLabel{N}.text。要点解读secondaryAxis2表示把第 2 个系列1 基索引逗号分隔可指定多个放到右侧次 Y 轴常用于销售额 vs 增长率这类量纲差异大的组合脚本中series1Sales:...series2Growth:...secondaryAxis2即为此意point{N}.color可单独给第 N 个数据点着色invertIfNegtrue让负值柱子向下并自动换色dataLabel{N}.text用自定义文本替换某个具体数据标签dataLabels.numFmt#,##0为全部标签设置数字格式。Sheet 6布局与坐标轴控制Layout第六张表聚焦手工布局绘图区、标题、图例的 01 归一化坐标、对数刻度、轴反转、显示单位、标签字体与误差线# 手工布局绘图区、标题、图例 officecli add data.xlsx /Sheet --type chart \ --prop plotArea.x0.15 --prop plotArea.y0.15 \ --prop plotArea.w0.7 --prop plotArea.h0.7 \ --prop title.x0.3 --prop title.y0.01 \ --prop legend.x0.02 --prop legend.y0.4 \ --prop legend.overlaytrue # 对数刻度、轴反转、显示单位 officecli add data.xlsx /Sheet --type chart \ --prop logBase10 \ --prop axisOrientationmaxMin \ --prop dispUnitsthousands # 标签字体、分隔符、单标签隐藏 officecli add data.xlsx /Sheet --type chart \ --prop labelFont11:2E75B6:true \ --prop dataLabels.separator: \ --prop dataLabel2.textBest! \ --prop dataLabel3.deletetrue # 误差线、次刻度、不透明度 officecli add data.xlsx /Sheet --type chart \ --prop errBarspercentage \ --prop majorTickMarkoutside --prop minorTickMarkinside \ --prop opacity80本表涉及属性plotArea.x/y/w/h、title.x/y、legend.x/y、legend.overlay、logBase、axisOrientation、dispUnits、labelFont、dataLabels.separator、dataLabel{N}.delete、errBars、minorTickMark、opacity。要点解读plotArea与title、legend的x/y/w/h都是 01 的百分比坐标相对整个图表区域legend.overlaytrue让图例浮在绘图区之上而不挤压它logBase10设置对数刻度脚本用series1Revenue:10,100,1000,10000直观展示axisOrientationmaxMin反转坐标轴方向dispUnitsthousands让数值轴以千为单位显示errBars支持percentage/stdDev/fixed三种误差计算模式labelFont11:2E75B6:true依次为字号、颜色、是否加粗。Sheet 7视觉效果Effects最后一张表集中演示渐变、条件着色、光晕与预设主题# 逐系列渐变 officecli add data.xlsx /Sheet --type chart \ --prop gradients4472C4-BDD7EE:90;ED7D31-FBE5D6:90 # 面积填充渐变 标题光晕 officecli add data.xlsx /Sheet --type chart \ --prop areafill4472C4-BDD7EE:90 \ --prop title.glow4472C4-8-60 # 条件着色低于/高于阈值 officecli add data.xlsx /Sheet --type chart \ --prop colorRule60:FF0000:70AD47 # 预设样式 引导线 officecli add data.xlsx /Sheet --type chart \ --prop style26 \ --prop dataLabels.showLeaderLinestrue本表涉及属性gradients、areafill、title.glow、colorRule、style、dataLabels.showLeaderLines。要点解读gradients用分号分隔多个系列各自的渐变起始色-结束色:角度与单一gradient属性对应全局与逐系列两种粒度areafill只作用于面积图系列填充title.glow4472C4-8-60依次为光晕颜色、半径、透明度colorRule60:FF0000:70AD47表示低于阈值 60 的点用红色、高于用绿色style可选用 148 的预设图表样式脚本示例分别用了style3与style26。生成后检查query 与 get 命令工作簿生成后可用以下命令检查图表结构也适用于主展示文件 charts.xlsxofficecli validate charts-basic.xlsx # 校验文档完整性 officecli query charts-basic.xlsx chart # 列出所有图表部件 officecli get charts-basic.xlsx /1-Column Charts/chart[1] # 取指定图表的原始 XMLquery ... chart会枚举工作簿中的全部图表路径形如/工作表名/chart[N]get则可按路径抽取单个图表的 ChartSpace XML便于调试某个属性是否按预期写入。底层实现速览AddChart 的完整生命周期从源码角度一次add --type chart在 ExcelHandler.Add.Chart.cs 的AddChart方法中经历如下关键步骤解析与校验读取chartType默认column解析dataRange或内联series/categories/data系列为空时抛出带修复建议的错误在创建任何部件前校验图表类型未知类型直接抛错创建 Drawing 部件若工作表尚无DrawingsPart则新建并写入xdr:wsDr/与工作表关系锚定位置解析anchor或x/y/width/height支持 cm/in/pt/EMU 单位纯整数按单元格数计生成 TwoCellAnchor 的 from/to 标记构建图表空间经典类型走 ChartHelper.BuildChartSpace扩展类型funnel、treemap、sunburst、boxWhisker、histogram 等走 ChartExBuilder并自动附加 Excel 必需的 ChartStylePart 与 ChartColorStylePart 侧车部件延迟属性应用axisTitle、dataLabels等被标记为 deferred 的属性在图表部件创建后通过ChartHelper.SetChartProperties应用若其中某个属性非法会把刚创建的 ChartPart 回滚删除保证报错即未添加的原子性见 ExcelHandler.Add.Chart.cs返回路径追加 anchor 与 graphicFrame 后返回/工作表名/chart[N]其中 N 为图表在该工作表的序号。这套先校验、后建件、失败回滚的设计保证了批量生成 28 个图表时不会留下半成品部件也是该示例在 AI 代理自动化场景下可安全重复执行的基础。延伸阅读单类型全属性深潜参见 examples/excel/charts/ 子目录下的charts-column.md、charts-line.md、charts-area.md、charts-bar.md等按图表类型拆分的深入示例更多图表类型组合图、散点、气泡、饼图、雷达、漏斗等参见 examples/excel/charts.md主展示文件 charts.xlsx八个类型横跨四个数据工作表与 examples/excel/charts/charts-combo.md、examples/excel/charts/charts-pie.md 等图表类型与属性解析核心阅读 src/officecli/Core/Chart/ChartHelper.cs 与 src/officecli/Core/Chart/ChartHelper.Builder.cs属性 schema 定义参见 schemas/xlsx/chart.json 与 schemas/xlsx/chart-axis.json其中标注了各属性的取值约束与默认值SDK 用法见 sdk/python/officecli.py 与 sdk/node/index.js以及本示例的 Python 孪生脚本 charts-basic.py。【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考