字段单元格值

本文详细说明所有字段类型及其对应的数据格式，帮助开发者在使用 OpenAPI 进行字段操作时，明确不同场景下的数据处理规范。

Field Models

不同字段类型的单元格值在读取和编辑时，部分字段会呈现不同的数据格式，具体分为以下两种场景：

read：指接口响应返回时字段单元格的数据格式，即从接口获取数据时该字段的呈现形式。
write：指编辑字段单元格时需遵循的数据格式，即向接口提交数据以修改字段值时的规范格式。

Cell Value Write Errors

写入字段单元格值时，若数据格式不符合要求，接口会返回格式错误提示。

例如，向数字字段写入字符串：

{
  "fields": {
    "number_field": "example text"
  }
}

会收到如下错误响应：

{
  "success": false,
  "code": 4031,
  "message": "The input value of field number_field is invalid: example text"
}

Field Types

Single Line Text

单行文本字段适用于存储简短且无需换行的文本信息，如名称、标题、标签等。该字段不支持换行、缩进等符号，输入内容将限制在同一行显示，确保文本展示的简洁性和规范性。

Write
- type：string
- example："example text"
Read
- cellFormat：json
  - type：string
  - example："example text"
- cellFormat：string
  - type：string
  - example："example text"

Multi Line Text

多行文本字段主要用于存储较长且需要换行的文本内容，如备注、描述、详细说明等。支持通过换行符实现内容换行，满足大段文本的输入和展示需求，使文本结构更清晰易读。

Write
- type：string
- example："这是一段 \n 多行文本"（支持换行符表示换行）
Read
- cellFormat：json
  - type：string
  - example："这是一段 \n 多行文本"
- cellFormat：string
  - type：string
  - example：" 这是一段多行文本 "（换行以<br>标签呈现）

Url

网址字段专门用于存储各类网络链接，如网页地址、资源链接等。能对输入的网址进行识别处理，读取时以规范形式展示，方便用户直接访问，提升链接使用便捷性。

Write
- type：string
- example："https://example.com"
Read
- cellFormat：json
  - type：string
  - example："https://example.com"
- cellFormat：string
  - type：string
  - example："https://example.com"

Email

邮箱字段用于存储电子邮件地址，适用于联系、通知等场景。可确保输入内容符合邮箱格式规范，便于系统进行邮箱验证及发送邮件等相关操作。

Write
- type：string
- example："example@mail.com"
Read
- cellFormat：json
  - type：string
  - example："example@mail.com"
- cellFormat：string
  - type：string
  - example："example@mail.com"

Phone

电话字段用于记录电话号码信息，支持不同国家和地区的号码格式。读取时会对号码进行格式化处理，使其更易读，同时方便进行拨号等相关操作。

Write
- type：string
- example："+8613800138000"
Read
- cellFormat：json
  - type：string
  - example："+8613800138000"
- cellFormat：string
  - type：string
  - example："+8613800138000"

Number

数字字段主要用于存储各类数值信息，如数量、金额、年龄等。仅支持数字类型输入，保证数值的准确性和一致性，便于进行数值计算、统计分析等操作。

Write
- type：number
- example：123.45
Read
- cellFormat：json
  - type：number
  - example：123.45
- cellFormat：string
  - type：string
  - example："123.4500"

Currency

货币字段用于处理与货币相关的数值，适用于记录价格、费用等信息。不仅能存储金额数值，还能关联对应的货币类型，展示时会根据货币类型进行格式化，清晰呈现货币信息。

Write
- type：number
- example：199.99
Read
- cellFormat：json
  - type：number
  - example: 199.99
- cellFormat：string
  - type：string
  - example："$199.99"

Percent

百分比字段用于表示比例关系，如完成率、增长率等。以小数形式写入，读取时转换为百分比形式展示，使比例信息更直观易懂，便于进行比例相关的分析和比较。

Write
- type：number
- example：75.33
Read
- cellFormat：json
  - type：number
  - example：75.33
