Form 表单

由输入框、选择器、单选框等控件组成，用以收集、校验、提交数据。

基础用法

请选择

<my-form :model="form" label-width="80px">
  <my-form-item label="用户名">
    <my-input v-model="form.username" />
  </my-form-item>
  <my-form-item>
    <my-button type="primary" native-type="submit">提交</my-button>
  </my-form-item>
</my-form>

行内表单

inline 使表单项水平排列。

<my-form :model="form" inline>
  <my-form-item label="姓名"><my-input v-model="form.name" /></my-form-item>
  <my-form-item label="邮箱"><my-input v-model="form.email" /></my-form-item>
  <my-form-item><my-button type="primary">查询</my-button></my-form-item>
</my-form>

对齐方式

align 控制表单水平对齐：left、center、right。

<my-form :model="form" align="left" />
<my-form :model="form" align="center" />
<my-form :model="form" align="right" />

居中表单

centered 使表单水平居中并限制最大宽度。

<my-form :model="form" centered label-width="80px">
  <my-form-item label="用户名"><my-input v-model="form.username" /></my-form-item>
  <my-form-item label="密码"><my-input v-model="form.password" type="password" /></my-form-item>
</my-form>

表单校验

通过 rules 配置验证规则，ref 调用 validate() 方法触发校验。支持 required、min、max、pattern。

<my-form ref="formRef" :model="form" :rules="rules">
  <my-form-item prop="name" label="姓名">
    <my-input v-model="form.name" />
  </my-form-item>
</my-form>

<script setup>
const rules = {
  name: [
    { required: true, message: '请输入姓名', trigger: 'blur' },
    { min: 2, max: 10, message: '2-10个字符', trigger: 'blur' },
  ],
}
// 调用校验
formRef.value.validate().then(valid => { ... })
</script>

自定义校验规则

validator 函数接收值和回调，适用于跨字段校验、异步校验等场景。

const rules = {
  password2: [
    { required: true, message: '请输入密码', trigger: 'blur' },
    { min: 6, message: '密码至少6位', trigger: 'blur' },
  ],
  password3: [
    { required: true, message: '请确认密码', trigger: 'blur' },
    {
      validator: (val, cb) => {
        if (val !== form.password2) cb('两次密码不一致')
        else cb()
      },
      trigger: 'blur',
    },
  ],
}

动态表单项

通过数组操作动态添加/删除表单项。

<div v-for="(item, idx) in form.items" :key="idx">
  <my-form-item :label="'键 ' + (idx + 1)">
    <my-input v-model="item.key" />
  </my-form-item>
  <my-button @click="removeItem(idx)">删除</my-button>
</div>
<my-button @click="addItem">+ 添加一项</my-button>

数字类型验证

rule 设置 type: 'number'，min / max 按数值（而非字符串长度）比较。

const rules = {
  quantity: [
    { type: 'number', required: true, message: '请输入数量' },
    { type: 'number', min: 1, max: 9999, message: '数量1-9999' },
  ],
  price: [
    { type: 'number', required: true, message: '请输入价格' },
    { type: 'number', min: 0.01, message: '价格不能小于0.01' },
  ],
}

尺寸控制

size 控制标签字体大小：large、default、small。

<my-form :model="form" size="large">
  <my-form-item label="大尺寸"><my-input /></my-form-item>
</my-form>
<my-form :model="form">
  <my-form-item label="默认尺寸"><my-input /></my-form-item>
</my-form>
<my-form :model="form" size="small">
  <my-form-item label="小尺寸"><my-input /></my-form-item>
</my-form>

标签位置

label-position 设为 top 将标签放在输入框上方。

<my-form :model="form" label-position="top">
  <my-form-item label="用户名"><my-input /></my-form-item>
</my-form>

组件结构

<form> 根元素通过默认插槽包含若干个 <my-form-item> 组件。每个 form-item 由 <label> 标签、<div> 内容区（含默认插槽和错误信息 <p>）组成。

CSS 类名

类名	说明
.my-form	根元素
.my-form--inline	行内模式
.my-form--label-top	标签顶部对齐
.my-form--label-left	标签左对齐
.my-form--label-right	标签右对齐
.my-form--align-left	水平左对齐
.my-form--align-center	水平居中对齐
.my-form--align-right	水平右对齐
.my-form--centered	居中表单
.my-form--large	大尺寸
.my-form--small	小尺寸
.my-form-item	表单项
.my-form-item--error	校验错误状态
.my-form-item__label	标签
.my-form-item__required	必填星号
.my-form-item__content	内容区域
.my-form-item__error	错误信息

API

Form Props

属性	说明	类型	默认值
model	表单数据对象	Record<string, any>	{}
rules	校验规则	Record<string, FormRule | FormRule[]>	{}
labelWidth	标签宽度	string	—
labelPosition	标签位置	'left' | 'right' | 'top'	'right'
size	控件尺寸	'large' | 'default' | 'small'	'default'
inline	行内表单	boolean	false
align	水平对齐	'left' | 'center' | 'right'	'left'
centered	居中表单（限制最大宽度）	boolean	false
disabled	禁用所有表单项	boolean	false
ariaLabel	无障碍标签	string	'表单'

Form Methods

方法	说明	参数
validate	校验所有字段，返回 Promise	—
clearValidate	清除所有校验错误	—
resetFields	重置所有字段并清空校验	—

Form Events

事件	说明	回调
submit	表单提交	(model, valid: boolean)

FormItem Props

属性	说明	类型	默认值
prop	字段名（对应 model 中的 key）	string	—
label	标签文字	string	—
required	是否必填（显示红色星号）	boolean	false
rules	校验规则（优先级高于 form rules）	FormRule | FormRule[]	—
labelWidth	标签宽度（覆盖 form 设置）	string	—
showMessage	是否显示校验错误信息	boolean	true

FormRule

属性	说明	类型	默认值
required	必填	boolean	—
message	错误提示文字	string	—
trigger	触发时机	'change' | 'blur' | 'submit'	'submit'
type	值类型	'string' | 'number'	'string'
min	最小长度/最小值	number	—
max	最大长度/最大值	number	—
pattern	正则匹配	RegExp	—
validator	自定义校验函数	(value, callback) => void	—