OfficeCLI 演示文稿全局设置实战：深入 `presentation` 容器与 PPTX 整档属性配置

OfficeCLI 演示文稿全局设置实战：深入presentation容器与 PPTX 整档属性配置

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

本文围绕 OfficeCLI 仓库中的examples/ppt/presentation-settings.md及其配套脚本展开，系统讲解如何通过presentation容器一次性配置 PPTX 的档级（deck-level）属性——包括核心/扩展元数据、幻灯片尺寸、打印设置、放映行为、隐私开关与主题色板。读完本文，你将掌握用officecli set file.pptx / ...完成整档配置的完整命令集，理解每条属性背后的 OOXML 实现位置，并能在 CLI 与 Python SDK 两套接口间自由切换。

什么是presentation容器

在 OfficeCLI 的路径模型中，presentation是一个只读容器，固定地址在/，代表 PPTX 的根节点。它没有按页（slide）或按形状（shape）的等价物，只承载「整份文档」级别的设置。因此你永远不会对它执行add或remove，只能set（写入）和get（读取）：

officecli set file.pptx / --prop title="Q4 Review" --prop slideSize=widescreen officecli get file.pptx /

这一行为由 schema 明确定义：在 schemas/help/pptx/presentation.json 中，operations声明add: false、remove: false、set: true、get: true、query: true，其paths.positional只有["/"]。schema 的note字段还解释了关键实现细节：

Root container. Get returns the presentation node with slide count + theme/master/layout references as children. Set on '/' exposes core document metadata (title/author/subject/keywords/description/category) — written todocProps/core.xml, same source as docx/xlsx. Element-level mutations go through/slide[N],/theme, etc.

也就是说，/上的get返回一个包含幻灯片数量及 theme/master/layout 子引用的节点；/上的set负责写入核心元数据（最终落到docProps/core.xml，与 Word、Excel 共用同一数据源）；而元素级的修改（如幻灯片、主题）则必须通过/slide[N]、/theme等具体路径完成。

一个关键前提：空白 PPTX 没有幻灯片

空白 PPTX 自带 master + layouts，但没有任何 slide。示例脚本在放置标题形状之前，必须先显式添加一页幻灯片——在零幻灯片的档上执行add /slide[1] ...会直接成为空操作（no-op）：

officecli create presentation-settings.pptx officecli open presentation-settings.pptx officecli add presentation-settings.pptx / --type slide officecli add presentation-settings.pptx "/slide[1]" --type shape --prop geometry=rect \ --prop left=2cm --prop top=3cm --prop width=26cm --prop height=4cm \ --prop fill=accent1 --prop text="Presentation Settings" \ --prop fontSize=40 --prop color=FFFFFF --prop bold=true

注意标题形状的fill=accent1引用的是主题色板中的 accent1——这正是后续「重映射主题色即可改变标题栏颜色」的伏笔。

快速复现：CLI 与 Python SDK 双路径

示例的四个文件协同工作：

• presentation-settings.sh — 通过officecliCLI 构建整档；
• presentation-settings.py — 通过 officecli Python SDK 完成相同构建（每次doc.send()对应一条命令，逐行镜像.sh）；
• presentation-settings.pptx — 生成的成品档（任一脚本均可产出）；
• presentation-settings.md — 本文讲解的源文档。

重新生成：

cd examples/ppt bash presentation-settings.sh # 通过 CLI # — 或 — pip install officecli-sdk # SDK（仍需安装 officecli 二进制） python3 presentation-settings.py # 通过 SDK，结果相同 # → presentation-settings.pptx

两个脚本采用「一条命令一条消息」的映射策略。SDK 侧用两个辅助函数把 CLI 语义封装成 JSON 消息：

def pres(**props): # 一次 presentation 容器的 set doc.send({"command": "set", "path": "/", "props": props}) def add(parent, type_, **props): # 一次 officecli add doc.send({"command": "add", "parent": parent, "type": type_, "props": props})

