企业官网建设流程全解析

• 人工智能
• AI 应用
• AI 技能
• CLI
• MCP 服务

本文以 OfficeCLI 仓库中的examples/ppt/transitions/transitions-timing演示为骨架，系统讲解通过officecli set ... --prop transition=...控制幻灯片切换时序的四种方式：传统速度令牌（@spd）、Office 2010+ 毫秒时长（@dur）、自动推进（advanceTime）与点击推进开关（advanceClick）。读完本文，你将掌握如何在命令行中为任意幻灯片精确设置切换快慢、实现无点击自动放映，并理解这些属性在 OOXML 中的落盘形式与读取回显语义。

演示概览：三个文件协作生成 9 页演示文稿

transitions-timing演示由三个文件组成，它们共同演示全部四个时序旋钮：

• transitions-timing.sh —— Shell 脚本，生成一份 9 页的演示文稿，覆盖传统速度令牌、毫秒时长、自动推进与点击禁用；
• transitions-timing.pptx —— 脚本生成的 9 页成品文稿；
• transitions-timing.md —— 本文对应的说明文档，系统记录四个时序旋钮的用法。

9 页幻灯片的组织方式非常清晰，一页一个实验变量：

重新生成演示文稿

如果你希望在自己的环境中复现这份演示，只需在仓库的examples/ppt/transitions目录下执行：

cd examples/ppt/transitions bash transitions-timing.sh # → transitions-timing.pptx

脚本内部的核心流程是标准的 OfficeCLI 生命周期：officecli create新建空文稿 →officecli open打开 → 循环officecli add追加幻灯片与形状 →officecli set设置切换属性 →officecli close关闭 →officecli validate校验。值得注意的一点是，脚本刻意没有使用set -e：它会容忍前向兼容性的UNSUPPORTED props警告（此时 officecli 返回退出码 2），继续把完整文档构建出来，避免因个别属性不被旧版本识别而中断整个生成过程。

Slide 1 —— 封面（无切换）

封面页只承载标题文本，不设置任何切换效果，作为对照基线：

officecli add transitions-timing.pptx / --type slide officecli add transitions-timing.pptx /slide[1] --type shape \ --prop x=0 --prop y=0 --prop width=33.87cm --prop height=19.05cm \ --prop fill=1F3864 officecli add transitions-timing.pptx /slide[1] --type shape \ --prop text="Transition Timing" --prop size=40 --prop bold=true \ --prop color=FFFFFF --prop align=center \ --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=4cm

Slide 2–4 —— 传统速度令牌（PowerPoint 97+ 兼容）

速度令牌是 OOXML 中最古老的切换速度表达方式，通过CT_SlideTransition的@spd属性承载，PowerPoint 97 起即可识别。OfficeCLI 把它们编码为切换类型名后的-fast/-med/-slow后缀：

# fast — snappiest legacy speed officecli add transitions-timing.pptx / --type slide officecli add transitions-timing.pptx /slide[2] --type shape \ --prop x=0 --prop y=0 --prop width=33.87cm --prop height=19.05cm \ --prop fill=C00000 officecli add transitions-timing.pptx /slide[2] --type shape \ --prop text="fade-fast (legacy @spd)" --prop size=40 --prop bold=true \ --prop color=FFFFFF --prop align=center \ --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=4cm officecli set transitions-timing.pptx /slide[2] --prop transition=fade-fast # medium officecli set transitions-timing.pptx /slide[3] --prop transition=fade-med # slow officecli set transitions-timing.pptx /slide[4] --prop transition=fade-slow

可用特性：transition=fade-fast、fade-med（或fade-medium）、fade-slow。

从源码看，ApplyTransition解析切换字符串时按-切分令牌，将slow/medium/med/fast识别为速度并映射到TransitionSpeedValues枚举（PowerPointHandler.Animations.cs）。除内联后缀外，OfficeCLI 还提供了独立的transitionSpeed属性专门改写速度，接受slow、medium/med、fast三种取值，非法值会直接抛出参数异常。

