<Formik> 是一個可以幫助您構建表單的組件。它使用由 React Motion 和 React Router 等函式庫推廣的渲染屬性模式。

範例

1 import React from 'react';
2 import { Formik } from 'formik';
3 
4 const BasicExample = () => (
5   <div>
6     <h1>My Form</h1>
7     <Formik
8       initialValues={{ name: 'jared' }}
9       onSubmit={(values, actions) => {
10         setTimeout(() => {
11           alert(JSON.stringify(values, null, 2));
12           actions.setSubmitting(false);
13         }, 1000);
14       }}
15     >
16       {props => (
17         <form onSubmit={props.handleSubmit}>
18           <input
19             type="text"
20             onChange={props.handleChange}
21             onBlur={props.handleBlur}
22             value={props.values.name}
23             name="name"
24           />
25           {props.errors.name && <div id="feedback">{props.errors.name}</div>}
26           <button type="submit">Submit</button>
27         </form>
28       )}
29     </Formik>
30   </div>
31 );

屬性

參考

屬性

Formik 渲染方法和屬性

有兩種方法可以使用 <Formik /> 渲染內容

• <Formik component>
• <Formik children>
• <Formik render> 在 2.x 版中已棄用

每個渲染方法都會傳遞相同的屬性

dirty: boolean

如果值與初始值深度不相等，則返回 true，否則返回 false。 dirty 是一個唯讀的計算屬性，不應直接修改。

errors: { [field: string]: string }

表單驗證錯誤。應與您在 initialValues 中定義的表單 values 的形狀匹配。如果您正在使用 validationSchema（您應該使用），鍵和形狀將與您的架構完全匹配。在內部，Formik 會代表您轉換原始的 Yup 驗證錯誤。如果您正在使用 validate，則該函式將決定 errors 物件的形狀。

handleBlur: (e: any) => void

onBlur 事件處理程式。當您需要追蹤輸入是否已被 touched 時很有用。這應該傳遞給 <input onBlur={handleBlur} ... />

handleChange: (e: React.ChangeEvent<any>) => void

一般輸入變更事件處理程式。這將更新 values[key]，其中 key 是發出事件的輸入的 name 屬性。如果 name 屬性不存在，handleChange 將尋找輸入的 id 屬性。注意：此處的「輸入」是指所有 HTML 輸入。

handleReset: () => void

重置處理程式。將表單重置為其初始狀態。這應該傳遞給 <button onClick={handleReset}>...</button>

handleSubmit: (e: React.FormEvent<HTMLFormElement>) => void

提交處理程式。這應該傳遞給 <form onSubmit={props.handleSubmit}>...</form>。要瞭解更多關於提交過程的資訊，請參閱 表單提交。

isSubmitting: boolean

表單的提交狀態。如果提交正在進行中，則返回 true，否則返回 false。重要提示：Formik 會在提交嘗試後立即將其設定為 true。要瞭解更多關於提交過程的資訊，請參閱 表單提交。

isValid: boolean

如果沒有 errors（即 errors 物件為空），則返回 true，否則返回 false。

注意：isInitialValid 在 2.x 版中已棄用。但是，為了向後相容，如果指定了 isInitialValid 屬性，如果沒有 errors，或者如果表單處於「原始」狀態（即非 dirty），則 isValid 將返回 isInitialValid 的結果。

isValidating: boolean

如果 Formik 正在提交期間或透過呼叫[validateForm]直接執行驗證，則返回 true，否則返回 false。要瞭解更多關於提交過程中 isValidating 的資訊，請參閱 表單提交。

resetForm: (nextState?: Partial<FormikState<Values>>) => void

強制重置表單。唯一的（可選）參數 nextState 是一個物件，其中任何這些 FormikState 欄位都是可選的

