1.43.0 • Published 22 days ago

rc-field-form v1.43.0

Weekly downloads
376,743
License
MIT
Repository
github
Last release
22 days ago

rc-field-form

React Performance First Form Component.

NPM version dumi build status Codecov npm download

Development

npm install
npm start
open http://localhost:8000

Feature

Install

rc-field-form

Usage

import Form, { Field } from 'rc-field-form';

const Input = ({ value = "", ...props }) => <input value={value} {...props} />;

const Demo = () => {
  return (
    <Form
      onFinish={(values) => {
        console.log("Finish:", values);
      }}
    >
      <Field name="username">
        <Input placeholder="Username" />
      </Field>
      <Field name="password">
        <Input placeholder="Password" />
      </Field>

      <button>Submit</button>
    </Form>
  );
};

export default Demo;

🔥 API

We use typescript to create the Type definition. You can view directly in IDE. But you can still check the type definition here.

Form

PropDescriptionTypeDefault
componentCustomize Form render componentstring | Component | falseform
fieldsControl Form fields status. Only use when in ReduxFieldData[]-
formSet form instance created by useFormFormInstanceForm.useForm()
initialValuesInitial value of FormObject-
nameConfig name with FormProviderstring-
preservePreserve value when field removedbooleanfalse
validateMessagesSet validate message templateValidateMessages-
onFieldsChangeTrigger when any value of Field changed(changedFields, allFields) => void-
onFinishTrigger when form submit and success(values) => void-
onFinishFailedTrigger when form submit and failed({ values, errorFields, outOfDate }) => void-
onValuesChangeTrigger when any value of Field changed(changedValues, values) => void-

Field

PropDescriptionTypeDefault
dependenciesWill re-render if dependencies changedNamePath[]-
getValueFromEventSpecify how to get value from event(..args: any[]) => any-
getValuePropsCustomize additional props with value. This prop will disable valuePropName(value) => any-
initialValueField initial valueany-
nameField name pathNamePath-
normalizeNormalize value before update(value, prevValue, prevValues) => any-
preservePreserve value when field removedbooleanfalse
rulesValidate rulesRule[]-
shouldUpdateCheck if Field should updateboolean | (prevValues, nextValues) => boolean-
triggerCollect value update by event triggerstringonChange
validateTriggerConfig trigger point with rule validatestring | string[]onChange
valuePropNameConfig value mapping prop with elementstringvalue

List

PropDescriptionTypeDefault
nameList field name pathNamePath[]-
childrenRender props for listing fields(fields: { name: NamePath }[], operations: ListOperations) => ReactNode-

useForm

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.

const Demo = () => {
  const [form] = Form.useForm();
  return <Form form={form} />;
};

For class component user, you can use ref to get form instance:

class Demo extends React.Component {
  setRef = form => {
    // Form instance here
  };

  render() {
    return <Form ref={this.setRef} />;
  }
}
PropDescriptionType
getFieldValueGet field value by name path(name: NamePath) => any
getFieldsValueGet list of field values by name path list(nameList?: (NamePath[]) => any) | true
getFieldErrorGet field errors by name path(name: NamePath) => string[]
getFieldsErrorGet list of field errors by name path list(nameList?: NamePath[]) => FieldError[]
isFieldsTouchedCheck if list of fields are touched(nameList?: NamePath[], allTouched?: boolean) => boolean
isFieldTouchedCheck if a field is touched(name: NamePath) => boolean
isFieldValidatingCheck if a field is validating(name: NamePath) => boolean
resetFieldsReset fields status(fields?: NamePath[]) => void
setFieldsSet fields status(fields: FieldData[]) => void
setFieldsValueSet fields value(values) => void
submitTrigger form submit() => void
validateFieldsTrigger fields to validate(nameList?: NamePath[], options?: ValidateOptions) => Promise

FormProvider

PropDescriptionTypeDefault
validateMessagesConfig global validateMessages templateValidateMessages-
onFormChangeTrigger by named form fields change(name, { changedFields, forms }) => void-
onFormFinishTrigger by named form fields finish(name, { values, forms }) => void-

📋 Interface

NamePath

Type
string | number | (string | number)[]

FieldData

PropType
touchedboolean
validatingboolean
errorsstring[]
namestring | number | (string | number)[]
valueany

Rule

PropType
enumany[]
lennumber
maxnumber
messagestring
minnumber
patternRegExp
requiredboolean
transform(value) => any
typestring
validator(rule, value, callback: (error?: string) => void, form) => Promise | void
whitespaceboolean
validateTriggerstring | 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.

ListOperations

PropType
add(initValue: any) => void
remove(index: number) => void

ValidateMessages

Validate Messages provides a list of error template. You can ref here for fully default templates.

PropDescription
enumRule enum prop
lenRule len prop
maxRule max prop
minRule min prop
nameField name
patternRule pattern prop
typeRule type prop

Different with rc-form

rc-field-form is try to keep sync with rc-form in api level, but there still have something to change:

1. Field will not keep snyc with initialValues when un-touched

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.

2. Remove Field will not clean up related value

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. Nest name use array instead of string

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' }.

4. Remove validateFieldsAndScroll

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:

<Form>
  <Field name="username">
    <input ref={this.inputRef} />
  </Field>
</Form>

5. getFieldsError always return array

rc-form returns null when no error happen. This makes user have to do some additional code like:

(form.getFieldsError('fieldName') || []).forEach(() => {
  // Do something...
});

