# PPT 转码服务 API 参考 (/zh-CN/realtime-media/ppt-transcoding/reference/slide-api)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本页提供 @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`](#rtcaudioclazz) 接口，用于创建 `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`](#on)。传入空值时，将移除所有事件的监听器。
### currentTime [#currenttime]
Number。音频当前的播放时间，单位为秒。
### isPaused [#ispaused]
Boolean。音频是否为暂停状态。
### duration [#duration]
Number。音频时长。
## RtcAudioClazz [#rtcaudioclazz]
`RtcAudioClazz` 类用于创建 `RtcAudio` 对象。
### new [#new]
```typescript
new (url: string): RtcAudio;
```
创建一个 `RtcAudio` 对象。
**参数**
- `url`：String。音频地址。
**返回**
[`RtcAudio`](#rtcaudio) 对象。
## ILogger [#ilogger]
`ILogger` 类用于定义逐条接收 PPT 运行日志的方法。需要在初始化 `slide` 对象时，在 [`ISlideConfig`](#islideconfig) 中的 `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`](#isliderenderoptions)。
- `controller`：Boolean。是否显示控制栏和统计信息。
- `resize`：Boolean。是否根据窗口大小自动调整分辨率。
- `timestamp`：() => Number。获取房间时间。
- `enableGlobalClick`：Boolean。是否启用全局点击，默认为 `false`。
- `rtcAudio`：配置 RTC 混音，详见 [`RtcAudioClazz`](#rtcaudioclazz)。
- `logger`：日志记录对象，详见 [`ILogger`](#ilogger)。
- `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 滤镜和特效。