开发文档
腾讯文档开放平台开发文档

在线表格相关的资源描述

... 2022-10-14 大约 6 分钟

# 在线表格相关的资源描述

完整示例

# 在线表格 (Spreadsheet)

spreadsheet: 在线表格由多个工作表（子表）组成，是承载数据的容器，支持数据的存储、计算和展示。作为在线表格，不仅可以方便快捷的通过网络进行分享和协作， 也可以通过设置文档权限的方式存储私人文件。

在线表格相关的资源描述：

字段名 数据类型 描述
fileId string 在线表格的id，文件的唯一标识
metadata object(Metadata) 在线表格的元数据
sheets array(Sheet) 工作表（子表）相关的数据和信息，一个 spreadsheet 中包含多个 sheet

# Metadata

在线表格元数据相关的资源描述：

字段名 数据类型 描述
title string 在线表格标题
url string 表格的链接
creator string 表格的创建者
createTime integer 表格创建时间，时间戳形式
owner string 在线表格的所有者

# Sheet

工作表相关的资源描述：

字段名 数据类型 描述
properties object(Properties) 工作表的元数据
merges array(GridRange) 表格里合并单元格的范围
data array(GridData) 表格多个范围内的数据和元数据

# Properties

工作表元数据相关的资源描述：

字段名 数据类型 描述
sheetId string 工作表ID，工作表的唯一标识
title string 工作表名称
rowCount integer 表格有内容的区域边界的行数
columnCount integer 表格的内容的区域边界的列数
rowTotal integer 表格的总行数
columnTotal integer 表格的总列数

# sheetId

工作表的唯一标识，可以通过在线表格的链接来获取，如果一个在线表格的链接是 https://docs.qq.com/sheet/ABCDEF12345abcdef?tab=BB08J2 ， 那么对应的 sheetId 为 BB08J2。

# GridRange

表示一片连续的范围（也可以表示一个单元格的范围），行列序号从0开始计算，遵循 左闭右开 ———— [start,end)，如果 end <= start 则该值无效。

例如以下可以表示一个工作表中的A1单元格：

{
  "sheetId": "abcdef",
  "startRow": 0,
  "endRow": 1,
  "startColumn": 0,
  "endColumn": 1
}
1
2
3
4
5
6
7
1
2
3
4
5
6
7

以下表示一个工作表中A1,B1,A2,B2四个单元格组成的范围：

{
  "sheetId": "abcdef",
  "startRow": 0,
  "endRow": 2,
  "startColumn": 0,
  "endColumn": 2
}
1
2
3
4
5
6
7
1
2
3
4
5
6
7

表格范围的资源描述：

字段名 数据类型 描述
sheetId string 该range作用的工作表的ID
startRow integer 起始行编号 （从0开始计算）
endRow integer 终止行编号 （从0开始计算）
startColumn integer 起始列编号 （从0开始计算）
endColumn integer 终止列编号 （从0开始计算）

# GridData

gridData存储了表格的具体数据内容，相关的资源描述：

字段名 数据类型 描述
startRow integer 起始行编号 （从0开始计算）
startColumn integer 起始列编号 （从0开始计算）
rows array(RowData) 各行的数据

# RowData

行数据的资源描述：

字段名 数据类型 描述
values array(CellData) 各个单元格的数据内容

# CellData

单元格的数据、样式等信息，相关资源描述：

字段名 数据类型 描述
cellValue object(CellValue) 单元格的数据内容
cellFormat object(CellFormat) 单元格的样式信息
dataType string 单元格的数据类型，枚举值参考：DataType

# CellValue

单元格的数据内容，支持以下几种数据类型（注：每个cellValue只能使用一下的其中一个字段来表示单元格的数据类型，若同时使用多个类型，则只有排序靠前的字段会生效）：

字段名 数据类型 描述
text string 文本内容
number float 数值数据
link object(Link) 超链接
time object(Time) 时间
location object(Location) 位置信息
select object(Select) 单选\多选

# Time

字段名 数据类型 描述
year integer 年份
month integer 月份
day integer 日期
hour integer 小时
minute integer 分钟
second integer 秒

# CellFormat

单元格的样式信息，相关的资源描述：

字段名 数据类型 描述
textFormat object(TextFormat) 文字样式

# TextFormat

文本样式信息，相关的资源描述：

字段名 数据类型 描述
font string 字体名称，表格支持的字体类型: 字体列表；写入数据时，字体默认为宋体（SimSun）
fontSize integer 字体大小；取值范围 (0,72]
bold boolean 字体加粗
italic boolean 斜体
strikethrough boolean 字体删除线
underline boolean 下划线
color object(Color) 颜色信息

# Color

