Form 表單這系列的文章在 Day0408 時(註14)有分享了比較常見的表單元件，為了將ANTD表單完整功能做個統整，從今天開始大約會花2~3篇文章篇幅將使用方法再做細說。和其他元件一樣，ANTD 的表單整體而言功能可說是一應俱全，像是初始值、驗證、提交動作、客製化樣式與動態新增欄位等，也有針對 React Hook 和 class component 做不同的案例解說，今天就讓我們開始認識它吧！

一、ANTD Table 最基本的使用方式：引用與呼叫它

  基本上 Form 是主體標籤，裡面的每一個輸入框(或稱填寫欄位)都須使用 <Form.Item> tag包起來，這樣可以方便讓 Form 的表單監聽事件中抓取該表單每個欄位的變化，另外要記得搭配一個 htmlType="submit" 的 button，實際送出的事件則是綁在 Form 表單的 onFinish function 裡。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import { Form, Button } from 'antd';

const App = () => (
  <div>
    <Form
      name="basic"
      labelCol={{span: 8}}
      wrapperCol={{span: 16}}
      initialValues={{}}
      onFinish={handleFinish}
      onValuesChange={handleValuesChange}
    >
      <Form.Item
        label="姓名"
        name="name"
        rules={[
          {
            required: true,
            message: '請輸入姓名',
          },
        ]}
      >
        <Input />
      </Form.Item>
      <Form.Item>
        <Button type="primary" htmlType="submit">
          送出
        </Button>
      </Form.Item>
    </Form>
  <div/>
);

export default App;

二、Form 可添加的參數

  以下列出我個人比較常用的，參數就如同下方程式碼說明，也可以點此連結去看更多官方 api 文件。比較方便的是labelCol與wrapperCol兩個參數，它們是拿來設定label和input的比例，如果你的表單項目是inline-style，希望label佔1/3、input佔2/3，那可以使用labelCol={{span: 8}} wrapperCol={{span: 16}}來達成，因為在表單裡也遵循ANTD的Grid rules，總計為24等份的規則。

屬性名稱 可以使用的值 說明
layout horizontal 或 vertical 或 inline 設定整個表單的每個<Form.Item> 的label和input的排列方式。預設是水平佈滿(horizontal)。
labelCol object 設定整個表單的每個<Form.Item> 的label佔據比例
labelWrap true 或 false 設定整個表單的每個<Form.Item> 的label，是否在寬度有限的狀況下自動換行。預設是false
wrapperCol object 設定整個表單的每個<Form.Item> 的input佔據比例
initialValues object 設定表單中的預設值(或初始值)
colon true 或 false 設定是否顯示每個<Form.Item> 的label和input中間的冒號，預設true。
name 字串 其實等同於表格的id
onValuesChange (changedValues, allValues) => {} 當表單值一有變動時會觸發的function，第一個參數是指有變動的，第二個參數則是指全部的。可視情形取用。
onFinish (values) => {} 當按下表單送出鈕時，會觸發的function，而參數values搭配label名稱，則可以得到對應的輸入值。
scrollToFirstError true 或 false 當表單送出時驗證有誤，是否要將畫面滾動至第一個有誤的輸入框。預設值為false

三、Form.Item 可添加的參數

  以下列出我個人比較常用的，參數就如同下方程式碼說明，也可以點此連結去看更多官方 api 文件。

  • 有三個值labelCol, wrapperCol, colon是可以在Form直接統一定義全部，也可個別在每個輸入框去設定的值。通常為了樣式統一，建議直接在Form設定即可，也可避免冗code狀況。
屬性名稱 可以使用的值 說明
label ReactNode 該欄位顯示在畫面上的名稱
required true 或 false 設定該欄位是否必填
rules 陣列 定義必填欄位的驗證方式，例如rules={[{type: 'email', message: '請輸入正確的email格式',}, {required: true, message: '請填寫您的email',},]}

註1：Day04：Ant Design 表單裡會看到的勾選框(checkbox 和 radio)
註2：Day05：Ant Design 表單裡會看到的輸入框
註3：Day06：Ant Design 表單裡會看到的下拉選單
註4：Day08：Ant Design 表單裡的日期選擇框