Skip to main content

Advanced Usage

Listening to Events​

Event Mechanism Introduction​

JSSDK provides an ApiEvent event mechanism that allows you to listen to document interaction behaviors and run some JavaScript code when triggered.

Events provided by JSSDK are divided into public events and component events (such as text events, spreadsheet events, etc.). Public events can be used in all major components.

JSSDK event mechanism only supports binding one callback function to the same event. Repeated binding only keeps the latest callback function.

Usage

const Application = await ZOfficeSDK.mount('http://172.16.22.98/docs/app/thirdparty-rest/1347466381985058817/edit/content?zdocs_access_token=653b90d845a785e3c69aeba', '#doc1');

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

// Listen to event
Application.addListener('Workbook.Event.SheetActivate', handle);

// Cancel listening
Application.removeListener('Workbook.Event.SheetActivate', handle);

Listening to Public Events​

List of Listenable Events:

Event NameDescription
IDocs.Event.FullScreenChangeTriggered when entering or exiting full screen
IDocs.Event.SessionExpireTriggered when session expires
IDocs.Event.FileStatusTriggered when file is saved or saved as

IDocs.Event.FullScreenChange​

Usage

const listenerId = await Application.addListener('IDocs.Event.FullScreenChange', (data) => {
  console.log("FullScreenChange: ", data);
});	// Application: Spreadsheet/Text application object

// Remove specific listener for the event
await Application.removeListener('IDocs.Event.FullScreenChange', listenerId);

// Remove all listeners for the event
await Application.removeListener('IDocs.Event.FullScreenChange');

Return Parameters

{
  status: 0, // Exit full screen
  status: 1, // Enter full screen
}

IDocs.Event.SessionExpire​

Usage

Application.addListener('IDocs.Event.SessionExpire', () => {
  console.log("SessionExpired");
});	// Application: Spreadsheet/Text application object

IDocs.Event.FileStatus​

Usage

Application.addListener('IDocs.Event.FileStatus', (data) => {
  console.log("FileStatus: ", data);
});	// Application: Spreadsheet/Text application object

Return Parameters

{
  status: 0, // Document has no updates
  status: 1, // Document saved successfully
  status: 2, // Document save failed
}

Listening to Spreadsheet Events​

List of Listenable Events:

Event NameDescription
Workbook.Event.SheetActivateTriggered when a worksheet is activated
Workbook.Event.ChangeTriggered when workbook content changes
Workbook.Event.SelectionChangeTriggered when workbook selection changes
Workbook.Event.BeforeEditTriggered before a worksheet cell enters edit mode
Workbook.Event.NamesAddedTriggered after a workbook name is created
Workbook.Event.NamesModifiedTriggered after a workbook name is modified
Workbook.Event.NamesDeletedTriggered after a workbook name is deleted

Workbook.Event.SheetActivate​

Usage

const listenerId = await Application.addListener('Workbook.Event.SheetActivate', (activatedSheet) => {
  console.log(activatedSheet.name, 'has been activated');
});	// Application: Spreadsheet application object

// Remove specific listener for the event
await Application.removeListener('Workbook.Event.SheetActivate', listenerId);

// Remove all listeners for the event
await Application.removeListener('Workbook.Event.SheetActivate');

Return Parameters

Return ValueTypeDescription
activatedSheetAn Excel.Sheet objectThe activated worksheet

Workbook.Event.Change​

Usage

Application.addListener('Workbook.Event.Change', (range) => {
            console.log('something changed in: ', range.getSheet().name,
            '\nStart row: ', range.row,
            '\nStart column: ', range.column,
            '\nEnd row: ', range.endRow,
            '\nEnd column: ', range.endColumn);
          };
);	// Application: Spreadsheet application object

Return Parameters

Return ValueTypeDescription
rangeAn Excel.Range objectThe range where changes occurred

Workbook.Event.SelectionChange​

Usage

var Application = await ZOfficeSDK.applications.get('#doc-container1'); 
Application.addListener('Workbook.Event.SelectionChange', (range) => {
    console.log('selection changed in: ', range.getSheet().name,
    '\nStart row: ', range.row,
    '\nStart column: ', range.column,
    '\nEnd row: ', range.endRow,
    '\nEnd column: ', range.endColumn);
});

Return Parameters

