Understand Form Component Architecture & Data Binding - Mobile Platform as a Service

A Form component is a high performance control with data domain management functionalities. It includes data entry, verification, and corresponding styles and is used for creating an entity or collecting information.

Important

To use a Form component in a mini-program project, you need to enable Component2.
When you use a Form component with the a:for command, we recommend that you specify key. Otherwise, an error may occur.
The value of form in the Form tag must be unique and the same as that in the internal FormItem tag. The value of name in the internal FormItem tag must be unique.
When you use this component together with the form component from the component library, the value of mode of the form component must be form.

Property

Form

Property	Type	Required	Default value	Description
form	string	Yes	-	The uid of the form.
initialValues	Record<sring, any>	No	-	The initial value of the form.
position	'horizontal' \| 'vertical'	No	'horizontal'	The layout of the form.
requiredMarkStyle	'asterisk' \| 'text-required' \| 'text-optional'	No	'asterisk'	The styling used to mark a required or an optional field. Asterisk: Use a red asterisk to mark a required field. Text-required: Use the word "Required" to mark a required field. Text-optional: Use the word "Optional" to mark an optional field.
className	string	No	-	The class name.

FromGroup

Property	Type	Required	Default value	Description
header	string	No	-	The name of the FormGroup component.
radius	boolean	No	false	Whether the FormGroup component has a round corner.
className	string	No	-	The class name.

FormItem

Property	Type	Required	Default value	Description
form	string	Yes	default	The uid of the form.
name	string	Yes	default	The uid of the field.
label	string	No	-	The field name.
position	'horizontal' \| 'vertical'	No	'horizontal'	The layout of the FormItem component, whose priority is higher than that of position in Form.
arrow	boolean	No	false	The arrow on the right of the FormItem component.
required	boolean	No	false	Whether a label is required. This property must be set if you want to display a label.
help	string	No	-	The description of a label.
className	string	No	""	The class name.

Event

Form

Event name	Description	Type
onValuesChange	Callback fired when a field is updated.	`( changedFields: Record<string, any>, allFields: Record<string, any> ) => void`
onFinish	Callback fired when the form is submitted.	`( changedFields: Record<string, any>, allFields: Record<string, any> ) => void`

Slot

FormGroup

Name	Description
header	The header.

FormItem

Name	Description
extra	Extra content about a form item.

Instantiation methods

Form

Event name	Description	Type
getComponentIns	Obtains a component example. The value is the same as the default return value of ref.	() => Component
setFieldsValue	Sets the value of a form field.	( formName: `string`, fieldsVals: `Record<string, any>` ) => void

Description

Form

Class name	Description
amd-form	The style of the entire form.
amd-form-footer	The style of the footer.

FormGroup

Class name	Description
amd-form-group-header	The style of the header.
amd-form-group-radius	The style of the rounded corner.

FormItem

Class name	Description
amd-form-item-label	The style of a label.
amd-form-item-field	The style of a field.
amd-form-item-extra	The style of the extra content.
amd-form-item-arrow	The style of an arrow.

Code sample

Basic usage

The following shows an example of the code in the index.axml file:

<view class="demo">
    <demo-block title="Horizontal layout form" padding="0">
        <form 
            form="{{form}}" 
            initialValues="{{initialValues}}"
            onFinish="handleSubmit"
            onValuesChange="handleValuesChange">
            <form-item
                label="Name"
                name="account"
                required
                help="Explanation of the name"
                form="{{form}}">
                <input-item mode="form" placeholder="Please enter the name"/>
            </form-item>
            <form-item
                label="Address"
                name="address"
                form="{{form}}">
                <input-item mode="form" password placeholder="Please enter the address"/>
            </form-item>
            <form-item
                label="Quantity"
                name="quantity"
                form="{{form}}">
                <stepper step="{{1}}"  min="{{0}}" mode="form"/>
            </form-item>
            <form-item
                label="Home delivery"
                name="needDelivery"
                form="{{form}}">
                <switch mode="form"/>
            </form-item>
            <button 
                slot="footer"
                type="primary" 
                mode="form"
                form="{{form}}"
                htmlType="submit">Submit
            </button>
        </form>
    </demo-block>
    <demo-block title="Vertical layout form" padding="0">
        <form 
            form="{{formV}}" 
            initialValues="{{initialValues}}"
            onFinish="handleSubmit"
            onValuesChange="handleValuesChange">
            <form-item
                label="Name"
                position="vertical" 
                name="account"
                required
                form="{{formV}}">
                <input-item mode="form" placeholder="Please enter the name"/>
            </form-item>
            <form-item
                label="Address"
                position="vertical" 
                name="address"
                form="{{formV}}">
                <input-item mode="form" password placeholder="Please enter the address"/>
            </form-item>
            <form-item
                label="Quantity"
                position="vertical" 
                name="quantity"
                form="{{formV}}">
                <stepper step="{{1}}"  min="{{0}}" mode="form"/>
            </form-item>
            <form-item
                label="Home delivery"
                position="vertical" 
                name="needDelivery"
                form="{{formV}}">
                <switch mode="form"/>
            </form-item>
            <button 
                slot="footer"
                type="primary" 
                mode="form"
                form="{{formV}}"
                htmlType="submit">Submit
            </button>
        </form>
    </demo-block>
