展示文件

  • Web

更新时间

了解 Fastboard SDK 在不同平台上的展示文件方式,包括接入流程、关键配置和平台差异。

声网 Fastboard SDK 支持在白板中插入和展示多种形式的文件,例如图片、音视频和文档,帮助用户快速分享丰富多元的信息,创造沉浸式的互动体验。

本文介绍如何调用 Fastboard SDK 的 API 插入图片、演示文档和播放音视频。

插入图片

声网 Fastboard SDK 提供 insertImage 方法,用于在白板主窗口中插入并展示图片。你只需调用该方法,并传入图片的 URL,即可在白板上展示指定图片。

开始前,请确保满足以下条件:

  • 在项目中集成声网 Fastboard SDK 并加入房间。详见加入白板房间。
  • 准备好图片的 URL 地址并确保 App 客户端能够访问该 URL,否则图片无法正常展示。
  • 确保图片的格式为 PNG、JPG/JPEG 或 WEBP。

下面在加入白板房间的示例项目基础上添加代码,展示如何在白板中插入一张图片。

  1. 在 main.js 文件的 mountFastboard(document.getElementById("app")); 后面添加如下行插入图片:

    JavaScript
    await app.insertImage(
      "https://web-cdn.agora.io/website-files/images/interactive-whiteboard-text-tab-1.png"
    );
  2. 运行项目:

    Shell
    npm run dev

    index.html 页面打开后可以看到插入的图片。

注意

目前 Fastboard SDK 没有为插入图片功能提供 UI,你需要自行实现。

播放音视频

声网 Fastboard SDK 集成了内置插件 MediaPlayer,用于播放音视频文件。你只需调用 Fastboard SDK 的 insertMedia 方法,传入子窗口标题和音视频文件的 URL 地址,即可在白板子窗口中播放音视频。

开始前,请确保满足以下条件:

  • 在项目中集成声网 Fastboard SDK 并加入房间。详见加入白板房间。
  • 准备好音频或视频文件的 URL 地址并请确保 App 客户端能够访问该 URL,否则音视频文件无法播放。
  • 确保要播放的音频文件为 MP3 格式,视频文件为 MP4 格式(推荐使用 h264 编码格式的 MP4 文件,否则可能会有兼容性问题)。

下面在加入白板房间的示例项目基础上添加代码,展示如何在白板中播放音视频。

  1. 在 main.js 文件的 mountFastboard(document.getElementById("app")); 后面添加如下行插入音视频文件:

    JavaScript
    await app.insertMedia(
      "test1.mp4",
      "https://beings.oss-cn-hxxxou.aliyuncs.com/test/aaa59xxxxxxxc695def4/1606277539701637%E7%9A%84%E5%89%AF%E6%9C%AC.mp4"
    );
  2. 运行项目:

    Shell
    npm run dev

    index.html 页面打开后可以看到名为 test1.mp4 的子窗口,点击开始按钮,即可播放视频。

注意

目前 Fastboard SDK 没有为插入音视频功能提供 UI,你需要自行实现。

演示文档

声网 Fastboard SDK 集成了内置插件 DocsViewer,用于展示文档。你只需调用 Fastboard SDK 的 insertDocs 方法,并传入文档的信息,即可在白板子窗口中分页演示文档,具体实现步骤如下:

  1. 调用发起文档转换将源文档分页转换成一组图片或网页。
  2. 调用查询文档转换任务进度获取文档转换结果。
  3. 调用 insertDocs 方法,并将每页图片或网页的宽、高和 URL 按顺序传入 scenes 参数中。

将源文档转换为图片或网页时,你需要特别注意以下几点:

  • 确保转换后的图片或网页格式正确。 目前 Fastboard SDK 支持插入并展示的图片或网页格式如下:

    • 由 PPT、PPTX、DOC、DOCX、PDF 格式的源文件转换成的 PNG、JPG/JPEG、WEBP 格式的静态图片。详见静态文档转换。
    • 由 PPTX 格式的源文件转换成的 HTML 网页。详见动态文档转换。
  • 确保图片或网页的访问权限。 你需要确保转换后的图片或网页可通过公网访问;此外,如果存储图片或网页的服务器与你的 Web 应用域名不同,你需要配置跨源资源共享(CORS)。否则,你的 Web 应用服务将无法访问并加载这些图片或网页。

开始前,请确保满足以下条件:

  • 在项目中集成声网 Fastboard SDK 并加入房间。详见加入白板房间。
  • 完成文档转换,并生成一组图片或网页的 URL 地址。

