自訂欄位 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

概述