數值型別：integer 與 float

用途

integer 適合件數、庫存量與優先級等離散數量；float 適合單價、重量與轉換率等可能有小數的數值。例如訂單明細用 integer 儲存數量 2，再用 float 儲存單價 1290.5，公式欄即可算出小計。

建立 schema

整數欄的 columns.create body：

{
  "name": "數量",
  "type": "integer",
  "required": true,
  "default_value": 1,
  "description": "本次訂購件數"
}

浮點數欄的 body：

{
  "name": "單價",
  "type": "float",
  "required": true,
  "default_value": 0.0,
  "description": "未稅單價"
}

合法與不合法的值

原生 JSON 數字是最穩定的寫法；float 同時接受整數與小數。選填欄也接受 null 或空字串作為空值，整合端建議固定送 null。

{
  "data": {
    "數量": 2,
    "單價": 1290.5
  }
}

寫入路徑也會把可解析的數字字串轉成數字，並依 Python round() 規則把送到 integer 的小數捨入後轉成整數；正好位於 .5 時會取最近偶數。前端仍應先正規化，以免使用者看不出值已改變。以下值無法轉成所需型別：

{
  "data": {
    "數量": true,
    "單價": "一千二百九十"
  }
}

布林值不會因 Python 的型別關係被當成 1 或 0；非數字字串也會收到 must be an integer 或 must be a number。

顯示與回傳

紀錄回應保留 JSON number，不會加千分位、幣別符號或單位：

{
  "data": {
    "數量": 2,
    "單價": 1290.5
  }
}

幣別、百分比與小數位數都是顯示層責任；不要把格式化後的 "NT$1,290.50" 寫回 float cell。

注意事項

• integer 會把小數與數字字串轉成整數；如果產品不能接受自動捨入，前端應先拒絕非整數輸入。
• float 拒絕 NaN、正負 Infinity 等非有限數，避免產生無法儲存的 JSON。
• true / false 對兩種數值型別都不合法。
• default_value 也必須符合欄位型別；它會用於既有紀錄的新增欄位遷移。

試試看

到 API Playground 建立兩個數值欄，再用 records.create 比較原生數字與數字字串的回傳結果。