# @extend-ai/react-pptx 中文文档

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

版本：0\.6\.0
npm 元数据更新时间：2026-11-13T15:51:08.695Z
中文译文更新时间：2026-11-14T05:51:19.852Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：17.4 MB，34 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.2 \<20，react-dom \>=18\.2 \<20
- 首次发布：2026-07-16T16:44:46.738Z
- 最新版本发布：2026-11-13T15:51:08.306Z
- 近 30 天下载量：444747（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

PowerPoint(PPTX,PPT)和OpenDocument(ODP,ODG)演示文稿的浏览器-本土,虚拟化的回声查看器

## 安装

```sh
npm install @extend-ai/react-pptx
```

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

## README

# @ extend-ai/ react- pptx

[![npm version](https://img.shields.io/npm/v/@extend-ai/react-pptx.svg)](https://www.npmjs.com/package/@extend-ai/react-pptx)

浏览器- 本地PowerPoint 查看反应, 与 **实验 OpenDocument 支持**。 。 。 .

```bash
npm install @extend-ai/react-pptx
```

React和React DOM是React应用程序中已经存在的同级依赖关系.

## 主要 API

-   `ReactPptxViewer` 制作 URL, `Blob`, (中文(简体) ), `ArrayBuffer`, (中文(简体) ), `Uint8Array`,解析演示文稿,或规范文件.
-   `parsePresentation` 进行本地解析,并返回查看器制作的同样规范的模型.
-   `initWasm` 财务报告和审定财务报表 `setWasmSource` 支持急切地初始化和自定义Wasm/CDN主机.
-   `PptxViewerController` 提供导航,缩放,适中,文本搜索,突出显示,模式访问, 并缩略图渲染.

导入 `@extend-ai/react-pptx/styles.css` 与组件并排;样式表作为 单独的软件包资产。 解析和渲染为客户端; 导入 JavaScript 包 在安保部门安全期间.

不明或已退化的内容通过 `onWarning` 财务报告和审定财务报表 `showDiagnostics` 相当 而不是默默地被清除.

## 响应缩放

收视者接受的对应缩放形状与 `@extend-ai/react-docx`数字值为 百分比,而 `automatic`, (中文(简体) ), `fit-page`,以及 `fit-width` 继续活动,随着视图的改变. 例如,共享的API可以表达为:

```tsx
<Viewer defaultZoom="fit-width" />
```

使用此软件包的组件和所需的源, 使用 :

```tsx
<ReactPptxViewer
  source={file}
  defaultZoom="fit-width"
  onZoomChange={({ level, resolvedZoom }) => {
    console.log(level, resolvedZoom);
  }}
/>
```

`automatic` 缩放宽于取景口的幻灯片而不扩展它们. `fit-width` 可扩大或缩小以填充可用的宽度,以及 `fit-page` 使用两个视图尺寸. 控制器显示 `setZoom(level)`, (中文(简体) ), `getZoom()`,以及 `getResolvedZoom()`工具栏 可保留语义模式,同时显示其当前百分比。 缩放或退出 响应模式应该通过 `getResolvedZoom() + delta` 改为 `setZoom()`,转换为数字 级别。 年长者 `fitMode` 相容性支持道具; `contain` 地图到 `automatic` 当新的缩放道具不存在时.

## 支持的列报格式

`.pptx` 97-2003年权力点 `.ppt` 两种文件都被相同的接受 `source` 螺旋桨和 `parsePresentation()` API (英语). 遗留文件从OLE 复合体内打开 由 Rust/Wasm 解析器存储; 浏览器不需要 LibreOffice, 服务器侧 转换终点,或临时 `.pptx` copy.

对于 `.ppt`,解析器遵循 `Current User`编号 :`UserEditAtom` 编辑链和活 ưμ㼯A 支助的办公室艺术小组 形状主锚、文本、图片和参考主图画内容实现正常化 同样的 `PresentationDocument` 由反应取景器消耗. PNG/JPEG 图片渲染 直接,而解码的EMF/WMF记录则使用有边框的浏览器侧图像转换 静态预览 .

遗产渲染是静态的,而不是完整的PowerPoint模拟. 高级效果, 可编辑 二进制图表和表格、动画、过渡、活动 OLE 对象和定时媒体可能 降解为静态图片或保持不支持。 检查 `onWarning` 或启用 `showDiagnostics` 接收明确 `degraded-rendering` 警告 :

```tsx
<ReactPptxViewer
  source={file}
  showDiagnostics
  onWarning={(warning) => {
    if (warning.code === 'degraded-rendering') {
      console.warn(warning.message, warning.slideIndex);
    }
  }}
/>
```

寄存器回归套件打开一个真实的 三滑 PowerPoint 97-2003 文件 `tests/fixtures/legacy/file-example-250kb.ppt` 直接在Rust和操场。 这个 检查幻灯片顺序、文本、常态节点、缩略图导航和诊断 转换步骤.

### 实验性 OpenDocument 支持

开放文件演示文稿`.odp`, (中文(简体) ), `.otp`, (中文(简体) ), `.fodp`)和绘画(`.odg`, (中文(简体) ), `.otg`, (中文(简体) ), `.fodg`(中文(简体) ) 由同一单位接受 `source` 螺旋桨和 `parsePresentation()` API (英语). 粗鲁/瓦斯解析器 从字节中检测格式并返回 `document.format` 作为 `odp` 或者说 `odg`绘图 页面以幻灯片显示。 这些格式只能查看 .

支持的图表根据数据渲染,自定义绘图形状使用增强几何 支持的地方. **支持是实验性的:** 忠诚程度各不相同,特别是: 图表布局和自定义形状,一些内容仍然不支持。 见 [打开文档支持指南](https://github.com/extend-hq/react-pptx/blob/main/docs/opendocument.md) 详细情况.

## 网络大会资产

原生PowerPoint解析通过一个Lazily加载的WebAssembly模块运行. 大多数应用程序可以 使用默认加载器。 如果您的捆绑或部署需要明确托管二进制, 在第一个演示文稿解析前配置 :

```ts
import { setWasmSource } from '@extend-ai/react-pptx';

setWasmSource('https://cdn.example.com/pptx_wasm_bg.wasm');
// A URL, Request, Response, ArrayBuffer/TypedArray, or WebAssembly.Module also works.
```

二进制还可以作为支持资产 URL 导入的捆绑者的软件包子路径:

```ts
import wasmUrl from '@extend-ai/react-pptx/pptx_wasm_bg.wasm?url';
import { setWasmSource } from '@extend-ai/react-pptx';

setWasmSource(wasmUrl);
```

配置字符串、 URL、 请求 URL、 字节和 `WebAssembly.Module` 数值转发到 解析器工人。 A 类 `Response` 支持主线程,因为它无法转发 对工人来说是可靠的. `initWasm()` 在急切初始化时可选择接受相同的源 帮助.

## 实例

见 `@extend-ai/react-pptx` 行动在这些现场 [扩展用户界面](https://www.extend.ai/ui) 实例。 点击截图打开演示和集成文件.

### [PowerPoint 查看器](https://www.extend.ai/ui/docs/components/pptx-viewer)

探索幻灯片导航,缩放和演示文稿预览.

[![PowerPoint viewer with a presentation slide and navigation controls](https://raw.githubusercontent.com/extend-hq/react-pptx/main/docs/readme-assets/extend-ui-pptx-viewer.png)](https://www.extend.ai/ui/docs/components/pptx-viewer)

## 字体

嵌入于 a 中的字体 `.pptx` 由 Rust 解码器解码,并在第一个解码器之前注册 幻灯片已导出。 应用程序还可以提供特许/自行托管的字体. 观众 保存请求的 PowerPoint 家族,然后附加 Office 兼容和脚本完成 拉丁语,CJK语,阿拉伯语,希伯来语,emoji语,和数学格利弗语的回落.

```tsx
<ReactPptxViewer
  source={file}
  fonts={{
    sources: [
      { family: 'Brand Sans', source: '/fonts/brand-sans.woff2' },
      {
        family: 'Brand Sans',
        source: '/fonts/brand-sans-bold.woff2',
        descriptors: { weight: '700' },
      },
    ],
    fallbacks: { 'Brand Sans': ['Inter', 'Arial'] },
    fallbackFamilies: ['Noto Sans', 'Noto Sans CJK SC', 'Noto Sans Arabic'],
  }}
  onWarning={(warning) => {
    if (warning.code === 'missing-font') console.warn(warning.message);
  }}
/>
```

取景器捆绑为卡利布里,阿里亚尔,时代新罗马,Courier New,Aptos和Aptos Norrow共享倒计时. 它在布局前加载所请求的家庭,并且更喜欢嵌入式,呼叫器提供并安装了正本. 每个家庭都是懒散的块;将所有产生的块和取景器一起部署. 设定 `fonts.useOfficeFallbacks` 改为 `false` 以禁用自动后退加载。 重新分配通知在 `dist/Office-Font-Licenses.txt`。 。 。 .

该套件不重新分配专有微软字体. 其他家族则依赖于由主机提供的嵌入字体或字体. `resolvePptxFontFamily()` 财务报告和审定财务报表 `OFFICE_FONT_FALLBACKS` 用于在查看器外生成演示文稿文本的应用程序.

## 自定义滚动区域和钩

将实际滚动的视图传送通过 `virtualization.scrollElement`。这与 Radix, Base UI, coss, 或任何主机拥有的滚动区域,使该元素成为了观察根.

```tsx
const [scrollElement, setScrollElement] = useState<HTMLDivElement | null>(null);
const viewer = usePptxViewer();
const parsed = usePptxPresentation(file);

return (
  <ScrollArea.Root>
    <ScrollArea.Viewport ref={setScrollElement}>
      {parsed.presentation ? (
        <ReactPptxViewer
          ref={viewer.ref}
          source={parsed.presentation}
          virtualization={{ enabled: true, overscanViewport: 2, scrollElement }}
        />
      ) : null}
    </ScrollArea.Viewport>
  </ScrollArea.Root>
);
```

`usePptxPresentation` (单位:千美元)`usePptxModel` 异名)将解析与渲染区分开来,而 `usePptxViewer` 曝光被动导航/搜索/分区控制器. `onViewportReady` 为高级集成和测试带提供内部幻灯片表面.

## 办公室艺术视觉

相片,所支持的形状,连接器,并保存了SmartArt图纸使用共享的Rust OfficeArt渲染器. SmartArt文本保留了它保存的文本框架与形状框架分开,包括独立的偏移,维度,旋转,和翻转. 没有支持被保存的绘图的语义数据仍然是明显的布局倒置.

### 列报元数据

该模型将PowerPoint数据带入所绘制的幻灯片之外,以便主机能够自行构建 表现在它。 幻灯片、布局和主机曝光 `transition` 财务报告和审定财务报表 `timing` (解说) `p:transition` 财务报告和审定财务报表 `p:timing` 部件,包括动画节点、目标和构建列表), 文本运行曝光 `math` (Office Math with a MathML 渲染)和 `field` (滑动数字, 日期和其他带有缓存文本的字段,表格单元格显示 `merge`,每个节点 可能携带 `clickAction`, (中文(简体) ), `hoverAction`, (中文(简体) ), `editing` (锁和连接器终点), `accessibilityTitle`, (中文(简体) ), `description` 财务报告和审定财务报表 `decorative`。媒体节点曝光 `playback` 修饰 和书签,a `poster` 框架,以及 `embeddedObject` oLE 对象和 控制系统。 查看器使数学成为 MathML , 跳过合并的单元格, 导航演示文稿 跳出和幻灯片链接动作到位,并显示带有播放控件的海报框 不播放过渡或动画时长.

`parsePresentation(source, { include3dModels: true })` 包括原始嵌入的3D模型字节和内容类型,模型和预览关系,以及场景 XML in `ImageNode.model3d`。该选项也可通过 `ReactPptxViewer`是因为 `parseOptions` 和解析钩。 默认为 `false`;缓存的 Office 光栅预览仍然是已显示的外观 。 此元数据不添加交互式 三维渲染器 .

## 冷启动缩略图

`createPptxThumbnailRenderer` 直接从 `ParsedPresentation`; 不挂载或 初始化 `ReactPptxViewer`一个渲染器重新使用其字体管理器DOM/SVG渲染上下文,以及 跨幻灯片请求的演示式资产缓存。 解析后的演示文稿可以传递给 `ReactPptxViewer` 无需再取取或分析.

```ts
import { createPptxThumbnailRenderer, parsePresentation } from '@extend-ai/react-pptx';

const presentation = await parsePresentation(source, {
  onPerformanceMeasurement: recordMeasurement,
});
const renderer = createPptxThumbnailRenderer(presentation, {
  fonts: {
    loadEmbeddedFonts: false,
    waitForFonts: false,
  },
  concurrency: 2,
  onPerformanceMeasurement: recordMeasurement,
});

const thumbnail = await renderer.renderSlide(0, {
  maxWidth: 240,
  maxHeight: 135,
  output: 'blob',
  signal: abortController.signal,
});

image.src = URL.createObjectURL(thumbnail.data);
renderer.destroy();
```

输出可以是 `blob` (PNG,默认), `canvas`, (中文(简体) ), `imageBitmap`,或 `svg`。 。 。 . `renderSlides()` 接受一个明确的索引列表,保留其顺序,并永远不要初始化其他幻灯片。 两者 单个和批量请求使用渲染器的受限队列. 默认情况下, 缩略图指定 字体策略跳过嵌入式字体、全局字体准备状态和缺失-font检测;呼叫者可以选择 回到任何那些行为 通过 `fonts`。 。 。 .

业绩观察员收到 `download`, (中文(简体) ), `wasm-parsing`, (中文(简体) ), `embedded-font-preparation`, (中文(简体) ), `slide-dom-svg-rendering`, (中文(简体) ), `image-decoding`,以及 `raster-encoding` 酌情测量。 每个 渲染结果还包含其幻灯片特定测量.

## 缩略图钩

`usePptxViewerThumbnails` 曝光消费自有电影的脱落幻灯片预览. 密码 缩略图使用与主取景器相同的活 DOM/SVG 渲染器和已装入的字体,所以每个都附加 稳定 `containerRef` 以常规元素而不是帆布.

```tsx
import { ReactPptxViewer, usePptxViewer, usePptxViewerThumbnails } from '@extend-ai/react-pptx';

export function PresentationWithThumbnails({ file }: { file: ArrayBuffer }) {
  const viewer = usePptxViewer();
  const { thumbnails } = usePptxViewerThumbnails(viewer.controller, {
    resolution: { maxWidth: 180, maxHeight: 120 },
    renderWindow: {
      visibleSlideIndexes: [0, 1, 2],
      prefetchSlideIndexes: [3, 4, 5],
    },
  });

  return (
    <div style={{ display: 'grid', gridTemplateColumns: '200px 1fr', gap: 16 }}>
      <aside style={{ display: 'grid', gap: 12, alignContent: 'start' }}>
        {thumbnails.map((thumbnail) => (
          <button
            key={thumbnail.slideIndex}
            type="button"
            onClick={() => void viewer.controller?.goToSlide(thumbnail.slideIndex)}
          >
            <div
              ref={thumbnail.containerRef}
              style={{
                width: thumbnail.width,
                height: thumbnail.height,
                overflow: 'hidden',
              }}
            />
          </button>
        ))}
      </aside>
      <ReactPptxViewer ref={viewer.ref} source={file} mode="slide" />
    </div>
  );
}
```

结果还提供了 `renderThumbnail(slideIndex, element)` 实现必要一体化 `rerenderAttachedThumbnails()` 用于刷新当前每个附件预览. `disabled` 保留 生成和处理缩略图渲染时,元数据保持稳定。 对于大型甲板,虚拟化 栏杆与实际滚动元素相对:挂起 `containerRef` 仅用于虚拟行,通过这些 横行 `renderWindow.visibleSlideIndexes`,并使用 `prefetchSlideIndexes` 在附近温暖 幻灯片。 内置 `showThumbnails` 电影旅行也遵循同样的窗口行为.

## 块和字词引用

捆绑的跑道使用Rust 6.4.1分解器和块取出器,有生锈-odf 0.2.0,生锈-office-art 0.1.9和生锈-office-charts 0.2.0. 打电话 `extractPresentationBlocks(parsed.document, { includeWords: true })`,然后将其块或文字传递到 `PptxBlockHighlights` 或者说 `PptxWordHighlights`。组件接受查看器 `rootRef`,选定的目标,可选的多个目标,颜色和一个 `onGeometry` 对选定目标进行回调,遵循React DOCX API.

`resolvePptxSourceGeometry`, (中文(简体) ), `resolvePptxBlockGeometries` 财务报告和审定财务报表 `resolvePptxWordGeometries` 返回轴相匹配的相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. `revealPptxSource(controller, root, ref)` 挂载和导航到引用的幻灯片. `normalizedPptxBoundingBox` 将片段转换为分数幻灯片坐标.

参考文献带有文档身份,幻灯片和节点路径,可选单元格/段落索引和UTF-16文本抵消. 保留取出的内容; 仅匹配可见文本无法区分重复发生 。 几何仅限于挂载的幻灯片内容. 注释,图表标签子行距和数学子行距不接收被发明的矩形.

见 [引用指南](https://github.com/extend-hq/react-pptx/blob/main/docs/citations.md) 用于使用和游乐场街景.

## 常见问题

### @extend-ai/react-pptx 是什么？

PowerPoint\(PPTX,PPT\)和OpenDocument\(ODP,ODG\)演示文稿的浏览器-本土,虚拟化的回声查看器

### 如何安装 @extend-ai/react-pptx？

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

### @extend-ai/react-pptx 支持 TypeScript 吗？

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

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

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

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

@extend-ai/react-pptx 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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