檢索項目或多個項目的自定義欄位的分頁列表，並提供過濾和排序選項
列出所有自定義欄位
自定義欄位允許您根據業務需求擴展 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 |
最小值 (數字、評分、百分比) |
max |
Float |
最大值 (數字、評分、百分比) |
currency |
String |
貨幣代碼 (貨幣類型) |
prefix |
String |
UNIQUE_ID 生成的前綴 |
isDueDate |
Boolean |
是否 DATE 欄位表示到期日 |
formula |
JSON |
公式配置 (公式類型) |
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 接口
- 某些欄位類型（如公式和引用）可能包含額外的嵌套數據結構
editable 欄位指示當前用戶是否可以修改此自定義欄位的值
相關端點