脚本头部有一条容易被忽略但很重要的工程约定：故意不启用set -e。和 SDK 孪生脚本的doc.batch一样，它要容忍向前兼容的UNSUPPORTED props警告（officecli 此时退出码为 2），继续构建，从而保证整份文档被完整产出。这意味着当你针对未来版本的属性表写命令时，遇到"不支持属性"警告不代表文档损坏，应结合officecli validate判断最终结果。

属性组一：元数据（核心 + 扩展属性）

/上的set可以直接写文档核心元数据，包括核心属性（对应docProps/core.xml）与扩展属性（对应docProps/app.xml，用extended.前缀）：

officecli set file.pptx / --prop author="Jane Author" --prop title="Q4 Business Review" \ --prop subject=Strategy --prop keywords="q4,review,strategy" \ --prop description="Quarterly business review deck." --prop category=Marketing \ --prop lastModifiedBy=Editorial --prop revisionNumber=3 officecli set file.pptx / --prop extended.company="Acme Corp" \ --prop extended.manager="Dana Lead" --prop extended.template="Widescreen.potx"

各字段的语义与 OOXML 落点可以对照 schema 确认：

值得注意的设计：extended.前缀下的多数属性（如extended.application、extended.pages、extended.words、extended.characters、extended.lines、extended.paragraphs、extended.totalTime、extended.applicationVersion）在 schema 中都是set: false，只能读取。可写扩展字段仅有company、manager、template三个，写多了会被识别为不支持的属性。

属性组二：幻灯片尺寸与版式设置

officecli set file.pptx / --prop slideSize=widescreen \ --prop firstSlideNum=1 --prop rtl=false --prop compatMode=false

slideSize是命名预设，底层直接改写p:sldSz/@type以及@cx/@cy。根据 presentation.json 的定义，预设的完整清单比文档注释里列出的更宽：

widescreen | standard | 16:10 | a4 | a3 | letter | b4 | b5 | 35mm | overhead | banner | ledger | custom

未列入清单的名字会被拒绝（unlisted names are rejected）。如果你需要任意尺寸，就不要用slideSize，而是显式给出slideWidth/slideHeight——二者互斥，一旦设置宽或高中任意一个，@type就会被切到custom：

officecli set file.pptx / --prop slideWidth=25.4cm --prop slideHeight=19.05cm # 自定义 4:3

slideWidth/slideHeight的 schema 属性值得细读：它们支持带单位的长度字符串或裸 EMU 值，读取时经FormatEmu格式化返回（如'25.4cm'、'720pt'）；别名分别为width/height。firstSlideNum是@firstSlideNum整数（默认 1），rtl与compatMode为布尔开关。其中rtl有一个不对称设计：rtl只能写入，读取时以规范键direction返回（值为'rtl'表示右到左，缺省表示默认左到右）——这与 docx 的约定保持一致，由 schema 中rtl（set-only input alias）与direction（get-only canonical key）两个属性共同体现。

底层实现：TrySetPresentationSetting

这些演示文稿属性在 src/officecli/Handlers/Pptx/PowerPointHandler.Set.Presentation.cs 中逐 case 落地。以slideSize之外最直接的三个为例：

case "firstslidenum" or "firstslidenumber": var pres = _doc.PresentationPart!.Presentation!; pres.FirstSlideNum = ParseHelpers.SafeParseInt(value, "firstSlideNum"); pres.Save(); return true; case "rtl": pres.RightToLeft = IsTruthy(value); pres.Save(); return true; case "compatmode" or "compatibilitymode": pres.CompatibilityMode = IsTruthy(value); pres.Save(); return true;

可以看到每个键都直接映射到P.Presentation的 OpenXML 属性对象，set后立即Save()，不存在延迟落盘。这也是为什么set一条命令就会改变档内实际 XML 内容。

属性组三：打印设置

打印相关属性统一以print.为前缀，对应 OOXML 的p:prnPr（PrintingProperties）：

