WPS WebOffice 开放平台WPS WebOffice 开放平台 | 开发文档

深色模式

事件机制 ​

JSSDK 提供了 ApiEvent 事件机制，使你可以监听文档的交互行为，并在触发时运行一些 JavaScript 代码。

JSSDK 提供的事件分为公共事件和组件事件（例如文字事件、表格事件等），公共事件在各大组件中都能使用。

JSSDK 事件机制 支持对同一个事件绑定多个回调函数，也支持对单个回调函数取消绑定。

注意

JSSDK: v1.1.14+、WebOffice v3.3.1+ 支持，低于该版本请使用 jssdk.on 或 jssdk.Application.Sub 注册事件

ApiEvent的基本用法如下所示：

js
// 获取 JSSDK 实例对象
const instance = WebOfficeSDK.init({
  officeType: WebOfficeSDK.OfficeType.Writer,
  appId: 'xxxxx',
  fileId: 'xxxxx'
})

await instance.ready()

const handle = res => console.log(res)

// 监听事件
instance.ApiEvent.AddApiEventListener('tabSwitch', handle)

// 取消监听
instance.ApiEvent.RemoveApiEventListener('tabSwitch', handle)

监听公共事件 ​

fileOpen ​

文档打开成功或者失败时的事件回调

js
instance.ApiEvent.AddApiEventListener('fileOpen', data => {
  console.log('fileOpen: ', data)
})

注意：该事件需要在 instance.ready() 之前进行注册

成功时的返回参数：

js
{
  duration: 812,
  fileInfo: {
    createTime: 1606461829,
    id: "94749723688",
    modifyTime: 1606461829,
    name: "userName",
    officeType: "s",
  },
  stageTime: 1614,
  success: true,
  time: 1614,
  ts: 1607858260164,
}

失败时的返回参数：

js
{
  msg: "Fail",
  result: "Fail"
}

error ​

错误发生时的事件回调

例如将 doc 文件改成 xls 文件等操作，会引发报错

js
instance.ApiEvent.AddApiEventListener('error', data => {
  console.log('error: ', data)
})

返回参数：

js
{
  reason: 'Fail'
}

tabSwitch ​

文档 Tab 切换的事件回调

js
instance.ApiEvent.AddApiEventListener('tabSwitch', data => {
  console.log('tabSwitch: ', data)
})

返回参数：

js
// 以 Excel 为例：
{
  tabKey: "InsertTab",
  tabKey: "StartTab",
  // ……更多状态看具体 tab
}

DocumentSaveStatus ​

文件保存的事件回调

js
instance.ApiEvent.AddApiEventListener('DocumentSaveStatus', data => {
  console.log('DocumentSaveStatus: ', data)
})

返回参数：

js
{
  status: 0, // 文档无更新
  status: 1, // 版本保存成功, 触发场景：手动保存、定时保存、关闭网页
  status: 2, // 暂不支持保存空文件, 触发场景：内核保存完后文件为空
  status: 3, // 空间已满
  status: 4, // 保存中请勿频繁操作，触发场景：服务端处理保存队列已满，正在排队
  status: 5, // 保存失败
  status: 6, // 文件更新保存中，触发场景：修改文档内容触发的保存
  status: 7, // 保存成功，触发场景：文档内容修改保存成功
}

previewLimit ​

预览页数限制事件，当滚动到限制页数底部时触发事件

此事件只在预览页数模式下有效，仅支持 Word、PPT 和 PDF 组件

js
instance.ApiEvent.AddApiEventListener('previewLimit', data => {
  console.log('previewLimit: ', data)
})

返回参数：

js
// 文字
// 由于文字文档是流式排版，无法获取准确的真实页数，因此回调只有 total 一个参数
{
  total: 4 // 限制页数
}
// PPT 以及 PDF
{
  total: 4 // 限制页数
  realTotal: 10 // 真实总页数
}

hasDocMap ​

文档是否存在目录，如果存在目录则会执行回调。

此事件只存在于文字组件（Word），由于文字获取目录是动态分片获取，因此需要以监听事件方式确定是否存在目录。

js
instance.ApiEvent.AddApiEventListener('hasDocMap', data => {
  console.log('hasDocMap: ', data)
})

fullscreenchange ​

进入或者退出全屏时会执行回调

如果在 commonOptions 下配置了 isBrowserViewFullscreen 或者 isIframeViewFullscreen，此项监听会无效。

js
instance.ApiEvent.AddApiEventListener('fullscreenchange', data => {
  console.log('fullscreenchange: ', data)
})

返回参数：

js
{
  status: 0, // 退出全屏
  status: 1, // 进入全屏
}

