Skip to Content
核心概念欄位型別單選與多選

選項型別：select 與 multi_select

用途

select 適合訂單狀態、風險等級等一次只能選一個值的受控字典；multi_select 適合商品標籤、技能與適用通路等可同時選多個值的欄位。例如 CRM 可用 select 限制商機階段只能是「新商機／洽談中／成交」，再用 multi_select 標註「企業客戶」與「續約優先」。

建立 schema

單選欄的 columns.create body：

{
  "name": "訂單狀態",
  "type": "select",
  "required": true,
  "default_value": "待處理",
  "options": ["待處理", "處理中", "已完成"]
}

多選欄的 body 不可設定 default_value：

{
  "name": "客戶標籤",
  "type": "multi_select",
  "required": false,
  "options": ["企業客戶", "續約優先", "需要培訓"]
}

合法與不合法的值

select 是一個選項字串；multi_select 是不重複的選項字串陣列。

{
  "data": {
    "訂單狀態": "處理中",
    "客戶標籤": ["企業客戶", "續約優先"]
  }
}

未列在 options 的值、重複值，以及把多選寫成單一字串都不合法：

{
  "data": {
    "訂單狀態": "已取消",
    "客戶標籤": ["企業客戶", "企業客戶"]
  }
}
{
  "data": {
    "客戶標籤": "企業客戶"
  }
}

顯示與回傳

回傳值保持字典中的原始字串與陣列順序；API 不會替選項加入顏色、代碼或翻譯：

{
  "data": {
    "訂單狀態": "處理中",
    "客戶標籤": ["企業客戶", "續約優先"]
  }
}

顏色與排序是前端呈現設定，不應改變寫回 API 的字串。

注意事項

  • options 必須有 1–50 個項目；每個項目是唯一、非空且不超過 64 字的字串。
  • 兩種型別都不可設定 max_length；multi_select 也不可設定 default_value，空值使用 []。選填 select 可用 null 或空字串表示未選，建議固定送 null。
  • select 的 default_value 必須是其 options 之一：其他任何字串在 columns.create 都會得到 400 Invalid default value for column '<name>': Default value '<value>' is not one of the column options（非字串的預設值則會得到 Default value '<value>' must be a string (one of the column options)），columns.update 也以 400 拒絕。multi_select 的 default_value 在兩者上都是 400。
  • 這兩種型別一律可用。過去用來控制它們的 CUSTOM_TABLE_RULES_V12 部署開關已從後端刪除，所以沒有東西需要開啟，也不會再出現「requires …」的拒絕。
  • PATCH columns/{column_id} 的 options 會整批取代清單。若移除仍被 live 紀錄使用的項目，伺服器回 409，其 detail.in_use 物件會列出每個選項的使用數量；已軟刪除的紀錄不會阻擋移除。新清單仍須包含欄位目前的 default_value，請先在前一個請求中更改預設值。
  • 選項改名要送非空的 option_renames 物件，例如 { "處理中": "進行中" }。每個舊名稱都必須存在；新名稱必須非空且最多 64 字；改名後的完整選項清單仍須唯一。
  • 選項改名會重寫相符的 select cell 與 multi_select 陣列成員，也包含軟刪除紀錄，避免之後還原時復活舊值。相符的 select 預設值也會改名，受影響的 unique 規則 entries 會重建。若該欄位是 unique_tuple 規則的成分，改名與任何型別變更都會被拒絕，須先移除該規則。同一請求同時送 options 與 option_renames 會被拒絕，但除了最先觸發的上述 unique_tuple 拒絕之外，options 清單會先單獨檢查：移除了仍被 live 紀錄使用之選項的清單會得到上面的 409，無效的清單或不含目前 default_value 的清單則得到該項檢查的 400。只有通過這些檢查的清單才會得到 400 options and option_renames cannot be combined in one request — rename first, then replace the list。先改名，再用下一個請求整批取代清單。
  • 無論是移除選項還是改名，都不會改寫紀錄歷史，而且兩條還原路徑都會檢查目前的選項清單。還原一個 cell 帶有已移除選項或改名前名稱的歷史版本，或還原一筆帶有已移除選項的垃圾桶紀錄，會回 409，detail.conflicts 的項目例如 {"type": "invalid_value", "field": null, "message": "Field 'Order status' value 'Canceled' is not an allowed option (valid: Pending, Processing, Complete)"}。不會還原任何東西，也不會暫存去等待簽核。

試試看

到 API Playground 建立選項欄；選項後續異動的完整契約請見 columns.update。

Last updated on
區間附件