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。
  • 這兩種型別一律可用。過去用來控制它們的 CUSTOM_TABLE_RULES_V12 部署開關已從後端刪除，所以沒有東西需要開啟，也不會再出現「requires …」的拒絕。
  • PATCH columns/{column_id} 的 options 會整批取代清單。若移除仍被現存紀錄使用的項目，伺服器回 409 並附使用數量。
  • 選項改名要送非空的 option_renames 物件，例如 { "處理中": "進行中" }。每個舊名稱都必須存在；新名稱必須非空且最多 64 字；改名後的完整選項清單仍須唯一。
  • 選項改名會重寫相符的 select cell 與 multi_select 陣列成員，也包含軟刪除紀錄，避免之後還原時復活舊值。相符的 select 預設值也會改名，受影響的 unique-rule entries 會重建。options 與 option_renames 不可在同一請求併用；先改名，再用下一個請求整批取代清單。

試試看

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

Last updated on
區間附件