AI 助理
备案控制台
文档
输入文档关键字查找
首页 移动开发平台 mPaaS 小程序 小程序开发 小程序扩展组件 antd-mini 实验性质的组件 表单（Form）

表单（Form）

更新时间：
产品详情
相关技术圈
我的收藏

高性能表单控件，自带数据域管理。包含数据录入、校验以及对应样式，用于创建一个实体或收集信息。

重要

  • 小程序项目使用 Form 表单需开启 Component2 选项。

  • 配合 a:for 指令使用时，推荐指定 key 值，否则可能出现异常。

  • Form 标签的 form 属性值与其内部 FormItem 标签的 form 属性值必须相同，且全局唯一；内部的 FormItem 标签的 name 属性必须唯一。

  • 配合组件库内的表单组件使用时候，表单组件的 mode 属性值需为 form。

属性

Form

属性

类型

必填

默认值

说明

form

string

是

-

表单 uid

initialValues

Record<sring, any>

否

-

表单初始值

position

'horizontal' | 'vertical'

否

'horizontal'

布局

requiredMarkStyle

'asterisk' | 'text-required' | 'text-optional'

否

'asterisk'

必填选填的标记样式

asterisk：使用红色星号标记必填项。

text-required：使用文字“必填”标记必填项。

text-optional：使用文字“选填”标记选填项。

className

string

否

-

类名

FormGroup

属性

类型

必填

默认值

说明

header

string

否

-

FormGroup 名称

radius

boolean

否

false

FormGroup 形状是否为圆角

className

string

否

-

类名

FormItem

属性

类型

必填

默认值

说明

form

string

是

default

表单 uid

name

string

是

default

字段 uid

label

string

否

-

字段名称

position

'horizontal' | 'vertical'

否

'horizontal'

布局，优先级高于 Form 的 position

arrow

boolean

否

false

表单项右侧箭头

required

boolean

否

false

是否必填，label 展示必填标识

help

string

否

-

label 的解释说明

className

string

否

""

类名

事件

Form

事件名

说明

类型

onValuesChange

字段更新，触发此回调

( changedFields: Record<string, any>, allFields: Record<string, any> ) => void

onFinish

表单提交后，触发此回调

( changedFields: Record<string, any>, allFields: Record<string, any> ) => void

插槽

FormGroup

名称

说明

header

标题内容

FormItem

名称

说明

extra

表单项额外内容

实例方法

Form

事件名

说明

类型

getComponentIns

获取组件示例，其值等同于默认的 ref 返回值

() => Component

setFieldsValue

设置表单字段值

( formName: string, fieldsVals: Record<string, any> ) => void

样式类

Form

类名

说明

amd-form

整体样式

amd-form-footer

footer 样式

FormGroup

类名

说明

amd-form-group-header

标题样式

amd-form-group-radius

圆角样式

FormItem

类名

说明

amd-form-item-label

标签样式

amd-form-item-field

字段样式

amd-form-item-extra

额外内容样式

amd-form-item-arrow

箭头样式

代码示例

基本使用

index.axml 的代码示例如下：

