金山文档开放平台主题
概述
警告
JSSDK 事件机制调整说明：jssdk.on、jssdk.off 和 jssdk.Application.Sub 将在后续版本中被弃用，请使用改进后的 ApiEvent，查看详情
在 js-sdk 中，可以通过实例的 on 方法监听事件：
jssdk.on('事件名', data => {
// do something...
})
对应可监听的事件列表有：
| 事件名 | 说明 |
|---|---|
fileOpen | 文档打开 |
error | 错误事件 |
tabSwitch | PC 头部 Tab 切换 |
fileStatus | 文件保存状态 |
previewLimit | 预览页数限制事件 |
hasDocMap | 文档是否存在目录 |
fullscreenChange | 进入或退出全屏事件 |
fileNameChange | 文件重命名 |
fileOpen
- 事件名：
fileOpen - 描述：文件打开成功或者失败时的事件回调
- 使用方式：
// 文件打开成功或者失败时的事件回调
jssdk.on('fileOpen', data => {
console.log('文件打开：', data)
})
注意：该事件需要在 jssdk.ready() 之前进行注册
- 返回参数：
成功：
{
duration: 812,
fileInfo: {
createTime: 1606461829,
id: "94749723688",
modifyTime: 1606461829,
name: "userName",
officeType: "s",
},
stageTime: 1614,
success: true,
time: 1614,
ts: 1607858260164,
performance: {
timing: {
connectEnd: 1634624487632,
connectStart: 1634624487632,
domComplete: 1634624488193,
/*...*/
}
}
}
失败：
{
msg: "Fail",
result: "Fail"
}
error
- 事件名：
error - 描述：错误发生时的事件回调
- 使用方式：
// 错误发生时的事件回调
jssdk.on('error', err => {
console.log('发生错误：', err)
})
- 返回参数：
将 doc 文件改成 xls 文件等操作，会引发报错
{
reason: 'Fail'
}
错误码对应的错误说明：
| 错误码 | 说明 |
|---|---|
Unknown | 未知错误 |
userNotLogin | 用户未登录 |
InvalidLink | 无效链接 |
SessionFull | 协作成员已满 |
Fail | 打开失败 |
PermissionDenied | 您的操作权限不足 |
GetTokenFailed | 获取 token 失败 |
SessionExpired | 会话过期 |
fileTooLarge | 文件过大，不支持预览服务 |
GetFileInfoFailed | 获取文件信息失败 |
fileStatus
- 事件名：
fileStatus - 描述：文件保存的事件回调
- 使用方式：
// 文件保存的事件回调
jssdk.on('fileStatus', data => {
console.log('文件保存：', data)
})
- 返回参数：
{
status: 0, // 文档无更新
status: 1, // 版本保存成功, 触发场景：手动保存、定时保存、关闭网页
status: 2, // 暂不支持保存空文件, 触发场景：内核保存完后文件为空
status: 3, // 空间已满
status: 4, // 保存中请勿频繁操作，触发场景：服务端处理保存队列已满，正在排队
status: 5, // 保存失败
status: 6, // 文件更新保存中，触发场景：修改文档内容触发的保存
status: 7, // 保存成功，触发场景：文档内容修改保存成功
}
webSocketStatus
- 事件名：
webSocketStatus - 描述：返回 webSocket 的连接状态
- 使用方式：
该事件需要在 jssdk ready 之前监听
// 返回 webSocket 的连接状态
jssdk.on('webSocketStatus', data => {
console.log('webSocket 的连接状态：', data)
})
- 返回参数：
{
status: '_online', // 已连接
status: '_offline', // 已离线
status: '_close', // 关闭连接
}
filePasswordStatus
- 事件名：
filePasswordStatus - 描述：监听加密文件的密码相关状态
- 使用方式：
JSSDK: v1.1.10+、WebOffice v2.3.1+ 支持
// 监听加密文件的密码相关状态
jssdk.on('filePasswordStatus', data => {
console.log('监听加密文件的密码相关状态：', data)
})
注意：该事件需要在 jssdk.ready() 之前进行注册
- 返回参数：
{
status: 'NeedPassword', // 需要输入密码
status: 'InvalidPassword', // 密码验证错误
}
fileNameChange
- 事件名：
fileNameChange - 描述：文件名重命名的事件回调
- 使用方式：
该事件需要在 jssdk ready 之前监听
JSSDK: v1.1.14+、WebOffice v2.6.1+ 支持
// 文件名重命名的事件回调
jssdk.on('fileNameChange', e => {
console.log('新的文件名为：', e.fileName)
})
- 返回参数：
当文件重命名（成功）后，会将新文件名返回出来。
{
fileName: 'NewWebOffice'
}
tabSwitch
- 事件名：
tabSwitch - 描述：
tab切换的事件回调 - 使用方式：
// tab 切换的事件回调
jssdk.on('tabSwitch', data => {
console.log('切换 tab：', data)
})
- 返回参数：
// 以 Excel 为例：
{
tabKey: "InsertTab",
tabKey: "StartTab",
// ……更多状态看具体 tab
}
fullscreenChange
- 使用前提：如果在
commonOptions下配置了isBrowserViewFullscreen或者isIframeViewFullscreen，此项监听会无效。 - 事件名：
fullscreenChange - 描述：进入或者退出全屏时会执行回调
- 使用方式：
// 进入或者退出全屏时会执行回调
jssdk.on('fullscreenChange', result => {
console.log('全屏事件监听：', result)
})
- 返回参数：
{
status: 0, // 退出全屏
status: 1, // 进入全屏
}
hasDocMap
- 使用前提：此事件只存在于文字组件（Word）。由于文字获取目录是动态分片获取，因此需要以监听事件方式确定是否存在目录。
- 事件名：
hasDocMap - 描述：文档是否存在目录，如果存在目录则会执行回调
- 使用方式：
// 文档是否存在目录，如果存在目录则会执行回调
jssdk.on('hasDocMap', () => {
console.log('存在目录')
})
previewLimit
- 使用前提：此事件只在预览页数模式下有效，仅支持
Word、PPT和PDF组件 - 事件名：
previewLimit - 描述：当滚动到限制页数底部时触发事件
- 使用方式：
// 当滚动到限制页数底部时触发事件
jssdk.on('previewLimit', data => {
console.log('预览页数：', data)
})
- 返回参数：
// todo: 待验证
// 文字
{
total: 4 // 限制页数
}
// PPT 以及 PDF
{
total: 4 // 限制页数
realTotal: 10 // 真实总页数
}
由于文字文档是流式排版，无法获取准确的真实页数，因此回调只有一个参数
total