PresentationEditor

PresentationEditor 使用类型化场景图保存幻灯片，只在编辑文本框时挂载 TipTap。中文等输入法的预编辑文字在组合期间只保留于本地，onChange 只接收最终确认的内容；编辑器快捷键也会在组合输入期间让输入法优先处理键盘事件。

属性

属性	类型	必填	默认值	说明
`content`	`PresentationContent`	是	—	受控演示文稿内容。
`onChange`	`(content: PresentationContent) => void`	是	—	返回完整的新演示文稿。
`collaboration`	`OfficeCollaborationSession`	否	无	使用已初始化的 Yjs Presentation 作为规范内容。
`presence`	`OfficeCollaborationPresence`	否	无	发布幻灯片与对象选择、显示远端对象框并支持参与者导航；必须与 `collaboration` 是同一个会话。
`preview`	`boolean`	否	`false`	只读演示文稿。
`saveStatus`	`string`	否	`'Saved automatically'`	由宿主管理的保存状态。
`fileActions`	`readonly OfficeFileAction[]`	否	`[]`	宿主文件操作。
`kernelWasmUrl`	`string`	否	内置内核	吸附、对齐与几何计算内核地址。
`onAgentRequest`	`(request: EditorAgentRequest) => void \| Promise<void>`	否	—	把幻灯片或对象上下文发送给宿主 AI 流程。
`onStartSlideshow`	`() => void`	否	—	内置放映开始后通知宿主。
`theme`	`'light' \| 'dark' \| 'system'`	否	`'system'`	配色模式。

内容结构

字段	类型	说明
`type`	`'presentation'`	内容类型标识。
`slides`	`WorkSlide[]`	幻灯片、元素、备注、批注、切换效果与入场动画。
`width`, `height`	`number`	演示文稿画布尺寸。
`masters`	`WorkPresentationMaster[]`	母版背景与元素。
`layouts`	`WorkPresentationLayout[]`	关联母版的版式、占位符与继承元素。

稳定的宿主接入应使用 fileActions、onAgentRequest 和 onStartSlideshow。内部场景命令运行时不是公共 Extension API。

入场动画

WorkSlide.animations 是单张幻灯片的规范动画顺序。每条记录通过稳定 ID 指向当前幻灯片中的一个对象。一个对象最多拥有一条可编辑入场动画，每张幻灯片最多保存 256 条动画记录。

type WorkSlideAnimationEffect = 'appear' | 'fade' | 'fly-in' | 'zoom';
type WorkSlideAnimationTrigger =
  | 'on-click'
  | 'with-previous'
  | 'after-previous';
type WorkSlideAnimationDirection = 'left' | 'right' | 'up' | 'down';

interface WorkSlideAnimation {
  id: string;
  elementId: string;
  effect: WorkSlideAnimationEffect;
  trigger: WorkSlideAnimationTrigger;
  durationMs: number;
  delayMs: number;
  direction?: WorkSlideAnimationDirection;
}

const slide = {
  id: 'launch',
  name: '发布计划',
  background: '#ffffff',
  elements: [
    {
      id: 'headline',
      type: 'text',
      x: 8,
      y: 10,
      width: 80,
      height: 16,
      text: '发布计划',
      fontSize: 34,
      color: '#111827',
      fill: 'transparent',
      bold: true,
      align: 'left',
    },
  ],
  animations: [
    {
      id: 'headline-entrance',
      elementId: 'headline',
      effect: 'fade',
      trigger: 'on-click',
      durationMs: 600,
      delayMs: 100,
    },
  ],
};

选择对象并打开功能区的动画选项卡，即可设置或删除效果，选择触发方式，编辑持续时间和延迟，设置飞入方向，调整前后顺序，并预览当前幻灯片。持续时间会规范到 100–60,000 毫秒，延迟会规范到 0–60,000 毫秒。每次编辑只产生一个受控 onChange 值和一条撤销记录。删除对象会同时清理动画；复制对象或幻灯片时会创建新的对象与动画 ID，并保持二者的目标映射。协作层只接受数量受限、动画 ID 唯一、目标对象有效、每个对象只有一个效果且计时已经规范化的动画序列。

