# @betteroffice/pptx-react 中文文档

规范地址：https://npmcn.com/package/%40betteroffice/pptx-react/

版本：0\.5\.1
npm 元数据更新时间：2026-10-27T11:28:04.404Z
中文译文更新时间：2026-11-08T00:24:22.832Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40betteroffice/pptx-react
原文对照：https://npmcn.com/package/%40betteroffice/pptx-react/?lang=original
项目主页：https://betteroffice.dev/
源码仓库：https://github.com/openooxml/betteroffice

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：457 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-07-19T18:27:38.749Z
- 最新版本发布：2026-10-27T11:28:03.518Z
- 近 30 天下载量：96570（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

PowerPoint-flish React PPTX编辑和取景器:全OOXML忠心,实时人类+AI代理协作.

## 安装

```sh
npm install @betteroffice/pptx-react
```

也可以使用：`pnpm add @betteroffice/pptx-react`、`yarn add @betteroffice/pptx-react`、`bun add @betteroffice/pptx-react`

## README

# @ betteroffice/ pptx 反应

使用幻灯片画布、幻灯片条、格式化工具栏和键盘编辑来反应演示文稿编辑器. 引擎默认在Web Worker中运行,承诺回放读取并输出.

## 安装

```bash
bun add @betteroffice/pptx-react react react-dom
```

同伴依赖性 : `react` 财务报告和审定财务报表 `react-dom`,18或19版本;PPTX核心是一个包依赖.

## 使用量

```tsx
import { PptxEditor } from '@betteroffice/pptx-react';

export function Presentation({ file, fontBytes }: {
  file: Uint8Array;
  fontBytes: Uint8Array;
}) {
  return (
    <div style={{ height: 720 }}>
      <PptxEditor file={file} fonts={[{ family: 'My Sans', bytes: fontBytes }]} />
    </div>
  );
}
```