1 interface FormikState<Values> {
2   /** Form values */
3   values: Values;
4   /** map of field names to specific error for that field */
5   errors: FormikErrors<Values>;
6   /** map of field names to **whether** the field has been touched */
7   touched: FormikTouched<Values>;
8   /** whether the form is currently submitting */
9   isSubmitting: boolean;
10   /** whether the form is currently validating (prior to submission) */
11   isValidating: boolean;
12   /** Top level status state, in case you need it */
13   status?: any;
14   /** Number of times user tried to submit the form */
15   submitCount: number;
16 }

如果指定了 nextState，Formik 將設定 nextState.values 作為新的「初始狀態」，並使用 nextState 的相關值來更新表單的 initialValues 以及 initialTouched、initialStatus、initialErrors。這對於在進行更改後更改表單的初始狀態（即「基礎」）很有用。

1 // typescript usage
2 function MyForm(props: MyFormProps) {
3   // using TSX Generics here to set <Values> to <Blog>
4   return (
5     <Formik<Blog>
6       initialValues={props.initVals}
7       onSubmit={(values, actions) => {
8         props.onSubmit(values).then(() => {
9           actions.setSubmitting(false);
10           actions.resetForm({
11             values: {
12               // the type of `values` inferred to be Blog
13               title: '',
14               image: '',
15               body: '',
16             },
17             // you can also set the other form states here
18           });
19         });
20       }}
21     >
22       // etc
23     </Formik>
24   );
25 }

如果省略 nextState，則 Formik 將狀態重置為原始初始狀態。後者適用於在 componentDidUpdate 或 useEffect 中呼叫 resetForm。

 actions.resetForm();

setErrors: (fields: { [field: string]: string }) => void

強制設定 errors。

setFieldError: (field: string, errorMsg: string) => void

強制設定欄位的錯誤訊息。 field 應與您要更新的 errors 的鍵匹配。適用於建立自定義輸入錯誤處理程式。

setFieldTouched: (field: string, isTouched?: boolean, shouldValidate?: boolean) => Promise<void | FormikErrors>

強制設定欄位的觸碰狀態。 field 應該與您想要更新的 touched 的鍵值相符。這對於建立自定義的輸入欄位失焦處理程序非常有用。呼叫此方法會在 validateOnBlur 設定為 true 時觸發驗證（預設值為 true）。如果未指定，isTouched 預設為 true。您也可以透過傳遞第三個參數為 false 來明確地防止/跳過驗證。

如果 validateOnBlur 設定為 true 且存在錯誤，則錯誤將在返回的 Promise 中被解析。

submitForm: () => Promise

觸發表單提交。如果表單無效，promise 將會被拒絕。

submitCount: number

使用者嘗試提交表單的次數。在呼叫 handleSubmit 時增加，在呼叫 handleReset 後重置。 submitCount 是一個唯讀的計算屬性，不應直接修改。

setFieldValue: (field: string, value: React.SetStateAction<any>, shouldValidate?: boolean) => Promise<void | FormikErrors>

強制設定欄位的值。 field 應該與您想要更新的 values 的鍵值相符。這對於建立自定義的輸入欄位變更處理程序非常有用。呼叫此方法會在 validateOnChange 設定為 true 時觸發驗證（預設值為 true）。您也可以透過傳遞第三個參數為 false 來明確地防止/跳過驗證。

如果 validateOnChange 設定為 true 且存在錯誤，則錯誤將在返回的 Promise 中被解析。

setStatus: (status?: any) => void

強制設定最上層的 status 為任何您想要的值。這對於控制與表單相關的任意最上層狀態非常有用。例如，您可以使用它在 handleSubmit 中將 API 回應傳遞回您的組件。

setSubmitting: (isSubmitting: boolean) => void

強制設定 isSubmitting。您應該在 onSubmit 處理程序中使用 setSubmitting(false) 呼叫它來完成循環。要瞭解更多關於提交過程的資訊，請參閱 表單提交。

setTouched: (fields: { [field: string]: boolean }, shouldValidate?: boolean) => Promise<void | FormikErrors>