触发与放映语义

触发方式	放映行为
`on-click`	开始一个新的单击提示。放映会先消费当前提示，再切换到下一张幻灯片。
`with-previous`	从上一项的开始时间加上自身延迟后开始。
`after-previous`	从上一项的结束时间加上自身延迟后开始。

如果第一项使用 with-previous 或 after-previous，第一组提示会在打开幻灯片时自动开始。观众模式和演讲者模式会呈现相同的待播放、播放中和已完成对象状态，因此切换视图不会跳过对象。在 prefers-reduced-motion: reduce 环境中，对象会直接显示而不播放装饰性运动，但提示顺序保持不变。

原生 PPTX 边界

受支持的子集会导出为原生 PresentationML 计时树。导入时，计时目标的 cNvPr 形状 ID 会映射回浏览器中的稳定对象 ID；再次导出并重新打开后，效果、顺序、触发方式、持续时间、延迟和飞入方向都保持不变。带文字的动画形状仍是一个 PPTX 对象，分组中的动画对象也会保留有效计时目标。

导入边界是明确且受限的。强调和退出效果、动作路径、不支持的入场预设、同一对象上的重复效果、缺失或歧义目标、格式错误的计时以及伪造命名空间的计时树都不会成为可编辑记录；兼容性诊断会说明跳过或规范化的内容。导出只写入受支持的可编辑序列，不承诺无损保留源文件中不受支持的计时树。音频、视频、排练、录制、点击指定对象触发以及更完整的动画目录仍属于后续工作。

在 Playground 中打开最新能力 → 入场动画，可以查看四种效果和三种触发方式，通过动画选项卡编辑顺序，并在内置放映中验证。模型、命令、组件、协作、剪贴板、放映和原生 PPTX 重新打开测试共同保证公开说明与实现保持同步。

实时协作

传入已初始化的 presentation 协作会话后，Yjs 场景图成为规范内容。幻灯片、母版和版式的顺序与 ID 记录分开保存，每个容器拥有按顺序排列的 ID 对象。只追加的创建声明会拒绝同一 ID 对应不同对象；删除会写入持久墓碑并永久保留该 ID。本地撤销只跟踪当前绑定产生的操作，presence 用于发布当前幻灯片与对象选择，并显示远端对象框。

Rust、CLI、MCP 与 A3S Code 提供封闭的 presentation-create-element、 presentation-update-element、presentation-move-element 和 presentation-delete-element。创建可在一个仍然有效的稳定对象之后插入完整对象。更新会比较完整的预期值、当前值和新值，只写入发生变化的顶层字段，因此无关的几何、文本或样式并发修改可以合并，同一字段的过期修改会在产生持久更新前失败。移动使用观察到的稳定前驱和目标前驱，不使用数组下标；null 表示对象顺序数组第一项。对象已经位于目标位置时保持幂等，否则源位置过期或锚点失效会原子失败；成功时只修改该对象自己的顺序项。删除要求完整对象精确匹配并写入墓碑。四种操作都不允许改变对象的 id 或 type。

内置放映

观众模式与演讲者模式共用同一组导航控件。方向键和 Page Up / Page Down 切换幻灯片，空格前进，Home 与 End 跳到首尾，Escape 退出。焦点位于放映按钮时这些快捷键仍然有效，输入框和可编辑内容则保留正常键盘行为。

演讲者模式显示当前页、下一页提示、演讲者备注和可暂停计时器。计时器属于同一次放映，切换观众与演讲者模式不会归零。手机宽度下，当前幻灯片保持全宽，下一页缩为标题提示，备注可以独立滚动，导航控件仍然可用。

#PresentationEditor

#属性

#内容结构

#入场动画

#触发与放映语义

#原生 PPTX 边界

#实时协作

#内置放映