創建自定義字段

添加新的自定義字段以擴展您的項目數據結構，並進行特定類型的配置

創建自定義字段

自定義字段允許您通過向記錄添加結構化數據字段來根據您的具體業務需求調整 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 字段需要單獨創建選項
命名：字段名稱應該清晰且具描述性，因為它們在 UI 中顯示

創建自定義字段

基本示例

高級示例

輸入參數

CreateCustomFieldInput

CustomFieldType 值

字段類型配置示例

帶約束的數字字段

貨幣字段

帶到期日標誌的日期字段

參考字段

查找字段

帶序列的唯一 ID

時間持續字段

有效的時間持續類型

創建選擇選項

響應字段

CustomField

所需權限

錯誤響應

無效的字段類型

找不到參考項目

缺少必需的配置

重要說明

相關端點

AI 助手

我能幫助您什麼？