- cellFormat：string
  - type：string
  - example："75.33%"

Rating

评分字段用于对事物进行等级评价，如产品满意度、服务质量等。通过整数表示评分值，直观反映评价高低，便于对评价结果进行统计和分析。

Write
- type：number（整数，代表评分值）
- example：4
Read
- cellFormat：json
  - type：number
  - example：4
- cellFormat：string
  - type：string
  - example："4"

AutoNumber

自动编号字段用于为每条记录生成唯一的自动递增编号，如订单编号、资产编号等。由系统自动生成，不支持手动写入，确保编号的唯一性和连续性，便于对记录进行标识和管理。

Write：read_only，不支持写入
Read
- cellFormat：json
  - type：number
  - example：2
- cellFormat：string
  - type：string
  - example："2"

CheckBox

复选框字段用于表示二值状态，如 “是 / 否”“已完成 / 未完成” 等。通过布尔值表示勾选或未勾选状态，操作简单直观，适用于需要进行二元判断的场景。

Write
- type：boolean
- example：true（勾选）、false（未勾选）
Read
- cellFormat：json
  - type：boolean
  - example：true
- cellFormat：string
  - type：string
  - example："true"、"false"

Single Select

单选字段提供一组预设选项，用户只能选择其中一个，适用于从固定范围选择唯一答案的场景，如性别、学历等。保证选择的唯一性，选项清晰明确，便于数据的统计和分析。

Write
- type：string（选项的唯一标识或名称）
- example："In Progress"
Read
- cellFormat：json
  - type：string
  - example："In Progress"
- cellFormat：string
  - type：string
  - example："In Progress"

Multi Select

多选字段与单选字段类似，但允许用户从预设选项中选择多个，适用于需要选择多个答案的场景，如兴趣爱好、技能标签等。满足多维度选择需求，便于对多个选项进行管理和分析。

Write
- type：array of string
- example：["Friday", "SatDay"]
Read
- cellFormat：json
  - type：array of string
  - example：["Friday", "SatDay"]
- cellFormat：string
  - type：string
  - example："Friday, SatDay"

Member

成员字段用于关联系统中的用户，如任务负责人、项目参与人等。通过成员 ID 进行关联，读取时显示成员相关信息，便于对成员进行管理和协作操作。

Write
- type：array of contact unit object
- example：['member_id']
Read
- cellFormat：json
  - type：array of object
    - object：
      - id：string
      - type: 'Member' | 'Team' | 'Role'
      - name：string
  - example：[{"id": "mem123", "type": "Member", "name": "John Doe"}]
- cellFormat：string
  - type：string
  - example："John Doe"

Date Time

日期时间字段用于记录具体的日期和时间，如事件发生时间、截止时间等。采用 ISO 8601 格式存储，精确到秒，便于进行时间的排序、筛选和计算等操作。

Write
- type：string（ISO 8601 Format，eg: "

2023-10-01"、"2023-10-01T12:00:00.000Z"）

example："2023-10-01T12:00:00Z"
Read
- cellFormat：json
  - type：string
  - example："2023-10-01T12:00:00Z"
- cellFormat：string
  - type：string
  - example："2023-10-01 20:00:00"（本地时间格式化显示）

Date Range

日期范围字段用于记录一个时间段，由开始日期和结束日期组成，如活动举办时间、假期时间等。清晰表示时间的起止范围，便于进行时间段的比较和分析。

Write
- type：string (格式: start/end)
  - properties：
    - start：string（开始日期，ISO 8601 格式）
    - end：string（结束日期，ISO 8601 格式）
- example："2021-03-29T10:05:00.000Z/2021-04-05T10:05:00.000Z"
Read
- cellFormat：json
  - type：string
  - example："2021-03-29 -> 2021-04-05"
- cellFormat：string
  - type：string
  - example："2021-03-29 -> 2021-04-05"

Attachment