`fonts` 需要时间。 每个条目是一个姓氏和一个TTF或OTF文件的字节,例如: 从您的服务器获取或装入 `loadBundledFontBytes` 从 [`@betteroffice/fonts`](https://www.npmjs.com/package/@betteroffice/fonts)。 。 。 .

## 关键选项

导出 `PptxAsyncEditorProps` 类型描述默认编辑器道具。 下面所有的道具都是 选项除外 `fonts`。 。 。 .

| 道具 | 类型 | 说明 |
| --- | --- | --- |
| `file` | `Uint8Array | ArrayBuffer` | 要打开的演示字节 . |
| `fonts` | `ReadonlyArray<PptxFontFace>` | 字体家族和文字布局的字节 . |
| `readOnly` | `boolean` | 屏蔽用户编辑,同时保留导航和选择. |
| `initialSlide` | `number` | 最初滑行,编号从1并被夹入甲板. |
| `fileName` | `string` | 下载名称; 默认为 `presentation.pptx`。 。 。 . |
| `className` | `string` | 编辑容器的课. |
| `style` | `CSSProperties` | 编辑器容器的内置样式. |
| `initialZoom` | `number` | 初始缩放比例从0.1缩放到5;省略后,幻灯片适合舞台. |
| `loadingIndicator` | `ReactNode` | 演示文稿打开时显示 . |
| `i18n` | `PptxAsyncEditorProps['i18n']` | UI 翻译自 `@betteroffice/pptx-i18n`。 。 。 . |
| `onReady` | `(api: PptxAsyncEditorApi) => void | (() => void)` | 接收 Aync API; 可选择返回清理 . |
| `onChange` | `(snapshot: DeckSnapshot) => void` | 更改后接收甲板快照 . |
| `onDocumentChange` | `(change: PptxDocumentChange) => void` | 接收 `{ version }` 在完成编辑后 `onChange`。 。 。 . |
| `onError` | `(error: Error) => void` | 接收加载和编辑错误 . |
| `onSave` | `(bytes: Uint8Array) => void` | 接收已保存的字节; 省略, 保存下载文件 . |
| `downloadOnSave` | `boolean` | 是否保存同时下载副本;默认为 `true` 只有没有 `onSave`。 。 。 . |
| `onSaveRequest` | `() => boolean | void | Promise<boolean | void>` | 截取工具栏和键盘保存; 返回 `true` 继续. |
| `toolbar` | `ReactNode` | 替换内置控制; `null` 把他们带走. |
| `showToolbar` | `boolean` | 显示工具栏区域;默认为 `true`。 。 。 . |
| `collaboration` | `PptxAsyncCollaborationOptions` | 共享种子、复制回调和存在选项. |
| `plugins` | `readonly PptxPlugin[]` | 主机拥有的工具,面板,并覆盖. |
| `pluginGrants` | `Readonly<Record<string, PptxPluginGrant>>` | 由插件 ID 键入权限 . |
| `onPluginError` | `(error: PptxPluginError) => void` | 接收孤立插件失败 . |

`PptxFontFace` 财务报告和审定财务报表 `DeckSnapshot` 导出于 `@betteroffice/pptx`; 编辑器和插件类型 导出者 `@betteroffice/pptx-react`。 。 。 . `ReactNode` 是反应类型.

折旧: `legacySyncApi` 将同步 API 保留在行进引擎上,并被去除为 6.6.0; 省略它以使用默认的 Aync 编辑器 。 还省略了被腐烂的 `experimentalWorkerOpen` 道具 (英语).

## 编辑器 API

`onReady` 接收 `PptxAsyncEditorApi`等待时 `save()` 将演示文稿序列化(`saveAsync()` 是一个 并等待着 `handleAsync()` 用于同步文档访问,包括 `snapshot()`, (中文(简体) ), `exportStructured()`,以及 `exportMarkdown()`。通过访问读取和导出对象返回承诺;API还 `exportStructured()` 财务报告和审定财务报表 `exportMarkdown()` 直接说 工作不能违背其输入或 目标拒绝方式 `PptxCommandAdmissionError`。 。 。 .

`flushPendingInput()` 等待被接受的输入. `goToSlide(slide)` 财务报告和审定财务报表 `selectText(target)` 返回时 承诺; 幻灯片数字基于1, 文本抵消使用UTF-16. `getPositionAtPoint(clientX, clientY)` 同步返回当前幻灯片上的命中值或 `null` 外部幻灯片内容.

在冲出输入的工作流程前完成指针手势. 把API绑在挂载上 演示文稿; 替换或关闭文档使其访问无效.

## 保存

工具栏和 Ctrl/Cmd+S 引用 `onSaveRequest` 在序列化之前。 正在等待结果: `true` 继续保存,同时 `false` 或者说 `void` 处理或取消请求。 如果储蓄继续, `onSave` 接收字节,编辑器使用 `fileName` 何时 `downloadOnSave` 实值 `true` (默认没有 `onSave`) (中文(简体) ).

通话 `save()` 直接返回字节,而不引用那些保存回调 .

## 工具栏

工具栏组成 API 是实验性. `api.commands` 由内置控制器共享 主机工具栏部件。 将控件替换为 `toolbar`,或以 `showToolbar={false}`。 。 。 . 见 [编写 PPTX 工具栏](https://docs.betteroffice.dev/docs/javascript#compose-the-pptx-toolbar) 用于组成、外部控制、指挥状态和外溢.

折旧: 丙基 `EditorToolbar` 财务报告和审定财务报表 `Toolbar` 使用被命令模式控制所取代; 使用情况 `EditorToolbar` 与 `mode="commands"`。 。 。 .

## 插件

`definePptxPlugin` 定义已安装的工具 `plugins`,并获得 `pluginGrants`。这个插件 API 是实验性的,可能会改变小版本. 见 [主机 PPTX 编辑器插件](https://docs.betteroffice.dev/docs/javascript#host-pptx-editor-plugins) 用于面板、叠加、寿命周期、权限和错误处理.

## 版本已检查的编辑批次

`readContent`, (中文(简体) ), `findText`, (中文(简体) ), `validateEdits`,以及 `applyEdits` aPI 返回承诺并运行 在等待输入后。 见 [在版本检查的批次中编辑 PPTX](https://docs.betteroffice.dev/docs/javascript#edit-pptx-in-version-checked-batches) 要求、原子性和打字拒绝.

## B. 审查代理人的建议

使用返回的访问 `handleAsync()` 调用 `propose`,然后等待着 `refreshProposals()`。 。 。 . 有待提出的提案出现在画布上,有文字差异、形状界限和发音. 审查控制预览、接受或拒绝一组;接受将产生一个倒数步骤.

逃脱或 **编辑幻灯片** 退出审查模式。 已承诺保存、 PNG 导出和显示模式使用 内容。 待决提案留在会场;接受的编辑保存并同步.

## 协作

过 `collaboration` 共同编辑甲板; `onReplica` 接收同步复制件或 `null` 关于清理. 设定 `roomId` 当切换室和种子对等者从相同的更新。 奥米 `clientId` 生成 每次开幕会各一个. 见 [协作指南](https://docs.betteroffice.dev/docs/collaboration) 运输设施.

## 浏览器集成

在浏览器中以明确高度的容器上载编辑器. 构成《公约》 服务器应该将编辑器客户端加载到服务器渲染被禁用。 见 [托管](https://docs.betteroffice.dev/docs/migrating-to-0-5#hosting) 页:1 工人,块和CSP需要.

## 文档

-   [Java脚本指南](https://docs.betteroffice.dev/docs/javascript)
-   [协作指南](https://docs.betteroffice.dev/docs/collaboration)
-   [软件包指南](https://docs.betteroffice.dev/docs/packages)
-   [PPTX 核心 : @ betteroffice/ pptx](https://www.npmjs.com/package/@betteroffice/pptx)
-   [用户界面翻译: @ betteroffice/pptx-i18n](https://www.npmjs.com/package/@betteroffice/pptx-i18n)
-   [仓库](https://github.com/openooxml/betteroffice)

## 常见问题

### @betteroffice/pptx-react 是什么？

PowerPoint-flish React PPTX编辑和取景器:全OOXML忠心,实时人类\+AI代理协作\.

### 如何安装 @betteroffice/pptx-react？

在项目目录运行 npm install @betteroffice/pptx-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @betteroffice/pptx-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @betteroffice/pptx-react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @betteroffice/pptx-react 可以商用吗？

@betteroffice/pptx-react 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @betteroffice/pptx-react 的下载量有多少？

根据 npm 官方下载统计，@betteroffice/pptx-react 在 2026/10/08 – 2026/11/06 这 30 天内被下载 96,570 次，日均约 3,219 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @betteroffice/pptx-react 还在维护吗？

最新版本 0\.5\.1 发布于 2026/10/27（12 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/07/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。