15 KiB
category | type | cols | title |
---|---|---|---|
Components | Data Entry | 1 | Form |
High performance Form component with data scope management. Including data collection, verification, and styles.
When to use
- When you need to create a instance or collect information.
- When you need to validate fields in certain rules.
API
Form
Property | Description | Type | Default |
---|---|---|---|
component | Set the Form rendering element. Do not create a DOM node for false |
ComponentType | false | form |
colon | Configure the default value of colon for Form.Item. Indicates whether the colon after the label is displayed (only effective when prop layout is horizontal) |
boolean | true |
fields | Control of form fields through state management (such as redux). Not recommended for non-strong demand. View example | FieldData[] | - |
form | Form control instance created by Form.useForm() . Automatically created when not provided |
FormInstance | - |
hideRequiredMark | Hide required mark for all form items | boolean | false |
initialValues | Set value by Form initialization or reset | object | - |
labelAlign | text align of label of all items | left | right |
right |
labelCol | label layout, like <Col> component. Set span offset value like {span: 3, offset: 12} or sm: {span: 3, offset: 12} |
object | - |
layout | Form layout | horizontal | vertical | inline |
horizontal |
name | Form name. Will be the prefix of Field id |
string | - |
size | Set field component size (antd components only) | small | middle | large |
- |
validateMessages | Validation prompt template, description see below | ValidateMessages | - |
wrapperCol | The layout for input controls, same as labelCol |
object | - |
onFinish | Trigger after submitting the form and verifying data successfully | Function(values) | - |
onFinishFailed | Trigger after submitting the form and verifying data failed | Function({ values, errorFields, outOfDate }) | - |
onFieldsChange | Trigger when field updated | Function(changedFields, allFields) | - |
onValuesChange | Trigger when value updated | Function(changedValues, allValues) | - |
validateMessages
Form provides default verification error messages. You can modify template by configuring validateMessages
property. A common usage is to configure localization:
const validateMessages = {
required: "'${name}' is required!",
// ...
};
<Form validateMessages={validateMessages} />;
Besides,ConfigProvider also provides a global configuration scheme that allows for uniform configuration error notification templates:
const validateMessages = {
required: "'${name}' is Required!",
// ...
};
<ConfigProvider form={{ validateMessages }}>
<Form />
</ConfigProvider>;
Form.Item
Form field component for data bidirectional binding, validation, layout, and so on.
Property | Description | Type | Default |
---|---|---|---|
colon | Used with label , whether to display : after label text. |
boolean | true |
dependencies | Set the dependency field. See below | NamePath[] | - |
extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time | string|ReactNode | - |
getValueFromEvent | Specify how to get value from event or other onChange arguments | (..args: any[]) => any | - |
hasFeedback | Used with validateStatus , this option specifies the validation status icon. Recommended to be used only with Input |
boolean | false |
help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string|ReactNode | - |
htmlFor | Set sub label htmlFor |
string | - |
noStyle | No style for true , used as a pure field control |
boolean | false |
label | Label text | string|ReactNode | - |
labelAlign | text align of label | left | right |
right |
labelCol | The layout of label. You can set span offset to something like {span: 3, offset: 12} or sm: {span: 3, offset: 12} same as with <Col> . You can set labelCol on Form. If both exists, use Item first |
object | - |
name | Field name, support array | NamePath | - |
normalize | Normalize value to form component | (value, prevValue, prevValues) => any | - |
required | Whether provided or not, it will be generated by the validation rule | boolean | false |
rules | Rules for field validation. Click here to see an example | Rule[] | - |
shouldUpdate | Custom field update logic. See bellow | boolean | (prevValue, curValue) => boolean | false |
trigger | When to collect the value of children node | string | onChange |
validateFirst | Whether stop validate on first rule of error for this field | boolean | false |
validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string | - |
validateTrigger | When to validate the value of children node | string | string[] | onChange |
valuePropName | Props of children node, for example, the prop of Switch is 'checked' | string | 'value' |
wrapperCol | The layout for input controls, same as labelCol . You can set wrapperCol on Form. If both exists, use Item first |
object | - |
dependencies
Used when there are dependencies between fields. If a field has the dependencies
prop, this field will automatically trigger updates and validations when upstream updated. A common scenario is user register form with "password" and "confirm password" fields. The "Confirm Password" validation depends on the "Password" field. After setting dependencies
, the "Password" field update will re-trigger the validation of "Check Password". You can refer examples.
shouldUpdate
Form updates only the modified field-related components for performance optimization purposes by incremental update. In most case, you only need to write code or do validation with the dependencies
property. And in some specific case, such as a new field option appears with a filed value changed, or just want to keep some area updating by form update. You can modify the update logic of Form.Item via the shouldUpdate
.
When shouldUpdate
is true
, any Form update will cause the Form.Item to be re-rendered. This is very helpful for custom rendering some areas:
<Form.Item shouldUpdate>
{() => {
return <pre>{JSON.stringify(form.getFieldsValue(), null, 2)}</pre>;
}}
</Form.Item>
You can ref example to see detail.
When shouldUpdate
is a function, it will be called by form values update. Providing original values and current value to compare. This is very helpful for rendering additional fields based on values:
<Form.Item shouldUpdate={(prevValues, curValues) => prevValues.additional !== curValues.additional}>
{() => {
return (
<Form.Item name="other">
<Input />
</Form.Item>
);
}}
</Form.Item>
You can ref example to see detail.
Form.List
Provides array management for fields.
Property | Description | Type | Default |
---|---|---|---|
name | Field name, support array | NamePath | - |
children | Render function | (fields: Field[], operation: { add, remove, move }) => React.ReactNode | - |
<Form.List>
{fields => (
<div>
{fields.map(field => (
<Form.Item {...field}>
<Input />
</Form.Item>
))}
</div>
)}
</Form.List>
Form.Provider
Provide linkage between forms. If a sub form with name
prop update, it will auto trigger Provider related events. See example.
Property | Description | Type | Default |
---|---|---|---|
onFormChange | Triggered when a sub form field updates | Function(formName: string, info: { changedFields, forms }) | - |
onFormFinish | Triggered when a sub form submits | Function(formName: string, info: { values, forms }) | - |
<Form.Provider
onFormFinish={name => {
if (name === 'form1') {
// Do something...
}
}}
>
<Form name="form1">...</Form>
<Form name="form2">...</Form>
</Form.Provider>
FormInstance
Name | Description | Type |
---|---|---|
getFieldValue | Get the value by the field name | (name: NamePath) => any |
getFieldsValue | Get values by a set of field names. Return according to the corresponding structure | (nameList?: NamePath[]) => any |
getFieldError | Get the error messages by the field name | (name: NamePath) => string[] |
getFieldsError | Get the error messages by the fields name. Return as an array | (nameList?: NamePath[]) => FieldError[] |
isFieldTouched | Check if a field has been operated | (name: NamePath) => boolean |
isFieldsTouched | Check if fields have been operated. Check if all fields is touched when allTouched is true |
(nameList?: NamePath[], allTouched?: boolean) => boolean |
isFieldValidating | Check fields if is in validating | (name: NamePath) => boolean |
resetFields | Reset fields to initialValues |
(fields?: NamePath[]) => void |
scrollToField | Scroll to field position | (name: NamePath, options: [ScrollOptions]) => void |
setFields | Set fields status | (fields: FieldData[]) => void |
setFieldsValue | Set fields value | (values) => void |
submit | Submit the form. It's same as click submit button |
() => void |
validateFields | Validate fields | (nameList?: NamePath[]) => Promise |
validateFields return sample
validateFields()
.then(values => {
/*
values:
{
username: 'username',
password: 'password',
}
*/
})
.catch(errorInfo => {
/*
errorInfo:
{
values: {
username: 'username',
password: 'password',
},
errorFields: [
{ password: ['username'], errors: ['Please input your Password!'] },
],
outOfDate: false,
}
*/
});
Interface
NamePath
string | number | (string | number)[]
FieldData
Name | Description | Type |
---|---|---|
touched | Whether is operated | boolean |
validating | Whether is in validating | boolean |
errors | Error messages | string[] |
name | Field name path | NamePath[] |
value | Field value | any |
Rule
Rule support config object, an also support function to get config object:
type Rule = RuleConfig | ((form: FormInstance) => RuleConfig);
Name | Description | Type |
---|---|---|
enum | Match enum value | any[] |
len | Length of string, number, array | number |
max | Max length of string, number, array | number |
message | Error message. Will auto generate by template if not provided | string |
min | Min length of string, number, array | number |
pattern | Regex pattern | RegExp |
required | Required field | boolean |
transform | Transform value to the rule before validation | (value) => any |
type | Normally string |number |boolean |url | email . More type to ref here |
string |
validator | Customize validation rule. Accept Promise as return. example参考 | (rule, value) => Promise |
whitespace | Failed if only has whitespace | boolean |
validateTrigger | Set validate trigger event. Must be the sub set of validateTrigger in Form.Item |
string | string[] |
Migrate to v4
If you are the user of v3, you can ref migrate doc。
FAQ
Custom validator not working
It may be caused by your validator
if it has some errors that prevents callback
to be called. You can use async
instead or use try...catch
to catch the error:
validator: async (rule, value) => {
throw new Error('Something wrong!');
}
// or
validator(rule, value, callback) => {
try {
throw new Error('Something wrong!');
} catch (err) {
callback(err);
}
}
Get form instance from function component
You can combine forwardRef
with useImperativeHandle
to get form instance:
import React, { forwardRef, useImperativeHandle } from 'react';
import Form, { FormComponentProps } from 'antd/lib/form/Form';
const FCForm = forwardRef<FormComponentProps, FCFormProps>(({ form, onSubmit }, ref) => {
useImperativeHandle(ref, () => ({
form,
}));
`...the rest of your form`;
});
const EnhancedFCForm = Form.create<FCFormProps>()(FCForm);
You can use your form component like this:
const TestForm = () => {
const formRef = createRef<Ref>();
return (
<EnhancedFCForm
onSubmit={() => console.log(formRef.current!.form.getFieldValue('name'))}
wrappedComponentRef={formRef}
/>
);
};
Online demo:
Why get form warning when used in Modal?
Warning: Instance created by
useForm
is not connect to any Form element. Forget to passform
prop?
Before Modal open, children element do not exist in the view. You can set forceRender
on Modal to pre-render its children. Click here to view example.