• CLI
• AI 应用
• MCP 服务

本文以 OfficeCLI 仓库中的 charts-stock.md 演示文档为主体，系统讲解如何在 PowerPoint 中通过officecli add ... --type chart --prop chartType=stock一行命令生成专业的高低价（HLC）与开高低收（OHLC）股票图表。你将掌握股票图的数据序列顺序要求、高低线/涨跌柱、标题图例、数据标签、坐标轴、系列样式、背景与预设等全部 16 项配置能力，并了解命令行、Bash 脚本与 Python SDK 三种驱动方式，以及它们背后的 OOXML 源码实现。

演示文件构成与重新生成

charts-stock演示由三个协同工作的文件组成：

• charts-stock.py— Python 脚本，通过officecli命令/Python SDK 生成演示文稿；
• charts-stock.pptx— 生成产物：8 页幻灯片，每页 4 个图表，共 32 个股票图；
• charts-stock.md— 本文关联的说明文档，将每页幻灯片映射到它所演示的功能。

命令行方式重新生成（CLI 视角）：

cd examples/ppt/charts python3 charts-stock.py # → charts-stock.pptx

仓库同时提供了与 Python 脚本等价的 Bash 脚本 charts-stock.sh。它的执行流程更完整地展示了 CLI 的文档生命周期：先officecli create创建文件，officecli open打开进入编辑会话，逐页add幻灯片、标题形状与图表，最后officecli close关闭并officecli validate校验生成的 OOXML 文件合法性：

CLI="${1:-officecli}" FILE="$(dirname "$0")/charts-stock.pptx" rm -f "$FILE" $CLI create "$FILE" $CLI open "$FILE" # ... 逐页 add slide / shape / chart ... $CLI close "$FILE" $CLI validate "$FILE" echo "Generated: $FILE"

值得注意：该脚本刻意不设置set -e。脚本头部注释解释了原因——OfficeCLI 对尚不支持的属性会以退出码 2 报UNSUPPORTED props警告，这是前向兼容设计，脚本会容忍警告并继续构建，从而产出完整文档。

Python SDK 双生版本

charts-stock.py 是.sh的 SDK 双生版本，二者生成等价的charts-stock.pptx。它驱动的是officecliPython SDK（pip install officecli-sdk）：只需启动一个常驻进程，每页的形状与图表通过命名管道在doc.batch(...)往返中批量下发。批次中每一项都是{"command","parent","type","props"}字典，与officecli batch列表中的条目完全一致；不支持的属性会被原样转发，常驻进程仅给出前向兼容警告而不会让批次失败。

