• CLI
• AI 应用
• MCP 服务

本文基于 OfficeCLI 仓库中 examples/excel/charts/charts-scatter.md 这一示例文档展开，系统讲解如何在无需安装 Microsoft Office 的前提下，通过 OfficeCLI 命令行与 Python SDK 生成包含 6 个图表面、24 张散点图的工作簿charts-scatter.xlsx。读完本文，你将掌握 scatter 图表类型下全部--prop参数的取值与组合方式，包括四种散点样式、八种标记形状、六类趋势线、四类误差线、完整的样式系统（标题、阴影、渐变、边框、网格线），以及次坐标轴、参考线、对数轴、条件着色等高级特性，并理解这些参数在仓库源码中的底层实现机制。

示例概览：三个文件协同工作

散点图示例由三份文件组成，它们共同产出同一份结果工作簿：

charts-scatter.py的脚本头注释明确声明：示例的目标是让 officecli 支持的每一个散点图特性都至少被演示一次——散点样式、标记类型、平滑曲线、趋势线（线性、多项式、指数、对数、幂、移动平均）、误差线、轴缩放、网格线、数据标签、图例、填充、阴影、边框、次坐标轴、参考线、对数刻度与颜色规则。

环境准备与快速再生

示例命令在examples/excel目录下执行，Python 与 Bash 两条路径均可产出等价的结果文件：

cd examples/excel python3 charts-scatter.py # → charts-scatter.xlsx（6 个图表面，24 张散点图）

Python 路径需要先安装 SDK 且保证officecli二进制在PATH上：

pip install officecli-sdk # 再加上可用的 officecli 二进制 python3 charts-scatter.py

charts-scatter.py在导入时做了双保险：优先导入已安装的officecli-sdk，失败则把仓库内的 sdk/python 目录插入sys.path作为回退。脚本通过officecli.create(FILE, "--force")打开一个常驻进程，然后以doc.batch(items)单次往返把所有 sheet 与图表通过命名管道提交——每个 item 都是{"command","parent","type","props"}结构，与officecli batch列表中的条目完全一致。.sh版本则有意不使用set -e，以便在遇到向前兼容的UNSUPPORTED props警告（officecli 退出码 2）时继续构建完整文档。

注意：charts-scatter.md中的命令示例使用了data.xlsx作为目标文件，而.py与.sh脚本实际生成的文件是charts-scatter.xlsx。下文命令统一以脚本实际使用的charts-scatter.xlsx为准，保证可直接复制运行。

Sheet 1：散点图基础（Scatter Fundamentals）

该图表面用 4 张图覆盖散点的四种基础形态：标记+连线、仅标记、平滑曲线、仅连线。

# ① 基本散点：圆形标记 + 连接线 officecli add charts-scatter.xlsx /1-Scatter Fundamentals --type chart \ --prop chartType=scatter \ --prop series1="Male:62,68,72,78,82,88,95" \ --prop categories=160,165,170,175,180,185,190 \ --prop marker=circle --prop markerSize=6 --prop lineWidth=1.5 \ --prop catTitle="Height (cm)" --prop axisTitle="Weight (kg)" # ② 仅标记（scatterStyle=marker，无连接线） officecli add charts-scatter.xlsx /1-Scatter Fundamentals --type chart \ --prop chartType=scatter --prop scatterStyle=marker \ --prop markerSize=8 --prop gridlines=D9D9D9:0.5:dot # ③ 平滑曲线（Bezier 插值） officecli add charts-scatter.xlsx /1-Scatter Fundamentals --type chart \ --prop chartType=scatter --prop scatterStyle=smooth \ --prop smooth=true --prop marker=diamond --prop lineWidth=2 # ④ 仅连线（无标记） officecli add charts-scatter.xlsx /1-Scatter Fundamentals --type chart \ --prop chartType=scatter --prop scatterStyle=line \ --prop showMarker=false --prop lineWidth=2.5 --prop lineDash=dash

涉及特性：scatter、scatterStyle=marker|smooth|line、smooth=true、marker=circle|diamond、markerSize、lineWidth、lineDash=dash、showMarker=false、catTitle、axisTitle、gridlines。

源码级原理：scatterStyle 如何落地

