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
      • 应用表格列及单元格值结构
      • 应用表格接口调用规则
      • 获取数据表列表
        GET
      • 创建数据表
        POST
      • 获取字段列表
        GET
      • 创建字段
        POST
      • 更新字段
        PUT
      • 删除字段
        DELETE
      • 新增行
        POST
      • 获取单行
        GET
      • 更新行
        PATCH
      • 删除行
        DELETE
    • 文件-获取额外信息 API
      • 获取文件的纯文本内容
      • 文件纯文本字数统计
      • 获取文件的历史列表
      • 获取文件的版本列表
      • 获取文件内容中所有的 @ 人信息列表
      • 还原文件历史版本
    • 系统管理 API
      • 应用管理
        • 获取应用详情
        • 更新应用回调地址
      • 用户席位管理
        • 用户席位状态说明
        • 获取用户列表和席位状态
        • 激活用户席位​
        • 取消用户席位​
        • 批量设置用户席位
    • 其他 API
      • 上报事件
      • 创建行为历史
      • 推送文件内全部的用户
      • 推送用户全部的 websocket 连接
    • 获取行列表
      GET
  • 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

应用表格列及单元格值结构

概述#

应用表格有21种列,不同的列的列结构以及对应单元格的值都不相同(除个别,例如日期列/首次填写时间/最后填写时间 列的单元格值时相同的),下面是各种列的结构以及单元格值的 JSON结构

列属性#

列结构为
type ColumnItem struct {
      Name        string      `json:"name"`    // 列名称
      Type        string      `json:"type"`    // 列类型
      TypeOptions interface{} `json:"props"`   // 列属性
      GUID        string      `json:"guid"`    // 列GUID
}

单行文本#

Type: SingleLineText
Prop:无

多行文本#

Type: LongText
Prop:
type LongTextOptions struct {
      EnableRichText bool `json:"enableRichText"`    //是否开启富文本
}

单选#

Type: SingleChoice
Prop:
type ChoiceOptions struct {
      ChoiceOrder    []string               `json:"choiceOrder" mapstructure:"choiceOrder"`          //选项guid列表
      Choices        map[string]*ChoiceMeta `json:"choices" mapstructure:"choices"`                  //选项信息
      DisableColors  bool                   `json:"disableColors" mapstructure:"disableColors"`      //是否开启颜色标签
      AllowAutoAdd   bool                   `json:"allowAutoAdd" mapstructure:"allowAutoAdd"`        //允许填写时新增选项
      DefaultChoices []string               `json:"defaultChoices" mapstructure:"defaultChoices"`    //默认选项
}
type ChoiceMeta struct {
      ID         string             `json:"guid" mapstructure:"guid"`   //选项guid
      Style      *ChoiceStyle       `json:"style"`                       //选项样式
      Name       string             `json:"name"`                        //选项名称
      Hidden     bool               `json:"hidden"`                      //是否隐藏
      StatusType tablepb.StatusType `json:"statusType"`                  //状态类型
      Locked     bool               `json:"locked"`                      //是否锁定
}
type ChoiceStyle struct {
      Color      string `json:"color"`       //颜色
      Background string `json:"background"`  //背景
}
枚举:
color :whiteColor | blackColor
其中:
whiteColor = cssVars.gray.gray0
blackColor = cssVars.transparency.transparency120
background :
#F9D7D7 | #F9DDCD | #FAEDBF | #DDF1C7 | #D3EDE3 | #CBE8F6 | #D1E2FD | #E1D9F6 | #F7D9E9 | #E7E7E7
#F3AEAE | #F4BB9C | #F6DB80 | #BBE290 | #A8DAC8 | #98D2ED | #A2C5FB | #C3B3EC | #EEB4D4 | #CFCFCF
#E85E5E | #E97839 | #EDB800 | #77C621 | #51B691 | #31A5DB | #468CF8 | #8767DA | #DE69A9 | #A0A0A0
#A80000 | #C76000 | #BF9500 | #549717 | #1B928A | #1085BC | #0065CF | #6614BD | #A60D75 | #666666

多选#

Type: MultipleChoice
Prop:同单选

多级下拉#

Type: Cascade
Prop:
type MultiDropdownOptions struct {
      Levels        []string        `json:"levels" mapstructure:"levels"`              //层级列表
      Display       string          `json:"display" mapstructure:"display"`            //展示方式
      DisableColors bool            `json:"disableColors" mapstructure:"disableColors"`//是否禁用颜色
      DropdownList  []*DropdownList `json:"dropdownList" mapstructure:"dropdownList"`  //下拉选项树
}
type DropdownList struct {
      Guid     string          `json:"guid" mapstructure:"guid"`          //选项guid
      Name     string          `json:"name" mapstructure:"name"`          //选项名称
      Style    *ChoiceStyle    `json:"style" mapstructure:"style"`        //选项样式
      Children []*DropdownList `json:"children" mapstructure:"children"`  //子选项
}