读取回显时，get会把速度值以只读格式键transitionSpeed暴露出来（如fade-fast回显为transitionSpeed=fast）。

Slide 5–7 —— Office 2010+ 毫秒时长

从 Office 2010 起，切换时长可以用毫秒精确定制。OfficeCLI 将毫秒整数作为切换名后缀：

officecli set transitions-timing.pptx /slide[5] --prop transition=fade-500 # 0.5 s officecli set transitions-timing.pptx /slide[6] --prop transition=fade-1500 # 1.5 s officecli set transitions-timing.pptx /slide[7] --prop transition=fade-3000 # 3.0 s

可用特性：transition=fade-500、fade-1500、fade-3000（任意整数毫秒均可）。

速度与时长可以同时指定——在同一个组合令牌里同时给出速度后缀和毫秒数字是完全合法的：新一代 PowerPoint 会优先认@dur（毫秒），旧版本则回退使用@spd（速度令牌），实现了向下兼容。get会把毫秒值以只读格式键transitionDuration（毫秒整数）暴露出来。

源码中ApplyTransition对每个-分隔片段逐一判定：能解析为整数的片段记作durationMs，进而写入trans.Duration；对于位于mc:AlternateContent内的 morph/p14/p15 切换元素，则通过p14:dur命名空间属性写入（PowerPointHandler.Animations.cs）。读取端在 PowerPointHandler.Animations.cs 中同时匹配spd="..."与(?:p14:)?dur="(\d+)"两种写法，分别填充transitionSpeed与transitionDuration。

Slide 8 —— 自动推进（advanceTime=2000）

在放映模式下，这张幻灯片停留 2 秒后自动进入下一页，无需任何点击：

officecli add transitions-timing.pptx / --type slide officecli add transitions-timing.pptx /slide[8] --type shape \ --prop x=0 --prop y=0 --prop width=33.87cm --prop height=19.05cm \ --prop fill=BF8F00 officecli add transitions-timing.pptx /slide[8] --type shape \ --prop text="advanceTime=2000 (auto-advance after 2s)" --prop size=36 \ --prop bold=true --prop color=FFFFFF --prop align=center \ --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=4cm officecli set transitions-timing.pptx /slide[8] \ --prop transition=fade --prop advanceTime=2000

之后如需清除自动推进：officecli set ... --prop advanceTime=none

可用特性：advanceTime=<ms>、advanceTime=none（清除）。

从实现细节看，advanceTime在 OOXML 中对应CT_SlideTransition的@advTm属性，其类型是ST_PositiveUniversalMeasure（非负整数毫秒）。PowerPointHandler.Helpers.Transition.cs 中的SetAdvanceTime做了两层防御性校验：

• 拒绝负数：advanceTime=-1这类输入直接抛错，避免写出 PowerPoint 忽略或误渲染的畸形属性（与border.width/padding的非负约束保持一致）；
• 拒绝非数字：像later、5s这样的垃圾值会被当场拦截。原因是 PowerPoint 打开文件时遇到无法解析的属性会静默丢弃——如果没有这层校验，畸形值会带着“成功”的假象落盘。

none、空字符串与false三个值被统一视为“清除”哨兵（advanceTime=none即从 XML 中移除advTm属性）。此外，如果切换元素位于 morph 或 p14/p15（vortex、switch、flip、ripple、glitter、prism、doors 等）的mc:AlternateContent包装内，该方法会原地更新其中的 transition，而不是追加一个多余的裸<p:transition>兄弟节点——后者会被 PowerPoint 以 0x80070570 错误拒绝。

Slide 9 —— 禁用点击推进（advanceClick=false）

这张幻灯片只允许通过自动计时或方向键推进，点击鼠标无效：

