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 titleQ4 Review --prop slideSizewidescreen 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-opofficecli 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 geometryrect \ --prop left2cm --prop top3cm --prop width26cm --prop height4cm \ --prop fillaccent1 --prop textPresentation Settings \ --prop fontSize40 --prop colorFFFFFF --prop boldtrue注意标题形状的fillaccent1引用的是主题色板中的 accent1——这正是后续「重映射主题色即可改变标题栏颜色」的伏笔。快速复现CLI 与 Python SDK 双路径示例的四个文件协同工作presentation-settings.sh — 通过officecliCLI 构建整档presentation-settings.py — 通过 officecli Python SDK 完成相同构建每次doc.send()对应一条命令逐行镜像.shpresentation-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 authorJane Author --prop titleQ4 Business Review \ --prop subjectStrategy --prop keywordsq4,review,strategy \ --prop descriptionQuarterly business review deck. --prop categoryMarketing \ --prop lastModifiedByEditorial --prop revisionNumber3 officecli set file.pptx / --prop extended.companyAcme Corp \ --prop extended.managerDana Lead --prop extended.templateWidescreen.potx各字段的语义与 OOXML 落点可以对照 schema 确认属性键类型落点说明title/subject/keywords/description/categorystringdocProps/core.xml核心元数据与 docx/xlsx 同源见 presentation.json 的noteauthorstring同上别名creatorlastModifiedBystring同上别名lastmodifiedby读取时返回 last-modified authorrevisionNumberstringdocProps/core.xmlRevision 字段即演示文稿的保存计数器schema 注释为 presentation save counterextended.company/extended.manager/extended.templatestringdocProps/app.xml由 schemas/help/_shared/root-metadata.json 提供created/modifiedstringdocProps/core.xml只读set: false返回 ISO 8601 时间戳值得注意的设计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 slideSizewidescreen \ --prop firstSlideNum1 --prop rtlfalse --prop compatModefalseslideSize是命名预设底层直接改写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就会被切到customofficecli set file.pptx / --prop slideWidth25.4cm --prop slideHeight19.05cm # 自定义 4:3slideWidth/slideHeight的 schema 属性值得细读它们支持带单位的长度字符串或裸 EMU 值读取时经FormatEmu格式化返回如25.4cm、720pt别名分别为width/height。firstSlideNum是firstSlideNum整数默认 1rtl与compatMode为布尔开关。其中rtl有一个不对称设计rtl只能写入读取时以规范键direction返回值为rtl表示右到左缺省表示默认左到右——这与 docx 的约定保持一致由 schema 中rtlset-only input alias与directionget-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:prnPrPrintingPropertiesofficecli set file.pptx / \ --prop print.whatslides \ # slides | handouts | notes | outline --prop print.colorModecolor \ # color | gray | bw --prop print.frameSlidestrue \ --prop print.hiddenSlidesfalse \ --prop print.scaleToFitPapertrue对照 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:presentationPrPresentationPropertiesPart因此源码里有一组「按需创建」的辅助方法EnsurePrintingProperties()会先确保p:prnPr存在且按 schema 顺序插在p:showPr之前注释明确说明p:prnPr must precede p:showPr in schema order避免产生不合规的部件顺序。属性组四放映行为放映相关属性以show.为前缀对应p:showPrShowPropertiesofficecli set file.pptx / \ --prop show.loopfalse --prop show.narrationtrue \ --prop show.animationtrue --prop show.useTimingstrue属性键含义show.loop放映到末尾后自动循环重启show.narration放映时播放录制的旁白show.animation放映时播放动画show.useTimings放映时使用存储的幻灯片计时注意show.loop、show.narration、show.animation各有无前缀别名showloop、shownarration、showanimationshow.useTimings的别名是usetimings/show.usetimings见 presentation.json 的 aliases 字段。读取侧 PopulatePresentationSettings 只把「非默认值」写进Format字典——例如firstSlideNum仅在值 ≠ 1 时返回print.frameSlides等布尔开关仅在true时返回读取不到键即表示该开关保持默认。属性组五隐私开关officecli set file.pptx / --prop removePersonalInfofalseremovePersonalInfo别名removepersonalinfoonsave对应 OOXML 的RemovePersonalInfoOnSave开启后保存时会剥离作者 / 最后保存者等个人信息。示例中设为false表示保留文档属性。它是布尔类型schema 里enforcement均为report——即属性写入是尽力而为的遇到不支持的属性只报告警告而不中断流程这再次呼应了脚本不设set -e的容错设计。属性组六主题色板与正文字体空白 PPTX 自带 theme part所以主题编辑总能解析成功。示例脚本用fillaccent1填充标题形状因此重映射theme.color.accent1会直接改变标题栏颜色——渲染出的档会显示新的强调色而不是 Office 默认值officecli set file.pptx / \ --prop theme.color.accent11F6FEB --prop theme.color.accent2E3572A \ --prop theme.color.hlink0969DA officecli set file.pptx / \ --prop theme.font.major.latinGeorgia --prop theme.font.minor.latinCalibri完整的色板覆盖在脚本中实际写满了 12 个色槽 4 个字体槽officecli set file.pptx / \ --prop theme.color.dk11A1A1A --prop theme.color.lt1FFFFFF \ --prop theme.color.dk22F3640 --prop theme.color.lt2EEF1F5 \ --prop theme.color.accent11F6FEB --prop theme.color.accent2E3572A \ --prop theme.color.accent32DA44E --prop theme.color.accent4BF8700 \ --prop theme.color.accent58250DF --prop theme.color.accent61B7C83 \ --prop theme.color.hlink0969DA --prop theme.color.folHlink8250DF officecli set file.pptx / \ --prop theme.font.major.latinGeorgia --prop theme.font.minor.latinCalibri \ --prop theme.font.major.eastAsiaSimHei --prop theme.font.minor.eastAsiaSimSun主题属性的两套入口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的短键版本分组属性键元数据author、title、subject、keywords、description、category、lastModifiedBy、revisionNumber、extended.*幻灯片设置slideSize、slideWidth、slideHeight、firstSlideNum、rtl、compatMode打印print.what、print.colorMode、print.frameSlides、print.hiddenSlides、print.scaleToFitPaper放映show.loop、show.narration、show.animation、show.useTimings隐私removePersonalInfo主题theme.color.accent1..6/dk/lt/hlink/folHlink、theme.font.major/minor.latin/eastAsiaSet → 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 GeorgiaSDK 版脚本 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考