文档

事件处理

更新时间:

为了监听文档的交互行为,可以使用ApiEvent事件机制,本文介绍事件处理机制和使用方法。

概述

JS-SDK提供了ApiEvent事件机制,使您可以监听文档的交互行为,并在触发时运行一些JavaScript代码。提供的事件分为公共事件和组件事件(例如文字事件、表格事件等),公共事件在各大组件中都能使用。

JS-SDK事件机制支持对同一个事件绑定多个回调函数,也支持对已注册的事件取消绑定。

重要
  • V1.1.14及以上版本JS-SDK支持此功能,低于该版本请使用instance.oninstance.Application.Sub注册事件。

  • JS-SDK事件机制调整说明:instance.oninstance.Application.Sub将在后续版本中被弃用,请使用改进后的ApiEvent

使用方式

// 获取JS-SDK实例对象
const instance = aliyun.config({
  url: '在线文档预览地址',
})

await instance.ready()

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

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

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

旧版事件机制介绍

instance.oninstance.off用于注册公共事件,instance.Application.Sub用于注册组件内事件,通过JS-SDK实例的on方法监听事件,off方法取消监听。

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

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

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

监听公共事件

公共事件如下表所示。

事件名

说明

fileOpen

文档打开。

error

错误事件。

tabSwitch

PC头部Tab切换。

fileStatus

文件保存状态。

previewLimit

预览页数限制事件。

hasDocMap

文档是否存在目录。

fullscreenchange

进入或退出全屏事件。

webSocketStatus

监听webSocket的连接状态。

fileNameChange

文件重命名。

filePasswordStatus

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

ModelVisible

模态框打开和关闭时触发。

OnBroadcast

全局广播事件。

fileOpen

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

重要

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

使用

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

成功响应

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

失败响应

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

error

错误发生时的事件回调。

使用

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

返回参数

{
  reason: "Fail"
}

tabSwitch

文档Tab切换的事件回调。

使用

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

返回参数

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

fileStatus

文件保存的事件回调。

使用

instance.ApiEvent.AddApiEventListener("fileStatus", (data) => {
  console.log("fileStatus: ", data);
});

返回参数

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

previewLimit

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

重要

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

使用

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

返回参数

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

hasDocMap

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

重要

此事件仅支持文字组件(Word),由于文字获取目录是动态分片获取,因此需要以监听事件方式确定是否存在目录。

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

fullscreenchange

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

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

使用

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

返回参数

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

webSocketStatus

监听webSocket的连接状态。

使用

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

返回参数

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

fileNameChange

文件名重命名的事件回调。当文件重命名成功后,会返回新文件名。

使用

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

返回参数

{
  fileName: "NewName"
}

filePasswordStatus

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

重要

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

使用

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

返回参数

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

ModelVisible

模态框打开和关闭时触发,例如更多>打印

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

OnBroadcast

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

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

监听文字事件

文字组件(Word)对应可监听的事件如下表所示。

事件名

说明

CurrentPageChange

监听当前页码改变事件。

ClipboardCopy

监听剪切板复制事件。

DocMapPanelChange

监听目录的显示与隐藏事件。

WindowScrollChange

监听文档滚动事件,注意不是页面滚动。

WindowSelectionChange

监听选区变化事件。

FontMissing

发现有缺失的字体。

DocMapItemClick

监听大纲中目录点击事件。

ControlItemClick

内容控件点击事件

ContentChange

监听文档内容改变事件

示例

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

监听表格事件

表格组件(Excel)对应可监听的事件如下表所示。

事件名

说明

Clipboard_Copy

监听剪切板复制事件。

Worksheet_Activate

监听工作表的切换。

Worksheet_SelectionChange

监听选区改变事件。

Worksheet_ScrollChange

监听用户自己的滚动画布行为。

Worksheet_ForceLandscape

监听强制横屏时通知。

Change

监听单元格更新

示例

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

监听服务端幻灯片更新后通知当前操作者(用户新增、移动、删除幻灯片后触发)。

示例

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

监听PDF事件

PDF组件对应可监听的事件如下表所示。

事件名

说明

CurrentPageChange

监听当前页码改变事件。

Scroll

监听滚动事件。

ZoomUpdated

监听缩放事件。

StartPlay

监听进入播放事件。

EndPlay

监听退出播放事件。

PicSelectionChange

图片选区变更。

TextSelectChange

文本选区变更。

示例

instance.ApiEvent.AddApiEventListener("CurrentPageChange", (data) => {
  console.log("CurrentPageChange: ", data);
});
  • 本页导读 (1)