<view class="demo">
    <demo-block title="水平布局表单" padding="0">
        <form 
            form="{{form}}" 
            initialValues="{{initialValues}}"
            onFinish="handleSubmit"
            onValuesChange="handleValuesChange">
            <form-item
                label="姓名"
                name="account"
                required
                help="关于姓名的解释"
                form="{{form}}">
                <input-item mode="form" placeholder="请输入姓名"/>
            </form-item>
            <form-item
                label="地址"
                name="address"
                form="{{form}}">
                <input-item mode="form" password placeholder="请输入地址"/>
            </form-item>
            <form-item
                label="数量"
                name="quantity"
                form="{{form}}">
                <stepper step="{{1}}"  min="{{0}}" mode="form"/>
            </form-item>
            <form-item
                label="送货上门"
                name="needDelivery"
                form="{{form}}">
                <switch mode="form"/>
            </form-item>
            <button 
                slot="footer"
                type="primary" 
                mode="form"
                form="{{form}}"
                htmlType="submit">提交
            </button>
        </form>
    </demo-block>
    <demo-block title="垂直布局表单" padding="0">
        <form 
            form="{{formV}}" 
            initialValues="{{initialValues}}"
            onFinish="handleSubmit"
            onValuesChange="handleValuesChange">
            <form-item
                label="姓名"
                position="vertical" 
                name="account"
                required
                form="{{formV}}">
                <input-item mode="form" placeholder="请输入姓名"/>
            </form-item>
            <form-item
                label="地址"
                position="vertical" 
                name="address"
                form="{{formV}}">
                <input-item mode="form" password placeholder="请输入地址"/>
            </form-item>
            <form-item
                label="数量"
                position="vertical" 
                name="quantity"
                form="{{formV}}">
                <stepper step="{{1}}"  min="{{0}}" mode="form"/>
            </form-item>
            <form-item
                label="送货上门"
                position="vertical" 
                name="needDelivery"
                form="{{formV}}">
                <switch mode="form"/>
            </form-item>
            <button 
                slot="footer"
                type="primary" 
                mode="form"
                form="{{formV}}"
                htmlType="submit">提交
            </button>
        </form>
    </demo-block>
</view>

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: '提交', content: JSON.stringify(e) });
  },
});

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

结合表单组件

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="请输入"/>
    </form-item>
    <form-item
      required
      label="password"
      name="password"
      rules="{{[{ pattern: /\d{6}/, message: '密码必须是6位数字' },]}}"
      form="{{form}}">
      <input-item mode="form" placeholder="请输入" 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="请选择" 
        data="{{pickerList}}"
        mode="form"
        onFormat="formatValue" 
        onDismiss="cancelPicker" 
      >
        <view slot="title">
          <text style="color: red;">Picker</text> 选择器</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-item>
        <radio-item value="a2">单选二</radio-item>
        <radio-item value="a3">单选三</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">复选框1</checkbox-item>
        <checkbox-item value="a2">复选框2</checkbox-item>
        <checkbox-item value="a3">复选框3</checkbox-item>
      </checkbox-group>
    </form-item>
    <button 
      slot="footer"
      type="primary" 
      mode="form"
      form="{{form}}"
      htmlType="submit">提交
    </button>
  </form>
</view>

index.js 的代码示例如下：

Page({
  data: {
    form: 'form',
    initialValues: {
      stepper: 20,
      switch: false,
      picker: ['2012', '12', 12],
    },
    selectorItems: [
      {
        text: '选项一',
        value: '1',
      },
      {
        text: '选项二',
        value: '2',
      },
      {
        text: '选项三',
        value: '3',
      },
      {
        text: '选项四',
        value: '4',
      },
      {
        text: '选项五',
        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: '提交', content: JSON.stringify(e) });
  },
});

index.acss 的代码示例如下：

.demo {
  padding: 24rpx;
}

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

表单分组

index.axml 的代码示例如下：

<view class="demo">
  <form form="{{form}}">
    <form-group radius header="基本信息">
      <form-item
        required
        label="姓名"
        name="name"
        form="{{form}}">
        <input-item mode="form" placeholder="请输入姓名"/>
      </form-item>
      <form-item
        required
        label="地址"
        name="address"
        form="{{form}}">
        <input-item mode="form" placeholder="请输入地址"/>
      </form-item>
    </form-group>
    <form-group radius header="联系方式">
      <form-item
        required
        label="手机号"
        name="phone"
        form="{{form}}">
        <input-item mode="form" placeholder="请输入手机号"/>
      </form-item>
      <form-item
        required
        label="邮箱"
        name="email"
        form="{{form}}">
        <input-item mode="form" placeholder="请输入邮箱"/>
      </form-item>
    </form-group>
  </form>
</view>

index.js 的代码示例如下：

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

index.acss 的代码示例如下：

.demo {
  padding: 24rpx;
}

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

动态表单

index.axml 的代码示例如下：

