飞书开放平台 Server API 文档

主题

自定义字段功能概述 ​

任务功能支持在任务中扩充自定义字段，更清晰地添加任务关键信息，高效管理任务，辅助协作推进。任务的使用者可以在使用“任务截止时间”，“任务负责人”……等系统字段之外，自行定义如”优先级“，”项目发布日期“，”价格“等和使用场景密切相关的字段。

自定义字段需要区分“自定义字段的设置”和“自定义字段的值”两个关联的概念。

自定义字段的设置是自定义字段的元数据，包含名称、类型和具体设置。每个自定义字段必须有一个名字。

当前已经支持的自定义字段类型如下：

字段类型描述
数字(number)支持表达一个数值，并以不同的格式在App显示
人员(member)支持添加内外部联系人；可同时选择多个人员
日期(datetime)支持表达一个具体的日期
单选(single_select)用于给任务添加标签，支持自定义标签内容与颜色；仅可选择一个标签
多选(multi_select)用于给任务添加标签，支持自定义标签内容与颜色；可同时选择多个标签
文本(text)用于添加一段自定义的文本描述

每种类型的设置各不相同，比如对于数字类型，可以设置数字格式，是否显示自定义符号，以及符号的位置等；对于日期类型，可以设置日期的显示格式；对于单选/多选，可以设置选项。

自定义字段的设置相关接口包括：

针对单选/多选两种类型的字段中的选项，支持：

自定义字段的值类似于系统内建字段的值。在某个清单定义了自定义字段后，就可以给该清单里的任务设置字段值。比如，可以通过更新任务接口来设置自定义字段的值，也可以通过创建任务接口在任务创建时就设置自定义字段的值。同时，用户可以通过获取任务详情接口查看该任务的自定义字段值。

数据模型和鉴权 ​

自定义字段和清单是多对多的关系。一个清单里可以定义多个自定义字段。一个自定义字段也可以被加入多个清单。

自定义字段的权限是根据清单来定义的。一个用户对一个自定义字段有编辑/读取权限，就意味着至少存在一条用户-清单-自定义字段的关联关系，且用户对该清单有编辑/读取权限（关于清单的鉴权方式见清单功能概述）。如果用户和自定义字段之间存在多条“清单”的管理，用户对自定义字段的权限取其中最大的一条边的权限。因此创建自定义字段时，总是要关联到清单才能添加这些清单的自定义字段；也可以通过将自定义字段加入资源接口将某个自定义字段添加入其他的清单。添加后，清单界面的“字段设置”中就可以查看该字段；同时该清单的所有其他协作成员也会获取该字段的相应权限。如不希望一个字段在某个清单上显示，可以通过将自定义字段移出资源接口将其移出。移出后，原清单的协作成员将失去该字段的权限，除非他们通过其他清单也能访问到该自定义字段。

例如，存在一个用户U1，对清单L1有编辑权限，对清单L2有阅读权限。L1拥有自定义字段F1，F2；L2拥有自定义字段F2和F3。则用户对F1和F2有编辑权限；对F3有阅读权限。如果还有一个清单L3，U1无法访问，L3拥有自定义字段F3和F4。则用户对F4无权限。但如果刚好有另外一个用户U2同时拥有对L1和L3的编辑权限。U2就获得了F4编辑权限。他可以将F4添加到L1中，之后U1就也对F4拥有可编辑权限了。如下图所示：

image.png

可以通过列取自定义字段接口查询调用身份所有有权限的自定义字段，或者通过指定清单GUID查看某一个清单中的自定义字段。

如果一个自定义字段被移出所有的清单，就意味着没有用户再可以访问到它。从用户视角看，被移出所有清单的自定义字段相当于被删除了。但目前并不支持直接删除自定义字段的操作。

自定义字段的值同时归属于任务和自定义字段。用户要查看到一个任务的自定义字段值，必须满足用户对任务有读取权限（详见任务功能概述，同时用户需要拥有自定义字段的读取权限；类似的，用户想要修改一个任务的自定义字段的值，必须同时拥有任务的编辑权限和自定义字段的编辑权限。

例如一个任务T有3个自定义字段的值F1，F2和F3。用户U1可以编辑T，同时对F1和F2有阅读权限，他可以通过获取任务详情接口查看到F1和F2对应的值，但F3的值对他不可见。

自定义字段的值也不可以删除，但可以“清空”，即设为“无”。

数字类型自定义字段 ​

数字类型自定义字段可以用于显示一个数字，例如

json
{
  "guid": "d1fd19fd-4810-479d-a093-fb9b0442c6f6",
  "name": "price",
  "type": "number",
  "number_setting": {
    "format": "custom",
    "decimal_count": 2,
    "separator": "thousand",
    "custom_symbol": "€",
    "custom_symbol_position": "right"
  }
}

表示按照自定义符号的方式显示数字，小数位数为2位。整数部分显示千分隔符，在数字右侧会显示€符号。除decimal_count外的设置仅会影响App中的显示效果，对openapi的字段值的输入输出无影响。

