# @betteroffice/pptx 中文文档

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

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

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

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

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

- 包体积（解压后）：6.7 MB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-19T18:27:33.434Z
- 最新版本发布：2026-10-27T11:28:38.352Z
- 近 30 天下载量：365226（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

PowerPoint-忠实的PPTX编辑器和取景器核心:全OOXML忠心,实时人类+AI代理协作. 无框架(Rust/Wasm).

## 安装

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

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

## README

# @ betteroffice/ pptx (英语)

无框架的PPTX通过Rust/WebAssembly引擎解析,编辑,渲染并保存. 使用它用自己的接口构建演示文稿查看器或编辑器.

## 安装

```bash
bun add @betteroffice/pptx
```

无对等依存.

## 使用量

将演示文稿的第一个幻灯片映入浏览器画布 :

```ts
import {
  initWasm,
  openPresentation,
  paintSlide,
  sizeCanvasForSlide,
} from '@betteroffice/pptx';

export async function renderFirstSlide(
  bytes: Uint8Array,
  fontBytes: Uint8Array,
  canvas: HTMLCanvasElement,
) {
  await initWasm();
  const deck = openPresentation(bytes, {
    fonts: [{ family: 'My Sans', bytes: fontBytes }],
  });
  try {
    const frame = deck.layoutSlide(0);
    const dpr = window.devicePixelRatio;
    sizeCanvasForSlide(canvas, frame, dpr);
    const context = canvas.getContext('2d');
    if (!context) throw new Error('Canvas 2D is unavailable');
    await paintSlide(context, frame, dpr);
  } finally {
    deck.dispose();
  }
}
```

