1. 公共 API
石墨文档中台-开发文档
  • 1. 适用范围
  • 00. 概述
    • 石墨文档中台能做什么？
    • 三种典型的业务接入场景
    • 石墨文档中台支持哪些格式？
  • 01. 快速开始
    • 基本概念
    • 场景一：10 分钟创建预览文件
    • 场景二：10 分钟创建协同编辑文件
  • 02. 鉴权与安全
    • 整体概述
    • 签名凭证 Token
    • 签名凭证 Signature
  • 03. 文件预览
    • 整体概述
    • 如何预热预览缓存
    • 如何防盗链
    • 常见问题处理
  • 04. 文件编辑
    • 整体概述
    • 协同文档权限设计
    • 协同文件保存与更新机制
    • 协同文件复制与删除
  • 05. 文件导入导出
    • 整体概述
    • 常见问题处理
  • 06. 石墨前端 API
    • 整体概述
    • 公共 API
      • 公共处理方法
      • 顶部栏定制 HeaderBars
    • 编辑器 API
      • 轻文档
      • 传统文档
      • 表格
      • 幻灯片
      • 表单
      • 应用表格
  • 07. 石墨后端 API
    • 整体概述
    • 错误码说明
    • 文件-预览 API
      • 访问预览文件
      • 创建文件预览缓存
    • 文件-协同编辑文件管理 API
      • 访问协同编辑文件
      • 创建协同文件
      • 创建协同文件副本
      • 删除协同文件
    • 文件-导入导出 API
      • 文件导入
        • 文件导入说明
        • 创建导入任务
        • 获取导入进度
        • 创建导入任务（旧版）
        • 获取导入进度（旧版）
      • 文件导出
        • 文件导出流程
        • 创建导出任务
        • 获取导出进度
    • 文件-表格文件（Excel） API
      • 表格接口参数说明
      • 获取表格内容
      • 获取表格中的评论数
      • 更新表格内容
      • 追加表格内容
      • 删除表格行
      • 新增表格工作表
    • 文件-文稿文件（Word） API
      • 文稿书签说明
      • 读取文稿书签内容
      • 替换文稿书签内容
    • 文件-文档文件（类 Markdown） API
      • 获取文档中的评论列表
    • 文件-应用表格文件（多维表格）API
      • 应用表格列及单元格值结构
      • 应用表格接口调用规则
      • 获取数据表列表
      • 创建数据表
      • 获取字段列表
      • 创建字段
      • 更新字段
      • 删除字段
      • 新增行
      • 获取单行
      • 更新行
      • 删除行
    • 文件-获取额外信息 API
      • 获取文件的纯文本内容
      • 文件纯文本字数统计
      • 获取文件的历史列表
      • 获取文件的版本列表
      • 获取文件内容中所有的 @ 人信息列表
      • 还原文件历史版本
    • 系统管理 API
      • 应用管理
        • 获取应用详情
        • 更新应用回调地址
      • 用户席位管理
        • 用户席位状态说明
        • 获取用户列表和席位状态
        • 激活用户席位​
        • 取消用户席位​
        • 批量设置用户席位
    • 其他 API
      • 上报事件
      • 创建行为历史
      • 推送文件内全部的用户
      • 推送用户全部的 websocket 连接
    • 获取行列表
  • 08. 回调接口（你的应用需实现的接口）
    • 整体概述
    • 文件信息
      • 文件权限说明
      • [重要] 获取文件元信息-协同文档
      • [重要] 获取文件元信息-预览文档
      • 获取当前用户的文件列表
      • 获取文件的协作者列表
      • 获取接入方指定文件的完整访问地址
      • 获取文件元信息-协同文档自动任务（admin）
      • 根据指定用户获取文件元信息-协同文档（admin）
    • 用户信息
      • 批量获取用户信息（admin）
      • [重要] 获取当前用户信息
      • 获取当前用户所在团队信息
      • 获取指定用户信息
      • 获取用户水印信息
      • 获取用户部门路径
      • 批量获取用户信息
    • 团队和部门
      • 特殊部门 ID 说明
      • 获取团队下的成员列表
      • 获取部门信息
      • 获取部门的下级部门节点
      • 获取部门下的成员分页列表
    • 搜索功能
      • 获取与文件相关的用户列表
      • 获取与文件相关的文件列表
      • 按关键字搜索文件和用户列表
    • 事件推送
      • 整体概述
      • 评论（Comment）
        • 轻文档
          • 添加评论
          • 删除评论
          • 结束评论
          • 对于评论的回复评论
        • 表格
          • 添加评论
          • 删除评论
          • 结束评论
          • 对于评论的回复评论
        • 传统文档
          • 对于评论的回复评论
          • 添加评论
          • 更新评论
          • 删除评论
        • 幻灯片
          • 添加评论
          • 删除评论
          • 结束评论
          • 对于评论的回复评论
        • 应用表格
          • 添加评论
          • 对于评论的回复评论
          • 删除评论
      • 讨论（Discussion）
        • 轻文档
          • 发送讨论消息
      • 提及（MentionAt @ 人）
        • 轻文档
          • 在评论中 at
          • 在讨论中 at
          • 在正文中 at
        • 表格
          • 在评论中 at
          • 在正文中 at
        • 传统文档
          • 在评论中 at
          • 在正文中 at
        • 应用表格
          • 在评论中 at
          • 在正文中 at
      • 日期提醒 (DateMention)
        • 轻文档
          • 创建
          • 修改
          • 删除
        • 表格
          • 创建
          • 修改
          • 删除
        • 传统文档
          • 创建
          • 修改
          • 删除
      • 文件内容更新 (FileContent)
        • 文件内容更新
      • 文档协作者协同状态变化 (Collaborator)
        • 文档协作者协同状态变化
      • 文件版本 (Revision)
        • 版本
      • 系统事件 (System)
        • 系统事件
      • 回调请求错误（实验性）
        • 回调请求错误
  • 09. 核心模型
    • 你的应用如何设计应用（app）模型？
    • 你的应用如何设计文件数据模型？
    • 你的应用如何设计通讯录模型？
    • 你的应用系统如何设计文件权限模型？
  • 10. 典型场景方案
    • 云盘场景
    • IM 场景
    • 示例代码仓库
  • 11. 常见问题
    • 访问接口提示 Signature
    • 文件预览或导入报错
    • 首次接入 SDK 报错
    • 文档预览如何做防盗链
    • 复制粘贴、全屏操作不正常
    • 如何实现文档模板功能
    • 文档内容何时保存
    • 移动端不支持 blob 协议导致预览失败
    • 如何实现文件重命名
    • 如何通过接口修改文档内容
    • @人员时如何直接跳转至对应锚点
  1. 公共 API