import officecli FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "charts-stock.pptx") with officecli.create(FILE, "--force") as doc: doc.batch(slide_items(1, "Basic stock — High-Low-Close vs Open-High-Low-Close", [ (TL, {"chartType": "stock", "title": "HLC", "legend": "bottom", "categories": CATS, "data": HLC}), (TR, {"chartType": "stock", "title": "OHLC", "legend": "bottom", "categories": CATS, "data": OHLC}), # ... ]))

脚本将每页的四个图表位置预定义为象限坐标TL / TR / BL / BR（左上、右上、左下、右下），每页先add slide，再add shape写页标题，最后为每个象限add chart。

股票图的序列顺序约束（HLC 3 序列 / OHLC 4 序列）

股票图对数据序列有严格的固定顺序要求，这是使用chartType=stock的前提：

• HLC：提供三个序列，顺序必须为High（最高价）、Low（最低价）、Close（收盘价）；
• OHLC：提供四个序列，顺序必须为Open（开盘价）、High、Low、Close。

这一约束在底层源码中有硬性校验。看 ChartHelper.Builder.cs 中BuildStockChart的实现：

// Stock chart expects series in Open-High-Low-Close order (4 series) // or High-Low-Close order (3 series) // BUG-R6A(BUG2): OOXML CT_StockChart constrains c:ser to minOccurs=3, // maxOccurs=4. Any other count writes a schema-invalid file ... if (seriesData.Count is < 3 or > 4) throw new ArgumentException( $"stock chart requires 3 or 4 data series (high, low, close [, open]); got {seriesData.Count}.");

这是因为 OOXML 规范中CT_StockChart对<c:ser>的子元素数量约束为minOccurs=3、maxOccurs=4，序列数不足 3 或超过 4 会写出不符合 schema 的 XML 文件。OfficeCLI 在构建阶段即提前拒绝，并给出可操作的错误信息，而不是生成损坏的 PPTX。

另外，ChartHelper.cs 显示chartType解析支持别名："stock" or "ohlc" => "stock"，即传入ohlc与stock等价。

示例数据约定

全篇演示使用统一的数据与分类变量（与 charts-stock.sh 一致）：

CATS="Mon,Tue,Wed,Thu,Fri" HLC="High:130,135,140,138,145;Low:118,122,128,125,132;Close:125,130,135,132,140" OHLC="Open:120,128,130,135,138;High:130,135,140,138,145;Low:118,122,128,125,132;Close:125,130,135,132,140"

data属性采用序列名:值1,值2,...;序列名:值2,...的分号分隔格式，categories提供横轴分类标签。

Slide 1 — 基础股票图：HLC 与 OHLC 对比

第一页用四宫格布局演示最基础的股票图：左上 HLC（3 序列）、右上 OHLC（4 序列）、左下 HLC 开启数据表、右下 OHLC 开启数据表。

# High-Low-Close (3-series) officecli add charts-stock.pptx /slide[1] --type chart \ --prop chartType=stock --prop title="HLC" --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" \ --prop x=0.3in --prop y=1.05in --prop width=6.1in --prop height=3in # Open-High-Low-Close (4-series) officecli add charts-stock.pptx /slide[1] --type chart \ --prop chartType=stock --prop title="OHLC" --prop legend=bottom \ --prop categories="$CATS" --prop data="$OHLC" \ --prop x=6.95in --prop y=1.05in --prop width=6.1in --prop height=3in # HLC with data table officecli add charts-stock.pptx /slide[1] --type chart \ --prop chartType=stock --prop title="HLC + dataTable=true" \ --prop dataTable=true --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" \ --prop x=0.3in --prop y=4.25in --prop width=6.1in --prop height=3in # OHLC with data table officecli add charts-stock.pptx /slide[1] --type chart \ --prop chartType=stock --prop title="OHLC + dataTable=true" \ --prop dataTable=true --prop legend=bottom \ --prop categories="$CATS" --prop data="$OHLC" \ --prop x=6.95in --prop y=4.25in --prop width=6.1in --prop height=3in

本页功能点：chartType=stock、HLC（3 序列）vs OHLC（4 序列）、dataTable。

dataTable=true会在图表下方附带数据表，直接展示各序列的原始数值，适合在演示/报告中同时呈现数据与图形。

源码视角：股票图到底画了什么

BuildStockChart（ChartHelper.Builder.cs）揭示了股票图三个关键实现细节：

1. 每个序列都是LineChartSeries，但轮廓设为NoFill、标记为None——股票图的视觉主体来自高低线与涨跌柱，而非序列自身的线条：

   // Hide individual series lines — stock chart visuals come from // hiLowLines + upDownBars, not from the series lines themselves spPr.AppendChild(new Drawing.Outline(new Drawing.NoFill())); ... series.AppendChild(new C.Marker(new C.Symbol { Val = C.MarkerStyleValues.None }));

2. 默认写入一条HighLowLines（高低线），在每个数据点处用竖线连接 High 与 Low；
3. 序列数 ≥ 4 时自动追加UpDownBars（涨跌柱），默认GapWidth = 150，上涨用绿色4CAF50、下跌用红色F44336填充：

   if (seriesData.Count >= 4) { var upDownBars = new C.UpDownBars(new C.GapWidth { Val = 150 }); // upBars: SolidFill 4CAF50 (green), downBars: SolidFill F44336 (red) }

也就是说，只用一行--prop chartType=stock命令，无需任何额外参数，OfficeCLI 就会按 OOXML 规范把高低线和涨跌柱的默认形态搭好；后续的hilowlines、updownbars属性只是在这个默认骨架之上做定制。

Slide 2 — 高低线与涨跌柱

第二页聚焦股票图的两个招牌元素：hilowlines（高低线，连接每个周期的高低点）与updownbars（类似蜡烛图的涨跌填充柱，仅 OHLC 可用）。

# hilowlines — vertical lines connecting high and low of each period officecli add charts-stock.pptx /slide[2] --type chart \ --prop chartType=stock --prop title="hilowlines=true" \ --prop hilowlines=true --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" # hilowlines with custom color and width officecli add charts-stock.pptx /slide[2] --type chart \ --prop chartType=stock --prop title="hilowlines=808080:0.5" \ --prop hilowlines="808080:0.5" --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" # updownbars — candlestick-like up/down fill bars (OHLC only) officecli add charts-stock.pptx /slide[2] --type chart \ --prop chartType=stock --prop title="updownbars=true (OHLC)" \ --prop updownbars=true --prop legend=bottom \ --prop categories="$CATS" --prop data="$OHLC" # updownbars with custom width and colors officecli add charts-stock.pptx /slide[2] --type chart \ --prop chartType=stock --prop title="updownbars=150:00AA00:FF0000" \ --prop updownbars="150:00AA00:FF0000" --prop legend=bottom \ --prop categories="$CATS" --prop data="$OHLC"

本页功能点：hilowlines（取值true或color:width）、updownbars（取值true或gapWidth:upColor:downColor，仅 OHLC）。

参数取值详解（源码级）

hilowlines与updownbars的Set处理逻辑位于 ChartHelper.Setter.cs，两种属性对取值有清晰的解析规则：

• hilowlines=true→ 写入默认样式的高低线；hilowlines=808080:0.5→ 颜色#808080、线宽0.5pt。"none"或"false"则移除已有高低线；
• updownbars接受三种输入形态（源码注释明确说明）：
  • 布尔"true"：使用默认形态；
  • 裸数字"150"：仅指定gapWidth（柱间间隔宽度），颜色回落到默认值；
  • 复合形态"gap:up:down"：如150:00AA00:FF0000，分别指定间隔宽度、上涨柱颜色、下跌柱颜色。实现中gapWidth默认 150，通过ushort.TryParse解析，颜色缺失时保持默认（涨绿4CAF50/ 跌红F44336）。

case "updownbars": { var lc = plotArea2?.GetFirstChild<C.LineChart>() as OpenXmlCompositeElement ?? plotArea2?.GetFirstChild<C.StockChart>(); if (lc == null) { unsupported.Add(key); break; } lc.RemoveAllChildren<C.UpDownBars>(); if (value.Equals("none", ...) || value.Equals("false", ...)) break; // Accept three input shapes: bool ("true"), bare numeric gapWidth ("150"), // and the compound "gap:up:down" ... }

源码注释还说明了一个兼容性细节：CT_StockChart与CT_LineChart携带相同的高低线/涨跌柱尾部元素，Add 阶段会为股票图构建它们，但历史上Set曾把这些键视为不支持属性而拒绝；ChartHelper.Setter.cs 修正了这一点，现在Set对已存在的股票图同样支持调整这些覆盖层。

Slide 3 — 标题与图例

第三页演示标题样式（字体、字号、颜色、加粗）与图例（位置、字体、覆盖模式、隐藏）。

officecli add charts-stock.pptx /slide[3] --type chart \ --prop chartType=stock --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="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[3] --type chart \ --prop chartType=stock --prop title="legend=top + legendFont" \ --prop legend=top --prop legendFont="10:333333:Calibri" \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[3] --type chart \ --prop chartType=stock --prop title="legend.overlay=true" \ --prop legend=topRight --prop legend.overlay=true \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[3] --type chart \ --prop chartType=stock --prop autotitledeleted=true --prop legend=none \ --prop categories="$CATS" --prop data="$HLC"

本页功能点：title.font/size/color/bold、legend位置、legendFont、legend.overlay、autotitledeleted。

参数说明：

注意第四个命令：当不需要图表标题时，可以不写title而直接设autotitledeleted=true（自动标题删除标记），这样图表标题区域为空、legend=none同时隐藏图例——适合输出纯绘图区的极简图表。这与 ChartHelper.Builder.cs 中的标题构建逻辑对应：title=none（大小写不敏感）或空字符串时不渲染字面标题文本；而autoTitle+AutoTitleDeleted{false}组合则渲染 PowerPoint 本地化的 "Chart Title" 占位符。

Slide 4 — 数据标签

第四页演示数据标签的四种形态及其组合，以及标签字体。

officecli add charts-stock.pptx /slide[4] --type chart \ --prop chartType=stock --prop title="dataLabels=value" \ --prop dataLabels=value --prop labelfont="9:333333:Calibri" \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[4] --type chart \ --prop chartType=stock --prop title="value,series" \ --prop dataLabels="value,series" --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[4] --type chart \ --prop chartType=stock --prop title="value,category" \ --prop dataLabels="value,category" --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[4] --type chart \ --prop chartType=stock --prop title="dataLabels=none" \ --prop dataLabels=none --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC"

本页功能点：dataLabels（value/series/category/none或逗号组合）、labelfont。

dataLabels是逗号分隔的标签内容标志：value显示数值、series显示序列名、category显示分类名，可自由组合（如value,series同时显示数值与序列名），none完全关闭。labelfont沿用size:color:font三段式格式，本页用9:333333:Calibri（9 磅、深灰、Calibri）统一标签外观。

Slide 5 — 坐标轴

第五页覆盖坐标轴的最常用定制：范围、主刻度单位、轴标题、轴字体、货币数字格式、网格线、标签旋转与显示单位。

# axis min/max + currency number format officecli add charts-stock.pptx /slide[5] --type chart \ --prop chartType=stock --prop title="min/max + currency format" \ --prop axismin=100 --prop axismax=160 --prop majorunit=10 \ --prop axistitle="Price (USD)" --prop cattitle="Day" \ --prop axisfont="10:333333:Calibri" --prop axisnumfmt='$#,##0.00' \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[5] --type chart \ --prop chartType=stock --prop title="gridlines + minorGridlines" \ --prop gridlines="E0E0E0:0.3" --prop minorGridlines="F0F0F0:0.25" \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[5] --type chart \ --prop chartType=stock --prop title="labelrotation=-30" \ --prop labelrotation=-30 --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[5] --type chart \ --prop chartType=stock --prop title="dispunits=hundreds" \ --prop dispunits=hundreds --prop legend=bottom \ --prop categories="$CATS" \ --prop data="High:13000,13500,14000,13800,14500;Low:11800,12200,12800,12500,13200;Close:12500,13000,13500,13200,14000"

本页功能点：axismin/max、majorunit、axistitle/cattitle、axisfont、axisnumfmt（货币格式）、gridlines/minorGridlines、labelrotation、dispunits。

关于dispunits，chart.pptx-xlsx.json 帮助 schema 给出了完整取值枚举：none、hundreds、thousands、tenThousands|10000、hundredThousands|100000、millions、tenMillions|10000000、hundredMillions|100000000、billions、trillions，并支持displayunits作为别名。示例中数据放大到 13000~14500 级别再设dispunits=hundreds，坐标轴标签即显示为 130、135、140……，实现大数值场景下的轴标签精简。

Slide 6 — 系列样式

第六页演示系列级配色与视觉特效。

officecli add charts-stock.pptx /slide[6] --type chart \ --prop chartType=stock --prop title="colors" \ --prop colors="4472C4,ED7D31,70AD47" --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[6] --type chart \ --prop chartType=stock --prop title="seriesoutline" \ --prop seriesoutline="000000:1" --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[6] --type chart \ --prop chartType=stock --prop title="transparency=30" \ --prop transparency=30 --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[6] --type chart \ --prop chartType=stock --prop title="seriesshadow" \ --prop seriesshadow="000000-5-45-3-50" --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC"

本页功能点：colors、seriesoutline、transparency、seriesshadow。

结合 ChartHelper.Builder.cs 的源码：股票图构建后调用ApplyDottedSeriesColors将series{N}.color指定的颜色应用到各LineChartSeries的spPr上；注释明确指出——"Stock series default to NoFill outline (hi-lo lines carry the visual).series{N}.colormust still be honored——apply after build so user-chosen tints reach the LineChartSeries spPr"，即用户选择的颜色在构建后统一注入。默认配色来自OfficeDefaultThemeColors.DefaultChartSeriesPalette（ChartHelper.Builder.cs），以保证 OOXML 构建器与 SVG 预览渲染器使用同一套标准主题色板。

Slide 7 — 背景与边框

第七页演示图表区/绘图区的填充与边框控制。

officecli add charts-stock.pptx /slide[7] --type chart \ --prop chartType=stock --prop title="chartareafill + plotFill + borders" \ --prop chartareafill=FFF8E7 --prop plotFill=FAFAFA \ --prop chartborder="000000:1" --prop plotborder="CCCCCC:0.5" \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[7] --type chart \ --prop chartType=stock --prop title="roundedcorners=true" \ --prop roundedcorners=true --prop chartborder="4472C4:2" \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[7] --type chart \ --prop chartType=stock --prop title="plotFill=none" \ --prop plotFill=none --prop gridlines=none \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" officecli add charts-stock.pptx /slide[7] --type chart \ --prop chartType=stock --prop title="chartareafill=none" \ --prop chartareafill=none --prop legend=bottom \ --prop categories="$CATS" --prop data="$HLC"

本页功能点：chartareafill、plotFill、chartborder、plotborder、roundedcorners。

这四个命令组合演示了"配色协调"（米色图表区FFF8E7+ 浅灰绘图区FAFAFA+ 黑色/灰色边框）、"品牌化"（蓝色圆角边框4472C4:2）、以及"极简透明"（plotFill=none/chartareafill=none让图表融入幻灯片背景）三种设计取向。

Slide 8 — 预设与逐系列 Set

第八页演示两件事：三套一键配色预设（minimal/dark/corporate），以及通过set命令对单个系列做精细化命名与着色。

for p in minimal dark corporate; do officecli add charts-stock.pptx /slide[8] --type chart \ --prop chartType=stock --prop preset=$p --prop title="preset=$p" \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" done officecli add charts-stock.pptx /slide[8] --type chart \ --prop chartType=stock --prop title="chart-series Set name+color" \ --prop legend=bottom --prop categories="$CATS" --prop data="$HLC" officecli set charts-stock.pptx "/slide[8]/chart[4]/series[1]" \ --prop name="H" --prop color=00AA00 officecli set charts-stock.pptx "/slide[8]/chart[4]/series[2]" \ --prop name="L" --prop color=C00000 officecli set charts-stock.pptx "/slide[8]/chart[4]/series[3]" \ --prop name="C" --prop color=4472C4

本页功能点：preset（minimal/dark/corporate）、chart-series Set（逐系列name/color）。

命令模式值得注意：前三张图表用preset属性在add（创建）时一次性套用预设主题；第四张图表先以默认样式创建，再用officecli set .../series[N]的位置寻址逐系列改写。路径"/slide[8]/chart[4]/series[1]"表示"第 8 页第 4 个图表的第 1 个系列"，这正是 ChartHelper.Setter.cs 等 Set 处理器工作的对象层级。通过这种方式，HLC 三个序列被重命名为H/L/C并分别着上绿色、红色与蓝色，实现"创建时套预设 + 创建后细调"的完整工作流。

完整功能覆盖一览

以下表格汇总了全部 8 页幻灯片与所覆盖的股票图功能点（继承自 charts-stock.md）：

检查生成的 PPTX

生成文件后，可以通过 OfficeCLI 的只读查询命令验证图表结构是否符合预期（原文档 Inspect 章节）：

# 列出文件中的所有图表及属性 officecli query charts-stock.pptx chart # 读取指定图表 / 系列的完整属性 officecli get charts-stock.pptx "/slide[1]/chart[1]" officecli get charts-stock.pptx "/slide[2]/chart[3]" officecli get charts-stock.pptx "/slide[8]/chart[4]/series[1]"

query chart用于宏观盘点（共有几个图表、各图表类型），get则按位置路径深入到单个图表或单个系列，适合验证preset、hilowlines、updownbars等属性是否按预期写入。

源码级原理小结

将演示与源码对应起来，可以归纳股票图实现的三层结构：

1. 构建层：ChartHelper.Builder.cs 中case "stock"分支调用BuildStockChart，强制校验 3~4 个序列并输出CT_StockChart（LineChartSeries序列 +HighLowLines+ 条件性UpDownBars），序列线默认NoFill、无标记，视觉完全交给高低线与涨跌柱；
2. 读写层：ChartHelper.Reader.cs 在回读时把hiLowLines、upDownBars元素格式化为hilowlines/updownbars属性（支持 dump→replay 往返），并在 L1765 通过检测C.StockChart识别图类型为stock；ChartHelper.Setter.cs 则负责对已存在图表的hilowlines/updownbars做增删改；
3. 别名层：ChartHelper.cs 将ohlc归一化为stock，保证命令行与 SDK 的chartType取值宽容易记。

通过这一套设计，OfficeCLI 把 PowerPoint 股票图从"需要在 XML 里手工拼<c:hiLowLines>、<c:upDownBars>"的繁琐操作，压缩为一条officecli add ... --type chart --prop chartType=stock命令——序列顺序由构建器校验兜底，默认样式由源码内置，全部 16 项功能点可在此演示的 8 页幻灯片中逐一复现与验证。

• CLI
• AI 应用
• MCP 服务