rc-field-form
    TypeScript icon, indicating that this package has built-in type declarations

    1.21.2 • Public • Published

    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

    • Support react.js and even react-native
    • Validate fields with async-validator

    Install

    rc-field-form

    Usage

    import Form, { Field } from 'rc-field-form';
    
    <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

    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 -

    Field

    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

    List

    Prop Description Type Default
    name List field name path NamePath[] -
    children Render 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} />;
      }
    }
    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

    FormProvider

    Prop Description Type Default
    validateMessages Config global validateMessages 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

    NamePath

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

    FieldData

    Prop Type
    touched boolean
    validating boolean
    errors string[]
    name string | number | (string | number)[]
    value any

    Rule

    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.

    ListOperations

    Prop Type
    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.

    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

    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.

    Install

    npm i rc-field-form

    DownloadsWeekly Downloads

    380,290

    Version

    1.21.2

    License

    MIT

    Unpacked Size

    229 kB

    Total Files

    60

    Last publish

    Collaborators

    • afc163
    • zinkey
    • zombiej
    • chenshuai2144