React Form Component
npm install @rc-component/formReact Performance First Form Component.
[![NPM version][npm-image]][npm-url]  [![build status][github-actions-image]][github-actions-url] [![Codecov][codecov-image]][codecov-url] [![npm download][download-image]][download-url]
[npm-image]: http://img.shields.io/npm/v/rc-field-form.svg?style=flat-square
[npm-url]: http://npmjs.org/package/rc-field-form
[github-actions-image]: https://github.com/react-component/field-form/workflows/CI/badge.svg
[github-actions-url]: https://github.com/react-component/field-form/actions
[codecov-image]: https://img.shields.io/codecov/c/github/react-component/field-form/master.svg?style=flat-square
[codecov-url]: https://codecov.io/gh/react-component/field-form/branch/master
[download-image]: https://img.shields.io/npm/dm/rc-field-form.svg?style=flat-square
[download-url]: https://npmjs.org/package/rc-field-form
``bash`
npm install
npm start
open http://localhost:8000
- Support react.js and even react-native
- Validate fields with @rc-component/async-validator
`js | pure
import Form, { Field } from 'rc-field-form';
const Input = ({ value = '', ...props }) => ;
const Demo = () => {
return (
console.log('Finish:', values);
}}
>
);
};
export default Demo;
`
We use typescript to create the Type definition. You can view directly in IDE. But you can still check the type definition here.
| Prop | Description | Type | Default |
| ---------------- | -------------------------------------------------- | -------------------------------------------- | ---------------- |
| component | Customize Form render component | string \| Component \| false | form |
| fields | Control Form fields status. Only use when in Redux | FieldData[] | - |
| form | Set form instance created by useForm | FormInstance | Form.useForm() |
| initialValues | Initial value of Form | Object | - |
| name | Config name with FormProvider | string | - |
| preserve | Preserve value when field removed | boolean | false |
| validateMessages | Set validate message template | ValidateMessages | - |
| onFieldsChange | Trigger when any value of Field changed | (changedFields, allFields) => void | - |
| onFinish | Trigger when form submit and success | (values) => void | - |
| onFinishFailed | Trigger when form submit and failed | ({ values, errorFields, outOfDate }) => void | - |
| onValuesChange | Trigger when any value of Field changed | (changedValues, values) => void | - |
| Prop | Description | Type | Default |
| ----------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- | -------- |
| dependencies | Will re-render if dependencies changed | NamePath[] | - |
| getValueFromEvent | Specify how to get value from event | (..args: any[]) => any | - |
| getValueProps | Customize additional props with value. This prop will disable valuePropName | (value) => any | - |
| initialValue | Field initial value | any | - |
| name | Field name path | NamePath | - |
| normalize | Normalize value before update | (value, prevValue, prevValues) => any | - |
| preserve | Preserve value when field removed | boolean | false |
| rules | Validate rules | Rule[] | - |
| shouldUpdate | Check if Field should update | boolean \| (prevValues, nextValues) => boolean | - |
| trigger | Collect value update by event trigger | string | onChange |
| validateTrigger | Config trigger point with rule validate | string \| string[] | onChange |
| valuePropName | Config value mapping prop with element | string | value |
| Prop | Description | Type | Default |
| -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------- | ------- |
| name | List field name path | NamePath[] | - |
| children | Render props for listing fields | (fields: { name: NamePath }[], operations: ListOperations) => ReactNode | - |
Form component default create an form instance by Form.useForm. But you can create it and pass to Form also. This allow you to call some function on the form instance.
`jsx | pure`
const Demo = () => {
const [form] = Form.useForm();
return ;
};
For class component user, you can use ref to get form instance:
`jsx | pure
class Demo extends React.Component {
setRef = form => {
// Form instance here
};
render() {
return
| Prop | Description | Type |
| ----------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
| getFieldValue | Get field value by name path | (name: NamePath) => any |
| getFieldsValue | Get list of field values by name path list | (nameList?: (NamePath[]) => any) \| true |
| getFieldError | Get field errors by name path | (name: NamePath) => string[] |
| getFieldsError | Get list of field errors by name path list | (nameList?: NamePath[]) => FieldError[] |
| isFieldsTouched | Check if list of fields are touched | (nameList?: NamePath[], allTouched?: boolean) => boolean |
| isFieldTouched | Check if a field is touched | (name: NamePath) => boolean |
| isFieldValidating | Check if a field is validating | (name: NamePath) => boolean |
| resetFields | Reset fields status | (fields?: NamePath[]) => void |
| setFields | Set fields status | (fields: FieldData[]) => void |
| setFieldsValue | Set fields value | (values) => void |
| submit | Trigger form submit | () => void |
| validateFields | Trigger fields to validate | (nameList?: NamePath[], options?: ValidateOptions) => Promise |
$3
| Prop | Description | Type | Default |
| ---------------- | ----------------------------------------- | ---------------------------------------- | ------- |
| validateMessages | Config global
template | ValidateMessages | - |
| onFormChange | Trigger by named form fields change | (name, { changedFields, forms }) => void | - |
| onFormFinish | Trigger by named form fields finish | (name, { values, forms }) => void | - |📋 Interface
$3
| Type |
| ---------------------------------------- |
| string \| number \| (string \| number)[] |
$3
| Prop | Type |
| ---------- | ---------------------------------------- |
| touched | boolean |
| validating | boolean |
| errors | string[] |
| name | string \| number \| (string \| number)[] |
| value | any |
$3
| Prop | Type |
| --------------- | ----------------------------------------------------------------------------------------------- |
| enum | any[] |
| len | number |
| max | number |
| message | string |
| min | number |
| pattern | RegExp |
| required | boolean |
| transform | (value) => any |
| type | string |
| validator | (rule, value, callback: (error?: string) => void, form) => Promise \| void |
| whitespace | boolean |
| validateTrigger | string \| string[] |
#### validator
To keep sync with
rc-form legacy usage of validator, we still provides callback to trigger validate finished. But in rc-field-form, we strongly recommend to return a Promise instead.$3
| Prop | Type |
| ------ | ------------------------ |
| add | (initValue: any) => void |
| remove | (index: number) => void |
$3
Validate Messages provides a list of error template. You can ref here for fully default templates.
| Prop | Description |
| ------- | ------------------- |
| enum | Rule
enum prop |
| len | Rule len prop |
| max | Rule max prop |
| min | Rule min prop |
| name | Field name |
| pattern | Rule pattern prop |
| type | Rule type prop |Different with
rc-form is try to keep sync with rc-form in api level, but there still have something to change:$3
In
rc-form, field value will get from initialValues if user not operate on it.
It's a bug but user use as a feature which makes fixing will be a breaking change and we have to keep it.
In Field Form, this bug will not exist anymore. If you want to change a field value, use setFieldsValue instead.$3
We do lots of logic to clean up the value when Field removed before. But with user feedback, remove exist value increase the additional work to keep value back with conditional field.
$3
In
rc-form, we support like user.name to be a name and convert value to { user: { name: 'Bamboo' } }. This makes '.' always be the route of variable, this makes developer have to do additional work if name is real contains a point like app.config.start to be app_config_start and parse back to point when submit.Field Form will only trade
['user', 'name'] to be { user: { name: 'Bamboo' } }, and user.name to be { ['user.name']: 'Bamboo' }.$3
Since
findDomNode is marked as warning in StrictMode. It seems over control of Form component.
We decide to remove validateFieldsAndScroll method and you should handle it with you own logic:`jsx | pure
`$3
returns null when no error happen. This makes user have to do some additional code like:`js | pure
(form.getFieldsError('fieldName') || []).forEach(() => {
// Do something...
});
`Now
will return [] if no errors.$3
Since ES8 is support
async/await, that's no reason not to use it. Now you can easily handle your validate logic:`js | pure
async function() {
try {
const values = await form.validateFields();
console.log(values);
} catch (errorList) {
errorList.forEach(({ name, errors }) => {
// Do something...
});
}
}
`Notice: Now if your validator return an
, not need to get error by e => e.message. FieldForm will handle this.$3
In
rc-form you should use preserve to keep a value cause Form will auto remove a value from Field removed. Field Form will always keep the value in the Form whatever Field removed. But you can still use preserve=false to disable value keeping since 1.5.0.$3
In
rc-form, we hope to help user auto trigger change event by setting to make redux dispatch easier, but it's not good design since it makes code logic couping.Additionally, user control update trigger
onFieldsChange & onValuesChange` event has potential dead loop risk.