在 ChartHelper.Builder.cs 的BuildScatterChart中，scatterStyle字符串被映射为 OOXML 的ScatterStyleValues枚举：marker → Marker、line → Line、smooth/smoothmarker → SmoothMarker，未指定时默认lineMarker。分类轴数据categories会被解析为散点图的 X 值数组（解析失败的点取 0）。特别地，当样式为marker（仅标记）时，源码会对每个系列的spPr显式追加一个NoFill的Outline，从而隐藏连接线——这是"仅标记"形态得以成立的底层实现。

对应地，ChartHelper.Setter.cs 中的case "scatterstyle"接受更宽容的别名输入：line/lineonly、linemarker、marker/markeronly、smooth/smoothline、smoothmarker，并直接写回C.ScatterStyle元素。case "smooth"（L2148）则同时作用于图表级C.Smooth与每个 line/scatter 系列的C.Smooth子元素；若图表类型不支持平滑（如柱状图），会以UNSUPPORTED提示表面化，避免调用方误以为设置已生效。case "showmarker"（L2177）在隐藏标记时会把散点系列中的Marker符号置为None，这与"仅连线"的视觉目标一致。

Sheet 2：标记样式（Marker Styles）

该图表面用 4 张图演示全部 8 种标记形状（circle、diamond、square、triangle、star、x、plus、dash）以及按系列独立控制标记的能力。

# ① 按系列指定标记：circle / diamond / square officecli add charts-scatter.xlsx /2-Marker Styles --type chart \ --prop chartType=scatter \ --prop series1.marker=circle --prop series2.marker=diamond \ --prop series3.marker=square --prop markerSize=8 # ② 按系列指定标记：triangle / star / x officecli add charts-scatter.xlsx /2-Marker Styles --type chart \ --prop chartType=scatter \ --prop series1.marker=triangle --prop series2.marker=star \ --prop series3.marker=x --prop markerSize=9 # ③ 大标记 + plus / dash 形状 officecli add charts-scatter.xlsx /2-Marker Styles --type chart \ --prop chartType=scatter --prop scatterStyle=marker \ --prop series1.marker=circle --prop series2.marker=plus \ --prop series3.marker=dash --prop markerSize=10 # ④ showMarker=false + lineDash=dashDot officecli add charts-scatter.xlsx /2-Marker Styles --type chart \ --prop chartType=scatter --prop scatterStyle=lineMarker \ --prop showMarker=false --prop lineDash=dashDot

涉及特性：series{N}.marker=circle|diamond|square|triangle|star|x|plus|dash、markerSize、scatterStyle=lineMarker|marker、showMarker=false、lineDash=dashDot。

在.py的对应实现中，per-series 属性以**{"series1.marker": "circle", ...}展开为 props 字典传入chart()辅助函数；配合colors（如4472C4,ED7D31,70AD47）与legend=bottom可以在一张图中清晰区分三个传感器或实验组的点形与颜色。scatterStyle=marker时 markerSize 可调至 10 以强调数据点本身。

Sheet 3：趋势线（Trendlines）

该图表面覆盖全部趋势线类型及其子属性：线性、多项式（含阶数）、指数（含前后外推）、对数，以及按系列分别配置。

# ① 线性趋势线 + 显示方程 officecli add charts-scatter.xlsx /3-Trendlines --type chart \ --prop chartType=scatter --prop scatterStyle=marker \ --prop trendline=linear \ --prop series1.trendline.equation=true # ② 多项式（3 阶）+ 显示 R 方 officecli add charts-scatter.xlsx /3-Trendlines --type chart \ --prop chartType=scatter --prop scatterStyle=marker \ --prop trendline=poly:3 \ --prop series1.trendline.rsquared=true # ③ 指数趋势线 + 前后外推（forward=2, backward=1） officecli add charts-scatter.xlsx /3-Trendlines --type chart \ --prop chartType=scatter --prop scatterStyle=marker \ --prop trendline=exp:2:1 \ --prop series1.trendline.name="Exponential Fit" # ④ 按系列趋势线：线性 vs 对数 officecli add charts-scatter.xlsx /3-Trendlines --type chart \ --prop chartType=scatter --prop scatterStyle=marker \ --prop series1.trendline=linear --prop series2.trendline=log \ --prop series1.trendline.equation=true \ --prop series2.trendline.rsquared=true