強制設定 touched。呼叫此方法會在 validateOnBlur 設定為 true 時觸發驗證（預設值為 true）。您也可以透過傳遞第二個參數為 false 來明確地防止/跳過驗證。

如果 validateOnBlur 設定為 true 且存在錯誤，則錯誤將在返回的 Promise 中被解析。

setValues: (fields: React.SetStateAction<{ [field: string]: any }>, shouldValidate?: boolean) => Promise<void | FormikErrors<Values>>

強制設定 values。呼叫此方法會在 validateOnChange 設定為 true 時觸發驗證（預設值為 true）。您也可以透過傳遞第二個參數為 false 來明確地防止/跳過驗證。

如果 validateOnChange 設定為 true 且存在錯誤，則錯誤將在返回的 Promise 中被解析。

status?: any

一個最上層的狀態物件，您可以使用它來表示無法用其他方法表達/儲存的表單狀態。這對於擷取 API 回應並將其傳遞到您的內部組件非常有用。

status 只能透過呼叫 setStatus 來修改。

touched: { [field: string]: boolean }

已觸碰的欄位。每個鍵值對應一個已被觸碰/訪問的欄位。

values: { [field: string]: any }

您的表單的值。將具有 mapPropsToValues 的結果形狀（如果已指定），或是傳遞給您包裝組件的所有非函數屬性。

validateForm: (values?: any) => Promise<FormikErrors<Values>>

根據指定的內容強制呼叫您的 validate 或 validateSchema。您可以選擇性地傳遞值以進行驗證，並據此修改 Formik 狀態，否則將使用表單的當前 values。

validateField: (field: string) => void

如果為指定的欄位指定了欄位的 validate 函數，則強制呼叫它，或者使用 Yup 的 schema.validateAt 和提供的最上層 validationSchema 屬性來執行結構描述驗證。Formik 將使用當前的欄位值。

component?: React.ComponentType<FormikProps<Values>>

1 <Formik component={ContactForm} />;
2 
3 const ContactForm = ({
4   handleSubmit,
5   handleChange,
6   handleBlur,
7   values,
8   errors,
9 }) => (
10   <form onSubmit={handleSubmit}>
11     <input
12       type="text"
13       onChange={handleChange}
14       onBlur={handleBlur}
15       value={values.name}
16       name="name"
17     />
18     {errors.name && <div>{errors.name}</div>}
19     <button type="submit">Submit</button>
20   </form>
21 );

**警告：** <Formik component> 優先於 <Formik render>，因此不要在同一個 <Formik> 中同時使用兩者。

render: (props: FormikProps<Values>) => ReactNode

在 2.x 版中已棄用

1 <Formik render={props => <ContactForm {...props} />} />
2 
3 <Formik
4   render={({ handleSubmit, handleChange, handleBlur, values, errors }) => (
5     <form onSubmit={handleSubmit}>
6       <input
7         type="text"
8         onChange={handleChange}
9         onBlur={handleBlur}
10         value={values.name}
11         name="name"
12       />
13       {errors.name &&
14         <div>
15           {errors.name}
16         </div>}
17       <button type="submit">Submit</button>
18     </form>
19   )}
20 />

children?: React.ReactNode | (props: FormikProps<Values>) => ReactNode

1 <Formik children={props => <ContactForm {...props} />} />
2 
3 // or...
4 
5 <Formik>
6   {({ handleSubmit, handleChange, handleBlur, values, errors }) => (
7     <form onSubmit={handleSubmit}>
8       <input
9         type="text"
10         onChange={handleChange}
11         onBlur={handleBlur}
12         value={values.name}
13         name="name"
14       />
15       {errors.name &&
16         <div>
17           {errors.name}
18         </div>}
19       <button type="submit">Submit</button>
20     </form>
21   )}
22 </Formik>

enableReinitialize?: boolean

預設值為 false。控制如果 initialValues 改變（使用深度相等性），Formik 是否應該重置表單。

isInitialValid?: boolean

