课件接入
适用于 Whiteboard Web SDK 2.16.59。
多窗口以 App 表示课件。先完成加入白板房间并开启多窗口；需要协同创建/操作课件时，当前端应有可写权限。保留 addApp 返回的 appId，后续用于聚焦、关闭和页面控制。
选择课件类型
| kind | 用途 | 数据来源 |
|---|---|---|
| Slide | 动态 PPT、动画与逐步播放 | 动态转码 taskId/url，或支持的转码 scenes |
| Presentation | 静态 PPT / PDF 图片页 | 静态转码 scenes |
| DocsViewer | 文档场景展示 | scenes 与 scenePath；沿用原文档展示流程 |
| MediaPlayer | 音视频文件 | 可播放的媒体 src |
| Plyr | 基于 app-plyr 的第三方媒体课件 | 自定义 App 注册后传入 provider/src |
| EmbeddedPage | H5 页面课件 | 自定义 App 注册后传入网页 src |
图片页 scenes 中需保留转码返回的 ppt.src、width、height；scenePath 使用唯一目录，避免多个窗口复用同一绑定路径。taskId 是转码任务 ID，不能用房间 UUID 替代。
接入内置课件
import { WindowManager } from '@netless/window-manager';
import Slide, { addHooks, type AppOptions as SlideAppOptions } from '@netless/app-slide';
// 在 mount 以及恢复房间课件前完成注册。Presentation、DocsViewer、MediaPlayer 为内置 App。
WindowManager.register({ kind: 'Slide', src: Slide, addHooks,
appOptions: { enableScale: true } });
// manager 已 mount；taskId/url/scenes 来自已完成的转码任务。
const slideId = await manager.addApp({
kind: 'Slide', options: { scenePath: '/slide/lesson-1', title: '动态课件' },
attributes: { taskId, url }
});
await manager.addApp({ kind: 'Presentation',
options: { scenePath: '/presentation/lesson-1', scenes, title: '静态课件' } });
await manager.addApp({ kind: 'DocsViewer',
options: { scenePath: '/docs/lesson-1', scenes, title: '文档' } });
await manager.addApp({ kind: 'MediaPlayer', options: { title: '媒体' },
attributes: { src: mediaUrl } });
配置动态 PPT
直接使用 WindowManager.register 时，在上述 Slide 注册的 appOptions 中按需补充 navigationButtonMode: "step"、syncEventQueuePolicy: "latest-pending-render"。不要在注册后为每个窗口重复改写全局注册表。
Slide 的 enableScale 默认 false，开启后才使用页面缩放。navigationButtonMode 默认 page，可设 step 控制底部按钮按动画步骤前后移动。syncEventQueuePolicy 默认 fifo；latest-pending-render 在 interactive 模式合并积压的待渲染页，不会把所有事件都丢弃为最新一条。
动态配置注册参数
课件注册参数可以由业务配置生成。Slide 的 appOptions 支持对象或返回对象的函数；内置 Presentation 的参数通过 WindowManager.mount 设置，无需重新注册。
| 课件 | 公开配置入口 | 配置时机 |
|---|---|---|
| Slide 动态 PPT | WindowManager.register({ kind: 'Slide', appOptions }) | 在 mount 和恢复课件前注册；参数含义见上文“配置动态 PPT” |
| Presentation 静态 PPT / PDF | WindowManager.mount({ builtinAppOptions: { Presentation } }) | 在 mount 时设置，供新建和恢复的 Presentation 读取 |
下面示例替换前文的 Slide 注册和多窗口挂载配置；保留业务原有的其他 mount 参数。
const coursewarePolicy = {
allowSlideScale: true,
presentationMaxScale: 4,
showScrollbar: true
};
await WindowManager.register({
kind: 'Slide', src: Slide, addHooks,
appOptions: (): SlideAppOptions => ({
enableScale: coursewarePolicy.allowSlideScale,
navigationButtonMode: 'step',
syncEventQueuePolicy: 'latest-pending-render',
onResourceMaxRetries: (url, error) => {
console.warn('课件资源重试已达上限', url, error);
}
})
});
const manager = await WindowManager.mount({
room, container,
builtinAppOptions: {
Presentation: {
maxCameraScale: coursewarePolicy.presentationMaxScale,
useScrollbar: coursewarePolicy.showScrollbar,
useClipView: true
}
}
});
Slide 的函数形式在 App 读取参数时求值；修改业务变量不会向所有已初始化课件自动广播更新。Presentation 在 mount 时确定本次配置，Presentation 的大小写需与上例一致。
Presentation 常用参数
| 参数 | 作用 |
|---|---|
maxCameraScale | 最大缩放倍率相对页面适配大小计算，例如 4 表示最多放大到适配大小的 4 倍 |
useScrollbar | 是否显示拖动滚动条 |
useClipView | 是否裁剪课件显示区域，只显示页面内容 |
这些参数在本端生效，各参与端应按业务要求配置。每个课件的 scenePath、scenes 和 title 仍在 addApp 的 options 中传入；每个窗口的 originSize 在 attributes 中设置，详见统一笔记。
自定义课件与 H5
import Plyr from '@netless/app-plyr';
import EmbeddedPage from '@netless/app-embedded-page';
WindowManager.register({ kind: 'Plyr', src: Plyr });
WindowManager.register({ kind: 'EmbeddedPage', src: EmbeddedPage });
// 在 mount 前注册，入房和 mount 后再 addApp。
await manager.addApp({ kind: 'Plyr', options: { title: '视频课件' },
attributes: { provider: 'youtube', src: 'https://www.youtube.com/embed/VIDEO_ID' } });
await manager.addApp({ kind: 'EmbeddedPage', options: { title: 'H5 课件' },
attributes: { src: 'https://YOUR_COURSEWARE_HOST/lesson' } });
插件数据和协议参考 app-plyr 与 app-embedded-page。
注册是本端能力，课件 attributes 是需要协同的初始数据。同房间所有参与端都需要注册兼容的同一 kind，不能只在创建端注册。注册成功后再创建窗口；已有窗口由房间状态恢复时，也需要本端已具备对应 App。
H5 课件受 iframe 嵌入、CSP、跨域、登录态及移动 WebView 媒体策略约束。Plyr 的 provider/src 需遵循插件文档，不能把任意播放页 URL 当作可直接播放的媒体文件。要把 H5 内部操作同步给远端，还需要课件自己的协同实现。