`fontBytes` 持有 TTF 或 OTF 文件, 例如从您的服务器获取或装入 `loadBundledFontBytes` 从 [`@betteroffice/fonts`](https://www.npmjs.com/package/@betteroffice/fonts)。包含图像的幻灯片也需要图像解析器,描述 见下文。 反应编辑器在 [`@betteroffice/pptx-react`](https://www.npmjs.com/package/@betteroffice/pptx-react) 管理渲染和用户输入.

## 入境点

以下所有入境点均从 `@betteroffice/pptx`。 。 。 .

| 进入点 | 说明 |
| --- | --- |
| `initWasm(input?)` | 在打开或检查文件前初始化 Web Assembly 。 浏览器可以省略输入;节点主机可以通过WASM字节. |
| `openPresentation(bytes, options?)` | 打开同步 `PresentationHandle` 用于读取、编辑、布局和保存. |
| `inspectPresentation(bytes, options?)` | 在不打开编辑手柄的情况下检查解析内容; `includeMedia: false` 省略媒体. |
| `sizeCanvasForSlide(canvas, frame, dpr, scale?)` | 设置画布支持维度和 CSS 大小用于幻灯片 . |
| `paintSlide(context, frame, dpr?, scale?, options?)` | 在画布上同步绘制显示列表 . |
| `slideToPng(frame, options?)` | 返回一个巴布亚新几内亚 `Blob` 同步使用浏览器画布后端. |
| `exportPptxStructured(bytes, options?)` | 将结构化内容同步导出, 不使用字体或 DOM . |
| `exportPptxMarkdown(bytes, options?)` | 导出 Markdown 和源锁定同步 . |
| `renderPptxMarkdown(content, options?)` | 作为Markdown的同步结构化内容. |

`openPresentationSession(bytes, options?)` 从 `@betteroffice/pptx/worker` 打开一个实验同步 工人会议.

`openPresentation` 接受 `fonts`, (中文(简体) ), `fallbackFonts`, (中文(简体) ), `clientId`,以及 `initialUpdate`后退字体 提供从跑步中消失的格言 从协作更新打开时,保留 源文件字节用来种子它,以便手柄可以保存.

核心直接拥有的手柄是同步的. React 编辑器在 Web Worker 中运行引擎 并暴露了承诺的回报 读取和出口.

## 布局和渲染

`layoutSlide(index)` 使用基于零的幻灯片索引. `snapshot()` 返回甲板模型,以及 `layouts()` 列表布局编号和名称 `insertSlide`。 。 。 . `duplicateSlide` 复制幻灯片内容和 发言者注意到,不包括评论。 形状坐标使用EMU(英语:Metric Units,每英寸914,400;文本抵消使用) UTF-16 代码单元.

对于嵌入式图像, 通过 `paintSlide` 选项对象 `resolveImage`,函数映射 资产 ID 到画布图像源 或对它的承诺 。 它会回来 `null` 用于不可用图像. `slideToPng` 接受相同的解析器和可选 `scale`。 。 。 .

## 储蓄和所有权

`save()` 返回已应用编辑的 PPTX 字节;未操作的幻灯片保留其源部分字节. 打电话 `dispose()` 当完成一个手柄. `fork()` 创建必须拥有的独立副本 亦将作处置.

## 代理提案

`propose(agentId, note, edits)` 级编辑而不修改承诺的甲板。 使用 `listProposals`, (中文(简体) ), `previewProposal`,以及 `layoutProposalSlide` 然后检查他们 `acceptProposal` 或者说 `rejectProposal`。 。 。 . 接受以一个倒数步骤适用集团;待决提案留在公开会议上.

`layoutProposalDiffSlide` 返回审查框架,并 `textChanges`; 将两者传递给 `paintSlide` 显示 插入和删除。 审查框架载有临时文本,仅供显示. 如果目标改变, 接受投放 `StaleProposalError`; 在选择前检查新预览 `acceptProposal(id, { force: true })`。 。 。 .

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

`readContent`, (中文(简体) ), `findText`, (中文(简体) ), `validateEdits`,以及 `applyEdits` 支持根据会话版本编辑. 见 [在版本检查的批次中编辑 PPTX](https://docs.betteroffice.dev/docs/javascript#edit-pptx-in-version-checked-batches) 对于请求形状、原子性、拒绝和限制.

## 有结构的出口

`exportStructured` 财务报告和审定财务报表 `exportMarkdown` 读取承诺状态; 无头导出接受文件字节. 见 [PPTX 结构导出](https://docs.betteroffice.dev/docs/javascript#pptx-structured-export) 选择、锚地、诊断和截断.

## 评论和历史

`comments()` 列出评论意见. `setCommentFlavor` 选择 `legacy` 或者说 `modern` 仅在该列表是 空无相. `replyToComment` 支持两种口味; `setCommentStatus` 需要现代评论. `addComment` 带走作者的 名称、文本和呼叫者提供 `created` 时间戳. `setCommentPosition` 使用 安全整数 EMU 坐标; 回复分享其根的位置 .

`setUndoCaptureMode('manual')` 组跟踪本地编辑直到 `addUndoBoundary()`· ; `undoCaptureMode()` 读取当前模式. `undo()` 财务报告和审定财务报表 `redo()` 导航历史. `anchorCaret(storyId, index)` 创建跟踪编辑的锚; `resolveCaretAnchor` 返回其 (单位:千美元) `null` 如果它的故事不再存在.

## 协作

`PresentationHandle` 执行复制界面 `CollaborationProvider` 从 `@betteroffice/pptx/collaboration`。 。 。 . 见 [协作指南](https://docs.betteroffice.dev/docs/collaboration) 用于运输, 共享种子、存在和连接生命周期.

## 操作简介

`layoutSlideProfiled`, (中文(简体) ), `insertTextProfiled`,以及 `undoProfiled` 揭露出发动机舞台时间. 见 [操作简介](https://docs.betteroffice.dev/docs/javascript#operation-profiles) 结果 形状和测量指导.

## 文档

-   [Java脚本指南](https://docs.betteroffice.dev/docs/javascript)
-   [协作指南](https://docs.betteroffice.dev/docs/collaboration)
-   [软件包指南](https://docs.betteroffice.dev/docs/packages)
-   [反应编辑器 : @ betteroffice/pptx- react](https://www.npmjs.com/package/@betteroffice/pptx-react)
-   [字体 : @ betteroffice/ fonts](https://www.npmjs.com/package/@betteroffice/fonts)
-   [仓库](https://github.com/openooxml/betteroffice)

## 常见问题

### @betteroffice/pptx 是什么？

PowerPoint-忠实的PPTX编辑器和取景器核心:全OOXML忠心,实时人类\+AI代理协作\. 无框架\(Rust/Wasm\)\.

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

在项目目录运行 npm install @betteroffice/pptx，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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