在 2.x 版中已棄用，請改用 initialErrors

控制掛載前 isValid 屬性的初始值。您也可以傳遞一個函數。這在您想要在初始掛載時啟用/禁用提交和重置按鈕的情況下非常有用。

initialErrors?: FormikErrors<Values>

表單初始欄位錯誤，Formik 會將這些值以 errors 的形式提供給渲染方法組件。

注意：高階組件 withFormik 無法使用 initialErrors，請改用 mapPropsToErrors。

initialStatus?: any

表單初始 status 的任意值。如果表單被重置，則會恢復此值。

注意：高階組件 withFormik 無法使用 initialStatus，請改用 mapPropsToStatus。

initialTouched?: FormikTouched<Values>

表單初始已訪問的欄位，Formik 會將這些值以 touched 的形式提供給渲染方法組件。

注意：高階組件 withFormik 無法使用 initialTouched，請改用 mapPropsToTouched。

initialValues: Values

表單的初始欄位值，Formik 會將這些值以 values 的形式提供給渲染方法組件。

即使您的表單預設為空，您也必須使用初始值初始化所有欄位，否則 React 會拋出錯誤，指出您已將輸入從非受控更改為受控。

注意：高階組件無法使用 initialValues，請改用 mapPropsToValues。

onReset?: (values: Values, formikBag: FormikBag) => void

您的選用表單重置處理程序。它會傳入您的表單 values 和「FormikBag」。

onSubmit: (values: Values, formikBag: FormikBag) => void | Promise<any>

您的表單提交處理程序。它會傳入您的表單 values 和「FormikBag」，其中包含一個物件，該物件包含注入的屬性和方法的子集（即所有名稱以 set<Thing> 開頭的方法 + resetForm）以及傳遞給包裝組件的任何屬性。

注意：errors、touched、status 和所有事件處理程序*不*包含在 FormikBag 中。

重要事項：如果 onSubmit 是非同步的，則 Formik 會在解析後自動將 isSubmitting 設定為 false。這表示您*不需要*手動呼叫 formikBag.setSubmitting(false)。但是，如果您的 onSubmit 函式是同步的，則您需要自行呼叫 setSubmitting(false)。

validate?: (values: Values) => FormikErrors<Values> | Promise<any>

注意：我建議使用 validationSchema 和 Yup 進行驗證。但是，validate 是一種不依賴任何函式庫、直接驗證表單的方法。

使用函式驗證表單的 values。此函式可以是：

1. 同步並返回一個 errors 物件。

1 // Synchronous validation
2 const validate = values => {
3   const errors = {};
4 
5   if (!values.email) {
6     errors.email = 'Required';
7   } else if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(values.email)) {
8     errors.email = 'Invalid email address';
9   }
10 
11   //...
12 
13   return errors;
14 };

• 非同步並返回一個解析為包含 errors 的物件的 Promise。

1 // Async Validation
2 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
3 
4 const validate = values => {
5   return sleep(2000).then(() => {
6     const errors = {};
7     if (['admin', 'null', 'god'].includes(values.username)) {
8       errors.username = 'Nice try';
9     }
10     // ...
11     return errors;
12   });
13 };

validateOnBlur?: boolean

預設值為 true。使用此選項可在 blur 事件上執行驗證。更具體地說，當呼叫 handleBlur、setFieldTouched 或 setTouched 時。

validateOnChange?: boolean

預設值為 true。使用此選項可告知 Formik 在 change 事件和與 change 相關的方法上執行驗證。更具體地說，當呼叫 handleChange、setFieldValue 或 setValues 時。

validateOnMount?: boolean

預設值為 false。使用此選項可告知 Formik 在掛載 <Formik /> 組件和/或 initialValues 變更時執行驗證。

validationSchema?: Schema | (() => Schema)

Yup 綱要 或返回 Yup 綱要的函式。這用於驗證。錯誤會透過鍵值對應到內部組件的 errors。其鍵值應與 values 的鍵值相符。