Form 表单

表单由容器 mu-form 与表单项 mu-form-item 组合而成，前者管理数据模型与校验规则，后者负责标签、必填星号与错误提示。支持标签位置、宽度与对齐方式，并提供校验、重置等实例方法。

小程序	APP	Web
✓	✓	✓

实例

以下按属性分别说明 mu-form 与 mu-form-item 的用法，可按需组合。

<template>
  <mu-form :model="form" :rules="rules">
    <mu-form-item label="用户名" prop="name">
      <mu-field v-model="form.name" placeholder="2-12 个字符"></mu-field>
    </mu-form-item>
    <mu-form-item label="密码" prop="password">
      <mu-field v-model="form.password" :password="true" placeholder="至少 6 位"></mu-field>
    </mu-form-item>
  </mu-form>
</template>

标签位置

labelPosition 控制标签位置，默认在左侧，设为 top 后显示在表单项上方。

<mu-form :model="topForm" label-position="top">
  <mu-form-item label="城市" prop="city" :rules="cityRules">
    <mu-select v-model="topForm.city" :options="cityOptions" placeholder="请选择城市"></mu-select>
  </mu-form-item>
  <mu-form-item label="评分" prop="rating" :rules="ratingRules">
    <mu-rate v-model="topForm.rating"></mu-rate>
  </mu-form-item>
  <mu-form-item label="音量" prop="volume">
    <mu-slider v-model="topForm.volume"></mu-slider>
  </mu-form-item>
</mu-form>

标签宽度

labelWidth 设置标签宽度，支持固定值，设为 auto 时自动取最宽标签的宽度。

<mu-form :model="autoForm" label-width="auto">
  <mu-form-item label="姓名" prop="shortName">
    <mu-field v-model="autoForm.shortName" placeholder="标签较短"></mu-field>
  </mu-form-item>
  <mu-form-item label="详细联系地址" prop="address">
    <mu-field v-model="autoForm.address" placeholder="标签较长"></mu-field>
  </mu-form-item>
</mu-form>

标签对齐

labelAlign 控制标签的对齐方式，如设为 right 使标签右对齐。

<mu-form :model="alignForm" label-align="right">
  <mu-form-item label="用户名" prop="name">
    <mu-field v-model="alignForm.name" placeholder="标签右对齐"></mu-field>
  </mu-form-item>
  <mu-form-item label="手机号" prop="phone">
    <mu-field v-model="alignForm.phone" placeholder="标签右对齐"></mu-field>
  </mu-form-item>
</mu-form>

自定义标签

不传 label 时不显示标签；也可通过 label 插槽自定义标签内容，优先级高于 label 属性。

<mu-form :model="plain" :rules="plainRules">
  <mu-form-item prop="keyword">
    <mu-field v-model="plain.keyword" placeholder="没有标签的表单项"></mu-field>
  </mu-form-item>
  <mu-form-item prop="nickname">
    <template #label>
      <text class="label-custom">昵称</text>
    </template>
    <mu-field v-model="plain.nickname" placeholder="自定义标签内容"></mu-field>
  </mu-form-item>
</mu-form>

必填标记

设置 required 在标签前显示必填星号；同时可通过 showMessage 与 border 控制错误提示与分隔线。

<mu-form :model="requiredForm" :show-message="false" :border="false">
  <mu-form-item label="姓名" prop="name" :required="true">
    <mu-field v-model="requiredForm.name" :bordered="true" placeholder="带 * 的必填项"></mu-field>
  </mu-form-item>
</mu-form>

提交事件

通过 ref 调用 submit 方法，校验通过后触发 submit 事件并回传表单数据。

<mu-form ref="submitFormRef" :model="submitForm" @submit="onFormSubmit">
  <mu-form-item label="昵称" prop="nick">
    <mu-field v-model="submitForm.nick" placeholder="输入后点击提交"></mu-field>
  </mu-form-item>
</mu-form>
<mu-button type="primary" @click="onSubmitForm">提交</mu-button>

校验方法

通过 ref 调用 validate 校验全部表单项，resetFields 重置为初始值，clearValidate 清除校验状态。

<mu-form ref="formRef" :model="form" :rules="rules">
  <mu-form-item label="用户名" prop="name">
    <mu-field v-model="form.name" placeholder="请输入用户名"></mu-field>
  </mu-form-item>
</mu-form>
<mu-button type="primary" @click="onSubmit">提交校验</mu-button>
<mu-button plain type="info" @click="onReset">重置清空</mu-button>
<mu-button text type="info" @click="onClear">清除校验</mu-button>

属性

全部属性均可选，未传入时使用默认值；默认值列为 - 表示空字符串。

表单容器

属性名称	说明	类型	默认值
model	表单数据对象	any	null
rules	校验规则对象，键为 mu-form-item 的 prop	any	null
labelPosition	标签位置，可选 left、top	string	left
labelWidth	标签宽度，支持固定值或 auto（自动取最宽标签）	string	160rpx
labelAlign	标签对齐方式，可选 left、center、right	string	left
border	是否显示表单项分隔线	boolean	true
showMessage	是否显示校验错误提示	boolean	true
customClass	自定义根节点类名	string	-
customStyle	自定义根节点样式	any	-

表单项

属性名称	说明	类型	默认值
prop	对应 model 中的字段名，用于取值与匹配校验规则	string	-
label	标签文字	string	-
labelPosition	标签位置，覆盖 mu-form 的配置，可选 left、top	string	-
labelWidth	标签宽度，覆盖 mu-form 的配置，支持固定值或 auto	string	-
labelAlign	标签对齐方式，覆盖 mu-form 的配置，可选 left、center、right	string	-
required	是否显示必填星号	boolean	false
showMessage	是否显示校验错误提示	boolean	true
border	是否显示分隔线	boolean	true
rules	表单项校验规则，设置后优先于 mu-form 的 rules	MuFormRule[]	[]
customClass	自定义根节点类名	string	-
customStyle	自定义根节点样式	any	-

校验规则

字段	说明	类型
required	是否必填	boolean
type	校验类型，可选 number、email、phone、url、array	string
min	最小值或最小长度	number
max	最大值或最大长度	number
len	固定长度	number
pattern	正则表达式字符串	string
message	校验失败提示文字	string
validator	自定义校验函数，返回错误文案，空串表示通过	(value: any) => string

事件

组件支持以下事件。

事件名	说明	回调参数
validate	校验完成时触发（mu-form）	valid: boolean
submit	调用 submit 且校验通过时触发（mu-form）	values: any

插槽

组件支持以下插槽。

名称	说明
default	表单项内容（mu-form-item）
label	自定义标签内容，优先级高于 label 属性（mu-form-item）

方法

通过 ref 获取组件实例后调用以下方法。

方法名	说明	参数	返回值
validate	校验全部表单项	callback?: (valid: boolean) => void	boolean
validateField	校验指定字段	prop: string	boolean
clearValidate	清除校验状态，不传 prop 时清除全部	prop?: string	-
resetFields	重置全部字段为初始值	-	-
getValues	获取表单数据对象	-	any
submit	校验通过后触发 submit 事件	-	-

注意事项

• 平台差异：App、小程序、Web 表现一致。
• 使用注意：mu-form-item 的 prop 必须与 model 中的字段名一致，mu-form 才能取到值并匹配 rules 中的同名规则。
• 使用注意：校验、重置等方法需通过 ref 调用，resetFields 重置为初始值而非清空。
• 使用注意：校验错误提示仅在触发校验（validate / submit）后显示。