顶部栏定制 HeaderBars

HeaderBars#

HeaderBars 用于控制编辑器顶部栏的显示状态，以及对顶部栏命令进行插入、查询和局部更新。
它适用于以下场景：
统一控制顶部栏显示 / 隐藏
在现有命令前后插入自定义按钮
动态更新命令的显示状态、禁用状态、图标和文案
监听标题变化，并将宿主侧逻辑与顶部栏联动

界面示意#

image.png
上图为 HeaderBars 的典型效果示意。接入方可以基于根级 sdk.headerBars：
控制整个顶部栏显示状态
插入自定义命令
获取指定命令引用，并继续修改其状态

方法#

方法列表#

以下 headerBars API 使用 OfficeSDK 根级 sdk.headerBars 调用，均为 PC only，并且需 co-1.8+。
方法说明
sdk.headerBars.visible顶栏显示状态（PC only，co-1.8+）
sdk.headerBars.onTitleChange标题变更监听（PC only，co-1.8+）
sdk.headerBars.getVisible获取顶栏显示状态（PC only，co-1.8+）
sdk.headerBars.setVisible设置顶栏显示状态（PC only，co-1.8+）
sdk.headerBars.addCommand插入顶栏命令（PC only，co-1.8+）
sdk.headerBars.getCommand获取命令引用（PC only，co-1.8+）
sdk.headerBars.listViewCommands获取当前顶栏命令列表（PC only，co-1.8+）
sdk.headerBars.commandRef.visible设置命令显示状态（PC only，co-1.8+）
sdk.headerBars.commandRef.disabled设置命令禁用状态（PC only，co-1.8+）
sdk.headerBars.commandRef.src设置命令图标地址（PC only，co-1.8+）
sdk.headerBars.commandRef.label设置命令文案（PC only，co-1.8+）
sdk.headerBars.commandRef.editable设置命令可编辑状态（PC only，co-1.8+）
sdk.headerBars.commandRef.onCommandClick设置命令点击回调（PC only，co-1.8+）
sdk.headerBars.commandRef.getState获取命令当前状态（PC only，co-1.8+）

能力概览#

sdk.headerBars 主要提供两层能力：
顶栏级能力：控制整个顶部栏的显示状态，以及监听标题变化
命令级能力：插入命令、获取命令引用，并更新命令属性
可以简单理解为：
sdk.headerBars.*：控制整个顶部栏
sdk.headerBars.getCommand(id) 返回的 commandRef：控制单个命令

API 调用方式#

使用流程#

典型接入流程如下：
1.
通过 connect(options) 获取 sdk
2.
使用 sdk.headerBars.setVisible(...) 控制顶栏整体显示状态
3.
使用 sdk.headerBars.addCommand(...) 插入自定义命令
4.
使用 sdk.headerBars.getCommand(id) 获取命令引用
5.
通过 commandRef.visible / disabled / label / src / editable / onCommandClick 调整命令行为
如果需要获取当前顶栏实际命令列表，可再调用：
sdk.headerBars.listViewCommands()

新旧兼容#

适用说明#