Now getFieldsError will return [] if no errors.

6. Remove callback with validateFields

Since ES8 is support async/await, that's no reason not to use it. Now you can easily handle your validate logic:

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 Error(message), not need to get error by e => e.message. FieldForm will handle this.

7. preserve is default to false

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.

8. setFields not trigger onFieldsChange and setFieldsValue not trigger onValuesChange

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.

1.43.0

22 days ago

1.42.1

24 days ago

1.42.0

30 days ago

1.40.0

5 months ago

1.41.0

4 months ago

1.39.0

6 months ago

1.40.0-0

5 months ago

1.39.0-0

5 months ago

1.38.2

6 months ago

1.38.1

6 months ago

1.37.0

8 months ago

1.32.0

10 months ago

1.32.1

10 months ago

1.34.2

9 months ago

1.34.0

9 months ago

1.34.1

9 months ago

1.38.0

7 months ago

1.33.0

9 months ago

1.35.0

8 months ago

1.36.0

8 months ago

1.36.1

8 months ago

1.32.2

10 months ago

1.36.2

8 months ago

1.30.0

11 months ago

1.31.0

11 months ago

1.29.0

1 year ago

1.29.1

1 year ago

1.29.2

12 months ago

1.27.4

1 year ago

1.28.0

1 year ago

1.27.3

1 year ago

1.27.2

2 years ago

1.26.7

2 years ago

1.26.5

2 years ago

1.26.6

2 years ago

1.27.0

2 years ago

1.27.1

2 years ago

1.26.3

2 years ago

1.26.4

2 years ago

1.25.0

2 years ago

1.25.1

2 years ago

1.25.2

2 years ago

1.26.0

2 years ago

1.26.1

2 years ago

1.26.2

2 years ago

1.23.1

2 years ago

1.24.0

2 years ago

1.22.1

2 years ago

1.23.0

2 years ago

1.22.0

2 years ago

1.22.0-2

2 years ago

1.22.0-1

2 years ago

1.22.0-0

2 years ago

1.21.2

3 years ago

1.21.1

3 years ago

1.21.0

3 years ago

1.21.0-0

3 years ago

1.21.0-2

3 years ago

1.21.0-1

3 years ago

1.20.1

3 years ago

1.20.0

3 years ago

1.19.0

3 years ago

1.18.1

3 years ago

1.18.0

3 years ago

1.17.4

3 years ago

1.17.3

3 years ago

1.17.2

3 years ago

1.17.1

3 years ago

1.17.0

3 years ago

1.16.0

3 years ago

1.15.1

3 years ago

1.15.0

3 years ago

1.14.0

3 years ago

1.13.2

3 years ago

1.13.1

3 years ago

1.13.0

3 years ago

1.12.1

3 years ago

1.12.0

4 years ago

1.11.1

4 years ago

1.11.0

4 years ago

1.10.1

4 years ago

1.8.1

4 years ago

1.10.0

4 years ago

1.9.4

4 years ago

1.9.3

4 years ago

1.9.2

4 years ago

1.9.1

4 years ago

1.9.0

4 years ago

1.8.0

4 years ago

1.7.1

4 years ago

1.5.1

4 years ago

1.7.0

4 years ago

1.6.0

4 years ago

1.5.0

4 years ago

1.4.4

4 years ago

1.4.3

4 years ago

1.4.2

4 years ago

1.4.1

4 years ago

1.4.0

4 years ago

1.3.0

4 years ago

1.2.4

4 years ago

1.2.3

4 years ago

1.2.2

4 years ago

1.2.1

4 years ago

1.2.0

4 years ago

1.1.3

4 years ago

1.1.2

4 years ago

1.1.1

4 years ago

1.1.0

4 years ago

1.0.1

4 years ago

0.0.1

4 years ago

1.0.0

4 years ago

0.0.0-rc.6

4 years ago

0.0.0-rc.5

4 years ago

0.0.0-rc.4

4 years ago

0.0.0-rc.3

4 years ago

0.0.0-rc.2

4 years ago

0.0.0-rc.1

4 years ago

0.0.0-rc.0

4 years ago

0.0.0-alpha.30

4 years ago

0.0.0-alpha.29

4 years ago

0.0.0-alpha.28

4 years ago

0.0.0-alpha.27

4 years ago

0.0.0-alpha.26

4 years ago

0.0.0-alpha.25

4 years ago

0.0.0-alpha.24

4 years ago

0.0.0-alpha.23

4 years ago

0.0.0-alpha.22

5 years ago

0.0.0-alpha.21

5 years ago

0.0.0-alpha.20

5 years ago

0.0.0-alpha.19

5 years ago

0.0.0-alpha.18

5 years ago

0.0.0-alpha.17

5 years ago

0.0.0-alpha.16

5 years ago

0.0.0-alpha.15

5 years ago

0.0.0-alpha.14

5 years ago

0.0.0-alpha.13

5 years ago

0.0.0-alpha.12

5 years ago

0.0.0-alpha.11

5 years ago

0.0.0-alpha.10

5 years ago

0.0.0-alpha.9

5 years ago

0.0.0-alpha.8

5 years ago

0.0.0-alpha.7

5 years ago

0.0.0-alpha.6

5 years ago

0.0.0-alpha.5

5 years ago

0.0.0-alpha.4

5 years ago

0.0.0-alpha.3

5 years ago

0.0.0-alpha.2

5 years ago

0.0.0-alpha.1

5 years ago

0.0.0

5 years ago