Form

A form with data collection, verification and submission functions, including checkboxes, radio buttons, input boxes, drop-down selection boxes and other elements.

Install

npm install @arco-design/web-react@2.66.18

Import @arco-design/web-react/dist/css/arco.css at the entry and set the locale with ConfigProvider. React 19 projects must also import @arco-design/web-react/es/_util/react-19-adapter first, or imperative APIs such as Message and Modal cannot render.

Examples

• Basic: Usage of uncontrolled mode.
• Layout: Form supports three layout: horizontal (default), vertical, inline.
• Controlled: You can set the field property in Form.Item to control the field. <ol> <li> In the controlled mode, Form.Item will automatically set value (or other attribute set by triggerPropName) and onChange (or other attribute set by trigger) properties for Form.Item's children. All data will be processed by Form. </li> <li> You cannot set defaultValue for Form.Item's children. The default value can be set by the initialValues of Form or the initialValue of Form.Item. </li> </ol>
• Methods: In functional components, you can use Form.useForm to get a form instance, You can call all form methods through this instance, such as setting form value, reset form, etc. If you are using class component, you can get it by ref.
• Set Error status: You can externally control the error status of form entries by using the error parameter of the setFields method.
• Object value: By setting field to a.b.c, you will get {a:{b:{c: xx}}}.
• Nest Form.Item: Form.Item can be nested.
• shouldUpdate: Dynamically change the field of the form by shouldUpdate.
• List: Manage the form structure of array type through Form.List. When setting validation rules, Form.List will render an additional DOM node to display the validation information. If you don’t need it, you can pass in noStyle=false and customize the validation information through Form.useFormState display.
• Nest List: Provides array management for fields.
• Custom Form: Form.Item will pass the onChange and value properties to its direct child nodes. Only after calling this onChange, can its own value be collected by Form.Item.
• Normalize: First, when using a controlled form, the values ​​of all form items will be collected by Form when they change. If you need to process the value of the form item and store it in the Form, you can use the normalize attribute. In contrast, when the form item is rendered, the value is taken from the Form and passed to the corresponding form item as the value attribute. If the value taken from the Form needs to be converted and then passed to For form items, you can use the formatter attribute.Note: form.setFieldValue does not trigger normalize.
• Register: Fill in the necessary information to register a new user
• Disabled: Set disabled to the Form component to globally disable all form controls.
• Size: The size attribute allows you to set forms of different sizes
• Validate status: Form.Item supports customizing the form verification status and verification copy through the hasFeedbackvalidateStatus and help attributes.
• validate: The form field can be validated through the form.validate method. You can specify to verify specific fields through parameters.
• async validate: Customize the validator method in rules and return a Promise to achieve asynchronous validation of the form. p.s: If using lodash.debounce does not work, it is recommended to use debounce.promise, which returns a promise.
• validate messages: The validation message prompt template can be set through the validateMessages property (2.32.0 support). example You can also set validateMessages for the global Form component in the componentConfig parameter of the ConfigProvider component.
• Scroll To Field
• validate level: You can use 'validateLevel' to set form validation failures to 'warning' and not block form submission.
• Manage multiple form data: The 'form.provider' component allows you to manage data from multiple forms. 2.30.0 support. To get the corresponding Form instance, you need to set the ID property for the Form component.
• useWatch: You can use Form.useWatch to monitor the changes of field values inside the form. (2.33.0 support)
• Get Form Context: In functional components, you can use Form.useFormContext to get a form context. Facilitate the encapsulation of form controls. (version 2.33.0, isSubmitting in 2.44.0). isSubmitting is only valid when the onSubmit attribute of the form Form is triggered to be submitted by a button with type=submit. If onSubmit contains asynchronous logic inside, return a Promise.
• useFormState: You can use Form.useFormState to monitor the changes of status inside the form. (2.44.0 support)

Examples come from the official Arco Design repository (MIT) at the commit published as npm 2.66.18. Some use online images or upload endpoints; network requests are disabled in previews.

API

Form

Form.Item

Form.List

Form.Provider(2.30.0)

FormInstance

export type FormInstance<
  FormData = any,
  FieldValue = FormData[keyof FormData],
  FieldKey extends KeyType = keyof FormData
> = Pick<
  Store<FormData, FieldValue, FieldKey>,
  | "getFieldsValue"
  | "getFieldValue"
  | "getFieldError"
  | "getFieldsError"
  | "getTouchedFields"
  | "getFields"
  | "setFieldValue"
  | "setFieldsValue"
  | "setFields"
  | "resetFields"
  | "clearFields"
  | "submit"
  | "validate"
  | "getFieldsState"
> & {
  scrollToField: (field: FieldKey, options?: ScrollIntoViewOptions) => void;
  // arco 内部使用，业务万不可调用
  getInnerMethods: (
    inner?: boolean
  ) => InnerMethodsReturnType<FormData, FieldValue, FieldKey>;
};

InnerMethodsReturnType

export type InnerMethodsReturnType<
  FormData = any,
  FieldValue = FormData[keyof FormData],
  FieldKey extends KeyType = keyof FormData
> = Pick<
  Store<FormData, FieldValue, FieldKey>,
  | "registerField"
  | "registerStateWatcher"
  | "registerFormWatcher"
  | "registerWatcher"
  | "innerSetInitialValues"
  | "innerSetInitialValue"
  | "innerSetCallbacks"
  | "innerSetFieldValue"
  | "innerGetStore"
  | "innerGetStoreStatus"
  | "innerCollectFormState"
  | "innerGetFieldValue"
>;

ComponentType

export type ComponentType =
  | keyof JSX.IntrinsicElements
  | React.ComponentType<any>;

