ant-design/components/form/index.en-US.md
2020-02-02 21:40:16 +08:00

15 KiB
Raw Blame History

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:

Edit wrappedComponentRef-in-function-component

Why get form warning when used in Modal?

Warning: Instance created by useForm is not connect to any Form element. Forget to pass form 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.