跳到主要内容
Office Open

PPTX

动画效果

为形状添加进入、退出、强调和运动路径动画

为形状添加动画效果，控制它们在演示文稿中的出现和行为方式。

#基本用法

动画位于幻灯片级别，不在形状上设置 —— XSD 中 CT_Shape 没有子级 timing 元素。每张幻灯片提供 animations 数组，其每一项携带 shapeId（目标形状的 cNvPr id）以及内联的动画字段：

ts
import { generatePresentation } from "@office-open/pptx";
JSON
{
  "slides": [
    {
      "children": [
        {
          "shape": {
            "id": 2,
            "x": "1.3cm",
            "y": "1.3cm",
            "width": "15.9cm",
            "height": "6.6cm",
            "textBody": { "text": "动画形状" }
          }
        }
      ],
      "animations": [{ "shapeId": 2, "type": "fade", "duration": 800 }]
    }
  ]
}

animations 的每一项把 shapeId 与动画预设字段配对。shapeId 与目标形状 NonVisualDrawingProperties（cNvPr id）上的 id 一致，由 shape.id 指定；其余字段即下面各小节记录的预设。

#按名称指定目标

新建文档可以改用 shapeName 引用目标——库在编译期把它解析为目标形状的 cNvPr id，作用域是同一张幻灯片上的形状：

json
{
  "children": [
    {
      "shape": {
        "name": "Hero",
        "x": "1.3cm",
        "y": "1.3cm",
        "width": "15.9cm",
        "height": "6.6cm",
        "textBody": {
          "text": "命名形状"
        }
      }
    }
  ],
  "animations": [
    {
      "shapeName": "Hero",
      "type": "fade",
      "duration": 800
    }
  ]
}

shapeName 是创作通道：id 重新编号时名称保持稳定；名称未知或重复会在编译期 抛错，而不是发出悬空的 spTgt @spid。shapeId 是往返通道（解析来源保留源 id）；两者同时给出时以 shapeId 为准。

#动画类型

#进入动画（class: "entrance"，默认类别）

类型描述支持的方向
appear立即出现—
fade淡入—
fly从边缘飞入left、right、up、down
wipe从边缘擦入left、right、up、down
dissolve溶解出现—
split分裂出现horizontal、vertical
blinds百叶窗效果horizontal、vertical
checker棋盘效果horizontal、vertical
randomBars随机条纹horizontal、vertical
wheel轮辐效果—
zoom缩放出现—
cover从边缘覆盖left、right、up、down
push从边缘推入left、right、up、down
strips从角落条状出现left、right、up、down

#退出动画（class: "exit"）

与进入动画相同的类型，添加 class: "exit"：

json
[
  { "shapeName": "Title", "type": "fade", "class": "exit", "duration": 800 },
  { "shapeName": "Title", "type": "fly", "class": "exit", "direction": "right" }
]

#强调动画（class: "emphasis"）

emphasisType描述
growShrink放大后缩小
spin完整旋转
colorChange变色（需指定 color）
transparency半透明闪烁
boldFlash加粗闪烁
wave波浪效果
pulse脉冲效果
growWithTurn旋转放大
json
[
  { "shapeName": "Title", "class": "emphasis", "emphasisType": "growShrink", "duration": 800 },
  { "shapeName": "Title", "class": "emphasis", "emphasisType": "spin", "duration": 1000 },
  { "shapeName": "Title", "class": "emphasis", "emphasisType": "colorChange", "color": "FF0000" }
]

#运动路径动画

pathType描述
line直线
arc弧线
circle圆形路径
curveS 形曲线
figureEight8 字形
bounce弹跳路径
loop环形路径
customPath自定义 SVG 路径（需指定 path）
json
[
  { "shapeName": "Title", "pathType": "circle", "duration": 1500 },
  {
    "shapeName": "Title",
    "pathType": "customPath",
    "path": "M 0 0 L 100 0 L 100 100 L 0 100 Z",
    "duration": 1200
  }
]

#媒体播放（class: "mediaCall"）

通过 mediaType 触发音视频播放（目标是 { video } / { audio } 子项的媒体 框），shapeId 必须指向该媒体框：

json
[
  {
    "shapeName": "Video 1",
    "class": "mediaCall",
    "mediaType": "playVideo",
    "fullScreen": true,
    "showWhenStopped": true
  },
  {
    "shapeName": "Video 1",
    "class": "mediaCall",
    "mediaType": "playAudio",
    "volume": 80,
    "mute": false
  }
]
属性类型说明
mediaType"playAudio" | "playVideo" | "play"媒体动画类型
isNarrationboolean媒体为旁白
fullScreenboolean全屏播放视频
volumenumber音量
muteboolean静音
showWhenStoppedboolean停止后保持媒体框可见

#动画选项

属性类型默认值描述
typeAnimationType"appear"动画预设类型
class"entrance" | "exit" | "emphasis" | "mediaCall""entrance"动画类别
durationnumber500持续时间（毫秒）
delaynumber0开始前延迟（毫秒）
triggerAnimationTrigger"onClick"触发方式
directionAnimationDirection—动画方向
emphasisTypeEmphasisType—强调动画类型（class="emphasis"）
pathTypePathAnimationType—运动路径类型
pathstring—自定义 SVG 路径字符串
speednumber—速度倍率
repeatCountnumber—重复次数
autoReversebooleanfalse完成后自动反转
colorstring—colorChange 的目标颜色
pathEditMode"relative" | "fixed" | "none"—运动路径编辑模式
rotationAnglenumber—运动路径旋转角（六万分之一度，p:animRot @rAng；原值透传）
motionFrom{ x: string; y: string }—运动路径起点
motionRotationCenter{ x: string; y: string }—运动旋转中心
zoomContentsbooleanfalse缩放动画时缩放内容

#触发模式

json
[
  { "shapeName": "Title", "type": "fade", "trigger": "onClick" },
  { "shapeName": "Title", "type": "fade", "trigger": "withPrevious" },
  { "shapeName": "Title", "type": "fade", "trigger": "afterPrevious" }
]