<view class="demo">
    <form 
        form="{{form}}" 
        initialValues="{{initialValues}}"
        onFinish="handleSubmit"
        onValuesChange="handleValuesChange">
        <form-item
            label="账号"
            name="account"
            required
            form="{{form}}">
            <input-item mode="form" placeholder="请输入账号"/>
        </form-item>
        <form-item 
            label="登录方式" 
            name="type" 
            position="vertical" 
            form="{{form}}">
            <radio-group mode="form">
                <radio-item value="password">密码</radio-item>
                <radio-item value="code">验证码</radio-item>
            </radio-group>
        </form-item>
        <form-item
            a:if="{{values.type==='password'}}"
            label="密码"
            required
            name="password"
            form="{{form}}">
            <input-item mode="form" password placeholder="请输入密码"/>
        </form-item>
        <form-item
            a:if="{{values.type==='code'}}"
            label="验证码"
            required
            name="code"
            form="{{form}}">
            <input-item mode="form" password placeholder="请输入验证码"/>
        </form-item>
        <button 
            slot="footer"
            type="primary" 
            mode="form"
            form="{{form}}"
            htmlType="submit">登录
        </button>
    </form>
</view>

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: '提交', content: JSON.stringify(e) });
  },
});

index.acss 的代码示例如下：

.demo {

}

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

必填展示样式

index.axml 的代码示例如下：

<view class="tip">
    Form 支持三种必填选填的展示样式
</view>
<demo-block title="星号" padding="0">
    <form form="{{form1}}" requiredMarkStyle="asterisk">
        <form-item 
            position="vertical"
            label="姓名" 
            name="name"
            required 
            form="{{form1}}">
            <input-item placeholder="请输入姓名"/>
        </form-item>
        <form-item 
            position="vertical"
            label="地址" 
            name="address"
            help="详细地址"  
            form="{{form1}}">
            <input-item placeholder="请输入地址"/>
        </form-item>
    </form>
</demo-block>
<demo-block title="文字-必填" padding="0">
    <form form="{{form2}}" requiredMarkStyle="text-required">
        <form-item 
            position="vertical"
            label="姓名" 
            name="name"
            required 
            form="{{form2}}">
            <input-item placeholder="请输入姓名"/>
        </form-item>
        <form-item 
            position="vertical"
            label="地址" 
            name="address"
            help="详细地址"  
            form="{{form2}}">
            <input-item placeholder="请输入地址"/>
        </form-item>
    </form>
</demo-block>
<demo-block title="文字-选填" padding="0">
    <form form="{{form3}}" requiredMarkStyle="text-optional">
        <form-item 
            position="vertical"
            label="姓名" 
            name="name"
            required 
            form="{{form3}}">
            <input-item placeholder="请输入姓名"/>
        </form-item>
        <form-item 
            position="vertical"
            label="地址" 
            name="address"
            help="详细地址"  
            form="{{form3}}">
            <input-item placeholder="请输入地址"/>
        </form-item>
    </form>
</demo-block>

index.js 的代码示例如下：

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

index.acss 的代码示例如下：

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

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

实例方法使用

index.axml 的代码示例如下：

<view class="demo">
  <form 
      form="{{form}}" 
      ref="getForm"
      onFinish="handleSubmit"
      initialValues="{{initialValues}}"
      onValuesChange="handleValuesChange">
      <form-item
          label="账号"
          name="account"
          form="{{form}}">
          <input-item mode="form" placeholder="请输入账号"/>
      </form-item>
      <form-item
          label="密码"
          name="password"
          form="{{form}}">
          <input-item mode="form" password placeholder="请输入密码"/>
      </form-item>
      <view slot="footer">
        <button 
            slot="footer"
            type="primary" 
            mode="form"
            form="{{form}}"
            htmlType="submit">登录
        </button>
      </view>
  </form>
  <button onTap="handleSetValue" className="btn">重置</button>
</view>

index.js 的代码示例如下：

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

index.acss 的代码示例如下：

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

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"
  }
}
上一篇：实验性质的组件下一篇：安全区（SafeArea）
文档推荐