Android

文档与页面

更新时间: 2022/09/16 07:43:26

下面是这篇文章中部分名词的含义:

  1. 原始文件:指用户上传的ppt, pptx, doc, docx, pdf文件
  2. 转码文件:指上传后的转码结果
  3. 文档:转码文件加载至房间后的结果

若要使用动态文档,请在html中添加SDK zip文件中的pptRenderer.js

若用户从老版本G1白板升级到3.4.0及以上,需要注意:

  1. 3.4.0以上使用工具栏上传转码文档后,文档不再与IM账号绑定。用户可以通过docAdd, docDelete等工具栏回调函数,更新应用服务器中文档与账号之间的关联关系。
  2. 3.4.0以上上传转码文档需要在初始化WhiteBoardSDK时,传入getAuthInfo。若使用webview接入,则需要监听webGetAuth,然后回传jsSendAuth

概要

互动白板的基本结构为房间--文档--页面。一个房间内可以加载多个文档,每个文档内可以有多个白板页面。下面是一个互动白板房间的结构示例。

md-- whiteboard (默认文档)
    -- page 1
-- 力学
    -- page 1
    -- page 2
    -- page 3
-- 电磁学
    -- page 1
    -- page 2
    -- page 3

互动白板文档使用的基本流程为:

  1. 上传原始文件, 转码得到转码文件
  2. 使用工具栏,或者白板的接口函数加载转码文件,得到房间中的文档。

文档转码

文档转码有三种方式:

  1. 服务器文档转码(高级功能/服务端文档转码)
  2. 客户端文档转码 (高级功能/客户端文档转码)
  3. 工具栏文档转码, 使用docUpload图标

docUpload点击后会弹出文档弹窗。该弹窗有三个功能:

  1. 转码原始文件
  2. 转码文件集合
  3. 加载转码文件

文档弹窗

转码原始文件

如图所示,点击右下角的静态转码,或者动态转码可以分别开启静态/动态转码任务。静态转码支持的文件格式为:ppt, pptx, doc, docx, pdf。如果不需要开启动态转码,可以配置docUpload为:

js{
    tool: 'docUpload',
    hint: '上传文档',
    supportPptToH5: false
    supportDocToPic: true
}

文档转码结果

无论是客户端文档转码,还是服务器文档转码,或者使用白板工具栏内置的文档转码,最终在白板sdk内使用时,都会转化为以下三种格式之一:IStaticDocParam, IStaticDocParamDeprecated, IDynamicDocParam

这三种格式的参数会被用在drawPlugin.addDoc, drawPlugin.addTransDoc, toolCollection.addDoc, toolCollection.setDefaultDocList, toolCollection.on('docAdd', cb)等函数中。

IDynamicDocParam

IDynamicDocParam客户端文档转码返回的动态转码结果。它的格式为:

jstype IDynamicDocParam = {
    url: string;
    width: number;
    height: number;
    pageCount: number
}

其中url为动态ppt转码后的入口文件地址。

IStaticDocParam

IStaticDocParam客户端文档转码返回的静态转码结果。该格式在3.6.1版本后开始使用。如果用户需要在大于等于3.6.1的版本和小于3.6.1的版本之间互通,则应该使用IStaticDocParamDeprecated

3.6.1版本及以后,工具栏内置的静态文档转码结果即为IStaticDocParam。相比于IStaticDocParamDeprecated,该格式会节约大量的数据同步成本,并避免潜在的同步问题。

js/**
 * staticDocType: 'template'
 * 最终每一页的图片url计算方法为:将template中的`{index}`替换为offset + 页码(从0开始计算)
 *
 * 比如若template为: `https://www.baidu.com/{index}.png', offset为1,则静态文档前三页的图片为: 
 * https://www.baidu.com/1.png
 * https://www.baidu.com/2.png
 * https://www.baidu.com/3.png
 */
type IStaticDocParam = {
    width: number
    height: number
    template: string
    offset: number
    pageCount: number
} 

IStaticDocParamDeprecated

IStaticDocParamDeprecated客户端文档转码返回的静态转码结果。该格式适合于所有的互动白板版本。但是除非需要和小于3.6.1的版本互通,否则不建议使用该格式。

小于3.6.1版本的互动白板默认使用该格式。大于等于3.6.1版本的互动白板如需使用该格式,则应该设置:

jsdrawPlugin.setAppConfig({
    staticDocType: 'array'
})
js/**
 * staticDocType: 'array'
 */
