公共处理方法

概述

本页描述 OfficeSDK 实例上的公共 API，也就是不依赖具体编辑器套件、宿主侧可以统一调用的能力。

这类能力主要用于：

建立连接并等待 SDK 就绪

读取当前文件类型和加载状态

监听 SDK / 编辑器通用事件

获取当前编辑器实例

断开连接

更新鉴权信息

HeaderBars 虽然也挂在 sdk 根级实例上，但它属于独立扩展能力，不在本页展开。请查看 HeaderBars。

使用示例

方法列表

API	说明
`connect(options)`	创建并连接 SDK，返回 `OfficeSDK` 实例
`sdk.ready()`	等待 SDK 进入可交互状态
`sdk.on(event, listener)`	监听事件
`sdk.once(event, listener)`	监听一次性事件
`sdk.off(event, listener?)`	取消事件监听
`sdk.fileType`	获取当前文件类型
`sdk.readyState`	获取当前 SDK 状态
`sdk.getEditor()`	获取当前编辑器实例
`sdk.disconnect()`	断开连接并移除 iframe
`sdk.setCredentials(payload)`	更新鉴权信息
`sdk.setSignature(signature)`	仅更新 signature，已废弃
`sdk.setToken(token)`	仅更新 token，已废弃
`sdk.getPerformanceEntries()`	获取性能信息片段列表

connect(options)

说明

创建并初始化一个 OfficeSDK 实例。

返回值

返回 Promise<OfficeSDK>。

说明补充

connect() 成功后返回 sdk

后续所有公共 API 和编辑器 API 都从该实例继续调用

sdk.ready()

说明

等待 SDK 进入 Ready 状态。若当前已经 ready，则会直接返回。

返回值

返回 Promise<void>。

适用场景

在调用具体编辑器能力前等待可交互状态

需要确保 fileType、根级 API 或编辑器方法已经可用

sdk.on(event, listener)

说明

监听 SDK 或编辑器转发出来的通用事件。

常见事件

Event.Error：错误事件

Event.ReadyState：SDK 状态变化事件

Event.EditorRendered：编辑器完成首屏渲染

返回值

返回当前 sdk 实例，便于链式调用。

sdk.once(event, listener)

说明

监听一次性事件，回调触发后会自动取消监听。

返回值

返回当前 sdk 实例。

sdk.off(event, listener?)

说明

取消事件监听。

参数

event：事件名

listener：要移除的监听函数；不传时会移除该事件下的监听

返回值

返回当前 sdk 实例。

sdk.fileType

说明

读取当前文件类型。

类型

适用场景

根据当前套件决定后续调用哪组编辑器 API

在一个统一入口中分发不同文档类型的处理逻辑

sdk.readyState

说明

读取当前 SDK 状态。

类型

说明补充

常见状态包括：

Loading

LoadingEditor

Ready

Failed

sdk.getEditor()

说明

获取当前文件对应的编辑器实例。

返回值

返回当前套件对应的编辑器实例类型。

说明补充

这是兼容历史代码的通用入口

如果当前文档已经提供根级 API，新增代码优先使用根级 API 写法

sdk.disconnect()

说明

断开 SDK 连接，并从宿主容器中移除当前 iframe。

适用场景

页面卸载

路由切换

需要主动销毁当前编辑器实例

sdk.setCredentials(payload)

说明

实时更新鉴权 signature 和 token。

参数

payload.signature：新的石墨鉴权签名

payload.token：新的业务 token

返回值

返回 Promise<void>。

说明补充

适用于长时间停留页面后刷新鉴权信息

相比单独更新 signature 或 token，优先使用这个方法

sdk.setSignature(signature)

说明

仅更新石墨鉴权 signature。

返回值

返回 Promise<void>。

说明补充

该方法已废弃，建议改用 sdk.setCredentials()。

sdk.setToken(token)

说明

仅更新业务 token。

返回值

返回 Promise<void>。

说明补充

该方法已废弃，建议改用 sdk.setCredentials()。

sdk.getPerformanceEntries()

说明

获取性能信息片段列表。

返回值

返回 Promise<PerformanceEntry[]>。

说明补充

该列表是分段、异步采集的

不同时间调用，返回结果可能不完全一致

概述#

使用示例#

方法列表#

connect(options)#

说明#

返回值#

说明补充#

sdk.ready()#

说明#

返回值#

适用场景#

sdk.on(event, listener)#

说明#

常见事件#

返回值#

sdk.once(event, listener)#

说明#

返回值#

sdk.off(event, listener?)#

说明#

参数#

返回值#

sdk.fileType#

说明#

类型#

适用场景#

sdk.readyState#

说明#

类型#

说明补充#

sdk.getEditor()#

说明#

返回值#

说明补充#

sdk.disconnect()#

说明#

适用场景#

sdk.setCredentials(payload)#

说明#

参数#

返回值#

说明补充#

sdk.setSignature(signature)#

说明#

返回值#

说明补充#

sdk.setToken(token)#

说明#

返回值#

说明补充#

sdk.getPerformanceEntries()#

说明#

返回值#

说明补充#

概述

使用示例

方法列表

connect(options)

说明

返回值

说明补充

sdk.ready()

说明

返回值

适用场景

sdk.on(event, listener)

说明

常见事件

返回值

sdk.once(event, listener)

说明

返回值

sdk.off(event, listener?)

说明

参数

返回值

sdk.fileType

说明

类型

适用场景

sdk.readyState

说明

类型

说明补充

sdk.getEditor()

说明

返回值

说明补充

sdk.disconnect()

说明

适用场景

sdk.setCredentials(payload)

说明

参数

返回值

说明补充

sdk.setSignature(signature)

说明

返回值

说明补充

sdk.setToken(token)

说明

返回值

说明补充

sdk.getPerformanceEntries()

说明

返回值

说明补充