颜色信息，采用 RGBA 表示法，资源描述：

字段名 数据类型 描述
red integer 红色，取值范围：[0,255]
green integer 绿色，取值范围：[0,255]
blue integer 蓝色，取值范围：[0,255]
alpha integer alpha通道，取值范围：[0,255]，alpha为0时则颜色为透明

超链接的相关信息，资源描述：

字段名 数据类型 必填参数 描述
url string 是 链接url
text string 是 链接展示的文本

# Dimension

声明维度属性为行或者列的字符串枚举值：

枚举值 含义
ROW 行
COLUMN 列

# DataType

表示单元格设置的 数据验证 类型，目前支持的类型枚举值如下：

枚举值 含义
DATA_TYPE_UNSPECIFIED 单元格未设置数据验证，没有指定类型
SELECT 单选\多选
TIME 时间日期
LOCATION 地理位置
STAR 评星

说明： 数据验证 是单元格的属性之一，未设置数据验证的单元格为 DATA_TYPE_UNSPECIFIED。

# Location

位置信息，包含经纬度和位置名。

字段名 数据类型 描述
longitude string 经度 （正数：东经，负数：西经）
latitude string 纬度 （正数：北纬，负数：南纬）
name string 地理位置名
uid string 地理位置的uid标识
source string 地图软件供应商

一下示例表示北京天安门（39.9055°N, 116.3976°E）的地理位置：

{
  "name": "深圳市宝安人民医院",
  "latitude": "113.914503",
  "longitude": "22.561882",
  "source": "tencentmap",
  "uid": "6977409163354664674"
}
1
2
3
4
5
6
7
1
2
3
4
5
6
7

# Select

单选或多选的单元格数据类型：

字段名 数据类型 描述
multiple boolean 是否为多选类型
value array(string) 单元格选择的选项的ID
options array(Option) 单元格选项

# Option

单元格选项：

字段名 数据类型 描述
id string 选项的ID
text string 选项的文本内容
color object(Color) 选项的颜色

# 完整示例

一个spreadsheet对象的 json 结构如下所示

{
  "fileID": "ABCDEF12345abcdef",
  "metadata": {
    "title": "表格示例",
    "url": "https://docs.qq.com/sheet/ABCDEF12345abcdef?tab=BB08J2",
    "creator": "user_name",
    "owner": "user_name",
    "createTime": 1640995200
  },
  "sheets": [
    {
      "properties": {
        "sheetId": "BB08J2",
        "title": "工作表1",
        "rowCount": 100,
        "columnCount": 10,
        "rowTotal": 200,
        "columnTotal": 26
      },
      "ranges": [
        {
          "sheetId": "BB08J2",
          "startRow": 2,
          "endRow": 3,
          "startColumn": 2,
          "endColumn": 3
        }
      ],
      "data": [
        {
          "startRow": 4,
          "startColumn": 4,
          "rows": [
            {
              "values": [
                {
                  "dataType": "DATA_TYPE_UNSPECIFIED",
                  "cellValue": {
                    "text": "this is the text in the cell"
                  },
                  "cellFormat": {
                    "textFormat": {
                      "font": "SimSun",
                      "fontSize": 0,
                      "bold": false,
                      "italic": false,
                      "strikethrough": false,
                      "underline": false,
                      "color": {
                        "red": 0,
                        "green": 0,
                        "blue": 0,
                        "alpha": 255
                      }
                    }
                  }
                },
                {
                  "dataType": "TIME",
                  "cellValue": {
                    "time": {
                      "year": 2022,
                      "month": 1,
                      "day": 2,
                      "hour": 3,
                      "minute": 4,
                      "second": 56
                    }
                  },
                  "cellFormat": {}
                }
              ]
            },
            {
              "values": [
                {
                  "dataType": "DATA_TYPE_UNSPECIFIED",
                  "cellValue": {
                    "link": "腾讯文档开放平台"
                  },
                  "cellFormat": {}
                },
                {
                  "cellValue": {
                    "location": {
                      "longitude": "114.03211865746414",
                      "latitude": "22.58150515054245",
                      "name": "白眉石",
                      "uid": "4338897722823917334",
                      "source": "tencentmap"
                    }
                  },
                  "cellFormat": {
                    "textFormat": {
                      "font": "",
                      "fontSize": 0,
                      "bold": false,
                      "italic": false,
                      "strikethrough": false,
                      "underline": false,
                      "color": {
                        "red": 0,
                        "green": 0,
                        "blue": 0,
                        "alpha": 255
                      }
                    }
                  },
                  "dataType": "LOCATION"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
上次编辑于: 2026年1月26日 16:19
贡献者: weixinqiu , muyanyang , naturalshen

批量更新接口