You can use the ApiEvent event mechanism to listen to the interactive behavior of a document. This topic describes the mechanism and usage of event handling.

Overview

The JS-SDK provides the ApiEvent event mechanism that allows you to listen to the interactive behaviors of the document and trigger the JavaScript code that you define. The events include public events and component events, such as Word component events and Excel component events. Public events can be used in all major components.

The JS-SDK event mechanism supports binding multiple callback functions to the same event, and unbinding functions from registered events.

Important

JS-SDK V1.1.14 and later support this feature. For earlier versions, use instance.on or instance.Application.Sub to register events.
JS-SDK event mechanism adjustment: instance.on and instance.Application.Sub will be deprecated in later versions. Use ApiEvent instead.

Usage

// Obtain the JS-SDK instance object.
const instance = aliyun.config({
  url: 'online document preview URL',
})

await instance.ready()

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

// Listen to the events.
instance.ApiEvent.AddApiEventListener('tabSwitch', handle)

// Stop listening to the events.
instance.ApiEvent.RemoveApiEventListener('tabSwitch', handle)

The event mechanism in previous versions

instance.on and instance.off are used to register public events. instance.Application.Sub are used to register the events within components. Use the on and off methods of the JS-SDK instance to enable and disable the event listening feature.

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

// Listen to the events.
instance.on('tabSwitch', handle)

// Stop listening to the events.
instance.on('tabSwitch', handle)

Listen to public events

The following table lists the public events.

Event name	Description
fileOpen	The file opens successfully or not.
error	An error occurs.
tabSwitch	The tab switches.
fileStatus	The saving status of the file.
previewLimit	The limited page is reached in preview.
hasDocMap	The file has a table of contents or not.
fullscreenchange	Enters or exits the full screen mode.
webSocketStatus	The connection status of the WebSocket.
fileNameChange	The file is renamed.
filePasswordStatus	The password status of encrypted files.
ModelVisible	The modal box opens or closes.
OnBroadcast	Global broadcast.

fileOpen

The callback of the fileOpen event.

Important

You need to register the event prior to instance.ready().

Usage

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

Success response

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

Failure response

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

error

The callback of the error event.

Usage

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

Response parameters

{
  reason: "Fail"
}

tabSwitch

The callback of tabSwitch event.

Usage

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

Response parameters

// Use Excel as an example.
{
  tabKey: "InsertTab",
  tabKey: "StartTab",
  // For more information about status, see the specific tabs.
}

fileStatus

The callback of the fileStatus event.

Usage

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

Response parameters

{
  status: 0, // The file is not updated.
  status: 1, // The version is saved. Trigger condition: manual saving, saving the file at a scheduled time, and automatic saving when the web page is closed.
  status: 2, // The file is empty and cannot be saved. Trigger condition: The file is empty after the kernel is saved.
  status: 3, // The storage space is used up.
  status: 4, // Frequent file saving operations are not allowed when the file is being saved. Trigger condition: The saving operation queue is full on the server.
  status: 5, // Failed to save the file.
  status: 6, // The file is being saved. Trigger condition: You update the file.
  status: 7, // The file is successfully saved. Trigger condition: You modify the file content.
}

previewLimit

The callback of the previewLimit event. The event is triggered when you scroll to the bottom of the limited page.

Important

This event is valid in page preview mode and supports only Word, PPT, and PDF components.

Usage

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

Response parameters

// Text file.
// Because text files use liquid layout, the exact number of pages cannot be obtained. The callback only has the total parameter.
{
  total: 4; // The page limit.
}
// PPT and PDF
{
  total: 4; // The page limit.
  realTotal: 10; // The total number of pages.
}

hasDocMap

If the file has a table of contents, a callback is executed.

Important

This event supports only the Word component. The Word component obtains the table of contents by using dynamic sharding. Therefore, you must listen to the hasDocMap event to determine whether the table of contents exists.

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

fullscreenchange

A callback is executed when you enter or exit full screen.

If isBrowserViewFullscreen or isIframeViewFullscreen is configured under commonOptions, this listener is invalid.

Usage

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

Response parameters

{
  status: 0, // Exits full screen.
  status: 1, // Enters full screen.
}

webSocketStatus

Listen to the connection status of the webSocket.

Usage

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

Response parameters

{
  status: '_online', // Connected
  status: '_offline', // Disconnected
  status: '_close', // Connection closed
}

fileNameChange

The callback of the fileNameChange event. After the file is successfully renamed, the new file name is returned.

Usage

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

Response parameters

{
  fileName: "NewName"
}

filePasswordStatus

Listen to the password status of encrypted files.

Important

You need to register this event prior to instance.ready().

Usage

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

Response parameters

{
  status: 'NeedPassword', // A password is required.
  status: InvalidPassword, // The password is incorrect.
}

ModelVisible

This event is triggered when a modal box is opened or closed. For example, this event is triggered when you choose More > Print.

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

OnBroadcast

Listen to global broadcasts for multi-user collaboration.

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

Listen to the events of the Word component

The following table lists the events of the Word component that can be listened to.

Event name	Description
CurrentPageChange	The page number changes.
ClipboardCopy	The content is copied to the clipboard.
DocMapPanelChange	The table of contents is displayed or hidden.
WindowScrollChange	The document window is scrolled. Note that this event is not triggered when you scroll the page.
WindowSelectionChange	The selection changes.
FontMissing	The font is missing.
DocMapItemClick	The table of contents is clicked.
ControlItemClick	The content control is clicked.
ContentChange	The document content changes.

Example

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

Listen to the events of the Excel component

The following table lists the events of the Excel component that can be listened to.

Event name	Description
Clipboard_Copy	The content is copied to the clipboard.
Worksheet_Activate	The active worksheet changes.
Worksheet_SelectionChange	The selection changes.
Worksheet_ScrollChange	The user scrolls the worksheet.
Worksheet_ForceLandscape	A notification is sent when the worksheet enters the landscape mode by force.
Change	The cell is updated.

Example

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

Listen to the events of the PPT component

The following table lists the events of the PPT component that can be listened to.

Event name	Description
SlideShowBegin	The full-screen slide show begins.
SlideShowEnd	The full-screen slide show ends.
SlideShowOnNext	The operation that triggers the next animation is performed.
SlideShowOnPrevious	The operation that triggers the previous animation is performed.
SlideSelectionChanged	The content in the current slide changes.
ActiveSlideChange	The active slide changes.
VideoFullscreenInfo	The video in the presentation file enters or exits the full-screen mode.
TriggerPlayEvent	The animation is triggered.
SlideMove	The slide is moved in the presentation file.
PresentationNewSlide	A slide is added to the presentation file.
SlideDelete	The slide is deleted from the presentation file.
SlidePlayerChange	The player status changes.
SlideMediaChanged	The video playback status changes.
SlideLaserPenInkPointsChanged	The ink position of the laser pointer changes.
SlideInkVisible	The annotation is displayed or hidden.
SlideInkToolbarVisible	The laser pointer and annotation are turned on or off.
SlideChangeOperator	A notification is sent to the current user after the user adds, moves, or deletes a slide.

Example

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

Listen to the events of the PDF component

The following table lists the events of the PDF component that can be listened to.

Event name	Description
CurrentPageChange	The page number changes.
Scroll	The document is scrolled.
ZoomUpdated	The document is zoomed in or out.
StartPlay	Playback starts.
EndPlay	Playback ends.
PicSelectionChange	The image selection changes.
TextSelectChange	The text selection changes.

Example

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