what is a form, what are the features of a form-Mobile Platform as a Service(mPaaS)-阿里云帮助中心

A high-performance form control that features built-in data domain management. It provides data entry, validation, and styles for creating entities or collecting information.

Important

To use the Form component in a miniapp project, enable the Component2 option.
When using the form with the a:for instruction, specify a key value to prevent potential errors.
The value of the form property for the Form tag must be the same as the value of the form property for the internal FormItem tags. This value must be globally unique. The name property of the internal FormItem tags must also be unique.
When using this component with other form components from the component library, set the mode property of the other form components to form.

Properties

Form

Property	Type	Required	Default	Description
form	string	Yes	-	Form UID
initialValues	Record<sring, any>	No	-	The initial values of the form.
position	'horizontal' \| 'vertical'	No	'horizontal'	The layout.
requiredMarkStyle	'asterisk' \| 'text-required' \| 'text-optional'	No	'asterisk'	The style for required field indicators. asterisk: Marks required fields with a red asterisk. text-required: Marks required fields with the text "Required". text-optional: Marks optional fields with the text "Optional".
className	string	No	-	The class name.

FormGroup

Property	Type	Required	Default	Description
header	string	No	-	The name of the FormGroup.
radius	boolean	No	false	Specifies whether the FormGroup has a border radius.
className	string	No	-	The class name.

FormItem

Property	Type	Required	Default	Description
form	string	Yes	default	The UID of the form.
name	string	Yes	default	UID field
label	string	No	-	The name of the field.
position	'horizontal' \| 'vertical'	No	'horizontal'	The layout. This property has a higher priority than the position property of the Form.
arrow	boolean	No	false	The arrow on the right side of the form item.
required	boolean	No	false	Specifies whether the field is required. If set to true, the label displays a required mark.
help	string	No	-	The explanatory text for the label.
className	string	No	""	The class name.

Events

Form

Event Name	Description	Type
onValuesChange	This callback is triggered when a field is updated.	`( changedFields: Record<string, any>, allFields: Record<string, any> ) => void`
onFinish	This callback is triggered after the form is submitted.	`( changedFields: Record<string, any>, allFields: Record<string, any> ) => void`

Slots

FormGroup

Name	Description
header	The content of the title.

FormItem

Name	Description
extra	The extra content of the form item.

Instance methods

Form

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

Style classes

Form

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

FormGroup

Class name	Description
amd-form-group-header	The style of the title.
amd-form-group-radius	The style for the border radius.

FormItem

Class name	Description
amd-form-item-label	The style of the label.
amd-form-item-field	The style of the field.
amd-form-item-extra	Additional Content Style
amd-form-item-arrow	The style of the arrow.

Code examples

Basic usage

The following is a code example for index.axml:

<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 about the name"
                form="{{form}}">
                <input-item mode="form" placeholder="Enter a name"/>
            </form-item>
            <form-item
                label="Address"
                name="address"
                form="{{form}}">
                <input-item mode="form" password placeholder="Enter an 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="Enter a name"/>
            </form-item>
            <form-item
                label="Address"
                position="vertical" 
                name="address"
                form="{{formV}}">
                <input-item mode="form" password placeholder="Enter an 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 is a code example for index.js:

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 is a code example for index.json:

{
  "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"
  }
}

Use with form components

The following is a code example for index.axml:

<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="Enter"/>
    </form-item>
    <form-item
      required
      label="password"
      name="password"
      rules="{{[{ pattern: /\d{6}/, message: 'The password must be a 6-digit number' },]}}"
      form="{{form}}">
      <input-item mode="form" placeholder="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="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">Radio 1</radio-item>
        <radio-item value="a2">Radio 2</radio-item>
        <radio-item value="a3">Radio 3</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">Check box 1</checkbox-item>
        <checkbox-item value="a2">Check box 2</checkbox-item>
        <checkbox-item value="a3">Check box 3</checkbox-item>
      </checkbox-group>
    </form-item>
    <button 
      slot="footer"
      type="primary" 
      mode="form"
      form="{{form}}"
      htmlType="submit">Submit
    </button>
  </form>
</view>

The following is a code example for index.js:

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 is a code example for index.acss:

.demo {
  padding: 24rpx;
}

The following is a code example for index.json:

{
  "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 groups

The following is a code example for index.axml:

<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="Enter a name"/>
      </form-item>
      <form-item
        required
        label="Address"
        name="address"
        form="{{form}}">
        <input-item mode="form" placeholder="Enter an address"/>
      </form-item>
    </form-group>
    <form-group radius header="Contact information">
      <form-item
        required
        label="Phone number"
        name="phone"
        form="{{form}}">
        <input-item mode="form" placeholder="Enter a phone number"/>
      </form-item>
      <form-item
        required
        label="Email"
        name="email"
        form="{{form}}">
        <input-item mode="form" placeholder="Enter an email"/>
      </form-item>
    </form-group>
  </form>
</view>

The following is a code example for index.js:

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

The following is a code example for index.acss:

.demo {
  padding: 24rpx;
}

The following is a code example for index.json:

{
  "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 forms

The following is a code example for index.axml:

<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="Enter an account"/>
        </form-item>
        <form-item 
            label="Logon method" 
            name="type" 
            position="vertical" 
            form="{{form}}">
            <radio-group mode="form">
                <radio-item value="password">Password</radio-item>
                <radio-item value="code">Captcha</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="Enter a password"/>
        </form-item>
        <form-item
            a:if="{{values.type==='code'}}"
            label="Captcha"
            required
            name="code"
            form="{{form}}">
            <input-item mode="form" password placeholder="Enter the captcha"/>
        </form-item>
        <button 
            slot="footer"
            type="primary" 
            mode="form"
            form="{{form}}"
            htmlType="submit">Log on
        </button>
    </form>
</view>

The following is a code example for index.js:

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 is a code example for index.acss:

.demo {

}

The following is a code example for index.json:

{
  "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"
  }
}

Required field display styles

The following is a code example for index.axml:

<view class="tip">
    Form supports three display styles for required and optional fields.
</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="Enter a name"/>
        </form-item>
        <form-item 
            position="vertical"
            label="Address" 
            name="address"
            help="Detailed address"  
            form="{{form1}}">
            <input-item placeholder="Enter an 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="Enter a name"/>
        </form-item>
        <form-item 
            position="vertical"
            label="Address" 
            name="address"
            help="Detailed address"  
            form="{{form2}}">
            <input-item placeholder="Enter an 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="Enter a name"/>
        </form-item>
        <form-item 
            position="vertical"
            label="Address" 
            name="address"
            help="Detailed address"  
            form="{{form3}}">
            <input-item placeholder="Enter an address"/>
        </form-item>
    </form>
</demo-block>

The following is a code example for index.js:

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

The following is a code example for index.acss:

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

The following is a code example for index.json:

{
  "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"
  }
}

Use instance methods

The following is a code example for index.axml:

<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="Enter an account"/>
      </form-item>
      <form-item
          label="Password"
          name="password"
          form="{{form}}">
          <input-item mode="form" password placeholder="Enter a password"/>
      </form-item>
      <view slot="footer">
        <button 
            slot="footer"
            type="primary" 
            mode="form"
            form="{{form}}"
            htmlType="submit">Log on
        </button>
      </view>
  </form>
  <button onTap="handleSetValue" className="btn">Reset</button>
</view>

The following is a code example for index.js:

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 is a code example for index.acss:

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

The following is a code example for index.json:

{
  "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"
  }
}