Return ValueTypeDescription
rangeAn Excel.Range objectThe range where selection changed

Workbook.Event.BeforeEdit​

Usage

Application.addListener('Workbook.Event.BeforeEdit', (sheet, cell) => {
    console.log(sheet.name, 'worksheet', cell.row, 'row', cell.column, 'column', 'is going to enter edit mode!');
});	// Application: Spreadsheet application object

Return Parameters

Return ValueTypeDescription
sheetAn Excel.Sheet objectThe worksheet where the cell entering edit mode is located
cellAn Excel.Range objectThe cell entering edit mode

Workbook.Event.NamesAdded​

Usage

Application.addListener('Workbook.Event.NamesAdded', (nameId) => {
  console.log(nameId, 'has been added');
});	// Application: Spreadsheet application object

Return Parameters

Return ValueTypeDescription
nameIdstringID of the newly added name

Workbook.Event.NamesModified​

Usage

Application.addListener('Workbook.Event.NamesModified', (nameId) => {
  console.log(nameId, 'has been modified');
});	// Application: Spreadsheet application object

Return Parameters

Return ValueTypeDescription
nameIdstringID of the modified name

Workbook.Event.NamesDeleted​

Usage

Application.addListener('Workbook.Event.NamesDeleted', (nameId) => {
  console.log(nameId, 'has been deleted');
});	// Application: Spreadsheet application object

Return Parameters

Return ValueTypeDescription
nameIdstringID of the deleted name

Listening to Text Events​

List of Listenable Events:

Event NameDescription
IDOCS.EVENT.selectionChangeCursor change
IDocs.Event.ContentChangeContent change
IDocs.Event.CommentActionComment operation (currently only supports delete operation)
Word.Event.PermMarkActionEditable area operation (add/delete)

IDOCS.EVENT.selectionChange​

Usage

Application.addListener('IDOCS.EVENT.selectionChange', () => {
  console.log('selectionChanged');
}); // Application: Text application object

IDocs.Event.ContentChange​

Currently only supports bookmark content change listening

JSSDK: 1.7.22、zOffice V7.2 FP3 support

Usage

Application.addListener('IDocs.Event.ContentChange', (data) => {
  console.log('ContentChange',data);
}); // Application: Text application object

Return Value Data Structure

{
  type:string,//bookmark
  data:[
      {
        id:'',//Bookmark name
        newData:string,//Content of bookmark area after change
        oldData:string//Content of bookmark area before change    
      }
    ]
}

IDocs.Event.CommentAction​

JSSDK: 1.8.2、zOffice V7.3 FP2 support

Usage

Application.addListener('IDocs.Event.CommentAction', (data) => {
  console.log('CommentAction',data);
}); // Application: Text application object

Return Value data Data Structure

{
  type: 'delete',
  data: {
    user: {
      id: string, // User ID who deleted the comment
      name: string  // Username who deleted the comment
    },
    bAll: boolean;  // When deleting all comments, there is no data below
    data: [
      {
        content: string,  // Comment content
        creator: {
          uid: string,  // Comment creator ID
          name: string  // Comment creator name
        },
        id: string,     // Comment ID
        pid: string,    // Parent comment ID (if it's a reply, this field will be returned)
        time: number,   // Comment creation timestamp
        done: boolean   // Whether the comment is resolved
      },
      ...
    ]
  }
}

Word.Event.PermMarkAction​

JSSDK: 1.9.1、zOffice V8.0 FP1 support

Usage

Application.addListener('Word.Event.PermMarkAction', async (data) => {
  const { type, data } = data;
  if (type === 'add') {
    const pm = await Application.ActiveDocument.PermMarks.item(data.id);
  } else if (type === 'delete') {
    console.log(`id: ${data.id}`);
  } else if (type === 'edit') {
    console.log(`id: ${data.id}`);
  }
}); // Application: Text application object

Listening to Presentation Document Events​

JSSDK: 1.7.0、zOffice7.2 support

List of Listenable Events:

Event NameDescription
IDocs.Event.OnDocViewChangeDocument view change

IDocs.Event.OnDocViewChange​

Usage

Application.addListener('IDOCS.EVENT.OnDocViewChange', (docView) => {
  console.log(docView);
}); // docvView: IDocView type
Last updated on