客户端文档转码

更新时间: 2024/07/24 13:59:48

3.4.0版本开始,白板的SDK中包含DocConverter.js。用户可以使用该文件在客户端上传,转码文档。

加载资源

DocConverter.js使用UMD格式打包。用户既可以直接在html文件中加载该脚本,也可以使用模块方式引入:

html<!-- 引入方式一:直接挂载在全局对象上 -->
<!doctype html>
<html lang="en">
   <head>
       <meta charset="utf-8">
       <script src="./sdk/DocConverter.js"></script>
   </head>
   <body>
       <script>
           console.log(DocConverter)
       </script>
   </body>
</html>
js//引入方式二:模块化加载
import DocConverter from './lib/DocConverter'

转码结果

文档转码分为静态转码与动态转码。动态转码仅适用于ppt, pptx等类型文件。静态转码适用于ppt, pptx, doc, docx, 以及pdf文件。

根据转码类型不同,转码返回的结果也不同。目前转码结果有:

  1. 动态转码: IDynamicDocParam
  2. 静态转码: IStaticDocParam, IStaticDocParamDeprecated
js/**
 * transcodeFormat: 'h5'
 * 动态转码返回格式
 */
type IDynamicDocParam = {
    url: string;
    width: number;
    height: number;
    pageCount: number
}

/**
 * transcodeFormat: 'jpg' | 'png'
 * staticDocType: 'template'
 *
 * 3.6.1及以上版本中,静态转码返回格式。
 *
 * 若同一房间中,可能存在版本小于3.6.1的用户,则应该使用staticDocType: 'array'
 * 
 * 建议新客户,或者能够控制用户强制升级为新版本的老客户,使用staticDocType: 'template'
 */
type IStaticDocParam = {
    width: number
    height: number
    /**
     * 最终每一页的图片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
     */
    template: string
    offset: number
    pageCount: number
} 

/**
 * transcodeFormat: 'jpg' | 'png'
 * staticDocType: 'array'
 *
 * 3.6.0及以下版本的转码格式。
 *
 * 若同一房间中,可能存在版本小于3.6.1的用户,则应该使用staticDocType: 'array'
 */
type IStaticDocParamDeprecated = {
    url: string;
    width: number;
    height: number;
}[]

如何使用

配置项

首先,创建一个转码配置对象。在该对象中设置转码的类型(静态、动态),以及转码返回的结果类型(staticDocType, 该参数仅对静态转码有效),以及转码各阶段的回调函数。

jsconst config = DocConverter.createConfig({
    /**
     * 转码结果的格式。jpg和png为静态转码,支持pdf, ppt, pptx, doc, docx格式
     * h5为动态转码,支持ppt和pptx
     * 
     * 
     * 若transcodeFormat为: 'jpg'或者'png',则转码为静态转码
     * 
     * 若transcodeFormat为'h5', 则转码为动态转码
     */
    transcodeFormat: "jpg",
    /**
     * 默认为template
     * 如果该参数为array,则静态转码结果的格式为 IStaticDocParamDeprecated
     * 如果该参数为template, 则静态转码结果的格式为 IStaticDocParam
     *
     * 注意,只有白板3.6.1及以上支持IStaticDocParam。
     * 如果你的白板版本小于等于3.6.0,则你应该使用'array'
     * 如果你的白板版本大于等于3.6.1,则你应该使用'template'
     */
    staticDocType: 'template' | 'array',
    /**
     * 可选参数。查询转码进度间隔时间,默认为4s。该参数的单位为(ms)
     */
    checkTransProgressInterval: 5000,
    /**
     * 可选参数。转码服务器地址。默认为 https://vcloud.163.com/app/wboard
     * 该参数仅对私有化部署用户有用
     */
    transServiceUrl: "https://vcloud.163.com/app/wboard",
    onBeginUpload: (opt: {docId: string}) => {
        console.log(`开始上传, docId为: ${opt.docId}`)
    }
    onUploadProgress: (progress) => {
        console.log(`上传进度:${(progress * 100).toFixed(2)}%`)
    },
    /**
     * docUrl为文件的下载地址
     */
    onUploadComplete: (opt: {docUrl: string}) => {
        console.log('上传已完成', res)
    },
    onTransBegin: (opt: {
        taskId: number
    }) => {
        console.log(`转码开始,任务id为: ${opt.taskId}`)
    },
    onTransProgress: (progress) => {
        console.log(`转码进度:${(progress * 100).toFixed(2)}%`)
    },
    onError: (err) => {
        console.log('上传或者转码异常', err)
    },
    onTransComplete: (res: IStaticDocParam | IDynamicDocParam | IStaticDocParamDeprecated) => {
        console.log('转码已完成', res)
    }
})

创建转码任务

第二个参数用于鉴权,其中checksum的生成需要appsecret。为了安全考虑,该参数应该从服务器接口中获取,避免appsecret被泄漏。创建转码任务后,文档上传、转码过程将开始。

jstask = DocConverter.createTask(file: File, {
    checksum: string        //sha1(appsecret + nonce + curTime)
    nonce: string           //随机长度小于128位的字符串
    curtime: number         //当前UTC时间戳,从1970年1月1日0点0分0秒开始到现在的秒数
    appkey: 'fskkkkk'
}, config)

查询转码进度

在转码时,如果用户刷新了页面,可以通过createQueryTask查询转码进度。taskId为开始转码任务后,onTransBegin返回的参数。

该函数的config参数和createTask中的config参数一样。但是该config中的onBeingUpload, onUploadProgress, onUploadComplete回调函数不会被唤醒。

此外,注意对于同一次转码,使用createTask时的transcodeFormat必须和createQueryTask时一致,否则onTransComplete返回的结果将不正确。

jstask = DocConverter.createQueryTask(opt: {
    taskId: number
}, {
    checksum: string        //sha1(appsecret + nonce + curTime)
    nonce: string           //随机长度小于128位的字符串
    curtime: number         //当前UTC时间戳,从1970年1月1日0点0分0秒开始到现在的秒数
    appkey: 'fskkkkk'
}, config)

终止任务

jstask.abort()
此文档是否对你有帮助?
有帮助
去反馈
  • 加载资源
  • 转码结果
  • 如何使用
  • 配置项
  • 创建转码任务
  • 查询转码进度
  • 终止任务