Skip to content

事件机制

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

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

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

注意

JSSDK: v1.1.14+、WebOffice v3.3.1+ 支持,低于该版本请使用 jssdk.onjssdk.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

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

此事件只在预览页数模式下有效,仅支持 WordPPTPDF 组件

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
发现有缺失的字体
DocMapItemClick
监听大纲中目录点击事件

使用方法如下:

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
监听播放缩略图的打开关闭状态

使用方法如下:

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)
})