</view>

The following shows an example of the code in the index.js file:

Page({
  data: {
    form: 'form',
    formV: 'formV',
    initialValues: {
      quantity: 1,
      needDelivery: false,
    },
  },
  handleValuesChange(value, values) {
    console.log(value, values);
  },
  handleSubmit(e) {
    my.alert({ title: 'Submit', content: JSON.stringify(e) });
  },
});

The following shows an example of the code in the index.json file:

{
  "defaultTitle": "Form",
  "usingComponents": {
    "form": "antd-mini/es/Form/index",
    "form-item": "antd-mini/es/Form/FormItem/index",
    "input-item": "antd-mini/es/InputItem/index",
    "button": "antd-mini/es/Button/index",
    "switch": "antd-mini/es/Switch/index",
    "stepper": "antd-mini/es/Stepper/index",
    "demo-block": "../../components/DemoBlock/index"
  }
}

Combined form component

The following shows an example of the code in the index.axml file:

<view class="demo">
  <form 
    form="{{form}}" 
    onFinish="handleSubmit"
    initialValues="{{initialValues}}"
    onValuesChange="handleValuesChange">
    <form-item
      required
      label="input"
      name="input"
      form="{{form}}">
      <input-item mode="form" placeholder="Please enter"/>
    </form-item>
    <form-item
      required
      label="password"
      name="password"
      rules="{{[{ pattern: /\d{6}/, message: 'The password must be 6 digits' },]}}"
      form="{{form}}">
      <input-item mode="form" placeholder="Please enter" password/>
    </form-item>
    <form-item
      label="stepper"
      name="stepper"
      form="{{form}}">
      <stepper 
        mode="form"
        min="{{0}}"
        max="{{100}}"
        step="{{1}}"/>
    </form-item>
    <form-item
      label="switch"
      name="switch"
      form="{{form}}">
      <switch 
        mode="form"
      />
    </form-item>
    <form-item 
      label="picker" 
      labelWidth="110px"
      name="picker" 
      form="{{form}}">
      <picker 
        pickerholder="Please select" 
        data="{{pickerList}}"
        mode="form"
        onFormat="formatValue" 
        onDismiss="cancelPicker" 
      >
        <view slot="title">
          <text style="color: red;">Picker</text> selector</view>
      </picker>
    </form-item>
    <form-item 
      label="selector" 
      name="selector" 
      position="vertical" 
      form="{{form}}">
      <selector 
        items="{{selectorItems}}" 
        multiple
        mode="form" />
    </form-item>
    <form-item 
      label="radio" 
      required
      name="radio" 
      position="vertical" 
      form="{{form}}">
      <radio-group mode="form" position="horizontal">
        <radio-item value="a1">choice one</radio-item>
        <radio-item value="a2">choice two</radio-item>
        <radio-item value="a3">choice three</radio-item>
      </radio-group>
    </form-item>
    <form-item 
      label="checkboxGroup" 
      required
      name="checkboxGroup" 
      position="vertical" 
      form="{{form}}">
      <checkbox-group mode="form" position="horizontal">
        <checkbox-item value="a1">checkbox 1</checkbox-item>
        <checkbox-item value="a2">checkbox 2</checkbox-item>
        <checkbox-item value="a3">checkbox 3</checkbox-item>
      </checkbox-group>
    </form-item>
    <button 
      slot="footer"
      type="primary" 
      mode="form"
      form="{{form}}"
      htmlType="submit">Submit
    </button>
  </form>
</view>

The following shows an example of the code in the index.js file:

Page({
  data: {
    form: 'form',
    initialValues: {
      stepper: 20,
      switch: false,
      picker: ['2012', '12', 12],
    },
    selectorItems: [
      {
        text: 'option 1',
        value: '1',
      },
      {
        text: 'option 2',
        value: '2',
      },
      {
        text: 'option 3',
        value: '3',
      },
      {
        text: 'option 4',
        value: '4',
      },
      {
        text: 'option 5',
        value: '5',
      },
    ],
    pickerList: [
      [
        '2011',
        '2012',
        '2013',
        '2014',
        '2015',
        '2016',
        '2017',
        '2018',
        '2019',
        '2020',
        '2021',
        '2022',
      ],
      ['01', '02', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12'],
      [
        1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
        21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31,
      ],
    ],
  },
  formatValue(v) {
    return v && v.join('/') || '';
  },
  handleValuesChange(value, values) {
    console.log(value, values);
  },
  handleSubmit(e) {
    my.alert({ title: 'Submit', content: JSON.stringify(e) });
  },
});

The following shows an example of the code in the index.acss file:

.demo {
  padding: 24rpx;
}

The following shows an example of the code in the index.json file:

{
  "defaultTitle": "Form",
  "usingComponents": {
    "form": "antd-mini/es/Form/index",
    "form-item": "antd-mini/es/Form/FormItem/index",
    "input-item": "antd-mini/es/InputItem/index",
    "button": "antd-mini/es/Button/index",
    "checkbox": "antd-mini/es/Checkbox/index",
    "stepper": "antd-mini/es/Stepper/index",
    "picker": "antd-mini/es/Picker/index",
    "checkbox-group": "antd-mini/es/CheckboxGroup/index",
    "checkbox-item": "antd-mini/es/CheckboxGroup/CheckboxItem/index",
    "radio-group": "antd-mini/es/RadioGroup/index",
    "radio-item": "antd-mini/es/RadioGroup/RadioItem/index",
    "switch": "antd-mini/es/Switch/index",
    "selector": "antd-mini/es/Selector/index",
    "form-group": "antd-mini/es/Form/FormGroup/index"
  }
}

Form grouping

The following shows an example of the code in the index.axml file:

<view class="demo">
  <form form="{{form}}">
    <form-group radius header="Basic information">
      <form-item
        required
        label="Name"
        name="name"
        form="{{form}}">
        <input-item mode="form" placeholder="Please enter the name"/>
      </form-item>
      <form-item
        required
        label="Address"
        name="address"
        form="{{form}}">
        <input-item mode="form" placeholder="Please enter the address"/>
      </form-item>
    </form-group>
    <form-group radius header="Contact details">
      <form-item
        required
        label="Mobile phone number"
        name="phone"
        form="{{form}}">
        <input-item mode="form" placeholder="Please enter the mobile phone number"/>
      </form-item>
      <form-item
        required
        label="Email"
        name="email"
        form="{{form}}">
        <input-item mode="form" placeholder="Please enter the email"/>
      </form-item>
    </form-group>
  </form>
</view>

The following shows an example of the code in the index.js file:

Page({
  data: {
    form: 'form',
  },
  handleValuesChange(value, values) {
    console.log(value, values);
  },
});

The following shows an example of the code in the index.acss file:

.demo {
  padding: 24rpx;
}

The following shows an example of the code in the index.json file:

{
  "defaultTitle": "Form",
  "usingComponents": {
    "form": "antd-mini/es/Form/index",
    "form-item": "antd-mini/es/Form/FormItem/index",
    "form-group": "antd-mini/es/Form/FormGroup/index",
    "input-item": "antd-mini/es/InputItem/index",
    "button": "antd-mini/es/Button/index",
    "switch": "antd-mini/es/Switch/index",
    "checkbox": "antd-mini/es/Checkbox/index",
    "radio-group": "antd-mini/es/RadioGroup/index",
    "radio-item": "antd-mini/es/RadioGroup/RadioItem/index",
    "stepper": "antd-mini/es/Stepper/index",
    "selector": "antd-mini/es/Selector/index"
  }
}

Dynamic form

The following shows an example of the code in the index.axml file:

<view class="demo">
    <form 
        form="{{form}}" 
        initialValues="{{initialValues}}"
        onFinish="handleSubmit"
        onValuesChange="handleValuesChange">
        <form-item
            label="Account"
            name="account"
            required
            form="{{form}}">
            <input-item mode="form" placeholder="Please enter the account"/>
        </form-item>
        <form-item 
            label="Login method" 
            name="type" 
            position="vertical" 
            form="{{form}}">
            <radio-group mode="form">
                <radio-item value="password">Password</radio-item>
                <radio-item value="code">Verification code</radio-item>
            </radio-group>
        </form-item>
        <form-item
            a:if="{{values.type==='password'}}"
            label="Password"
            required
            name="password"
            form="{{form}}">
            <input-item mode="form" password placeholder="Please enter the password"/>
        </form-item>
        <form-item
            a:if="{{values.type==='code'}}"
            label="Verification code"
            required
            name="code"
            form="{{form}}">
            <input-item mode="form" password placeholder="Please enter the verification code"/>
        </form-item>
        <button 
            slot="footer"
            type="primary" 
            mode="form"
            form="{{form}}"
            htmlType="submit">Login
        </button>
    </form>
</view>

The following shows an example of the code in the index.js file:

Page({
  data: {
    form: 'form',
    initialValues: {
      type: 'password',
    },
    values: {
      type: 'password',
    },
  },
  handleValuesChange(value, values) {
    console.log(value, values);
    this.setData({ values });
  },
  handleSubmit(e) {
    my.alert({ title: 'Submit', content: JSON.stringify(e) });
  },
});

The following shows an example of the code in the index.acss file:

.demo {

}

The following shows an example of the code in the index.json file:

{
  "defaultTitle": "Form",
  "usingComponents": {
    "form": "antd-mini/es/Form/index",
    "form-item": "antd-mini/es/Form/FormItem/index",
    "input-item": "antd-mini/es/InputItem/index",
    "button": "antd-mini/es/Button/index",
    "radio-group": "antd-mini/es/RadioGroup/index",
    "radio-item": "antd-mini/es/RadioGroup/RadioItem/index"
  }
}

Display style of required fields

The following shows an example of the code in the index.axml file:

<view class="tip">
    Form supports three mandatory and optional display styles
</view>
<demo-block title="Asterisk" padding="0">
    <form form="{{form1}}" requiredMarkStyle="asterisk">
        <form-item 
            position="vertical"
            label="Name" 
            name="name"
            required 
            form="{{form1}}">
            <input-item placeholder="Please enter the name"/>
        </form-item>
        <form-item 
            position="vertical"
            label="Address" 
            name="address"
            help="Detailed address"  
            form="{{form1}}">
            <input-item placeholder="Please enter the address"/>
        </form-item>
    </form>
</demo-block>
<demo-block title="Text-Required" padding="0">
    <form form="{{form2}}" requiredMarkStyle="text-required">
        <form-item 
            position="vertical"
            label="Name" 
            name="name"
            required 
            form="{{form2}}">
            <input-item placeholder="Please enter the name"/>
        </form-item>
        <form-item 
            position="vertical"
            label="Address" 
            name="address"
            help="Detailed address"  
            form="{{form2}}">
            <input-item placeholder="Please enter the address"/>
        </form-item>
    </form>
</demo-block>
<demo-block title="Text-Optional" padding="0">
    <form form="{{form3}}" requiredMarkStyle="text-optional">
        <form-item 
            position="vertical"
            label="Name" 
            name="name"
            required 
            form="{{form3}}">
            <input-item placeholder="Please enter the name"/>
        </form-item>
        <form-item 
            position="vertical"
            label="Address" 
            name="address"
            help="Detailed address"  
            form="{{form3}}">
            <input-item placeholder="Please enter the address"/>
        </form-item>
    </form>
</demo-block>

The following shows an example of the code in the index.js file:

Page({
  data: {
    form1: 'form1',
    form2: 'form2',
    form3: 'form3',
  },
});

The following shows an example of the code in the index.acss file:

.tip {
  background: #fff;
  padding: 24rpx;
  font-size: 28rpx;
}

The following shows an example of the code in the index.json file:

{
  "defaultTitle": "Form",
  "usingComponents": {
    "form": "antd-mini/es/Form/index",
    "form-item": "antd-mini/es/Form/FormItem/index",
    "input-item": "antd-mini/es/InputItem/index",
    "demo-block": "../../components/DemoBlock/index"
  }
}

Usage of the instantiation methods

The following shows an example of the code in the index.axml file:

<view class="demo">
  <form 
      form="{{form}}" 
      ref="getForm"
      onFinish="handleSubmit"
      initialValues="{{initialValues}}"
      onValuesChange="handleValuesChange">
      <form-item
          label="Account"
          name="account"
          form="{{form}}">
          <input-item mode="form" placeholder="Please enter the account"/>
      </form-item>
      <form-item
          label="Password"
          name="password"
          form="{{form}}">
          <input-item mode="form" password placeholder="Please enter the password"/>
      </form-item>
      <view slot="footer">
        <button 
            slot="footer"
            type="primary" 
            mode="form"
            form="{{form}}"
            htmlType="submit">Login
        </button>
      </view>
  </form>
  <button onTap="handleSetValue" className="btn">Reset</button>
</view>

The following shows an example of the code in the index.js file:

const initialValues = {
  account: '',
  password: '',
};
Page({
  data: {
    form: 'form',
    initialValues,
  },
  handleValuesChange(value, values) {
    console.log(value, values);
  },
  handleSubmit(e) {
    my.alert({ title: 'Submit', content: JSON.stringify(e) });
  },
  getForm(ref) {
    this.formRef = ref;
  },
  handleSetValue() {
    this.formRef.setFieldsValue(this.data.form, initialValues);
  },
});

The following shows an example of the code in the index.acss file:

.demo {
}
.btn {
  margin: 0 12px;
}

The following shows an example of the code in the index.json file:

{
  "defaultTitle": "Form",
  "usingComponents": {
    "form": "antd-mini/es/Form/index",
    "form-item": "antd-mini/es/Form/FormItem/index",
    "input-item": "antd-mini/es/InputItem/index",
    "button": "antd-mini/es/Button/index"
  }
}