headerBars 与各套件中的正文能力不同，它不属于 sdk.getEditor() 的旧扁平 API 分组，而是直接挂在 OfficeSDK 根级实例上的公共扩展能力：

顶栏显示状态 sdk.headerBars.visible#

说明#

顶栏显示状态属性。

类型定义#

说明补充#

读取时返回 SDK 本地缓存的显示状态
写入时会异步触发 sdk.headerBars.setVisible(visible)
如果业务需要等待 iframe 侧完成更新，优先使用 await sdk.headerBars.setVisible(...)

示例#

标题变更监听 sdk.headerBars.onTitleChange#

说明#

监听顶栏标题变化。

类型定义#

相关类型#

HeaderBarsTitleChangeHandler

示例#

获取顶栏显示状态 sdk.headerBars.getVisible()#

说明#

获取顶栏当前显示状态。

类型定义#

示例#

设置顶栏显示状态 sdk.headerBars.setVisible(visible)#

说明#

设置顶栏显示状态。

类型定义#

参数#

visible: 目标显示状态

示例#

插入顶栏命令 sdk.headerBars.addCommand(command, posCommand, pos?)#

说明#

向顶栏插入一个命令。通常用于在现有命令前后增加接入方自定义操作。

类型定义#

参数#

command: 待插入的命令定义
posCommand: 参考命令 id
pos: 插入位置，默认 after

返回值#

boolean：是否插入成功

相关类型#

HeaderBarsCommandDefinition
HeaderBarsCommandInsertPosition

示例#

获取命令引用 sdk.headerBars.getCommand(id)#

说明#

获取一个命令引用对象。获取后可以继续通过属性方式更新该命令状态。

类型定义#

参数#

id: 命令 id

返回值#

HeaderBarsCommandRef：命令引用对象

相关类型#

HeaderBarsCommandRef

示例#

获取当前顶栏命令列表 sdk.headerBars.listViewCommands()#

说明#

获取当前顶栏命令列表，并刷新本地缓存。适合在批量更新后重新获取最新视图状态。

类型定义#

返回值#

HeaderBarsCommandState[]：当前视图中的命令列表

相关类型#

HeaderBarsCommandState

示例#

设置命令显示状态 sdk.headerBars.commandRef.visible#

说明#

命令显示状态属性。

类型定义#

说明补充#

写入时会先更新本地缓存，再异步调用 iframe 侧更新

示例#

设置命令禁用状态 sdk.headerBars.commandRef.disabled#

说明#

命令禁用状态属性。

类型定义#

说明补充#

写入时会先更新本地缓存，再异步调用 iframe 侧更新

示例#

设置命令图标地址 sdk.headerBars.commandRef.src#

说明#

命令图标地址属性。

类型定义#

说明补充#

仅当赋值为字符串时才会触发更新

示例#

设置命令文案 sdk.headerBars.commandRef.label#

说明#

命令文案属性。

类型定义#

说明补充#

仅当赋值为字符串时才会触发更新
title、save-status 命令不支持通过此属性修改文案

示例#

设置命令可编辑状态 sdk.headerBars.commandRef.editable#

说明#

命令可编辑状态属性。

类型定义#

说明补充#

当前仅 title 命令支持设置 editable

示例#

设置命令点击回调 sdk.headerBars.commandRef.onCommandClick#

说明#

命令点击回调属性。

类型定义#

说明补充#

赋值后会启用宿主侧点击回调桥接
当 iframe 侧触发该命令点击时，SDK 会在宿主侧执行此回调

示例#

获取命令当前状态 sdk.headerBars.commandRef.getState()#

说明#

获取命令当前缓存状态。

类型定义#

返回值#

HeaderBarsCommandState | undefined：当前命令状态；若本地尚未拉取到命令，可能返回 undefined

相关类型#

HeaderBarsCommandState

示例#

类型定义#

HeaderBarsTitleChangeHandler#

HeaderBarsCommandType#

HeaderBarsCommandInsertPosition#

HeaderBarsCommandDefinition#

用于定义插入到顶部栏中的命令初始状态。

HeaderBarsCommandState#

表示顶部栏中某个命令的当前状态快照。

HeaderBarsCommandRef#

表示通过 sdk.headerBars.getCommand(id) 获取到的命令引用对象，可继续对单个命令做局部更新。

HeaderBarsChangedPayload#

注意事项#

本页仅描述根级 sdk.headerBars 的调用方式
本页新增接口均为 PC only
本页新增接口均需 co-1.8+
sdk.headerBars 不属于 sdk.getEditor() 的旧扁平方法分组
command.label 当前不支持修改 title、save-status
command.editable 当前仅支持 title
command.visible、command.disabled、command.src、command.label、command.editable 的属性写入均为异步触发 iframe 更新；如需更严格状态对齐，建议结合 listViewCommands() 或 getState() 做结果确认
修改于 2026-07-17 02:34:58
上一页
公共处理方法
下一页
轻文档
Built with