渲染转码后文档

本文介绍如何使用 @netless/slide 库渲染转码后的文档。

前提条件

开始前，确保你已参考实现 PPT 转码完成文档转码并获取本次转码任务的 UUID (uuid) 和转换结果文件地址前缀路径 (prefixUrl)。

实现流程

@netless/slide SDK 用于在 Web 浏览器中渲染转码后的文档，支持对 PPT 文档进行翻页、播放动画等操作。

集成 SDK

使用 npm 集成 @netless/slide 到你的项目中：

Shell

npm install @netless/slide

信息

@netless/slide SDK 使用 WebGL 渲染 PPT 文档，你需要确保你的浏览器支持 WebGL。

初始化 Slide 对象

要初始化 Slide 对象, 至少要指定三项配置：

Key	类型	描述
anchor	HTMLElement	作为 Slide 渲染出的 canvas 元素的挂载点。
interactive	boolean	PPT 是否可交互，不可交互的 PPT 无法响应用户的事件。
mode	"local" | "interactive"	local: 单机模式，Slide 对象不会触发任意同步事件。 interactive：互动模式，所有客户端都可以交互。

JavaScript

import { Slide } from "@netless/slide";

const slide = new Slide({
  anchor: someDivElement,
  interactive: true,
  mode: "local",
});

设置转换资源

设置转换资源需要传入两个参数：

• taskId：一串 hash 字符串代表一次转换任务 ID，即调用发起 PPT 转码或查询转码任务进度返回的 uuid。
• prefixUrl：一段 URL 地址, 指向转码后的资源前缀路径，即调用查询转码任务进度返回的 prefixUrl。

注意

你需要保证访问 prefixUrl 路径里的资源不会跨域。

JavaScript

slide.setResource(
  // 传入 taskId
  "06415a307f2011ec8bdc15d18ec9acc7", 
  // 传入 prefixUrl
  "https://convertcdn.netless.group/dynamicConvert"
);

渲染 PPT 页面

调用 renderSlide 方法并传入 PPT 的页码以渲染该页 PPT（页码从 1 开始）。你也可以调用 renderSlide 跳转到任意页码。

信息

你需要确保传入的页码在原始 PPT 页数范围内，访问 slide.slideCount 可以获取 PPT 的总页数。

JavaScript

// 渲染第一页
slide.renderSlide(1);

// 渲染最后一页
slide.slideCount(slide.slideCount);

参考信息

API 参考

本节提供 @netless/slide 的 TypeScript API 参考。

Slide

Slide 类提供管理 Slide 对象的方法。

setResource

TypeScript

setResource(taskId: string, url: string): void;

设置转换后的资源。

参数

• taskId：String。转码任务 ID，即调用发起 PPT 转码或查询转码任务进度返回的 uuid。
• url：String。转码后的资源前缀路径，即调用查询转码任务进度返回的 prefixUrl。

注意

需要保证访问 prefixUrl 路径里的资源不会跨域。

renderSlide

TypeScript

renderSlide(index: number, isForward?: boolean): void;

渲染 PPT 资源的指定页码。

参数

• index：Number。欲渲染 PPT 页面的页码。
• isForward：Boolean。是否向前翻页，默认为 false。

注意

页码从 1 开始，需要确保传入的页码在原始 PPT 页数范围内。

nextStep

TypeScript

nextStep(): void;

执行下一个主序列动画。

prevStep

TypeScript

prevStep(): void;

执行上一个主序列动画。

setMainSeqStep

TypeScript

setMainSeqStep(index: number, status: "start" | "end"): void;

重置主序列动画。

参数

• index：Number。欲重置的 PPT 主序列动画的编号。
• status：欲重置动画到的状态。
  • "start"：重置到动画的开始。
  • "end"：重置到动画的结束。

RtcAudio

RtcAudio 类提供管理 RtcAudio 对象的方法和属性。

信息

PPT 里的音频和视频默认使用浏览器的 API 播放，如果有 RTC 混音需求可以提供自定义的播放器类来替换掉内置播放器。自定义的播放器需要实现 RtcAudioClazz 接口，用于创建 RtcAudio 对象。

play

TypeScript

play(): void;

开始播放音频。

pause

TypeScript

pause(): void;

暂停播放音频，且当前音频的播放时间保持不变。

destroy

TypeScript

destroy(): void;

销毁音频对象。

volume

TypeScript

volume(value: number): void;

设置音频播放音量。

参数

• value：Number。音量值，取值范围为 [0,1]。

on

TypeScript

on(event: "load" | "pause" | "play", listener: () => void): this;

注册事件监听器。

参数

• event：事件名称，可传以下值：
  • "load"：音频加载完成。
  • "pause"：音频暂停。
  • "play"：音频开始播放。
• listener：事件处理函数。event 事件发生时，listener 函数将被调用。

removeAllListeners

TypeScript

removeAllListeners(event: string): void;

移除指定事件或所有事件的监听器。

参数

• event：欲移除的事件名称，详见 on。传入空值时，将移除所有事件的监听器。

currentTime

Number。音频当前的播放时间，单位为秒。

isPaused

Boolean。音频是否为暂停状态。

duration

Number。音频时长。

RtcAudioClazz

RtcAudioClazz 类用于创建 RtcAudio 对象。

new

TypeScript

new (url: string): RtcAudio;

创建一个 RtcAudio 对象。

参数

• url：String。音频地址。

返回

RtcAudio 对象。

ILogger

ILogger 类用于定义逐条接收 PPT 运行日志的方法。需要在初始化 slide 对象时，在 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

TypeScript

info?(msg: string): void;

记录信息日志。

参数

• msg：String。日志消息。

error

TypeScript

error?(msg: string): void;

记录错误日志。

参数

• msg：String。日志消息。

warn

TypeScript

warn?(msg: string): void;

记录警告日志。

参数

• msg：String。日志消息。

类型定义

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<string>;
}

Slide 对象的配置项。

• anchor：HTMLElement。Slide 对象渲染出的 canvas 元素挂载点。
• interactive：Boolean。PPT 是否可交互。不可交互的 PPT 无法响应用户的事件。
• mode：String。操作模式，可传入以下值：
  • "interactive"：交互模式，所有客户端都可以操作 PPT。
  • "sync"：同步模式，仅一个客户端可以操作 PPT。
  • "local"：单机模式，Slide 对象不会触发任意同步事件。
• renderOptions：渲染选项，详见 ISlideRenderOptions。
• controller：Boolean。是否显示控制栏和统计信息。
• resize：Boolean。是否自动调整分辨率根据窗口大小。
• timestamp：() => Number。获取房间时间。
• enableGlobalClick：Boolean。是否启用全局点击，默认为 false。
• rtcAudio：配置 RTC 混音，详见 RtcAudioClazz。
• logger：日志记录对象，详见 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

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 滤镜和特效。