下面在加入白板房间的示例项目基础上添加代码,展示如何插入并展示一个三页、带动画效果的 PPTX 文件。

  1. 将 PPTX 源文件上传至第三方云存储,调用发起文档转换,创建一个动态文档转换任务,将 PPTX 文件按页转换为 HTML 网页。

  2. 调用查询转换任务进度 获取文档转换的结果。

  3. 在加入白板房间的 main.js 文件中添加如下行插入文档:

    JavaScript
    // 将查询结果(查询文档转换任务进度 API 返回的整个响应包体)传入 response 参数。
    var response = {
    uuid: "01xxxx82",
    type: "dynamic",
    status: "Finished",
    progress: {
        totalPageSize: 3,
        convertedPageSize: 3,
        convertedPercentage: 100,
        convertedFileList: [
        {
            width: 1280,
            height: 720,
            conversionFileUrl:
            "pptx://docs-test-ct.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/016127900ed511ec8ad01bd5558ec882/1.slide",
            preview:
            "https://docs-test-ct.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/016127900ed511ec8ad01bd5558ec882/preview/1.png",
        },
        {
            width: 1280,
            height: 720,
            conversionFileUrl:
            "pptx://docs-test-ct.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/016127900ed511ec8ad01bd5558ec882/2.slide",
            preview:
            "https://docs-test-ct.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/016127900ed511ec8ad01bd5558ec882/preview/2.png",
        },
        {
            width: 1280,
            height: 720,
            conversionFileUrl:
            "pptx://docs-test-ct.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/016127900ed511ec8ad01bd5558ec882/3.slide",
            preview:
            "https://docs-test-ct.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/016127900ed511ec8ad01bd5558ec882/preview/3.png",
        },
        ],
        currentStep: "Packaging",
    },
    };
    // 调用 insertDocs 插入文档。
    var btn = document.getElementById("addPPT");
    btn.onclick = async function addPPT() {
    await app.insertDocs("演示文档", response);
    };
  4. 在 index.html 文件中添加如下代码,将演示文档的按钮加载到页面上:

    HTML
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Vite App</title>
      </head>
      <body>
        <div
          id="app"
          style="width: 600px; height: 400px; border: 1px solid;"
        ></div>
        <!--定义演示文档按钮的样式,并将其添加到网页上-->
        <div style="display: inline-block;">
        <div id="viewDocs" class="Prev" style="width: 50px; border: 1px solid; position: fixed; bottom: 430px; right:20px;">
          演示文档
      </div>
    </div>
        <script type="module" src="/main.js"></script>
      </body>
    </html>
  5. 运行项目:

    Shell
    npm run dev

    index.html 页面打开后可以看到演示文档按钮,点击该按钮,即会弹出子窗口并加载文档,点击切页箭头,即可分页演示文档。

信息

Fastboard SDK 还提供一个同名的 insertDocs 方法,用于插入和展示文档。你可参考上述步骤和 insertDocs 参考文档,实现演示文档的功能。

当前版本的课件接口

dispatchDocsEvent(app, event, options)、app.getPageState(options)、app.focusApp(appId)、app.insertDocs(params, options)、app.appliancePlugin.addListener/removeListener。

统一页面控制

MainView、DocsViewer、Slide、Presentation 的 page 从 1 开始;target 输入可为 mainView 或 appId,省略时跟随焦点。查询输出的 target 为 mainView/DocsViewer/Slide/Presentation。scale 为相对适配尺寸倍率,1 表示适配尺寸,DocsViewer 不支持 scalePage。

accepted=true 表示命令接收;accepted=false 包含 reason/message。通过统一页事件或查询观察实际状态,不能把命令回调作为首帧完成信号。

窗口与课件配置

参数行为
originSize正数 width/height 参考尺寸;MainView 与各 App 分别设置
pageScaleRange相对适配尺寸的 minScale/maxScale,均为有限正数
forceMaximized房间级强制最大化,与 useBoxesStatus 不兼容
lazySetupInMaximizedMode本端按焦点初始化,默认关闭
maxCachedAppsInMaximizedMode本端 LRU runtime 缓存,默认 4
navigationButtonModeSlide 底部按钮:page 默认按页,step 按动画步骤
syncEventQueuePolicyfifo 默认;latest-pending-render 仅合并待执行渲染页
表格内容超出当前宽度,可横向滚动查看更多列。

focusApp 的布尔值表示焦点提交完成;不能用它判断 setup 或全部资源就绪。插入课件需先转换,普通图片页可以创建 Presentation;原有静态文档 API 保持 DocsViewer 行为。