decimal_count会影响数字的小数位数，最大支持6位小数。用户输入的字段超过该设置会被自动四舍五入。

此外，当format不是"custom"时，custom_symbol可以不设置；但如果format是"custom"，则custom_symbol必须设置为最大4个字符的字符串。

该类型字段支持常规的数字（考虑到json的精度问题，会用字符串的格式来输入输出），比如：

PATCH /task/v2/tasks/:task_guid
{
   "task": {
     "custom_fields": [
        {
           "guid": "b78a2bca-b580-4853-b3f8-2ebd477d91ca",
           "number_value": "12.34"
        }
      ]
   },
   "update_fields": ["custom_fields"]
}

可以将一个任务的数字自定义字段（custom_field_guid=b78a2bca-b580-4853-b3f8-2ebd477d91ca)设为12.34。

一些合法的数字如：

  • "1.23"
  • "0.9248"
  • "0"
  • "-12.45"
  • "+6"

而如下输入会被视作非法:

  • "1.2.3" (不是个数字)
  • "1e9" (不支持科学计数法）
  • " 99 " (有空格）
  • "0x125" (不支持16进制，带有非数字的符号视作非法)
  • "20%" (不支持直接输入带百分号的数字，如输入百分数，要输入实际的值0.2)

空字符串""被视作“空”数字。

数字输入时会自动存储为等值的最简格式，例如:

  • 输入"1.200"会只保留"1.2"
  • 输入"054"只会保留"54"，0开头的数字不会被当作8进制解析，只会被视作是10进制高位冗余的0
  • 输入"+67.1"会只保留"67.1"

数字输入时如果超过了decimal_count规定的值将被四舍五入：

  • 输入"20.124", decimal_count=2，会得到"20.12"
  • 输入"0.1558"，decimal_count=2，会得到"0.16"

当输入一个百分数format=percentage时，依然输入数字的原始的值。比如：

  • 输入"0.2"，decimal_count=0, 界面会显示"20%"
  • 输入"2.45"，decimal_count=2, 界面会显示"245.00%"

需要留意当输入为百分数时，decimal_count是指显示为百分数之后的小数位数。因此其实际的小数位数比非百分数总是大2。如输入"0.24563", decimal_count=2；

  • 当format不是百分数时，会得到"0.25"
  • 当format是百分时，会得到"0.2556"（界面上显示25.56%)

修改一个数字自定义字段的decimal_count不会改变已经设置的字段值，但会影响界面上的显示。比如decimal_count设为2，然后写入一个该字段的值"1.23"，之后修改decimal_count为1。通过openapi获取的字段值依然为"1.23"，但界面上会显示为"1.2"，同时筛选/排序等功能都会按照"1.2"来执行。

人员类型自定义字段 ​

人员类型可以填写一个或多个用户。比如：

json
{
  "guid": "b78a2bca-b580-4853-b3f8-2ebd477d91ca",
  "name": "reviewers",
  "type": "member",
  "member_setting": {
    "multi": true,
  }
}

表示设置一个人员类型的字段，字段支持多选，可以在写入值时填写多个用户的信息。

人员类型的值用"member"表示。类似于添加任务成员中的成员格式，但不支持填写role,只能填写id和type。type只支持"user"，同时也是默认值，因此可以省略。id必须填写，其格式根据user_id_type参数来定义（见功能概述中的"如何使用user_id_type修改用户ID格式？")，默认为"open_id"。

PATCH /task/v2/tasks/:task_guid
{
   "task": {
     "custom_fields": [
        {
           "guid": "b78a2bca-b580-4853-b3f8-2ebd477d91ca",
           "member_value": [
              { "id": "ou_49dadcd6fd55da971d887087c4f3a37a" },
              { "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f" }
           ]
        }
      ]
   },
   "update_fields": ["custom_fields"]
}

当multi设为false后，member_value只能设置一个元素。如果一个字段值已经设为多个人员，之后字段的multi由true改为false后，也不会影响字段值，直到字段值在下一次修改。

当multi设为true时，member_value中的多个元素不允许重复。

人员类型字段值使用空数组来表示“空”。

日期类型自定义字段 ​

日期类型可以填写一个表示日期的时间戳。其设置为：

json
{
  "guid": "a0fddac1-0fd5-4903-8cae-5b93ccf0f797",
  "name": "release day",
  "type": "datetime",
  "datetime_setting": {
    "format": "yyyy/mm/dd",
  }
}

日期自定义字段的设置只影响App显示格式。

日期自定义字段的值使用以毫秒为单位的时间戳格式表示，但精度只保留到天。

