检索项目或多个项目的自定义字段的分页列表，并提供过滤和排序选项
列出所有自定义字段
自定义字段允许您根据业务需求扩展 Blue 的标准记录结构，添加特定的数据字段。此端点检索您项目中可用的自定义字段，并支持按字段类型过滤和分页。
基本示例
query ListCustomFields {
customFields(
filter: { projectId: "project_123" }
sort: position_ASC
take: 20
) {
items {
id
uid
name
type
position
}
pageInfo {
totalItems
hasNextPage
}
}
}
高级示例
query ListCustomFieldsAdvanced {
customFields(
filter: {
projectId: "project_123"
types: [TEXT_SINGLE, NUMBER, SELECT_SINGLE]
}
sort: name_ASC
skip: 20
take: 50
) {
items {
id
uid
name
type
position
description
# Type-specific fields
min # For NUMBER, RATING, PERCENT
max # For NUMBER, RATING, PERCENT
currency # For CURRENCY type
prefix # For UNIQUE_ID type
isDueDate # For DATE type
formula # For FORMULA type
# Validation settings
editable
metadata
# For SELECT types
customFieldOptions {
id
title
color
position
}
}
pageInfo {
totalItems
hasNextPage
hasPreviousPage
}
}
}
输入参数
| 参数 |
类型 |
必需 |
描述 |
projectId |
String |
否 |
按特定项目 ID 过滤 |
types |
[CustomFieldType!] |
否 |
按自定义字段类型过滤 |
CustomFieldSort 值
| 值 |
描述 |
name_ASC |
按名称升序排序 (A-Z) |
name_DESC |
按名称降序排序 (Z-A) |
createdAt_ASC |
按创建日期排序 (最旧的在前) |
createdAt_DESC |
按创建日期排序 (最新的在前) |
position_ASC |
按位置排序 (默认) |
position_DESC |
按位置降序排序 |
CustomFieldType 值
| 值 |
描述 |
TEXT_SINGLE |
单行文本输入 |
TEXT_MULTI |
多行文本区域 |
SELECT_SINGLE |
单选下拉菜单 |
SELECT_MULTI |
多选下拉菜单 |
CHECKBOX |
布尔复选框字段 |
RATING |
星级评分 (1-5 或自定义范围) |
PHONE |
带验证的电话号码 |
NUMBER |
数字输入 |
CURRENCY |
货币金额 |
PERCENT |
百分比值 |
EMAIL |
带验证的电子邮件地址 |
URL |
带验证的网页 URL |
UNIQUE_ID |
自动生成的唯一标识符 |
LOCATION |
地理位置 (纬度/经度) |
FILE |
文件附件 |
DATE |
日期选择器 |
COUNTRY |
国家选择器 |
FORMULA |
基于其他字段的计算字段 |
REFERENCE |
链接到另一个项目中的记录 |
LOOKUP |
从引用记录中提取数据 |
TIME_DURATION |
时间跟踪字段 |
BUTTON |
可操作按钮字段 |
CURRENCY_CONVERSION |
货币转换字段 |
分页参数
| 参数 |
类型 |
必需 |
描述 |
skip |
Int |
否 |
跳过的项目数量 (默认: 0) |
take |
Int |
否 |
返回的项目数量 (默认: 20, 最大: 500) |
响应字段
CustomField
| 字段 |
类型 |
描述 |
id |
String! |
唯一标识符 |
uid |
String! |
唯一用户友好的 ID |
name |
String! |
字段的显示名称 |
type |
CustomFieldType! |
自定义字段的类型 |
position |
Float! |
排序顺序位置 |
description |
String |
可选字段描述 |
min |
Float |
最小值 (NUMBER, RATING, PERCENT) |
max |
Float |
最大值 (NUMBER, RATING, PERCENT) |
currency |
String |
货币代码 (CURRENCY 类型) |
prefix |
String |
UNIQUE_ID 生成的前缀 |
isDueDate |
Boolean |
DATE 字段是否表示截止日期 |
formula |
JSON |
公式配置 (FORMULA 类型) |
editable |
Boolean |
当前用户是否可以编辑此字段 |
metadata |
JSON |
额外字段配置 |
customFieldOptions |
[CustomFieldOption!] |
SELECT 类型的可用选项 |
CustomFieldOption
| 字段 |
类型 |
描述 |
id |
String! |
唯一标识符 |
title |
String! |
选项的显示文本 |
color |
String! |
十六进制颜色代码 |
position |
Float! |
排序顺序位置 |
PageInfo
| 字段 |
类型 |
描述 |
totalItems |
Int |
自定义字段的总数 |
hasNextPage |
Boolean! |
是否存在更多页面 |
hasPreviousPage |
Boolean! |
是否存在前面的页面 |
endCursor |
String |
分页的游标 (已弃用 - 使用基于偏移量的分页) |
所需权限
自定义字段的访问权限取决于您的项目角色。如果您有自定义角色并限制了字段访问，则仅返回标记为可编辑的字段。
| 角色 |
可以列出自定义字段 |
OWNER |
✅ 是 (所有字段) |
ADMIN |
✅ 是 (所有字段) |
MEMBER |
✅ 是 (基于角色权限) |
CLIENT |
✅ 是 (基于角色权限) |
错误响应
项目未找到
{
"errors": [{
"message": "Project not found.",
"extensions": {
"code": "PROJECT_NOT_FOUND"
}
}]
}
无效字段类型
{
"errors": [{
"message": "Variable \"$filter\" got invalid value \"INVALID_TYPE\" at \"filter.types[0]\"; Value \"INVALID_TYPE\" does not exist in \"CustomFieldType\" enum.",
"extensions": {
"code": "GRAPHQL_VALIDATION_FAILED"
}
}]
}
重要说明
- 自定义字段的作用范围限于项目 - 您必须在过滤器中指定一个
projectId
take 参数每个请求限制为 500 个项目以提高性能- 字段的返回基于用户权限 - 自定义角色可能会有访问限制
- 默认排序顺序为
position 升序，反映 UI 中显示的顺序
- 此查询支持单项目过滤 - 对于多项目查询，请使用嵌套的 CustomFieldQueries 接口
- 某些字段类型（如 FORMULA 和 REFERENCE）可能包含额外的嵌套数据结构
editable 字段指示当前用户是否可以修改此自定义字段的值
相关端点