type IStaticDocParamDeprecated = Array<{
    url: string;
    width: number;
    height: number;
}>

文档集合

文档弹窗转码文件的集合展示窗口。默认情况下,文档弹窗仅展示当前房间内,当前用户的转码文件。开发者可以通过接口, 在文档弹窗中添加任意的转码文件记录,比如添加上一次教学时的转码文件,或者添加公共账号上传的转码文件

通过docUpload添加,或者删除文档后,工具栏会触发回调函数docAdd, docDelete通知用户文档弹窗的变化,用户使用回调函数保存,或者删除转码结果

docAdd

文档弹窗中文档转码成功时触发此回调。注意,3.6.0版本之前请使用toolCollection.addDocEventListener监听docAdd事件。

jsinterface IDocEntity {
    docId: string,                      //文档的唯一id,删除文档时使用
    fileType: 'pdf' | 'ppt' | 'doc',    //文档类型,会影响弹窗中文档的图标
    name: string,                       //文档名称
    showDelete?: boolean,               //是否显示删除按钮,默认为不显示删除按钮
    params: IDynamicDocParam | IStaticDocParam | IStaticDocParamDeprecated
}


toolCollection.on('docAdd', (docList: Array<IDocEntity>) => any)

docDelete

文档弹窗中删除文档后触发此回调函数。注意,3.6.0版本之前请使用toolCollection.addDocEventListener监听docDelete事件。

jstoolCollection.on('docDelete', (docList: Array<IDocEntity>) => any)

setDefaultDocList

设置文档弹窗的默认文档集合。可一次性设置多个文档

请注意,如果您的页面地址为https协议,则添加的图片也必须为https协议。

jstoolCollection.setDefaultDocList(docList: Array<IDocEntity>)

toolCollection.setDefaultDocList([
    {
        docId: '12222',
        fileType: 'pdf',
        name: '示例pdf',
        showDelete: true,
        params: {
            template: 'https://nim.nosdn.127.net/36b5e510-79e3-418f-9b67-41c4275f1be4_1_{index}.jpg',
            pageCount: 2,
            offset: 1,
            width: 1000,
            height: 1000
        }
    }
])

addDoc

addDoc可在弹窗中添加单个文档。如果多次插入的docId重复,则新插入的文档会覆盖之前的文档。

jstoolCollection.addDoc(doc: IDocEntity)

toolCollection.addDoc({
    docId: '12222',
    fileType: 'pdf',
    name: '示例pdf',
    showDelete: true,
    params: {
        template: 'https://nim.nosdn.127.net/36b5e510-79e3-418f-9b67-41c4275f1be4_1_{index}.jpg',
        offset: 1,
        pageCount: 2,
        width: 1000,
        height: 1000
    }
})

deleteDoc

删除文档弹窗中文档

jstoolCollection.deleteDoc(docId: string)

加载文档

点击文档弹窗使用按钮,将转码文件加载到房间内,形成新的文档。也可以直接调用接口加载转码文件

文档操作

转码文件加载到房间中成了文档。下面将介绍文档相关的操作:

  1. 加载转码文件
  2. 切换文档
  3. 删除文档
  4. 获取文档信息

加载转码文件

除了文档弹窗中图形界面加载转码文件,也可以使用drawPlugin的接口加载转码文件。用户调用接口操作文档时,需要保存接口返回的名字。调用接口删除文档,切换文档时,需要使用添加接口时的返回值。

addDoc

添加静态文件。注意urltemplate应为https协议。请注意drawPlugin.addDoctoolCollection.addDoc。前者将转码文件载入到房间中,形成文档。后者将转码文件添加至文档弹窗中,方便用户进一步选择,加载。

js//返回文档内部名称,调用deleteBoard, gotoBoard时,应该使用返回值
addDoc: (params: {
    docName: string, 
    params: IStaticDocParam | IStaticDocParamDeprecated
}) => string

/**
 * sdk >= 3.6.1
 * staticDocType: 'template'
 */
const boardUniqueName = drawPlugin.addDoc({
    docName: '示例',
    params: {
        template: 'https://nim.nosdn.127.net/36b5e510-79e3-418f-9b67-41c4275f1be4_1_{index}.jpg',
        width: 1000,
        height: 1000pageCount: 2,
        offset: 1
    }
})

/**
 * sdk < 3.6.1
 * staticDocType: 'array'
 */
