自定义字段 API

完整的 API 参考，用于管理 Blue 中的自定义字段 - 创建、配置和使用自定义字段以扩展您的数据结构

概述

自定义字段允许您通过额外的数据字段扩展 Blue 的标准记录结构，以满足您的业务需求。它们提供了一种强大的方式来捕获超出内置字段（如标题、描述和截止日期）的结构化数据。

自定义字段在项目级别定义，并可以在该项目内的所有记录（待办事项）中使用。每个字段都有一个特定的类型，决定其验证规则、输入格式和显示行为。

可用操作

核心字段管理

操作	描述	链接
List Custom Fields	查询和过滤自定义字段	View Details →
Create Custom Field	向项目添加新自定义字段	View Details →
Delete Custom Field	适当清理后移除自定义字段	View Details →

字段值

操作	描述	链接
Set Field Values	在记录上设置和更新自定义字段值	View Details →

自定义字段类型

文本字段

类型	描述	用例	链接
TEXT_SINGLE	单行文本输入	Names, titles, short descriptions	View Details →
TEXT_MULTI	多行文本区域	长描述、备注、评论	View Details →

选择字段

类型	描述	用例	链接
SELECT_SINGLE	单选下拉菜单	Status, priority, category	View Details →
SELECT_MULTI	多选下拉菜单	Tags, skills, categories	View Details →
CHECKBOX	布尔复选框字段	Flags, approvals, confirmations	View Details →

数字字段

类型	描述	用例	链接
NUMBER	数字输入	Quantities, scores, measurements	View Details →
CURRENCY	货币金额	Budgets, costs, pricing	View Details →
PERCENT	百分比值	Completion rates, discounts	View Details →
RATING	自定义评分的星级	Performance ratings, satisfaction	View Details →
FORMULA	基于其他字段的计算字段	Totals, computations, aggregations	View Details →

联系人字段

类型	描述	用例	链接
EMAIL	带验证的电子邮件地址	联系信息、通知	View Details →
PHONE	带国际格式的电话号码	Contact details, emergency contacts	View Details →
URL	带验证的网页 URL	Links, references, resources	View Details →

日期和时间字段

类型	描述	用例	链接
DATE	日期选择器	Deadlines, milestones, events	View Details →
TIME_DURATION	时间跟踪字段	Work hours, duration estimates	View Details →

位置和地理

类型	描述	用例	链接
LOCATION	地理位置（纬度/经度）	Addresses, venues, service areas	View Details →
COUNTRY	国家选择器	Regional assignments, localization	View Details →

文件和媒体

类型	描述	用例	链接
FILE	文件附件	Documents, images, resources	View Details →

系统字段

类型	描述	用例	链接
UNIQUE_ID	自动生成的唯一标识符	Ticket numbers, order IDs	View Details →
REFERENCE	链接到另一个项目中的记录	Cross-project relationships	View Details →
LOOKUP	从引用的记录中提取数据	Aggregate data from related records	View Details →

交互字段

类型	描述	用例	链接
BUTTON	可操作的按钮字段	Triggers, actions, workflows	View Details →
CURRENCY_CONVERSION	货币转换字段	Multi-currency calculations	View Details →

关键概念

字段定义

自定义字段在项目级别定义
每个字段都有一个唯一的名称和类型
字段可以包括验证规则和约束
配置选项因字段类型而异

字段值

值存储在单个记录（待办事项）上
每个记录可以对同一字段有不同的值
可选字段允许为空/空值
值根据字段类型规则进行验证

权限模型

自定义字段遵循项目级别的权限：

角色	创建字段	编辑字段*	设置值	查看值
OWNER	✅ 是	✅ 是	✅ 是	✅ 是
ADMIN	✅ 是	✅ 是	✅ 是	✅ 是
MEMBER	❌ 否	❌ 否	✅ 是	✅ 是
CLIENT	❌ 否	❌ 否	✅ 有限	✅ 有限

*编辑字段是指修改字段设置（名称、类型、选项、验证规则） - 而不是在记录上设置字段值

自定义角色权限

项目可以拥有具有字段特定权限的自定义角色
字段可以根据角色标记为可编辑/不可编辑
自定义角色可以限制对特定字段的访问

常见模式

创建基本自定义字段

mutation CreateCustomField {
  createCustomField(input: {
    name: "Priority Level"
    type: SELECT_SINGLE
    description: "Task priority level"
    customFieldOptions: [
      { title: "Low", color: "#28a745" }
      { title: "Medium", color: "#ffc107" }
      { title: "High", color: "#fd7e14" }
      { title: "Critical", color: "#dc3545" }
    ]
  }) {
    id
    name
    type
    customFieldOptions {
      id
      title
      color
    }
  }
}

在记录上设置字段值

mutation SetFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionId: "option_789"  # For SELECT_SINGLE
  })
}

查询具有自定义字段的记录

query GetTodosWithCustomFields {
  todos(projectId: "project_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      # Type-specific value fields
      text           # TEXT_SINGLE, TEXT_MULTI, EMAIL, etc.
      number         # NUMBER, CURRENCY, PERCENT, RATING
      selectedOption # SELECT_SINGLE
      selectedOptions # SELECT_MULTI
      checked        # CHECKBOX
      date           # DATE
    }
  }
}

使用自定义字段值创建记录

mutation CreateTodoWithCustomFields {
  createTodo(input: {
    title: "New task"
    todoListId: "list_123"
    customFields: [
      { customFieldId: "priority_field", value: "high_priority_option" }
      { customFieldId: "budget_field", value: "5000" }
      { customFieldId: "notes_field", value: "Additional context here" }
    ]
  }) {
    id
    title
    customFields {
      customField { name }
      value
    }
  }
}

最佳实践

字段设计

使用描述性名称 - 使字段目的明确
选择适当的类型 - 将字段类型与数据要求匹配
设置验证规则 - 使用最小/最大值、必填字段
逻辑组织 - 将相关字段分组在一起

性能考虑

限制字段数量 - 字段过多可能影响性能
使用分页 - 查询大型数据集时
索引关键字段 - 对用于过滤/排序的字段
避免深层嵌套 - 保持字段关系简单

数据质量

验证输入 - 使用适当的字段类型和验证
提供默认值 - 在适当的地方设置合理的默认值
使用一致的格式 - 标准化数据输入模式
定期清理 - 移除未使用的字段和选项

用户体验

清晰的描述 - 提供有用的字段描述
逻辑排序 - 按自然工作流程顺序排列字段
视觉层次 - 有效使用颜色和格式
渐进式披露 - 在相关时显示字段

错误处理

使用自定义字段时常见的错误：

错误代码	描述	解决方案
`CUSTOM_FIELD_NOT_FOUND`	字段不存在	Verify field ID and project access
`VALIDATION_ERROR`	值与字段类型不匹配	Check format and validation rules
`UNAUTHORIZED`	权限不足	Ensure proper role level
`CUSTOM_FIELD_VALUE_PARSE_ERROR`	无效的值格式	Review field type requirements

概述