IndexedObject

export type IndexedObject = {
  [key: string]: any;
};

FieldError

export type FieldError<FieldValue = any> = {
  value?: FieldValue;
  message?: ReactNode;
  type?: string;
  requiredError?: boolean;
};

FormItemChildrenFn

export type FormItemChildrenFn<
  FormData = any,
  FieldValue = FormData[keyof FormData],
  FieldKey extends KeyType = keyof FormData
> = (
  formData: any,
  form: FormInstance<FormData, FieldValue, FieldKey>
) => React.ReactNode;

Rules

Low-level use b-validate.

export interface RulesProps {
  // when to validate
  validateTrigger?: string | string[];
  // When the verification fails, the error message will be displayed in the form of `error` or `warning`. Will not block form submission when set to `warning`
  validateLevel?: 'error' | 'warning';
  required?: boolean;
  type?: string;
  length?: number;
  // Array
  maxLength?: number;
  minLength?: number;
  includes?: boolean;
  deepEqual?: any;
  empty?: boolean;
  // Number
  min?: number;
  max?: number;
  equal?: number;
  positive?: boolean;
  negative?: boolean;
  // Object
  hasKeys?: string[];
  // String
  match?: RegExp;
  uppercase?: boolean;
  lowercase?: boolean;
  // Boolean
  true?: boolean;
  false?: boolean;
  // custom
  validator?: (value, callback: (error?: ReactNode) => void) => void;
  message?: string;
}

this.form

You can get this.form through ref, and this.form contains common operations such as form validation and setting.

<Form ref={(ref) => (this.form = ref)}>
  <FormItem>...</FormItem>
</Form>

validate Usage

this.form.validate((errors, values) => {
  console.log(errors, values);
});
// Or
this.form.validate().then((values) => {
  console.log(values);
}).catch((error) => {
  console.log(error.name);
  console.log(error.message);
  console.log(error.errors);
});
// Or (Note to use in the async method)
try {
  const values = await this.form.validate();
} catch (error) {
  console.log(error.name);
  console.log(error.message);
  console.log(error.errors);
}

setFields Usage

this.form.setFields({
  name: {
    value: 'pjy',
    error: {
      message: 'Yes, I know!'
    },
    warning: 'warning...'
  }
});

Common Problems

How to set the default value of Form?(Why doesn't setting defaultValue directly to Input control take effect)

Do not set the defaultValue and value attributes on the control wrapped by the Form.Item with the field attribute set. You can set the default value on the Form.Item through the initialValue or the initialValues property of the Form.

Why can't call the method of Form nested in Modal?

For example, the following usage:

// ...
const [form] = Form.useForm();
useEffect(() => {
  form.setFieldsValue({})
}, [])
return <div>
  <Modal visible={visible}>
    <Form form={form}>
      {/** ... */}
    </Form>
  </Modal>
</div>

This is because when the form method is called, Modal has not yet been mounted and Form has not been created yet. You can set the mountOnEnter=false of Modal.

Form.Item did not collect the value of the wrapped form control / did not trigger verification?

• Form.Item sets the field attribute
• Form.Item is directly wrapped outside the form control, and the form control is the only child node of FormItem
• The default triggerPropName of Form.Item is value, which means that the value attribute will be injected into the child control. If the controlled property of the form control is checked (such as switch, checkbox, radio), fileList (such as Upload) or others, then you need to set the triggerPropName={ of the form control in Form.Item according to the actual situation. control attribute}
• Similar to triggerPropName, by default FormItem listens to the onChange callback of child components to collect control values and trigger validation logic. If the callback of the subcomponent is not onChange, remember to set trigger={form control event callback} of FormItem
• The control wrapped by Form.Item is in a mounted state (that is, it has not been destroyed)

A form element has a value filled in but has been destroyed. How do I get this value?

The getFields method will obtain the values ​​of all fields registered in Form, including form items that are created and destroyed.

Verification throttling or asynchronous verification?

Customize the validator method in rules and return a Promise to implement asynchronous verification of the form. If throttling with lodash.debounce does not take effect, it is recommended to use debounce.promise, which returns a promise. [Official website example](https://arco.design/react/components/form#%E8%A1%A8%E5%8D%95%E5%BC%82%E6%AD%A5%E6%A0%A1% E9%AA%8C)

The Checkbox/Switch/Upload settings in Form do not take effect.

Set triggerPropName=checked on the Form.Item corresponding to Checkbox/Switch Set triggerPropName=fileList on the Form.Item corresponding to Upload Other components are similar

Does the Input in the Form appear with a light blue background color (Chrome browser)?

The blue background color is the automatic filling style of the Chrome browser. Just turn off the automatic filling of the form.

How to turn off autofill?

The native property of Form component, just set autoComplete=off.

Will clicking the label trigger a change in the behavior of the corresponding form control? For example: switch, checkbox selected, input focused

https://www.runoob.com/tags/tag-label.html Label definition and usage instructions The label tag defines the label (marker) for the input element. The label element does not present any special effects to the user. However, it improves usability for mouse users. This control is triggered if you click on the text inside the label element. That is to say, when the user selects the label, the browser will automatically turn the focus to the form control related to the label. label The for attribute of the label should be the same as the id attribute of the related element. If you really don't want this effect, just set an id attribute to the form control, and don't match it with the for attribute of the label. Such as <Switch id="aaaaa" />

Advanced customization of error message display

https://codepen.io/yinkaihui/pen/GRwRQao?editors=1011

DatePicker.WeekPicker value cannot be parsed

Same as DatePicker.QuarterPicker Add getValueFromEvent={(v, dv) => dv} to Form.Item.