WPS 基础接口 > 加载项 API 参考 > 事件 > ApiEvent 对象

ApiEvent 对象用于接收 WPS 应用程序各种事件通知。

说明

ApiEvent对象用于注册和反注册 WPS 事件回调函数,注册一个事件回调函数的接口为:ApiEvent.AddApiEventListener(eventName, func), 其中eventName表示要响应的事件类型,这些事件类型由wps内部规定,func表示要回调的js函数,当wps有某个事件被触发时,这些注册的js函数会被wps执行。 例如需要在打开文档时,弹出一个打开文档后的消息框,示例代码如下如下:

示例代码
wps.ApiEvent.AddApiEventListener("DocumentOpen", (doc)=>{alert("文档已打开,文档名是: " + doc.Name)});

同样,如果不再需要某个已注册的回调函数,可以把相关的回调函数进行反注册,wps内部也会在网页关闭时,把网页中所有已注册的回调函数自动反注册,反注册一个回调函数的方式为: ApiEvent.RemoveApiEventListener(eventName)。其中eventName表示事件类型,反注册后当前网页不再有此事件的回调函数被执行。

示例代码
wps.ApiEvent.RemoveApiEventListener("DocumentOpen")

api事件分为询问型事件和通知型事件,询问型事件是指wps在准备做某一个事情时发出事件回调,第三方代码有机会来控制这个事情, 通知型事件是指wps做了某个事件后通知第三方代码这个事情已经结束,这种情况下事情已然发生。以上面的几个事件类型为例, DocumentBeforeClose和DocumentBeforeSave事件是询问型事件,其它几个是通知型事件。下面分别对两种事件各举一个例子

1.询问型事件:
示例:当用户想保存一个文件时,通过js事件回调禁止保存这个文件,代码如下:
示例代码

let func = (doc)=>{
	wps.alert(doc.Name)
	wps.ApiEvent.Cancel = true
}										
window.ApiEvent.AddApiEventListener("DocumentBeforeSave", func)
										

上面代码的意思是在文件保存前OnDocBeforeSave这个js函数被调用到,此时js函数里边通过ApiEvent.Cancel这个属性设置了要取消掉这次流程, wps执行完OnBeforeSave这个js函数后,检测到Cancel属性被设置为true, 从而中止了保存流程。 对于询问型事件,一般是通过Cancel属性来继续或是中止流程的执行。

2.通知型事件:
示例:示例:当用户打开文件后弹出这个文件的磁盘路径,代码如下:
示例代码

let func = (doc)=>{
	wps.alert(doc.Name)
}										
wps.ApiEvent.AddApiEventListener("DocumentOpen", func)
													

上面代码的意思是在文件打开这个事件发生后,wps把事件发生后通知给了网页上注册的回调函数。



关于事件类型的定义,在wps/et/wpp中各有不同,事件类型也基本上保持与office标准的事件类型相对应,详细的事件类型如下表:

wps文字支持的事件类型如下:

事件名称 级别 类型 说明
DocumentOpen
Application
通知型 当打开一个文档后被触发
DocumentBeforeClose
Application
询问型 当文档关闭前被触发,js可以控制是否要中断这个关闭流程
DocumentBeforeSave
Application
询问型 当文档保存前被触发,js可以控制是否要中断这个保存流程
WindowActivate
Application
通知型 当文档窗口发生切换时被触发
DocumentAfterClose
Application
通知型 当文档关闭结束后被触发
AfterLogin
Application
通知型
当用户登录成功后触发
AfterLogout
Application
通知型
当用户退出登录成功后触发

wps表格支持的api事件为:

事件名称 级别 类型 说明
WorkbookOpen
Application
通知型 当打开一个工作簿之后触发
NewWorkbook
Application
通知型
当新建一个工作簿之后触发
WorkbookBeforeSave
Application
询问型
当保存文件之前触发
WorkbookBeforeClose
Application
询问型
当关闭文件之前触发
SheetSelectionChange
Application
通知型
当选区变化之后触发
SheetActivate
Application
通知型
当工作表切换后触发
WindowActivate
Application
通知型
当文档窗口切换后触发
AfterLogin
Application
通知型
当用户登录成功后触发
AfterLogout
Application
通知型
当用户退出登录成功后触发

wps演示支持的api事件为:

事件名称 级别 类型 说明
NewPresentation
Application
通知型
当新建一个文件触发
PresentationOpen
Application
通知型
当打开一个文件触发
PresentationBeforeClose
Application
询问型
当文档关闭前触发
PresentationBeforeSave
Application
询问型
当文档保存前触发
PresentationSave
Application
通知型
当文档保存后触发
WindowActivate
Application
通知型
当文档窗口切换后触发
AfterLogin
Application
通知型
当用户登录成功后触发
AfterLogout
Application
通知型
当用户退出登录成功后触发


请参阅
适用环境:web
适用平台:windows/linux