# 渲染转码后文档 (/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 前提条件 [#前提条件] 本文介绍如何使用 @netless/slide 库渲染转码后的文档。 开始前,确保你已参考[实现 PPT 转码](/zh-CN/realtime-media/ppt-transcoding/get-started/quick-start)完成文档转码并获取本次转码任务的 UUID (`uuid`) 和转换结果文件地址前缀路径 (`prefixUrl`)。 ## 实现流程 [#实现流程] @netless/slide SDK 用于在 Web 浏览器中渲染转码后的文档,支持对 PPT 文档进行翻页、播放动画等操作。 ### 集成 SDK [#集成-sdk] 使用 npm 集成 [`@netless/slide`](https://www.npmjs.com/package/@netless/slide) 到你的项目中: ```shell npm install @netless/slide ``` :::info[信息] @netless/slide SDK 使用 WebGL 渲染 PPT 文档,你需要确保你的浏览器支持 WebGL。 ::: ### 初始化 Slide 对象 [#初始化-slide-对象] 要初始化 `Slide` 对象,至少要指定三项配置: | Key | 类型 | 描述 | | --- | --- | --- | | anchor | HTMLElement | 作为 `Slide` 渲染出的 `canvas` 元素的挂载点。 | | interactive | boolean | PPT 是否可交互,不可交互的 PPT 无法响应用户事件。 | | mode | "local" | "interactive" | [render-ppt-markdown-0-3-2 details](#table-slot-render-ppt-markdown-0-3-2) | **render-ppt-markdown-0-3-2 details** - `local`: 单机模式,`Slide` 对象不会触发任意同步事件。 - `interactive`:互动模式,所有客户端都可以交互。 ```javascript import { Slide } from "@netless/slide"; const slide = new Slide({ anchor: someDivElement, interactive: true, mode: "local", }); ``` ### 设置转换资源 [#设置转换资源] 设置转换资源需要传入两个参数: - `taskId`:一串 hash 字符串代表一次转换任务 ID,即调用[发起 PPT 转码](/zh-CN/api-reference/api-ref/ppt-conversion-service/start-conversion)或[查询转码任务进度](/zh-CN/api-reference/api-ref/ppt-conversion-service/query-task)返回的 `uuid`。 - `prefixUrl`:一段 URL 地址,指向转码后的资源前缀路径,即调用[查询转码任务进度](/zh-CN/api-reference/api-ref/ppt-conversion-service/query-task)返回的 `prefixUrl`。 :::warning[注意] 你需要保证访问 `prefixUrl` 路径里的资源不会跨域。 ::: ```javascript slide.setResource( // 传入 taskId "06415a307f2011ec8bdc15d18ec9acc7", // 传入 prefixUrl "https://convertcdn.netless.group/dynamicConvert" ); ``` ### 渲染 PPT 页面 [#渲染-ppt-页面] 调用 `renderSlide` 方法并传入 PPT 的页码以渲染该页 PPT(页码从 1 开始)。你也可以调用 `renderSlide` 跳转到任意页码。 :::info[信息] 你需要确保传入的页码在原始 PPT 页数范围内,访问 `slide.slideCount` 可以获取 PPT 的总页数。 ::: ```javascript // 渲染第一页 slide.renderSlide(1); // 渲染最后一页 slide.slideCount(slide.slideCount); ``` ## 参考信息 [#参考信息] ### API 参考 [#api-参考] 本节提供 `@netless/slide` 的 TypeScript API 参考。 #### Slide [#slide] `Slide` 类提供管理 `Slide` 对象的方法。 ##### setResource [#setresource] ```typescript setResource(taskId: string, url: string): void; ``` 设置转换后的资源。 **参数** - `taskId`:String。转码任务 ID,即调用[发起 PPT 转码](/zh-CN/api-reference/api-ref/ppt-conversion-service/start-conversion)或[查询转码任务进度](/zh-CN/api-reference/api-ref/ppt-conversion-service/query-task)返回的 `uuid`。 - `url`:String。转码后的资源前缀路径,即调用[查询转码任务进度](/zh-CN/api-reference/api-ref/ppt-conversion-service/query-task)返回的 `prefixUrl`。 :::warning[注意] 需要保证访问 `prefixUrl` 路径里的资源不会跨域。 ::: ##### renderSlide [#renderslide] ```typescript renderSlide(index: number, isForward?: boolean): void; ``` 渲染 PPT 资源的指定页码。 **参数** - `index`:Number。欲渲染 PPT 页面的页码。 - `isForward`:Boolean。是否向前翻页,默认为 `false`。 **注意** 页码从 1 开始,需要确保传入的页码在原始 PPT 页数范围内。 ##### nextStep [#nextstep] ```typescript nextStep(): void; ``` 执行下一个主序列动画。 ##### prevStep [#prevstep] ```typescript prevStep(): void; ``` 执行上一个主序列动画。 ##### setMainSeqStep [#setmainseqstep] ```typescript setMainSeqStep(index: number, status: "start" | "end"): void; ``` 重置主序列动画。 **参数** - `index`:Number。欲重置的 PPT 主序列动画的编号。 - `status`:欲重置动画到的状态。 - `"start"`:重置到动画的开始。 - `"end"`:重置到动画的结束。 #### RtcAudio [#rtcaudio] `RtcAudio` 类提供管理 `RtcAudio` 对象的方法和属性。 :::info[信息] PPT 里的音频和视频默认使用浏览器的 API 播放,如果有 RTC 混音需求可以提供自定义的播放器类来替换掉内置播放器。自定义的播放器需要实现 [`RtcAudioClazz`](/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt) 接口,用于创建 `RtcAudio` 对象。 ::: ##### play [#play] ```typescript play(): void; ``` 开始播放音频。 ##### pause [#pause] ```typescript pause(): void; ``` 暂停播放音频,且当前音频的播放时间保持不变。 ##### destroy [#destroy] ```typescript destroy(): void; ``` 销毁音频对象。 ##### volume [#volume] ```typescript volume(value: number): void; ``` 设置音频播放音量。 **参数** - `value`:Number。音量值,取值范围为 [0,1]。 ##### on [#on] ```typescript on(event: "load" | "pause" | "play", listener: () => void): this; ``` 注册事件监听器。 **参数** - `event`:事件名称,可传以下值: - `"load"`:音频加载完成。 - `"pause"`:音频暂停。 - `"play"`:音频开始播放。 - `listener`:事件处理函数。`event` 事件发生时,`listener` 函数将被调用。 ##### removeAllListeners [#removealllisteners] ```typescript removeAllListeners(event: string): void; ``` 移除指定事件或所有事件的监听器。 **参数** - `event`:欲移除的事件名称,详见 [`on`](/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt)。传入空值时,将移除所有事件的监听器。 ##### currentTime [#currenttime] Number。音频当前的播放时间,单位为秒。 ##### isPaused [#ispaused] Boolean。音频是否为暂停状态。 ##### duration [#duration] Number。音频时长。 #### RtcAudioClazz [#rtcaudioclazz] `RtcAudioClazz` 类用于创建 `RtcAudio` 对象。 ##### new [#new] ```typescript new (url: string): RtcAudio; ``` 创建一个 `RtcAudio` 对象。 **参数** - `url`:String。音频地址。 **返回** [`RtcAudio`](/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt) 对象。 #### ILogger [#ilogger] `ILogger` 类用于定义逐条接收 PPT 运行日志的方法。需要在初始化 `slide` 对象时,在 [`ISlideConfig`](/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt) 中的 `logger` 属性中传入一个实现了该类下方法的对象。该类下的方法都是可选的,如果不实现该类下的方法,则日志记录器不会记录任何日志。示例如下: ```typescript import { Slide } from "@netless/slide"; const slide = new Slide({ anchor: someDivElement, interactive: true, mode: "local", logger: { info(msg: string) { console.log(msg); } } }); ``` ##### info [#info] ```typescript info?(msg: string): void; ``` 记录信息日志。 **参数** - `msg`:String。日志消息。 ##### error [#error] ```typescript error?(msg: string): void; ``` 记录错误日志。 **参数** - `msg`:String。日志消息。 ##### warn [#warn] ```typescript warn?(msg: string): void; ``` 记录警告日志。 **参数** - `msg`:String。日志消息。 #### 类型定义 [#类型定义] ##### ISlideConfig [#islideconfig] ```typescript export interface ISlideConfig { anchor: HTMLDivElement; interactive: boolean; mode: "interactive" | "sync" | "local"; renderOptions?: ISlideRenderOptions; controller?: boolean; resize?: boolean; timestamp?: () => number; enableGlobalClick?: boolean; rtcAudio?: RtcAudioClazz; logger?: ILogger; useLocalCache?: boolean; resourceTimeout?: number; fixedFrameSize?: { width: number; height: number; }; clientId?: string; enableTracking?: boolean; urlInterrupter?: (url: string) => Promise; } ``` Slide 对象的配置项。 - `anchor`:HTMLElement。`Slide` 对象渲染出的 `canvas` 元素挂载点。 - `interactive`:Boolean。PPT 是否可交互。不可交互的 PPT 无法响应用户的事件。 - `mode`:String。操作模式,可传入以下值: - `"interactive"`:交互模式,所有客户端都可以操作 PPT。 - `"sync"`:同步模式,仅一个客户端可以操作 PPT。 - `"local"`:单机模式,`Slide` 对象不会触发任意同步事件。 - `renderOptions`:渲染选项,详见 [`ISlideRenderOptions`](/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt)。 - `controller`:Boolean。是否显示控制栏和统计信息。 - `resize`:Boolean。是否自动调整分辨率根据窗口大小。 - `timestamp`:() => Number。获取房间时间。 - `enableGlobalClick`:Boolean。是否启用全局点击,默认为 `false`。 - `rtcAudio`:配置 RTC 混音,详见 [`RtcAudioClazz`](/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt)。 - `logger`:日志记录对象,详见 [`ILogger`](/zh-CN/realtime-media/ppt-transcoding/get-started/render-ppt)。 - `useLocalCache`:Boolean。是否启用本地缓存,默认为 `true`。 - `resourceTimeout`:Number。资源加载超时,默认为 15 秒。 - `fixedFrameSize`:为 PPT 设置固定的宽高,设置后 PPT 将不会自动随着父元素的大小而改变。如果需要缩放,需要调用 `updateFixedFrameSize` 方法。 - `width`:Number。PPT 的宽度,单位为 px。 - `height`:Number。PPT 的高度,单位为 px。 - `clientId` :String。客户端 ID。在同步和交互场景下,该参数用于区分每个不同的客户端,不设置该参数可能会导致在某些情况下状态不同步。对于接收同步消息的端,需要使用该参数来判断是否是自己发送的消息。 - `enableTracking`:Boolean。是否启用日志追踪,默认为 `true`。 - `urlInterrupter`: 用于开启 PPT URL 拦截替换功能的回调函数。该功能可用于加密用户上传的 PPT 资源,保护用户隐私。你需要在该回调函数中编写 URL 替换逻辑,通过返回 `Promise` 对象提供替换后的 URL。 - `url`:待替换的 URL。 ##### ISlideRenderOptions [#isliderenderoptions] ```typescript export interface ISlideRenderOptions { minFPS?: number; maxFPS?: number; resolution?: number; autoResolution?: boolean; autoFPS?: boolean; transactionBgColor?: string | number; maxResolutionLevel?: number; forceCanvas?: boolean; } ``` PPT 资源可选渲染配置项。 **参数** - `minFPS`:Number。最小帧率 (FPS),默认值为 30。App 会尽量保证实际 FPS 高于此值,此值越小,CPU 开销越小。 - `maxFPS`:Number。最大 fps,默认值为 40。应用会保证实际 FPS 低于此值,此值越小,CPU 开销越小。 - `resolution`:Number。渲染分辨倍率,桌面端默认值为 `window.devicePixelRatio`,移动端默认值为 1。原始 PPT 有自己的像素尺寸,当在 2K 或者 4K 屏幕下,如果按原始 ppt 分辨率显示,画面会比较模糊。可以调整此值,使画面更清晰,但同时性能开销也会变高。声网建议保持默认值或者固定值为 1。 - `autoResolution`:Boolean。是否根据实际 FPS 自动缩放分辨率,默认为 `false`。自动缩放渲染分辨率会使 PPT 渲染时的 FPS 保持在 `minFPS` 和 `maxFPS` 之间。 - `autoFPS`:是否开启动态 FPS,默认为 `false`。开启后,会根据 CPU 效率动态提升和降低 FPS。 - `transactionBgColor`:切页动画的背景色,默认值为 `0x000000`(纯黑色)。支持设置为 CSS 颜色字符串或者 16 进制颜色值。 - `maxResolutionLevel`:Number。最高显示分辨率。支持以下值: - `0`:640 × 360 (360p)。 - `1`:960 × 540 (540p)。 - `2`:1280 × 720 (720p),为移动端设备的默认值。 - `3`:1920 × 1080 (1080p)。 - `4`:3200 × 1800 (3K),为桌面端设备的默认值。 该属性将同时影响 canvas 渲染分辨率和材质质量。在低端设备上,降低该属性的值可以降低内存占用,改善因内存不足,图像渲染失败导致的黑屏现象。 - `forceCanvas`:Boolean。是否强制使用 2D 渲染。启用后可能会导致渲染时丢失部分 3D 滤镜和特效。