const boardUniqueName = drawPlugin.addDoc({
    docName: '示例',
    params: [
        {
            url: 'https://nim.nosdn.127.net/36b5e510-79e3-418f-9b67-41c4275f1be4_1_1.jpg',
            width: 1000,
            height: 1000
        },
        {
            url: 'https://nim.nosdn.127.net/36b5e510-79e3-418f-9b67-41c4275f1be4_1_2.jpg',
            width: 1000,
            height: 1000
        }
    ]
})

addTransDoc

加载动态文件

js//返回文档内部名称,调用deleteBoard, gotoBoard时,应该使用返回值
addTransDoc: (params: {
    docName: string,
    pageCount: number
    width: number
    height: number
    url: string
}) => string

const boardUniqueName = drawPlugin.addTransDoc({
    docName: '示例',
    pageCount: 10
    height: 720,
    width: 960,
    url: 'https://wboard-dev.vod.126.net/vodgm0kupit/doc/132984393/2180/XqznxcJz/index.json',
})

addBoard

addBoard添加多页空白文档。

js//添加名为[力学.pdf]的文档,文档内共有2页白板
const boardName = drawPlugin.addBoard('力学', 2)

切换文档

切换文档有两种方式:

  1. gotoBoard切换文档。
  2. 工具栏中docSelect组件切换文档
jsdrawPlugin.gotoBoard(boardName)

删除文档

删除文档有两种方式:

  1. deleteBoard删除文档。
  2. 工具栏中docSelect组件删除文档
jsdrawPlugin.deleteBoard(boardName)

文档信息

SDK提供了主动查询文档信息的接口,以及监听文档信息变化的接口

getBoardInfos

getBoardInfos会返回房间内的文档信息。返回的数据结构如下

js/**
 * {
 *    // 当前文档的文档名
 *    currBoard: "ppt_sample_1622962933286"
 *
 *    // 文档的显示名
 *    currBoardDisplayName: "ppt_sample"
 *
 *    //所有文档的名称
 *    boardNames: ["whiteboard", "ppt_sample_1622962933286"]
 *
 *    //所有文档的显示名
 *    boardDisplayNames: ["whiteboard", "ppt_sample"]
 *  }
 */
drawPlugin.getBoardInfos()

appState

应用状态变化时,会触发下面的回调函数。如果stateNameboard,表示房间内文档状态变化,此变化可能是文档新增,删除,或者切换。

jsdrawPlugin.on('event:appState:change', handler: (stateName: string, value1: any, value2?: any) => {
    if (stateName === 'board') {
        //处理文档变化
    }
})

页面操作

每个白板内的文档包含了1至多张页面。各页面之间的内容相互独立。通过预览(preview)弹窗,可以预览文档内所有页面的内容快照。下面介绍页面相关操作:

  1. 添加页面
  2. 切换页面
  3. 删除页面

添加页面

新增页面有两种方式:

  1. 使用工具栏preview组件添加页面
  2. 使用addPage接口添加页面

新页面默认添加在文档的最后一页。若insertAfter为K,则新页面位于第K个页面之后。

添加页面时,可以将一些自定义的数据,通过payload和添加的页面绑定。比如说使用互动白板在客户的动态ppt上做标注。当动态ppt切换到第N页时,可以创建页面,并设置payload: {pptPageNumber: N}。之后ppt再次切换时,可以根据getPageInfos的结果判断该页面是否创建,以及其位置。根据这些结果决定是否创建页面,以及如何跳转页面。

jsdrawPlugin.addPage(insertAfter?: number)
drawPlugin.addPage(opt: {
    insertAfter?: number,
    payload: any
})

切换页面

和添加页面一样,切换页面也有工具栏和接口两种方式。这两种方式是一一对应的。

firstPage

切换至第一页

js//工具栏按钮
{
    tool: 'firstPage',
    hint: '第一页'
}

drawPlugin.gotoFirstPage()

prevPage

切换至上一页

js//工具栏按钮
{
    tool: 'prevPage',
    hint: '上一页'
}

drawPlugin.gotoPrevPage()

nextPage

切换至下一页

js//工具栏按钮
{
    tool: 'nextPage',
    hint: '下一页'
}

drawPlugin.gotoNextPage()

lastPage

切换至最后一页

js//工具栏按钮
{
    tool: 'lastPage',
    hint: '最后一页'
}

drawPlugin.gotoLastPage()

gotoPage

切换至指定页面