涉及特性：trendline=linear|poly:N|exp|log|power|movingAvg、trendline=exp:forward:backward（外推）、series{N}.trendline（按系列）、series{N}.trendline.equation、series{N}.trendline.rsquared、series{N}.trendline.name。

源码级原理：BuildTrendline 的参数解析

ChartHelper.SetterHelpers.cs 的BuildTrendline是趋势线的核心解析函数，支持"type"、"type:order"、"type:forward:backward"三种格式：

• 类型映射：linear→Linear、exp/exponential→Exponential、log/logarithmic→Logarithmic、poly/polynomial→Polynomial、power→Power、movingavg/moving/movingaverage→MovingAverage，未知类型抛出CliException。
• 多项式阶数：poly:N中的N被写入PolynomialOrder并Clamp(2, 6)（OOXML 要求阶数 2~6）；未显式指定时默认阶数 2（与 Excel "添加趋势线 → 多项式" 的默认一致）。
• 移动平均周期：movingAvg:N写入Period，且周期必须>= 2（OOXMLST_Skip MinInclusive=2），未指定时回退到 2。
• 外推：type:forward:backward的第二个数字写入C.Forward，第三个写入C.Backward，即示例 ③ 中的exp:2:1表示向前外推 2 个周期、向后外推 1 个周期。

ApplyTrendlineOptions（L136 起）负责子属性写入：name/label会同时生成<c:trendlineName>与带富文本的<c:trendlineLbl>（只有后者才能让 Excel 真正在趋势线旁绘制标签）；forward/backward/order/period分别对应C.Forward、C.Backward、PolynomialOrder、Period。case "trendline"（ChartHelper.Setter.cs L2313）还支持以分号连接的多规格列表（如"linear;exp"），保证 dump→replay 能还原一条系列上的多条趋势线。

Sheet 4：误差线（Error Bars）

该图表面用 4 张图覆盖散点系列上全部误差线类型：固定值、百分比、标准差、标准误。

# ① 固定误差（±5） officecli add charts-scatter.xlsx /4-Error Bars --type chart \ --prop chartType=scatter \ --prop errBars=fixed:5 # ② 百分比误差（10%） officecli add charts-scatter.xlsx /4-Error Bars --type chart \ --prop chartType=scatter \ --prop errBars=percent:10 # ③ 标准差误差线 officecli add charts-scatter.xlsx /4-Error Bars --type chart \ --prop chartType=scatter \ --prop errBars=stddev # ④ 标准误 + 系列阴影 officecli add charts-scatter.xlsx /4-Error Bars --type chart \ --prop chartType=scatter \ --prop errBars=stderr \ --prop series.shadow=000000-4-315-2-30

涉及特性：errBars=fixed:N|percent:N|stddev|stderr、series.shadow。

在 ChartHelper.Setter.cs 的case "errbars"中，设置器会先清空所有系列上的既有C.ErrorBars，再通过SeriesSupportsErrorBars(ser)校验系列是否支持误差线，最后调用BuildErrorBars(value)生成 OOXML 元素——因此 errBars 可以安全地重复设置或重置（值为none时仅清空）。此外源码还提供errBars.direction/errbardirection子属性（L2398-L2423），取值plus、minus、both（默认 both），控制C.ErrorBarType的plus|minus|both，实现对误差方向的微调。

series.shadow=000000-4-315-2-30是 OfficeCLI 的阴影参数规范：依次为颜色（000000）、模糊半径、角度（315°）、距离（2）与透明度（30）。阴影用于增强"带误差的测量数据"的层次感，示例 ④ 将其与gridlines=D9D9D9:0.5:dot的浅色点状网格组合，突出实验数据的离散度。

Sheet 5：样式系统（Styling）

该图表面覆盖标题样式、填充、渐变、边框与坐标轴格式化的全部能力。

