创建自定义字段

添加新的自定义字段，以扩展项目的数据结构并进行特定类型的配置

创建自定义字段

自定义字段允许您通过向记录添加结构化数据字段来根据特定的业务需求定制 Blue。此端点创建一个具有特定于每个字段类型的配置的新自定义字段。

基本示例

mutation CreateTextField {
  createCustomField(input: {
    name: "Customer Name"
    type: TEXT_SINGLE
    description: "Primary customer contact name"
  }) {
    id
    uid
    name
    type
    position
  }
}

高级示例

mutation CreateAdvancedField {
  createCustomField(input: {
    name: "Project Budget"
    type: CURRENCY
    description: "Total allocated budget for this project"
    currency: "USD"
    min: 0
    max: 1000000
  }) {
    id
    uid
    name
    type
    currency
    min
    max
    position
    createdAt
  }
}

输入参数

CreateCustomFieldInput

参数	类型	必需	描述
`name`	String!	✅ 是	自定义字段的显示名称
`type`	CustomFieldType!	✅ 是	字段类型（见下文类型）
`description`	String	否	可选描述，解释字段的目的
`min`	Float	否	NUMBER、RATING、PERCENT 字段的最小值
`max`	Float	否	NUMBER、RATING、PERCENT 字段的最大值
`currency`	String	否	CURRENCY 字段的 ISO 货币代码
`prefix`	String	否	UNIQUE_ID 字段的文本前缀
`isDueDate`	Boolean	否	DATE 字段是否表示截止日期
`formula`	JSON	否	FORMULA 字段的公式配置
`referenceProjectId`	String	否	REFERENCE 字段的目标项目 ID
`referenceMultiple`	Boolean	否	允许在 REFERENCE 字段中进行多重选择
`referenceFilter`	TodoFilterInput	否	REFERENCE 字段的过滤选项
`lookupOption`	CustomFieldLookupOptionInput	否	LOOKUP 字段的配置
`timeDurationDisplay`	CustomFieldTimeDurationDisplayType	否	TIME_DURATION 的显示格式
`timeDurationTargetTime`	Float	否	TIME_DURATION 的目标时间（秒）
`timeDurationStartInput`	CustomFieldTimeDurationInput	否	TIME_DURATION 的开始触发器
`timeDurationEndInput`	CustomFieldTimeDurationInput	否	TIME_DURATION 的结束触发器
`buttonType`	String	否	BUTTON 字段的按钮操作类型
`buttonConfirmText`	String	否	BUTTON 字段的确认提示
`useSequenceUniqueId`	Boolean	否	UNIQUE_ID 使用顺序编号
`sequenceDigits`	Int	否	序列中的数字位数（例如，5 → 00001）
`sequenceStartingNumber`	Int	否	序列的起始数字
`currencyFieldId`	String	否	CURRENCY_CONVERSION 的参考货币字段
`conversionDate`	String	否	CURRENCY_CONVERSION 的转换日期
`conversionDateType`	String	否	CURRENCY_CONVERSION 的转换日期类型
`metadata`	JSON	否	自定义字段的附加元数据

CustomFieldType 值

值	描述	必需参数
`TEXT_SINGLE`	单行文本输入	无
`TEXT_MULTI`	多行文本区域	无
`SELECT_SINGLE`	单选下拉菜单	Create options separately
`SELECT_MULTI`	多选下拉菜单	Create options separately
`CHECKBOX`	布尔复选框	无
`RATING`	星级评分字段	Optional: `max` (default: 5)
`PHONE`	带验证的电话号码	无
`NUMBER`	数字输入	Optional: `min`, `max`
`CURRENCY`	货币金额	Optional: `currency`, `min`, `max`
`PERCENT`	百分比（0-100）	Optional: `min`, `max`
`EMAIL`	带验证的电子邮件	无
`URL`	带验证的网页 URL	无
`UNIQUE_ID`	自动生成的标识符	Optional: `prefix`, `useSequenceUniqueId`
`LOCATION`	地理坐标	无
`FILE`	文件附件	无
`DATE`	日期选择器	Optional: `isDueDate`
`COUNTRY`	国家选择器	无
`FORMULA`	计算字段	Required: `formula`
`REFERENCE`	链接到其他记录	Required: `referenceProjectId`
`LOOKUP`	从引用中提取数据	Required: `lookupOption`
`TIME_DURATION`	时间跟踪	Required: duration inputs (see below)
`BUTTON`	动作按钮	Optional: `buttonType`, `buttonConfirmText`
`CURRENCY_CONVERSION`	货币转换器	Special configuration

字段类型配置示例

带约束的数字字段

mutation CreateQuantityField {
  createCustomField(input: {
    name: "Quantity"
    type: NUMBER
    description: "Number of items"
    min: 1
    max: 999
  }) {
    id
    name
    min
    max
  }
}

货币字段

mutation CreateBudgetField {
  createCustomField(input: {
    name: "Budget"
    type: CURRENCY
    currency: "EUR"
    min: 0
  }) {
    id
    name
    currency
    min
  }
}

带截止日期标志的日期字段

mutation CreateDeadlineField {
  createCustomField(input: {
    name: "Project Deadline"
    type: DATE
    isDueDate: true
    description: "When this project must be completed"
  }) {
    id
    name
    isDueDate
  }
}