jsdrawPlugin.gotoPage(index: number)

切换动画

使用下面的函数可以切换动态文档内的动画。注意,下面的函数在静态文档中无效

prevAnim

跳转至上一动画。如果已经跳转到当前页第一个动画,则跳转至上一页面的最后一个动画结束状态。工具栏中对应的工具名称为prevAnim

js{
    tool: 'prevAnim',
    hint: '上一步'
}

drawPlugin.prevAnim()

nextAnim

跳转至下一动画。如果当前页动画播放完毕,则跳至下一页面。工具栏中对应的工具名称为nextAnim

js{
    tool: 'nextAnim',
    hint: '下一步'
}

drawPlugin.nextAnim()

动态文档工具栏配置示例

下面是云信官网demo的工具栏配置示例

jslet hasTransDoc = false
drawPlugin.on('event:appState:change', (name, value) => {
    if (name === 'board') {
    if (!hasTransDoc && drawPlugin.hasTransDoc()) {
        hasTransDoc = true
        toolCollection.addOrSetContainer({
            position: 'bottomRight',
            items: [
                {
                    tool: 'prevPage',
                    hint: '上一页'
                },
                {
                    tool: 'prevAnim',
                    hint: '上一步'
                },
                {
                    tool: 'pageInfo'
                },
                {
                    tool: 'nextAnim',
                    hint: '下一步'
                },
                {
                    tool: 'nextPage',
                    hint: '下一页'
                },
                {
                    tool: 'preview',
                    hint: '预览',
                    previewSliderPosition: 'right'
                }
            ]
        })
    } else if (hasTransDoc && !drawPlugin.hasTransDoc()) {
        hasTransDoc = false
        toolCollection.addOrSetContainer({
            position: 'bottomRight',
            items: [
                {
                    tool: 'firstPage',
                    hint: '第一页'
                },
                {
                    tool: 'prevPage',
                    hint: '上一页'
                },
                {
                    tool: 'pageInfo'
                },
                {
                    tool: 'nextPage',
                    hint: '下一页'
                },
                {
                    tool: 'lastPage',
                    hint: '最后一页'
                },
                {
                    tool: 'preview',
                    hint: '预览',
                    previewSliderPosition: 'right'
                }
            ]
        })
    }
}

删除页面

删除指定页面。可以通过接口,或者通过工具栏中preview弹窗删除页面

jsdrawPlugin.deletePage(index: number)

页面信息

工具栏pageInfo可以展示当前页码/总页码

getPageInfos返回指定文档内的页面信息,若参数未设置,则返回当前文档的页面信息

js/**
 *  {
 *     //当前页面索引
 *     activeIndex: 2
 *
 *     //文档内页面的名字(每次添加页面,新页面名字自动+1)
 *     //若insertAfter设置为 undefined, undefined, 1, 会出现下面的pageNames组合
 *     //即最后一页白板插入的位置为索引为1的页面后
 *     pageNames: (4) ["0", "1", "3", "2"]
 *
 *     //当前页面的名字
 *     currPage: 3
 *
 *     //页面的payloads
 *     pagePayloads: (4) [undefined, undefined, undefined, undefined]
 *  }
 */

drawPlugin.getPageInfos(boardName?: string)

appState

应用状态变化时,会触发下面的回调函数。如果stateNameboard,表示房间内文档状态变化,此变化可能是文档新增,删除,或者切换。

jsdrawPlugin.on('event:appState:change', handler: (stateName: string, value1: any, value2?: any) => {
    if (stateName === 'page') {
        //处理页面变化
    }
})
此文档是否对你有帮助?
有帮助
去反馈
  • 概要
  • 文档转码
  • 转码原始文件
  • 文档转码结果
  • IDynamicDocParam
  • IStaticDocParam
  • IStaticDocParamDeprecated
  • 文档集合
  • docAdd
  • docDelete
  • setDefaultDocList
  • addDoc
  • deleteDoc
  • 加载文档
  • 文档操作
  • 加载转码文件
  • addDoc
  • addTransDoc
  • addBoard
  • 切换文档
  • 删除文档
  • 文档信息
  • getBoardInfos
  • appState
  • 页面操作
  • 添加页面
  • 切换页面
  • firstPage
  • prevPage
  • nextPage
  • lastPage
  • gotoPage
  • 切换动画
  • prevAnim
  • nextAnim
  • 动态文档工具栏配置示例
  • 删除页面
  • 页面信息
  • appState