# ① 标题样式 + 系列阴影与描边 officecli add charts-scatter.xlsx /5-Styling --type chart \ --prop chartType=scatter \ --prop title.font=Georgia --prop title.size=16 \ --prop title.color=1F4E79 --prop title.bold=true \ --prop title.shadow=000000-3-315-2-30 \ --prop series.shadow=000000-4-315-2-30 \ --prop series.outline=333333:1.5 # ② 渐变、透明度、绘图区与图表区填充 officecli add charts-scatter.xlsx /5-Styling --type chart \ --prop chartType=scatter \ --prop 'gradients=4472C4-BDD7EE:90;ED7D31-FBE5D6:90' \ --prop transparency=20 \ --prop plotFill=F5F5F5 --prop chartFill=FAFAFA # ③ 轴字体、网格线、次网格线、轴线 officecli add charts-scatter.xlsx /5-Styling --type chart \ --prop chartType=scatter \ --prop axisfont=9:C00000:Arial \ --prop gridlines=BFBFBF:0.75:solid \ --prop minorGridlines=E0E0E0:0.25:dot \ --prop axisLine=333333:1 # ④ 图表区/绘图区边框 + 圆角 officecli add charts-scatter.xlsx /5-Styling --type chart \ --prop chartType=scatter \ --prop chartArea.border=333333:1.5 \ --prop plotArea.border=999999:0.75 \ --prop roundedCorners=true

涉及特性：title.font/size/color/bold、title.shadow、series.shadow、series.outline、gradients、transparency、plotFill、chartFill、axisfont、gridlines、minorGridlines、axisLine、chartArea.border、plotArea.border、roundedCorners。

几个值得注意的参数格式：

• gradients用分号连接多个系列的渐变，每个渐变为起色-止色:角度格式；示例 ② 为两个系列分别配置了蓝系（4472C4→BDD7EE）与橙系（ED7D31→FBE5D6），角度 90°，配合transparency=20的 20% 透明度。
• axisfont=9:C00000:Arial为"字号:颜色:字体"三段式；gridlines/minorGridlines均为颜色:线宽:线型三段式（线型取solid、dot、dash等）；axisLine=333333:1为轴线的颜色与粗细。
• 边框参数chartArea.border与plotArea.border使用颜色:线宽格式（注意此处冒号分隔，与 series.outline 一致），可分别控制图表外框与绘图区内框。

Sheet 6：高级特性（Advanced）

该图表面集中展示次坐标轴、参考线、对数刻度与条件着色四类高级能力。

# ① 次 Y 轴（第 2 个系列放到右侧 Y 轴） officecli add charts-scatter.xlsx /6-Advanced --type chart \ --prop chartType=scatter \ --prop secondaryAxis=2 # ② 参考线（水平目标线） officecli add charts-scatter.xlsx /6-Advanced --type chart \ --prop chartType=scatter \ --prop referenceLine=75:FF0000:Target:dash # ③ 对数轴 + 坐标轴上下限 officecli add charts-scatter.xlsx /6-Advanced --type chart \ --prop chartType=scatter \ --prop logBase=10 \ --prop axisMin=1 --prop axisMax=10000 # ④ 数据标签 + 条件着色规则 officecli add charts-scatter.xlsx /6-Advanced --type chart \ --prop chartType=scatter --prop scatterStyle=marker \ --prop dataLabels=true --prop labelPos=top \ --prop colorRule=60:C00000:00AA00

涉及特性：secondaryAxis、referenceLine=value:color:label:dash、logBase、axisMin、axisMax、dataLabels、labelPos=top、colorRule=threshold:belowColor:aboveColor。

源码级原理：参考线与条件着色

referenceLine由 ChartHelper.Advanced.cs 的AddReferenceLine实现，其规范是冒号分隔的位置参数，支持多种形态：

• value（默认红色虚线）
• value:color
• value:color:label
• value:color:width:dash（4 段，第 3 段为数字且第 4 段为已知虚线样式时按"宽度"解释）
• value:color:label:dash（4 段，旧式标签写法）
• value:color:width:dash:label（5 段标准写法，宽度可留空取默认 1.5pt）

源码会先解析数值与颜色（默认FF0000），线宽默认 1.5pt、范围校验为0.25~10，虚线样式支持solid/dot/dash/dashdot/longdash/longdashdot/longdashdotdot。实现方式是在现有图表中插入一个隐藏的LineChart覆盖层（共享现有坐标轴 ID），其系列的所有取值均为参考值，从而绘制出一条平坦的目标线。值得一提的是，源码对百分比堆叠图上的参考线做了溢出告警：当参考值 > 1 时提示用户很可能把 50 误写成了 0.5，避免 Excel 自动拉长数值轴导致真实数据被压缩。