officecli set file.pptx / \ --prop print.what=slides \ # slides | handouts | notes | outline --prop print.colorMode=color \ # color | gray | bw --prop print.frameSlides=true \ --prop print.hiddenSlides=false \ --prop print.scaleToFitPaper=true

对照 schema 与源码，print.*五个键的实际可接受值比注释更精细：

• print.what：接受简写slides、handouts、notes、outline，也接受显式 OOXML tokenhandouts1、handouts2、handouts3、handouts4、handouts6、handouts9；裸handouts是handouts1的别名，读取时返回 OOXML token（如handouts1）。在 PowerPointHandler.Set.Presentation.cs 中，非法值会抛出带完整合法清单的ArgumentException。
• print.colorMode：接受color|clr、grayscale|gray、blackAndWhite|bw三组写法，统一归一化后写入PrintColorModeValues。
• print.frameSlides：布尔值，打印时为每页幻灯片描细边框。
• print.hiddenSlides：布尔值，是否把隐藏幻灯片纳入打印输出。
• print.scaleToFitPaper：布尔值，是否缩放幻灯片以填满纸张页面。

print、show两组属性在 OOXML 中都属于p:presentationPr（PresentationPropertiesPart），因此源码里有一组「按需创建」的辅助方法：EnsurePrintingProperties()会先确保p:prnPr存在，且按 schema 顺序插在p:showPr之前（注释明确说明p:prnPr must precede p:showPr in schema order），避免产生不合规的部件顺序。

属性组四：放映行为

放映相关属性以show.为前缀，对应p:showPr（ShowProperties）：

officecli set file.pptx / \ --prop show.loop=false --prop show.narration=true \ --prop show.animation=true --prop show.useTimings=true

注意show.loop、show.narration、show.animation各有无前缀别名（showloop、shownarration、showanimation），show.useTimings的别名是usetimings/show.usetimings（见 presentation.json 的 aliases 字段）。读取侧 PopulatePresentationSettings 只把「非默认值」写进Format字典——例如firstSlideNum仅在值 ≠ 1 时返回，print.frameSlides等布尔开关仅在true时返回，读取不到键即表示该开关保持默认。

属性组五：隐私开关

officecli set file.pptx / --prop removePersonalInfo=false

removePersonalInfo（别名removepersonalinfoonsave）对应 OOXML 的RemovePersonalInfoOnSave，开启后保存时会剥离作者 / 最后保存者等个人信息。示例中设为false，表示保留文档属性。它是布尔类型，schema 里enforcement均为report——即属性写入是尽力而为的，遇到不支持的属性只报告警告而不中断流程，这再次呼应了脚本不设set -e的容错设计。

属性组六：主题色板与正文字体

空白 PPTX 自带 theme part，所以主题编辑总能解析成功。示例脚本用fill=accent1填充标题形状，因此重映射theme.color.accent1会直接改变标题栏颜色——渲染出的档会显示新的强调色，而不是 Office 默认值：

officecli set file.pptx / \ --prop theme.color.accent1=1F6FEB --prop theme.color.accent2=E3572A \ --prop theme.color.hlink=0969DA officecli set file.pptx / \ --prop theme.font.major.latin=Georgia --prop theme.font.minor.latin=Calibri

完整的色板覆盖在脚本中实际写满了 12 个色槽 + 4 个字体槽：

officecli set file.pptx / \ --prop theme.color.dk1=1A1A1A --prop theme.color.lt1=FFFFFF \ --prop theme.color.dk2=2F3640 --prop theme.color.lt2=EEF1F5 \ --prop theme.color.accent1=1F6FEB --prop theme.color.accent2=E3572A \ --prop theme.color.accent3=2DA44E --prop theme.color.accent4=BF8700 \ --prop theme.color.accent5=8250DF --prop theme.color.accent6=1B7C83 \ --prop theme.color.hlink=0969DA --prop theme.color.folHlink=8250DF officecli set file.pptx / \ --prop theme.font.major.latin=Georgia --prop theme.font.minor.latin=Calibri \ --prop theme.font.major.eastAsia=SimHei --prop theme.font.minor.eastAsia=SimSun