附件字段用于存储各类文件，如文档、图片、音频等。支持上传多个文件，记录文件的名称、大小、访问地址等信息，便于对文件进行管理和查看，满足数据存储的多样性需求。

Write
- type：array
  - items：object
    - properties：
      - id: attachment id
      - name：optional<string>（附件名称）
- example：[{"id": "attach123"}, {id: "attach456"}]
Read
- cellFormat：json
  - type：array
    - items：object
      - properties：
        
        id：string（附件 ID）
        
        name：string
        
        mimeType: string
        
        size：number（附件大小，单位字节）
        
        url：string（附件的访问 URL）
        
        thumbnailUrl: string
  - example：[{"id": "att1", "name": "file1.pdf", "url": "https://example.com/file1.pdf", "size": 102400}]
- cellFormat：string
  - type：string
  - example："file1.pdf(https://example.com/file1.pdf)"（多个附件以逗号分隔）

Created Time

创建时间字段用于记录记录的创建时刻，由系统自动生成，不支持手动修改。准确反映记录的产生时间，便于对记录进行时间维度的管理和追踪，如按创建时间排序、筛选等。

Write：read_only，不支持写入
Read
- cellFormat：json
  - type：string（ISO 8601 格式）
  - example："2023-09-01T08:00:00Z"
- cellFormat：string
  - type：string
  - example："2023-09-01 16:00:00"（本地时间格式化显示）

Modified Time

修改时间字段用于记录记录最后一次被修改的时间，每当记录内容变更时，该字段会自动更新。反映记录的最新变动情况，便于跟踪记录的修改历史和版本变化。

Write：read_only，不支持写入
Read
- cellFormat：json
  - type：string（ISO 8601 格式）
  - example："2023-09-02T09:30:00Z"
- cellFormat：string
  - type：string
  - example："2023-09-02 17:30:00"（本地时间格式化显示）

Created By

创建人字段用于记录创建该记录的用户，由系统自动关联，不支持手动修改。明确记录的创建者，便于追溯记录的来源和责任归属，在协作场景中具有重要意义。

Write：read_only，不支持写入
Read
- cellFormat：json
  - type：object
    - properties：
      - id：string (member id)
      - name：string (member name)
  - example：{"id": "mem456", "name": "John Doe"}
- cellFormat：string
  - type：string
  - example："John Doe"

Modified By

修改人字段用于记录最后一次修改该记录的用户，每当记录被修改时，该字段会自动更新为修改者信息。跟踪记录的修改责任人，便于在出现问题时进行追溯和沟通。

Write：read_only，不支持写入
Read
- cellFormat：json
  - type：object
    - properties：
      - id：string (member id)
      - name：string (member name)
  - example：{"id": "mem456", "name": "John Doe"}
- cellFormat：string
  - type：string
  - example："John Doe"

Link

链接字段用于关联其他记录，如关联订单记录、客户记录等。通过目标记录的 ID 进行关联，能快速跳转到关联记录，便于数据之间的关联查询和管理。

Write
- type：string of array（record id of table）
- example：["record123", "record456"]
Read
- cellFormat：json
  - type：string of array
  - example：["record123", "record456"]
- cellFormat：string
  - type：string
  - example："record123, record456"

Lookup

查找字段用于从关联的其他数据表中获取并显示指定字段的值，如从客户表中查找客户所属行业并显示在订单表中。由关联字段自动计算生成，不支持直接写入，确保数据的一致性和准确性。

Write：read_only，由关联字段自动计算，不支持直接写入
Read
- cellFormat: json
  - type: field type cell value
- cellFormat: string
  - type: array of any from field cell value
  - example: ["example text", "another text"]

Formula

公式字段通过预设的计算公式自动计算并显示结果，如根据数量和单价计算总价、根据开始时间和结束时间计算时长等。计算公式由用户设定，字段值随相关字段的变化自动更新，不支持手动写入。

Write：read_only
Read
- type: string | number | boolean | array of (strings | numbers)
- example: '5'

模板

帮助

价格

博客

社区