colorRule由同文件中的ApplyColorRule（L290 起）实现，支持两种格式：threshold:belowColor:aboveColor双区着色，以及low:lowColor:mid:midColor:high:highColor三段式着色。示例 ④ 的60:C00000:00AA00表示低于 60 的点标红（C00000）、高于 60 的点标绿（00AA00），非常适合 KPI 达标监控类图表。源码遍历每个数据点，按阈值区间为单个数据点应用独立颜色。

参数速查总表

将六张图表面涉及的参数汇总如下，便于实际使用时快速查阅：

Python SDK 批处理路径与 CLI 生命周期

.py版本演示了 OfficeCLI Python SDK 的典型用法：一个常驻进程、一次batch往返完成所有构建。核心模式如下（摘自 charts-scatter.py）：

import officecli # pip install officecli-sdk def sheet(name): return {"command": "add", "parent": "/", "type": "sheet", "props": {"name": name}} def chart(parent, **props): return {"command": "add", "parent": parent, "type": "chart", "props": props} with officecli.create("charts-scatter.xlsx", "--force") as doc: items = [ sheet("1-Scatter Fundamentals"), chart("/1-Scatter Fundamentals", chartType="scatter", categories="160,165,170,175,180,185,190", series1="Male:62,68,72,78,82,88,95", marker="circle", markerSize="6", lineWidth="1.5", catTitle="Height (cm)", axisTitle="Weight (kg)", legend="bottom"), # ... 其余 5 个 sheet、23 张图 ... {"command": "remove", "path": "/Sheet1"}, # 删除默认空白 Sheet1 ] doc.batch(items)

SDK 代码位于 sdk/python/officecli.py，与命令行共享同一套props语义——这也是为什么.py与.sh能产出等价文件。.sh脚本则展示了完整的 CLI 生命周期（charts-scatter.sh）：

officecli create charts-scatter.xlsx officecli open charts-scatter.xlsx officecli add charts-scatter.xlsx / --type sheet --prop name="1-Scatter Fundamentals" officecli add charts-scatter.xlsx "/1-Scatter Fundamentals" --type chart --prop chartType=scatter ... officecli remove charts-scatter.xlsx /Sheet1 officecli close charts-scatter.xlsx officecli validate charts-scatter.xlsx

即create → open → add（sheet/图表）→ remove（清理默认 Sheet1）→ close → validate的完整流程。脚本末尾的validate会对生成文件做一次结构校验，是生产环境自动化生成 Office 文档时值得保留的一步。

检查生成的散点图

charts-scatter.md提供了两个用于检查生成结果的命令：

# 列出工作簿中的所有图表 officecli query charts-scatter.xlsx chart # 精确定位某个图表节点（按路径），查看其属性 officecli get charts-scatter.xlsx "/1-Scatter Fundamentals/chart[1]"

query用于快速确认图表总数与分布，get配合路径索引可以深入到某个 sheet 下的第 N 张图，核对chartType、scatterStyle、trendline、errBars等属性是否按预期写入，是验证参数生效与排查问题的最直接手段。结合validate的结构校验，可以确保生成的charts-scatter.xlsx既符合 OOXML 规范，又完整呈现了 OfficeCLI 散点图模块的全部能力。

小结

charts-scatter.md示例是 OfficeCLI 散点图能力的全景演示：从四种基础散点形态出发，覆盖 8 种标记、6 类趋势线、4 种误差线、完整样式系统与次坐标轴/参考线/对数轴/条件着色等高级特性，并且同一份工作簿可以通过 CLI 与 Python SDK 两条等价路径生成。配合 ChartHelper.Builder.cs、ChartHelper.Setter.cs、ChartHelper.SetterHelpers.cs 与 ChartHelper.Advanced.cs 中的实现，你可以按需组合上述参数，为 AI 工作流批量产出符合 Excel 规范的、带统计语义（趋势、误差、阈值）的散点图。

• CLI
• AI 应用
• MCP 服务