Skip to main content

监听事件

监听事件​

事件机制介绍​

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(Sheet.Event.SheetActivate, handle);

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

监听公共事件​

可监听的事件列表：

事件名使用方法说明
FileOpenIDocs.Event.FileOpen当文档打开时触发该事件（包括 reload 后重新打开）
FullScreenChangeIDocs.Event.FullScreenChange当进入或者退出全屏时触发该事件
SessionExpireIDocs.Event.SessionExpire当session过期时触发该事件
FileStatusIDocs.Event.FileStatus当文件保存或另存为时触发该事件

FileOpen​

该事件在文档每次打开时触发，包括文档 reload 后重新打开的场景。与其他事件不同，该事件通过 ZOfficeSDK.addListener 监听，不受文档 reload 影响。

适用于在文档打开后重新注册事件监听或重新设置 SDK 配置，详见【文档 reload 后事件监听/SDK配置失效】。

示例

ZOfficeSDK.addListener('.my-doc-editor', IDocs.Event.FileOpen, async () => {
    console.log('file open');
    const app = await ZOfficeSDK.connect('.my-doc-editor');
    await app.ready();

    // 在此处注册事件监听或设置 SDK 配置
    Application.addListener(IDocs.Event.FileStatus, (data) => {
        console.log('FileStatus: ', data);
    });
});

注意： 该事件通过 ZOfficeSDK.addListener 监听（第一个参数为挂载容器选择器），而非 Application.addListener。

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, // 进入全屏
}

SessionExpire​

示例

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

FileStatus​

示例

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

返回参数

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

监听表格事件​

可监听的事件列表：

事件名使用方法说明
SheetActivateSheet.Event.SheetActivate当工作表被激活时触发该事件
ContentChangeIDocs.Event.ContentChange当工作簿内容产生变化时触发该事件
SelectionChangeIDocs.Event.SelectionChange当工作簿选区产生变化时触发该事件
BeforeEditSheet.Event.BeforeEdit当工作表单元格进入编辑模式之前触发该事件
NamesAddedSheet.Event.NamesAdded当工作簿创建名称后触发该事件
NamesModifiedSheet.Event.NamesModified当工作簿名称发生修改后触发该事件
NamesDeletedSheet.Event.NamesDeleted当工作簿名称被删除后触发该事件

SheetActivate​

示例

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

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

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

返回参数

返回值类型说明
activatedSheetSheet.Sheet对象被激活的工作表

ContentChange​

示例

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

返回参数

返回值类型说明
rangeSheet.Range对象产生变化的区间

SelectionChange​

示例

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

返回参数

返回值类型说明
rangeSheet.Range对象产生变化的区间

BeforeEdit​

示例

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

返回参数

返回值类型说明
sheetSheet.Sheet对象进入编辑模式单元格所在的工作表
cellSheet.Range对象进入编辑模式的单元格

NamesAdded​

示例

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

返回参数

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

NamesModified​

示例

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

返回参数

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

NamesDeleted​

示例

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

返回参数

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

监听文字事件​

可监听的事件列表：

事件名使用方法说明
ScrollIDocs.Event.Scroll文档滚动
SelectionChangeIDocs.Event.SelectionChange光标变化
ContentChangeIDocs.Event.ContentChange内容变化
CommentActionIDocs.Event.CommentAction批注操作（暂仅支持删除操作）
PermMarkActionWriter.Event.PermMarkAction可编辑区域操作（添加/删除）

SelectionChange​

示例

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

ContentChange​

支持书签和可编辑区域内容变化监听

JSSDK: 1.7.22、FilezOffice V7.2 FP3 支持（书签内容变化）

JSSDK: 1.9.1、FilezOffice V8.0 FP1 支持（可编辑区域内容变化）

示例

Application.addListener(IDocs.Event.ContentChange, (data) => {
  console.log('ContentChange', data);
  if (data.type === 'bookmark') {
    // 处理书签内容变化
    console.log('书签内容发生变化:', data.data);
  } else if (data.type === 'permMark') {
    // 处理可编辑区域内容变化
    console.log('可编辑区域内容发生变化:', data.data);
  }  
}); // Application: 文字应用对象

返回值Data数据结构

当书签内容变化时：

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

当可编辑区域内容变化时：

{
  type: 'permMark',
  data: [
    {
      id: '',  // 可编辑区域名称
      newData: string,  // 变化后的可编辑区域内容
      oldData: string   // 变化前的可编辑区域内容    
    }
  ]
}

CommentAction​

JSSDK: 1.8.2、FilezOffice 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   // 批注是否已解决
      },
      ...
    ]
  }
}

Scroll​

JSSDK: 1.10.1、FilezOffice v8.2 FP1 支持

示例

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

返回参数

返回值类型说明
data.ScrollLeftnumber文档水平滚动距离（单位 px）
data.ScrollTopnumber文档垂直滚动距离（单位 px）

PermMarkAction​

JSSDK: 1.9.1、FilezOffice V8.0 FP1 支持

示例

Application.addListener(Writer.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、FilezOffice v7.2 支持

可监听的事件列表：

事件名使用方法说明
OnDocViewChangeIDocs.Event.OnDocViewChange文档视图变化

OnDocViewChange​

示例

Application.addListener(IDocs.Event.OnDocViewChange, (docView) => {
  console.log(docView);
}); // docvView: IDocView类型

监听PDF文档事件​

JSSDK: 1.9.4、FilezOffice v8.0 FP4 支持

** 可监听的事件列表：**

事件名使用方法说明
PicturePlacedPDF.Event.PicturePlaced放置图片事件

PicturePlaced​

JSSDK: 1.9.4、FilezOffice v8.0 FP4 支持

示例

Application.addListener(IDocs.Event.PicturePlaced, ({ id }) => {
  console.log(id);
}); // 取消放置图片时用到的id
Last updated on