API 使用指南

本文档主要说明工作表和行记录相关接口的推荐使用方式与调用规范，帮助你按场景完成结构设计、数据写入和结构变更。

1. API 使用技巧

创建关联表/子表的流程

先创建目标实体表，再给主表新增字段。

关联字段与子表字段都依赖 dataSource，必须先有目标工作表。

新增/更新行记录流程

先获取工作表结构，确认字段 id、选项 key、关联字段类型。

涉及关联字段时，先拿到目标记录 rowId，再写入主记录。

附件字段值

支持 URL 和 base64。

附件字段更新时可用 type 控制覆盖/追加（0 覆盖，1 追加）。

2. 场景一：创建基础工作表

适合先搭一张能跑起来的表，包含：

标题

数值

单选

多选

日期

日期时间

接口：

示例：

{
  "name": "合同管理",
  "alias": "contracts",
  "fields": [
    {
      "name": "合同名称",
      "alias": "title",
      "type": "Text",
      "isTitle": true,
      "required": true
    },
    {
      "name": "合同金额",
      "alias": "amount",
      "type": "Number",
      "precision": 2
    },
    {
      "name": "状态",
      "alias": "status_option",
      "type": "SingleSelect",
      "options": [
        { "value": "待处理", "index": 1 },
        { "value": "已完成", "index": 2 }
      ]
    },
    {
      "name": "标签",
      "alias": "tag_set",
      "type": "MultipleSelect",
      "options": [
        { "value": "重点", "index": 1 },
        { "value": "续签", "index": 2 },
        { "value": "归档", "index": 3 }
      ]
    },
    {
      "name": "签约日期",
      "alias": "biz_date",
      "type": "Date",
      "subType": "3"
    },
    {
      "name": "更新时间",
      "alias": "biz_datetime",
      "type": "DateTime",
      "subType": "6"
    }
  ]
}

3. 场景二：给工作表补充关联字段

如果业务里有“客户 -> 合同”“项目 -> 任务”这种关系，建议拆成两步：

先创建被关联表

再在主表新增关联字段

3.1 先创建被关联表

{
  "name": "客户表",
  "alias": "customers",
  "fields": [
    {
      "name": "客户名称",
      "alias": "name",
      "type": "Text",
      "isTitle": true,
      "required": true
    }
  ]
}

3.2 在主表新增单条关联字段

{
  "addFields": [
    {
      "name": "客户",
      "alias": "customer_ref",
      "type": "Relation",
      "dataSource": "{customer_worksheet_id}",
      "subType": "1"
    }
  ]
}

3.3 在主表新增多条关联字段

如果一条记录要关联多条数据，把 subType 改成 2：

{
  "addFields": [
    {
      "name": "相关客户",
      "alias": "customer_refs",
      "type": "Relation",
      "dataSource": "{customer_worksheet_id}",
      "subType": "2"
    }
  ]
}

4. 场景三：给工作表补充子表字段

子表和关联字段一样，都需要先有目标实体表（dataSource），再通过“更新工作表”新增。

推荐顺序：

先创建子表源工作表

再给主表新增子表字段

示例：

{
  "addFields": [
    {
      "name": "明细子表",
      "alias": "detail_items",
      "type": "SubTable",
      "dataSource": "{detail_worksheet_id}",
      "subType": "2"
    }
  ]
}

5. 场景四：更新工作表结构

更新工作表之前，建议先获取结构，确认字段 id、字段类型和选项值。

接口：

然后再做结构修改。

5.1 新增字段

{
  "addFields": [
    {
      "name": "附件资料",
      "alias": "attachment_docs",
      "type": "Attachment"
    },
    {
      "name": "优先级",
      "alias": "priority_level",
      "type": "Rating",
      "max": 5
    }
  ]
}

5.2 编辑字段

{
  "editFields": [
    {
      "id": "{field_id}",
      "name": "优先级（新版）"
    }
  ]
}

5.3 删除字段

{
  "removeFields": [
    "{field_id}"
  ]
}

6. 场景五：新增和更新行记录

新增或更新记录前，建议先获取工作表结构。

原因是：

你要确认字段别名

如果有选项字段，你需要先知道选项 key

如果有关联字段，你要先拿到被关联记录的 rowId

6.1 新增基础行记录

接口：

示例：

{
  "fields": [
    { "id": "title", "value": "合同 A" },
    { "id": "amount", "value": "5200.00" },
    { "id": "biz_date", "value": "2026-03-26" },
    { "id": "biz_datetime", "value": "2026-03-26 11:22:33" },
    { "id": "priority_level", "value": "2" }
  ],
  "triggerWorkflow": false
}

6.2 新增带关联的行记录

如果一条记录要关联另一张表，推荐先查到目标记录，再写主记录。

写入单条关联时，可以直接传目标记录的 rowId：

{
  "fields": [
    { "id": "title", "value": "合同 B" },
    { "id": "customer_ref", "value": "{customer_row_id}" }
  ],
  "triggerWorkflow": false
}

如果还要写负责人：

{
  "fields": [
    { "id": "title", "value": "合同 C" },
    { "id": "owner_user", "value": "{user_account_id}" },
    { "id": "customer_ref", "value": "{customer_row_id}" }
  ],
  "triggerWorkflow": false
}

6.3 更新行记录

接口：

示例：

{
  "fields": [
    { "id": "owner_user", "value": "{user_account_id}" },
    { "id": "customer_ref", "value": "{customer_row_id}" },
    { "id": "priority_level", "value": "5" }
  ],
  "triggerWorkflow": false
}

6.4 更新附件字段

如果要追加附件，可以这样写（支持 URL / base64）：

{
  "fields": [
    {
      "id": "attachment_docs",
      "type": "1",
      "value": "[{\"name\":\"file.png\",\"url\":\"https://example.com/file.png\"}]"
    }
  ],
  "triggerWorkflow": false
}

API 使用指南

API 使用指南#

API 使用指南