跳到主要内容

高级用法

监听事件​

事件机制介绍​

JSSDK 提供了 ApiEvent 事件机制，使你可以监听文档的交互行为，并在触发时运行一些 JavaScript 代码。

JSSDK 提供的事件分为公共事件和组件事件（例如文字事件、表格事件等），公共事件在各大组件中都能使用。

JSSDK 事件机制仅支持对同一个事件绑定一个回调函数，重复绑定只保留最新的回调函数。

使用方式

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);

// 监听事件
Application.addListener('Workbook.Event.SheetActivate', handle);

// 取消监听
Application.removeListener('Workbook.Event.SheetActivate', handle);

监听公共事件​

可监听的事件列表：

事件名说明
IDocs.Event.FullScreenChange当进入或者退出全屏时触发该事件
IDocs.Event.SessionExpire当session过期时触发该事件
IDocs.Event.FileStatus当文件保存或另存为时触发该事件

IDocs.Event.FullScreenChange​

使用方法

const listenerId = await Application.addListener('IDocs.Event.FullScreenChange', (data) => {
  console.log("FullScreenChange: ", data);
});	// Application: 表格/文字应用对象

// 移除事件的指定监听
await Application.removeListener('IDocs.Event.FullScreenChange', listenerId);

// 移除事件的所有监听
await Application.removeListener('IDocs.Event.FullScreenChange');

返回参数

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

IDocs.Event.SessionExpire​

使用方法

Application.addListener('IDocs.Event.SessionExpire', () => {
  console.log("SessionExpired");
});	// Application: 表格/文字应用对象

IDocs.Event.FileStatus​

使用方法

Application.addListener('IDocs.Event.FileStatus', (data) => {
  console.log("FileStatus: ", data);
});	// Application: 表格/文字应用对象

返回参数

{
  status: 0, // 文档无更新
  status: 1, // 文档保存成功
  status: 2, // 文档保存失败
}

监听表格事件​

可监听的事件列表：

事件名说明
Workbook.Event.SheetActivate当工作表被激活时触发该事件
Workbook.Event.Change当工作簿内容产生变化时触发该事件
Workbook.Event.SelectionChange当工作簿选区产生变化时触发该事件
Workbook.Event.BeforeEdit当工作表单元格进入编辑模式之前触发该事件
Workbook.Event.NamesAdded当工作簿创建名称后触发该事件
Workbook.Event.NamesModified当工作簿名称发生修改后触发该事件
Workbook.Event.NamesDeleted当工作簿名称被删除后触发该事件

Workbook.Event.SheetActivate​

使用方法

const listenerId = await Application.addListener('Workbook.Event.SheetActivate', (activatedSheet) => {
  console.log(activatedSheet.name, 'has been activated');
});	// Application: 表格应用对象

// 移除事件的指定监听
await Application.removeListener('Workbook.Event.SheetActivate', listenerId);

// 移除事件的所有监听
await Application.removeListener('Workbook.Event.SheetActivate');

返回参数

返回值类型说明
activatedSheet一个Excel.Sheet对象被激活的工作表

Workbook.Event.Change​

使用方法

Application.addListener('Workbook.Event.Change', (range) => {
            console.log('something changed in: ', range.getSheet().name,
            '\n开始行：', range.row,
            '\n开始列：', range.column,
            '\n结束行：', range.endRow,
            '\n结束列：', range.endColumn);
          };
);	// Application: 表格应用对象

返回参数

返回值类型说明
range一个Excel.Range对象产生变化的区间

Workbook.Event.SelectionChange​

使用方法

var Application = await ZOfficeSDK.applications.get('#doc-container1'); 
Application.addListener('Workbook.Event.SelectionChange', (range) => {
    console.log('selection changed in: ', range.getSheet().name,
    '\n开始行：', range.row,
    '\n开始列：', range.column,
    '\n结束行：', range.endRow,
    '\n结束列：', range.endColumn);
});