数值#

Type: Number
Prop:
type NumberOptions struct {
      Precision            int32 `json:"precision"`              //精度
      HasThousandSeparator *bool `json:"hasThousandSeparator"`   //是否开启千分位
}

百分比#

Type: Percent
Prop:
type PercentOptions struct {
      Precision       int32 `json:"precision"`       //精度
      ShowProgressBar bool  `json:"showProgressBar"` //是否显示进度条
}

评分#

Type: Rate
Prop:
type Rating struct {
      Count int32    `json:"count"` //评分总数
      Icon  string   `json:"icon"`  //评分图标
      Color []string `json:"color"` //评分颜色(前端未使用字段)
}
枚举:
icon :'star' | 'flame' | 'heart' | 'honor' | 'stone'

复选框#

Type: CheckBox
Prop:
type CheckBoxOptions struct {
      ShowLineThrough bool                  `json:"showLineThrough"`    //是否开启勾选后改记录显示中划线
      Shape           *CheckBoxShapeOptions `json:"shape"`              //复选框样式
}
type CheckBoxShapeOptions struct {
      Type  string `json:"type"`      //类型
      Color string `json:"color"`     //颜色
}
枚举:
type :'check' | 'star' | 'close'
color :无固定枚举,前端类型为 string;默认值来自 cssVars.colors?.text?.secondary || cssVars.text.secondary。

链接#

Type: Link
Prop:无

附件#

Type: Attachment
Prop:无

公式#

Type: Formula
Prop:
type FormulaOptions struct {
      FormulaText     string  `json:"formula" mapstructure:"formula"`       //公式内容
      Format          *string `json:"format,omitempty" mapstructure:"format"`//展示格式
      Error           *string `json:"error,omitempty"`                       //错误信息
      ShowProgressBar bool    `json:"showProgressBar"`                      //是否显示进度条
}
枚举:
format生成方法 :
数值格式:#,##0.00_
日期格式:DateFormats
百分比格式:0.00%
文本格式:@
其中 DateFormats 可选值为:
yyyy/M/d HH:mm:ss
yyyy/M/d
yyyy/MM/dd
yyyy-M-d
y年M月d日 EEEE
M-d
M月d日
yyyy年M月
M月
EEEE
EEE
M-d-yyyy
M/d/yyyy
H:mm
HH:mm
H:mm:ss
HH:mm:ss
H:mm bbb
H:mm:ss bbb
MMM d
MMM d, yyyy

自动编号#

Type: AutoNumber
Prop:
type AutoNumberOptions struct {
      AutoType AutoType `json:"type" mapstructure:"type"`   //自动编号类型:increment/custom
      Rules    []*Rules `json:"rules" mapstructure:"rules"` //自定义编号规则
}
type Rules struct {
      RuleType RuleType `json:"type" mapstructure:"type"`     //规则类型:auto/date/text
      Digit    int64    `json:"digit" mapstructure:"digit"`   //自增位数
      Format   string   `json:"format" mapstructure:"format"` //日期格式
      Text     string   `json:"text" mapstructure:"text"`     //固定文本
}

关联引用#

Type: ReferenceRecord
Prop:
type ReferenceRecordOptions struct {
      ForeignTableGUID       string  `json:"tableGuid" mapstructure:"tableGuid"`                              //引用的表guid
      ForeignBaseGUID        string  `json:"baseGuid,omitempty" mapstructure:"baseGuid"`                      //引用的文件guid,空表示同文件
      ForeignTableColumnGUID string  `json:"foreignTableColumnGuid,omitempty" mapstructure:"foreignTableColumnGuid"` //引用表的双向关联列guid
      ForeignViewGUID        string  `json:"refViewGuid,omitempty" mapstructure:"refViewGuid"`                //引用表视图guid
      ReferenceView          bool    `json:"isRefToView" mapstructure:"isRefToView"`                          //是否关联引用表视图
      IsMultiple             bool    `json:"isMultiple" mapstructure:"isMultiple"`                            //是否允许引用多行
      Error                  *string `json:"error,omitempty" mapstructure:"error"`                            //错误信息
}

关联公式#

