客户端文档转码
更新时间： 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文件。
根据转码类型不同，转码返回的结果也不同。目前转码结果有：
- 动态转码:
IDynamicDocParam - 静态转码:
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()
此文档是否对你有帮助？