返回参数

返回值类型说明
range一个Excel.Range对象产生变化的区间

Workbook.Event.BeforeEdit​

使用方法

Application.addListener('Workbook.Event.BeforeEdit', (sheet, cell) => {
    console.log(sheet.name, '工作表', cell.row, '行', cell.column, '列', 'is going to enter edit mode!');
});	// Application: 表格应用对象

返回参数

返回值类型说明
sheet一个Excel.Sheet对象进入编辑模式单元格所在的工作表
cell一个Excel.Range对象进入编辑模式的单元格

Workbook.Event.NamesAdded​

使用方法

Application.addListener('Workbook.Event.NamesAdded', (nameId) => {
  console.log(nameId, 'has been added');
});	// Application: 表格应用对象

返回参数

返回值类型说明
nameIdstring新添加的名称的ID

Workbook.Event.NamesModified​

使用方法

Application.addListener('Workbook.Event.NamesModified', (nameId) => {
  console.log(nameId, 'has been modified');
});	// Application: 表格应用对象

返回参数

返回值类型说明
nameIdstring被修改名称的ID

Workbook.Event.NamesDeleted​

使用方法

Application.addListener('Workbook.Event.NamesDeleted', (nameId) => {
  console.log(nameId, 'has been deleted');
});	// Application: 表格应用对象

返回参数

返回值类型说明
nameIdstring被删除名称的ID

监听文字事件​

可监听的事件列表：

事件名说明
IDOCS.EVENT.selectionChange光标变化
IDocs.Event.ContentChange内容变化
IDocs.Event.CommentAction批注操作（暂仅支持删除操作）
Word.Event.PermMarkAction可编辑区域操作（添加/删除）

IDOCS.EVENT.selectionChange​

使用方法

Application.addListener('IDOCS.EVENT.selectionChange', () => {
  console.log('selectionChanged');
}); // Application: 文字应用对象

IDocs.Event.ContentChange​

当前仅支持书签内容变化监听

JSSDK: 1.7.22、zOffice V7.2 FP3 支持

使用方法

Application.addListener('IDocs.Event.ContentChange', (data) => {
  console.log('ContentChange',data);
}); // Application: 文字应用对象

返回值Data数据结构

{
  type:string,//bookmark
  data:[
      {
        id:'',//书签名称
        newData:string,//变化后的书签区域内容
        oldData:string//变化前的书签区域内容    
      }
    ]
}

IDocs.Event.CommentAction​

JSSDK: 1.8.2、zOffice V7.3 FP2 支持

使用方法

Application.addListener('IDocs.Event.CommentAction', (data) => {
  console.log('CommentAction',data);
}); // Application: 文字应用对象

返回值data数据结构

{
  type: 'delete',
  data: {
    user: {
      id: string, // 删除批注的用户 ID
      name: string  // 删除批注的用户名
    },
    bAll: boolean;  // 是否删除所有批注时，没有下面的 data
    data: [
      {
        content: string,  // 批注内容
        creator: {
          uid: string,  // 批注创建者 ID
          name: string  // 批注创建者名字
        },
        id: string,     // 批注ID
        pid: string,    // 父批注ID（如果是回复，会返回该字段）
        time: number,   // 批注创建时间戳
        done: boolean   // 批注是否已解决
      },
      ...
    ]
  }
}

Word.Event.PermMarkAction​

JSSDK: 1.9.1、zOffice V8.0 FP1 支持

使用方法

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: 文字应用对象

监听演示文档事件​

JSSDK: 1.7.0、zOffice7.2 支持

可监听的事件列表：

事件名说明
IDocs.Event.OnDocViewChange文档视图变化

IDocs.Event.OnDocViewChange​

使用方法

Application.addListener('IDOCS.EVENT.OnDocViewChange', (docView) => {
  console.log(docView);
}); // docvView: IDocView类型
最后于 更新