Type: RefRecordRollUp
Prop:
type RefRecordRollUpOptions struct {
      ForeignTableColumnGUID string  `json:"foreignRefFieldGuid" mapstructure:"foreignRefFieldGuid"` //引用表中参与公式计算的列guid
      RelationColumnGUID     string  `json:"refFieldGuid" mapstructure:"refFieldGuid"`               //本表关联引用列guid
      FormulaText            string  `json:"formula" mapstructure:"formula"`                         //公式内容
      Format                 *string `json:"format,omitempty" mapstructure:"format"`                  //展示格式
      Error                  *string `json:"error,omitempty" mapstructure:"error"`                    //错误信息
      ShowProgressBar        bool    `json:"showProgressBar"`                                        //是否显示进度条
}

联系人#

Type: Collaborator
Prop:
type CollaboratorOptions struct {
      IsMultiple   bool `json:"isMultiple"`   //是否允许多选
      IsNotify     bool `json:"isNotify"`     //是否通知联系人
      AssignedToMe bool `json:"assignedToMe"` //是否分配给我(已废弃字段)
}

首次填写人#

Type: FirstModifiedBy
Prop:无

最后修改人#

Type: LastModifiedBy
Prop:无

日期时间#

Type: Date
Prop:
type DateOptions struct {
      DateFormat string `json:"dateFormat,omitempty"` //日期格式
      TimeFormat string `json:"timeFormat,omitempty"` //时间格式
      AutoFill   bool   `json:"isAutoFill"`           //是否自动填充
}

首次填写时间#

Type: FirstModifiedAt
Prop:
type ModifiedOptions struct {
      DateFormat string   `json:"dateFormat" mapstructure:"dateFormat"`      //日期格式
      TimeFormat string   `json:"timeFormat,omitempty" mapstructure:"timeFormat"` //时间格式
      RefGuids   []string `json:"fieldGuids" mapstructure:"fieldGuids"`      //跟踪字段guid列表
      Error      string   `json:"error,omitempty" mapstructure:"error"`      //错误信息
}

最后修改时间#

Type: LastModifiedAt
Prop:同首次填写时间

单元格值#

单行文本#

string

多行文本#

兼容普通文本字符串,也支持富文本结构:
string
type RichText struct {
      Text  string `json:"text"`  //纯文本
      Slate string `json:"slate"` //前端展示数据
}

单选#

string //选项guid

多选#

[]string //选项guid列表

多级下拉#

[]string //各层级选项guid列表

数值#

float64

百分比#

float64

评分#

int64

复选框#

bool

链接#

type LinkValue struct {
      Text string `json:"text"` //展示文本
      URL  string `json:"url"`  //链接地址
      Logo string `json:"logo"` //图标
}

附件#

type Attachments []*AttachmentValue

type AttachmentValue struct {
      GUID     string  `json:"guid"`     //附件guid
      URL      string  `json:"url"`      //附件地址
      Name     string  `json:"name"`     //附件名称
      MimeType string  `json:"mimeType"` //MIME类型
      Size     float64 `json:"size"`     //文件大小
      Width    float64 `json:"width"`    //图片宽度
      Height   float64 `json:"height"`   //图片高度
      FileType string  `json:"fileType"` //文件类型,云文件有该字段
}

公式#

公式值按计算结果保存,可能是布尔、数值、字符串、日期、数组或错误。
type Value struct {
      Type   ValueType   //Boolean/Number/String/Date/Empty/Unknown/Error/Array
      holder interface{} //实际值:bool/float64/string/[]interface{}等
}
JSON 序列化时通常表现为具体结果值:
bool | float64 | string | []interface{}

自动编号#

type AutonumberValue struct {
      Num  int64  `json:"num,omitempty"`  //自增序号
      Text string `json:"text,omitempty"` //展示文本
}

关联引用#

type ReferenceRecordValue []*ReferenceRecord

type ReferenceRecord struct {
      ReferenceRecordID    string `json:"refRecordGuid" mapstructure:"refRecordGuid"` //被引用记录guid
      ReferenceDisplayName string `json:"refDisplayName" mapstructure:"refDisplayName"` //被引用记录展示名
}

关联公式#

同公式

联系人#

[]*User

type User struct {
      ID     int64  `json:"id"`     //用户id
      Name   string `json:"name"`   //用户名称
      Avatar string `json:"avatar"` //头像
      Email  string `json:"email"`  //邮箱
}

首次填写人#

type User struct {
      ID     int64  `json:"id"`     //用户id
      Name   string `json:"name"`   //用户名称
      Avatar string `json:"avatar"` //头像
      Email  string `json:"email"`  //邮箱
}

最后修改人#

同首次填写人

日期时间#

float64 //日期时间数值

首次填写时间#

同公式结果,通常为日期类型的 float64

最后修改时间#

同首次填写时间
修改于 2026-07-13 05:39:15
上一页
获取文档中的评论列表
下一页
应用表格接口调用规则
Built with