参考字段

mutation CreateRelatedTasksField {
  createCustomField(input: {
    name: "Dependencies"
    type: REFERENCE
    referenceProjectId: "proj_abc123"
    referenceMultiple: true
    referenceFilter: {
      statusIds: ["status_open", "status_inprogress"]
    }
  }) {
    id
    name
    referenceProjectId
    referenceMultiple
  }
}

查找字段

mutation CreateLookupField {
  createCustomField(input: {
    name: "Customer Email"
    type: LOOKUP
    lookupOption: {
      referenceId: "field_customer_ref"
      lookupId: "field_email"
      lookupType: TODO_CUSTOM_FIELD
    }
  }) {
    id
    name
    customFieldLookupOption {
      referenceId
      lookupId
      lookupType
    }
  }
}

带序列的唯一 ID

mutation CreateOrderNumberField {
  createCustomField(input: {
    name: "Order Number"
    type: UNIQUE_ID
    prefix: "ORD-"
    useSequenceUniqueId: true
    sequenceDigits: 6
    sequenceStartingNumber: 1000
  }) {
    id
    name
    prefix
  }
}

时间持续字段

mutation CreateTimeTrackingField {
  createCustomField(input: {
    name: "Time to Resolution"
    type: TIME_DURATION
    timeDurationDisplay: FULL_DATE_STRING
    timeDurationStartInput: {
      type: TODO_CREATED_AT
      condition: FIRST
    }
    timeDurationEndInput: {
      type: TODO_MARKED_AS_COMPLETE
      condition: FIRST
    }
  }) {
    id
    name
  }
}

有效的时间持续类型

TODO_CREATED_AT - 记录创建时
TODO_CUSTOM_FIELD - 自定义字段更改时
TODO_DUE_DATE - 设置/更改截止日期时
TODO_MARKED_AS_COMPLETE - 记录标记为完成时
TODO_MOVED - 记录移至不同列表时
TODO_TAG_ADDED - 添加标签时
TODO_ASSIGNEE_ADDED - 添加指派人时

创建选择选项

创建 SELECT_SINGLE 或 SELECT_MULTI 字段后，添加选项：

mutation CreateSelectOptions {
  createCustomFieldOptions(input: {
    customFieldId: "field_xyz789"
    customFieldOptions: [
      { title: "High", color: "#FF0000", position: 1 }
      { title: "Medium", color: "#FFA500", position: 2 }
      { title: "Low", color: "#00FF00", position: 3 }
    ]
  }) {
    id
    title
    color
    position
  }
}

响应字段

CustomField

字段	类型	描述
`id`	String!	唯一标识符
`uid`	String!	用户友好的唯一 ID
`name`	String!	显示名称
`type`	CustomFieldType!	字段类型
`description`	String	字段描述
`position`	Float!	显示顺序位置
`createdAt`	DateTime!	创建时间戳
`updatedAt`	DateTime!	最后更新时间戳
`min`	Float	最小值（如适用）
`max`	Float	最大值（如适用）
`currency`	String	货币代码（CURRENCY 类型）
`prefix`	String	ID 前缀（UNIQUE_ID 类型）
`isDueDate`	Boolean	截止日期标志（DATE 类型）
`formula`	JSON	公式配置（FORMULA 类型）
`referenceProjectId`	String	参考项目（REFERENCE 类型）
`customFieldLookupOption`	CustomFieldLookupOption	查找配置（LOOKUP 类型）

所需权限

创建自定义字段需要项目访问权限：

角色	可以创建自定义字段
`OWNER`	✅ 是
`ADMIN`	✅ 是
`MEMBER`	✅ 是
`CLIENT`	❌ 否

注意：自定义角色可能对字段管理有额外限制。

错误响应

无效的字段类型

{
  "errors": [{
    "message": "Variable \"$input\" got invalid value \"INVALID\" at \"input.type\"; Value \"INVALID\" does not exist in \"CustomFieldType\" enum.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

找不到参考项目

{
  "errors": [{
    "message": "Reference project not found or access denied",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

缺少必需配置

{
  "errors": [{
    "message": "REFERENCE fields require referenceProjectId",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

重要说明

字段位置：自动计算以出现在现有字段的末尾
字段限制：项目可能对自定义字段的数量有限制
立即可用性：创建的字段立即可供使用
副作用：创建字段会触发：
- 活动日志条目
- 实时更新连接用户
- Webhook 通知
- FORMULA、LOOKUP 和 UNIQUE_ID 字段的后台作业
特殊考虑：
- REFERENCE 字段需要访问目标项目
- LOOKUP 字段依赖于现有的 REFERENCE 字段
- FORMULA 字段不能引用自身
- UNIQUE_ID 序列异步处理
- SELECT 字段需要单独创建选项
命名：字段名称应清晰且描述性，以便在用户界面中显示

创建自定义字段

基本示例

高级示例

输入参数

CreateCustomFieldInput

CustomFieldType 值

字段类型配置示例

带约束的数字字段

货币字段

带截止日期标志的日期字段

参考字段

查找字段

带序列的唯一 ID

时间持续字段

有效的时间持续类型

创建选择选项

响应字段

CustomField

所需权限

错误响应

无效的字段类型

找不到参考项目

缺少必需配置

重要说明

相关端点

AI助手

我能帮您什么？