Event handling

fileOpen

Fires when the document finishes loading. Listen for this event to run initialization logic after the document is ready, or to detect whether the document opened successfully.

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

Fires when an error occurs in the document. Listen for this event to display error messages or trigger fallback logic in your application.

Usage

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

Response parameters

{
  reason: "Fail"
}

tabSwitch

Fires when the user switches to a different toolbar tab. Listen for this event to track the active tab or update your UI accordingly.

Usage

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

Response parameters

// Example: Excel
{
  tabKey: "InsertTab",
}

fileStatus

Fires when the file save status changes. Listen for this event to show save indicators in your UI, such as "Saving..." or "All changes saved".

Usage

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

Response parameters

Status values:

// Example: check save status in the callback
instance.ApiEvent.AddApiEventListener("fileStatus", (data) => {
  if (data.status === 6) {
    console.log("Saving...");
  } else if (data.status === 7) {
    console.log("All changes saved.");
  } else if (data.status === 5) {
    console.log("Save failed. Please retry.");
  }
});

previewLimit

Fires when the user scrolls to the bottom of the last page allowed in preview mode. Listen for this event to prompt users to purchase access or display a preview-limit message.

Usage

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

Response parameters

// Word document (flow layout — exact page count unavailable)
{
  total: 4,
}

// PPT and PDF
{
  total: 4,
  realTotal: 10,
}

hasDocMap

Fires to indicate whether the document contains a table of contents. Because the Word component retrieves the table of contents using dynamic sharding, listen for this event to determine whether a table of contents is present before displaying navigation UI.

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

fullscreenchange

Fires when the document enters or exits full-screen mode. Listen for this event to update your application layout when full-screen state changes.

If isBrowserViewFullscreen or isIframeViewFullscreen is set in commonOptions, this event has no effect.

Usage

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

Response parameters

{
  status: 0, // Exited full-screen mode.
  status: 1, // Entered full-screen mode.
}

webSocketStatus

Fires when the WebSocket connection status changes. Listen for this event to show connection indicators or handle offline scenarios in your application.

Usage

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

Response parameters

Status values:

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

fileNameChange

Fires after the file is successfully renamed. Listen for this event to update the file name displayed in your application UI.

Usage

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

Response parameters

{
  fileName: "NewName"
}

filePasswordStatus

Fires to report the password status of an encrypted file. Listen for this event to prompt users to enter a password or display an error when an incorrect password is entered.

Usage

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

Response parameters

Status values:

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

ModelVisible

Fires when a modal opens or closes. For example, this event fires when you choose More > Print.

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

OnBroadcast

Fires on a global broadcast in multi-user collaboration sessions. Listen for this event to synchronize state or display notifications across connected users.

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