跳至主要内容
💬 回報這一頁

表單頁

一次把一件事填完。 表單頁服務「建立一筆新的」； 修改既有資料是明細頁逐欄編輯的事——這條分工先記住， 後面的規則都是從它長出來的。

何時用​

情境用什麼
建立一筆新紀錄表單頁
修改既有紀錄的欄位明細頁的逐欄編輯
兩三個欄位的輕量輸入（改名、填備註）Dialog 內嵌小表單
一長串有順序依賴的輸入表單頁的多步驟變體（見下）
✅ 這樣做

一頁一件事：標題直接說出那件事（「建立項目」），填完送出就離開。

🚫 不要這樣

不要做「一頁改十件事」的萬用表單。什麼都能改的畫面， 使用者每次都要重新掃一遍才找得到要改的那格。

組成​

表單頁：分組卡＋行內錯誤＋動作區在 Storybook 開啟
區內容元件與規範
頁首區標題＋一句話說明範圍（哪些之後可補）—
內容區依情境分組的卡片，一欄式排列Card、輸入控制項
動作區取消（左、有離開防呆）＋送出（右、唯一主要動作）Button、Dialog

欄位怎麼排​

✅ 這樣做

依使用者回答問題的順序分組——「這是什麼」一組、「數量與管道」一組， 一組一張卡。組織原則與長表單拆法見情境化申請單。

🚫 不要這樣

不要照資料表欄位順序從上排到下。資料模型的順序是給程式看的， 40 個欄位平鋪的表單是給人受苦的。

✅ 這樣做

一欄式優先：視線直直往下走。欄位窄且相關（如數量＋金額）才併排。

🚫 不要這樣

不要為了「看起來緊湊」排三欄。Z 字形的視線路徑讓漏填率變高， 而且 Tab 順序與視覺順序容易對不上。

必填標示全站一種寫法（標在 Label 上），可選欄位不標——反過來標「（選填）」 的前提是必填佔多數。兩種都標等於都沒標。

錯誤的位置​

跨頁一致性守則第 4 條在表單頁的展開：

  • 行內錯誤緊貼欄位：用 FormField——它把 aria-invalid＋aria-describedby＋ 錯誤小字的固定寫法接好（見錯誤態）， 不再需要手寫這三條。
  • 頂部只做彙總：用 Callout（warning）列「有幾個欄位待補」， 不重複每一條錯誤內容。
  • 時機：blur 或送出後才標紅。使用者還沒碰過的欄位就標紅， 是在懲罰還沒發生的錯（輸入控制項的既有規則）。

動作區​

✅ 這樣做

主要動作在右、取消在左；送出中把按鈕停用＋換「處理中…」文案。 取消要有離開防呆：表單有內容時按取消，先用 Dialog 確認「要放棄這份表單？」。

🚫 不要這樣

不要做「重設」按鈕。誤觸的代價（整張白填）遠大於它的用處， 而且它長得跟「取消」太像。

送出成功的回饋去向全站固定一種：跳轉到新紀錄的明細頁、或就地 Callout live（success）——選一種，寫進團隊的驗收清單（Toast 尚未收錄， 見缺件表）。

多步驟變體​

多步驟：Stepper＋分步內容＋末步總覽在 Storybook 開啟

拆步的門檻：欄位有順序依賴（先選單位才知道有哪些選項）、或單頁超過三組。 純粹欄位多但彼此獨立，用分組卡就好——翻頁本身也是成本。

✅ 這樣做

步驟 ≤5、每步標題是名詞短語、可回上一步且已填內容不丟； 末步永遠是總覽確認，送出前看得到全部要送的東西。

🚫 不要這樣

不要在中間步驟就寫入資料。「填到第三步就已經建立了草稿」會留下 一堆半成品紀錄，而使用者以為自己按了取消就什麼都沒發生。

Stepper 的可點回跳、目前步驟標示見 Stepper； 第一次使用的引導疊加見引導式導覽。

無障礙​

  • 每個輸入都有 Label（htmlFor 綁定）；錯誤用 aria-invalid＋aria-describedby。
  • 頂部彙總 Callout 加 live，錯誤數量變化時螢幕閱讀器唸得到。
  • Tab 順序＝視覺順序；動作區永遠是最後兩個停留點。
  • 多步驟的目前步驟要以文字呈現（「第 2 步，共 3 步」），不能只靠顏色。

取用​

npx shadcn@latest add \
  https://kielchang.github.io/dooping-design-book/r/input.json \
  https://kielchang.github.io/dooping-design-book/r/label.json \
  https://kielchang.github.io/dooping-design-book/r/number-input.json \
  https://kielchang.github.io/dooping-design-book/r/select.json \
  https://kielchang.github.io/dooping-design-book/r/checkbox.json \
  https://kielchang.github.io/dooping-design-book/r/seg-group.json \
  https://kielchang.github.io/dooping-design-book/r/chips.json \
  https://kielchang.github.io/dooping-design-book/r/card.json \
  https://kielchang.github.io/dooping-design-book/r/callout.json \
  https://kielchang.github.io/dooping-design-book/r/dialog.json \
  https://kielchang.github.io/dooping-design-book/r/stepper.json

缺件與替代​

Form 包裝與欄位錯誤元件、Textarea、RadioGroup、DatePicker、Toast 尚未收錄—— 替代寫法見頁面總覽的缺件表。在那之前，錯誤標示照本頁 「錯誤的位置」一節的固定寫法手排，不要各畫面自創。