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

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

添加静态文件。注意url和template应为https协议。请注意drawPlugin.addDoc与toolCollection.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: 1000，
        pageCount: 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

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

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

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

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