@rc-component/form

If you are moving from the legacy rc-form to rc-field-form, note the following behavioral changes:

1. Field Synchronization: Fields that have not been interacted with will no longer automatically sync with initialValues. To update a field value manually, use setFieldsValue.
2. Field Removal: Removing a Field component no longer automatically cleans up its corresponding value in the form store.
3. Nested Names: Use arrays for nested paths (e.g., ['user', 'name']) instead of dot-notation strings (e.g., 'user.name'). Dot-notation strings are now treated as literal keys.
4. Validation API: validateFields now returns a Promise and no longer accepts a callback. Use async/await for cleaner logic. If a validator returns Error(message), the message is automatically extracted.
5. Error Retrieval: getFieldsError now always returns an array [] instead of null when no errors exist.
6. Value Preservation: The preserve prop defaults to false. Set it to true if you want to keep field values even when the field is unmounted.
7. Event Triggers: setFields does not trigger onFieldsChange, and setFieldsValue does not trigger onValuesChange to prevent infinite loops and decouple logic.

// New async/await pattern for validateFields
async function validate() {
  try {
    const values = await form.validateFields();
    console.log(values);
  } catch (errorList) {
    // errorList is an array of { name, errors }
    errorList.forEach(({ name, errors }) => {
      // Handle errors
    });
  }
}

If you are migrating from rc-form to rc-field-form, note the following breaking changes:

1. Initial Values: Fields no longer automatically sync with initialValues when un-touched. To change a field value, use setFieldsValue.
2. Field Removal: Removing a field no longer automatically cleans up its related value in the form store. To disable this behavior (keep the value), use preserve={false} (which is the new default).
3. Nested Names: Use arrays for nested paths (e.g., ['user', 'name']) instead of dot-notation strings (e.g., 'user.name'). Dot-notation strings are now treated as literal keys.
4. Validation API: validateFieldsAndScroll has been removed. Use your own logic with refs to handle scrolling.
5. Error Returns: getFieldsError now always returns an array [] instead of null when there are no errors.
6. Async Validation: validateFields is now Promise-based. Use async/await and try/catch blocks.
7. Event Triggers: setFields does not trigger onFieldsChange, and setFieldsValue does not trigger onValuesChange to prevent infinite loops and reduce coupling.

The List component (typically accessed via Form.List) is used to manage dynamic arrays of fields within a form. It provides a render prop pattern that gives you access to the current list of fields, operations to modify the list (add, remove, move), and metadata about the list field.

Key Requirements:

• The children prop must be a function. Passing any other type will trigger a warning and return null.
• The underlying form value for the provided name must be an array. If the value is not an array, a warning will be issued in non-production environments.

Render Prop Arguments:

• fields: ListField[]: An array of objects representing each item in the list. Each object contains:
  • name: The index of the field in the list.
  • key: A unique identifier for the field (used for stable rendering).
  • isListField: A boolean indicating it is part of a list.
• operations: ListOperations: Functions to mutate the list:
  • add(defaultValue?: StoreValue, index?: number): Adds a new item. If index is provided and valid, it inserts at that position; otherwise, it appends to the end.
  • remove(index: number | number[]): Removes items at the specified index or indices.
  • move(from: number, to: number): Moves an item from one position to another.
• meta: Meta: Metadata about the field (e.g., validation status).

<Form.List name="users">
  {(fields, operations, meta) => (
    <>
      {fields.map(({ key, name, isListField }) => (
        <Form.Item
          key={key}
          name={[name, 'firstName']}
          rules={[{ required: true, message: 'Missing firstName' }]}
        >
          <Input />
        </Form.Item>
      ))}
      <Button onClick={() => operations.add()}>Add User</Button>
    </>
  )}
</Form.List>