officecli add transitions-timing.pptx / --type slide officecli add transitions-timing.pptx /slide[9] --type shape \ --prop x=0 --prop y=0 --prop width=33.87cm --prop height=19.05cm \ --prop fill=2E5C8A officecli add transitions-timing.pptx /slide[9] --type shape \ --prop text="advanceClick=false (no click advance)" --prop size=36 \ --prop bold=true --prop color=FFFFFF --prop align=center \ --prop x=2cm --prop y=7cm --prop width=29.87cm --prop height=4cm officecli set transitions-timing.pptx /slide[9] \ --prop transition=fade --prop advanceClick=false

可用特性：advanceClick=false（禁用点击推进）。

advanceClick对应 OOXML 的@advClick布尔属性。源码中的SetAdvanceClick遵循了一个重要约定：CT_SlideTransition @advClick的 schema 默认值是true，因此：

• 值为true时剥离属性，不写入冗余 XML；
• 值为false时写入advClick="0"。

这一“默认值不落盘”的策略同样保证了往返一致性（见下节）。与SetAdvanceTime一样，该方法也会正确识别并原地更新mc:AlternateContent包裹内的 morph/p14/p15 切换元素（PowerPointHandler.Helpers.Transition.cs）。

完整特性对照表

往返语义（Round-Trip Semantics）

OfficeCLI 的set→get遵循“默认值不冗余、显式值才落盘”的往返规则，四种旋钮行为一致：

• advanceClick=true→ XML 属性被剥离 → 读取时不输出advanceClick键（因为默认就是 true）；
• advanceClick=false→ XML 保留advClick="0"→ 读取时输出advanceClick=false；
• advanceTime=none→ XML 属性被移除 → 读取时不输出advanceTime键。

这些规则在 PowerPointHandler.Helpers.Transition.cs 的实现中都能找到对应逻辑：剥离属性对应RemoveAttribute("advClick", "")/AdvanceOnClick = null，显式 false 对应SetAttribute(..., "0")/AdvanceOnClick = false，而advTm的清除仅在已存在 transition 元素时才移除属性，不会为了删属性而凭空合成一个空的<p:transition/>。

属性分派：一条命令背后的完整调用链

officecli set ... --prop transition=... --prop advanceTime=2000 --prop advanceClick=false这类复合命令在 PowerPointHandler.Set.Slide.cs 中按属性键逐一分派：

• transition→ApplyTransition（解析组合令牌，支持方向/速度/时长/thru-black修饰符，none/false清除整个切换元素，morph 前缀自动处理）；
• transitionspeed→ApplyTransitionSpeed（独立改写@spd）；
• advancetime/advanceaftertime→SetAdvanceTime；
• advanceclick/advanceonclick→SetAdvanceClick。

在批量（batch）场景下，PptxBatchEmitter.cs 的白名单允许transition、transitionSpeed、transitionDuration、advanceTime、advanceClick这组键通过过滤器，意味着这五个旋钮同样可以在批量模式与 SDK 的doc.batch工作流中使用。

检查生成的文件

脚本生成完成后，可以用query与get反向验证每一页的切换属性：

officecli query transitions-timing.pptx slide officecli get transitions-timing.pptx /slide[2] officecli get transitions-timing.pptx /slide[8] officecli get transitions-timing.pptx /slide[9]

get /slide[2]应回显transitionSpeed（速度令牌页），/slide[8]应回显advanceTime=2000，/slide[9]应回显advanceClick=false，从而直观验证前文所述的往返语义。

相关文档

• transitions-basic.md —— 基础切换设置，含transition=none清除整个 transition 元素的用法；
• 同目录下还提供了transitions-bands、transitions-directional、transitions-dynamic、transitions-modern、transitions-morph、transitions-random、transitions-shapes等针对不同切换家族与效果的配套演示，可对照学习各类切换类型与本文时序旋钮的组合使用。

• 人工智能
• AI 应用
• AI 技能
• CLI
• MCP 服务