webSocketStatus ​

监听 webSocket 的连接状态

js
instance.ApiEvent.AddApiEventListener('webSocketStatus', data => {
  console.log('webSocketStatus: ', data)
})

返回参数：

js
{
  status: '_online', // 已连接
  status: '_offline', // 已离线
  status: '_close', // 关闭连接
}

fileNameChange ​

文件名重命名的事件回调

当文件重命名（成功）后，会将新文件名返回出来。

js
instance.ApiEvent.AddApiEventListener('fileNameChange', data => {
  console.log('fileNameChange: ', data)
})

返回参数：

js
{
  fileName: 'NewWebOffice'
}

filePasswordStatus ​

监听加密文件的密码相关状态

注意：该事件需要在 instance.ready() 之前进行注册

js
instance.ApiEvent.AddApiEventListener('filePasswordStatus', data => {
  console.log('filePasswordStatus: ', data)
})

返回参数：

js
{
  status: 'NeedPassword', // 需要输入密码
  status: 'InvalidPassword', // 密码验证错误
}

ModelVisible ​

模态框打开和关闭时触发，例如「更多 ➜ 打印」

js
instance.ApiEvent.AddApiEventListener('ModelVisible', data => {
  console.log('ModelVisible: ', data)
})

OnBroadcast ​

接收全局广播，用于多人协作场景。

js
instance.ApiEvent.AddApiEventListener('OnBroadcast', data => {
  console.log('OnBroadcast: ', data)
})

监听文字事件 ​

文字组件（Word）对应可监听的事件列表有：

事件名说明
CurrentPageChange
监听当前页码改变事件
ClipboardCopy
监听剪切板“复制”事件
DocMapPanelChange
监听目录的显示与隐藏事件
WindowScrollChange
监听文档滚动事件，注意不是页面滚动
WindowSelectionChange
监听选区变化事件
FontMissing
发现有缺失的字体
ContentChange
监听文档内容改变事件

使用方法如下：

js
instance.ApiEvent.AddApiEventListener('ClipboardCopy', data => {
  console.log('ClipboardCopy: ', data)
})

监听表格事件 ​

表格组件（Excel）对应可监听的事件列表有：

事件名说明
Clipboard_Copy
监听剪切板“复制”事件
Worksheet_Activate
监听工作表的切换
Worksheet_SelectionChange
监听选区改变事件
Worksheet_ScrollChange
监听用户自己的滚动画布行为
Worksheet_ForceLandscape
监听强制横屏时通知

使用方法如下：

js
instance.ApiEvent.AddApiEventListener('Worksheet_Activate', data => {
  console.log('Worksheet_Activate: ', data)
})

监听演示事件 ​

演示组件（PPT）对应可监听的事件列表有：

事件名说明
SlideShowBegin
监听进入幻灯片全屏播放
SlideShowEnd
监听退出幻灯片全屏播放
SlideShowOnNext
监听下一步动画操作
SlideShowOnPrevious
监听上一步动画操作
SlideSelectionChanged
监听当前页改变事件
ActiveSlideChange
监听页面跳转
VideoFullscreenInfo
演示视频进入/退出全屏播放的事件监听
TriggerPlayEvent
触发器动画事件
SlideMove
监听 PPT 的移动操作
PresentationNewSlide
监听 PPT 的新增操作
SlideDelete
监听 PPT 的删除操作
SlidePlayerChange
监听播放状态改变
SlideMediaChanged
监听视频播放状态改变
SlideLaserPenInkPointsChanged
监听发送激光笔的墨迹
SlideInkVisible
监听是否显示标注内容
SlideInkToolbarVisible
监听是否使用激光笔和标注
SlideChangeOperator
监听服务端幻灯片更新后通知当前操作者（用户新增、移动、删除幻灯片后触发）
MiniThumbnailVisibleInfo
监听播放缩略图的打开关闭状态
OnDocViewChange
监听文档操作变化，可应用于会议同步场景

使用方法如下：

js
instance.ApiEvent.AddApiEventListener('SlideShowBegin', data => {
  console.log('SlideShowBegin: ', data)
})

监听 PDF 事件 ​

PDF 组件对应可监听的事件列表有：

事件名说明
CurrentPageChange
监听「当前页码改变」事件
Scroll
监听滚动事件
ZoomUpdated
监听缩放事件
StartPlay
监听进入播放事件
EndPlay
监听退出播放事件
PicSelectionChange
图片选区变更
TextSelectChange
文本选区变更

使用方法如下：

js
instance.ApiEvent.AddApiEventListener('CurrentPageChange', data => {
  console.log('CurrentPageChange: ', data)
})