主题属性的两套入口

theme.color.*/theme.font.*键由 schemas/help/_shared/root-metadata.json 声明（presentation容器通过extends继承它们），而独立的/theme元素（schemas/help/pptx/theme.json）以更短的键暴露同一套色板与字体：

• 短键：accent1..6、dk1/dk2/lt1/lt2、hyperlink（别名hlink）、followedhyperlink（别名folhlink）、headingFont/bodyFont及其.ea/.cs变体、name；
• 长键：theme.color.accent1..6、theme.color.dk1/lt1/dk2/lt2、theme.color.hlink/folHlink、theme.font.major/minor.latin/eastAsia。

从源码看，/上的set在 PowerPointHandler.Set.cs 处形成调用链：先尝试TrySetPresentationSetting，不命中再交由Core.ThemeHandler.TrySetTheme处理；/theme上的set则走 PowerPointHandler.Theme.cs 的SetThemeProperties。两处最终都写入同一份 ThemePart，因此长键与短键指向的是同一组 OOXML 颜色槽。

底层实现细节值得展开：

• 颜色写入由SetSchemeColor完成：先清空该颜色槽上已有的RgbColorModelHex/SystemColor/SchemeColor/HslColor/PresetColor子元素，再通过ParseHelpers.SanitizeColorForOoxml支持 3 位短十六进制、命名色、rgb()、ARGB 等输入，最终只接受 6 位十六进制写入RgbColorModelHex，否则抛异常。
• 字体写入由SetFontScheme完成，特殊之处在于归一化逻辑：""、"none"、"default"均表示「清除该槽位以继承主题默认值」，不会把这三个字符串当作字体名写进 XML。
• 主题部件解析优先取presentationPart.ThemePart，找不到时回退到第一个 SlideMaster 的 ThemePart（见GetThemePart）。
• 读取侧GetThemeNode会把色槽统一格式化为#前缀大写十六进制（如#1F6FEB），字体读取headingFont/bodyFont及其.ea/.cs变体——与theme.font.*的长键命名保持一致性约定。

完整功能覆盖

下表汇总presentation容器支持的六组属性键（完整列表可随时通过officecli help pptx presentation查看；officecli help pptx theme则给出/theme的短键版本）：

Set → Get 往返验证

示例脚本构建完所有属性后，通过一次get /做往返验证，确认规范键都能按预期读回：

author = Jane Author title = Q4 Business Review slideSize = widescreen print.what = slides show.useTimings = True theme.color.accent1 = #1F6FEB theme.font.major.latin = Georgia

SDK 版脚本 presentation-settings.py 的做法与此一致：doc.send({"command": "get", "path": "/"})后，从返回的data.results[0].format中按白名单键逐个取出打印，最后在同一会话内通过doc.send({"command": "validate"})完成校验（无额外进程开销），再doc.close()停止常驻进程并落盘。

需要提醒的读回差异有三点：一是rtl设置后以direction键读回（值为rtl）；二是布尔开关多数仅在非默认/为 true 时出现在读取结果中；三是颜色统一以#大写十六进制返回。这些细节在自动化巡检、对比生成结果时非常容易踩坑。

小结

presentation容器是 OfficeCLI 处理 PPTX 整档属性的统一入口：核心与扩展元数据写入docProps/core.xml与docProps/app.xml，幻灯片尺寸、打印、放映、隐私设置直接驱动p:presentation与p:presentationPr下的 OOXML 属性，主题色板与字体则落到 ThemePart 的颜色方案与字体方案中。配合examples/ppt/下的 CLI 脚本、SDK 脚本与 schema 定义，你可以快速复现整个属性面，并在生成后通过get /+validate闭环确认结果——这套工作流非常适合 AI Agent 在批量生成、改写演示文稿时做统一的档级规范化处理。

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