PATCH /task/v2/tasks/:task_guid
{
   "task": {
     "custom_fields": [
        {
           "guid": "b78a2bca-b580-4853-b3f8-2ebd477d91ca",
           "datetime_value": "1666108800000"
        }
   },
   "update_fields": ["custom_fields"]
}

要设置某个日期的字段值，需要用该日期UTC时间的00:00:00的时间戳表示。比如，使用javascript的moment库可以这样产生：

let m = require('moment');
m('2022-10-19T00:00:00Z').valueOf();
// 得到1666137600000

在设置字段值时，如果精度超过了天，会被自动舍去。比如输入了"1666137600322"，只会保留"1666137600000"。

日期类型字段只支持正数时间戳（即表示1970-01-01之后的日期），填入负数时间戳会提示错误。

日期类型字段值使用空字符串""表示空。

单选/多选类型自定义字段 ​

单选和多选的设置类似，都是提供一组选项。区别是单选的值只能设置一个选项；而多选可以设置多个选项。

单选的例子：

json
{
  "guid": "a0fddac1-0fd5-4903-8cae-5b93ccf0f797",
  "name": "priority",
  "type": "single_select",
  "single_select_setting": {
    "options": [
      {"guid": "734a0135-fcbb-4482-8909-f9589b03d9f1", "name": "high", "color_index": 23, "is_hidden": false},
      {"guid": "89a7d5b0-e29f-4363-a614-1fe47f2d3255", "name": "mid", "color_index": 24, "is_hidden": false},
      {"guid": "f911b99f-c6df-477a-a014-8b76ac40aa00", "name": "low", "color_index": 23, "is_hidden": false},
     ]
  }
}

多选的例子：

json
{
  "guid": "7748b214-d299-4fc3-9d12-d95ef39979f7",
  "name": "publish regions",
  "type": "multi_select",
  "multi_select_setting": {
    "options": [
      {"guid": "345638bd-35b2-48a3-b3cd-ca17169a674f", "name": "america", "color_index": 10, "is_hidden": false},
      {"guid": "439615eb-2d11-41f6-b1c7-4418fd96dd62", "name": "asia", "color_index": 15, "is_hidden": false},
      {"guid": "f911b99f-c6df-477a-a014-8b76ac40aa00", "name": "europe", "color_index": 14, "is_hidden": false},
     ]
  }
}

单选的字段值就是该字段的一个选项的GUID；多选字段的值是本字段一个或多个选项的GUID。同一个多选字段的值中的选项GUID不能重复。

PATCH /task/v2/tasks/:task_guid
{
   "task": {
     "custom_fields": [
        {
           "guid": "a0fddac1-0fd5-4903-8cae-5b93ccf0f797",
           "single_select_value": "89a7d5b0-e29f-4363-a614-1fe47f2d3255"
        },
        {
           "guid": "7748b214-d299-4fc3-9d12-d95ef39979f7",
           "multi_select_value": [
             "345638bd-35b2-48a3-b3cd-ca17169a674f",
             "0f8165c6-b6f9-45e6-ad47-618189546007"
           ]
        }
   },
   "update_fields": ["custom_fields"]
}

单选字段值使用空字符串表示空；多选使用空数组表示空。

关于选项 ​

每个选项包含一个名字，一个颜色索引值，一个隐藏标记(is_hidden) 。选项因为需要关联字段值的缘故，不允许删除，否则字段值就无法找到对应的选项了。但选项可以被标记为隐藏(is_hidden=true)。标记为隐藏的选项将不出现在界面中，openapi也不允许将一个单选/多选的字段值设置为一个隐藏的选项。

一个单选/多选字段最多有100个选项（包含隐藏和可见）。

不被隐藏的选项被称为“可见选项”，单选/多选的设置需要满足如下约束：同一字段的所有可见选项不得重名。因此尝试用openapi创建一个带有同名可见选项的单选/多选字段，或者将一个隐藏的字段恢复为可见，刚好与另外一个可见的选项重名都会得到一个错误。

选项的颜色索引（color_index)是一个0～54的枚举值。每一个数值代表一个颜色。创建时如果不指定，则会随机选择一个。下图是color_index的值与颜色的对应关系。

image.png

选项存在顺序。可见选项在openapi中的返回顺序就是其在界面中的显示顺序。可以通过创建自定义字段选项和更新自定义字段选项中的insert_before或者insert_after来调整选项的顺序，或者直接通过更新自定义字段接口来直接设定可见选项的顺序。

文本类型自定义字段 ​

文本类型自定义字段允许用户为一个任务填写一段文本描述。文本类型除了通用的字段名外没有类型专用的设置：

json
{
  "guid": "a0fddac1-0fd5-4903-8cae-5b93ccf0f797",
  "name": "review comment",
  "type": "text",
  "text_setting": {}
}

该类型字段支持输入一段文本。输入格式和任务的系统字段标题（summary ）完全相同。

PATCH /task/v2/tasks/:task_guid
{
   "task": {
     "custom_fields": [
        {
           "guid": "b78a2bca-b580-4853-b3f8-2ebd477d91ca",
           "text_value": "这是一段文本"
        }
      ]
   },
   "update_fields": ["custom_fields"]
}

可以使用空字符串""将文本自定义字段的值设为空。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有