Form 表单

说明

基于 el-form、el-form-item、el-row、el-col 封装，整合栅格布局与表单数据联动能力。

（1）y-form 整合 el-form + el-row，作为外层容器

（2）y-form-item 整合 el-form-item + el-col，内置栅格布局，详见 FormItem 表单项

（3）除扩展属性外，其余 API 与 Element Plus 官方文档保持一致，可直接透传使用

注意：

• y-form 的 span 会作为所有 y-form-item 的默认栅格占位；单项可通过 :span 覆盖
• 属性会分发给内部的 el-form 或 el-row，无需手动嵌套

用法示例

布局用法

y-form 设置 :span="12" 时表单项默认两列；y-form-item 可通过 span 单独控制占位

姓名

年龄

备注

<template>
  <y-form
    :model="form"
    :rules="rules"
    label-width="120px"
    :span="12"
    :gutter="24">
    <y-form-item
      label="姓名"
      prop="name">
      <el-input
        v-model="form.name"
        placeholder="请输入姓名" />
    </y-form-item>
    <y-form-item
      label="年龄"
      prop="age">
      <el-input-number
        v-model="form.age"
        :min="0"
        placeholder="请输入年龄"
        style="width: 100%" />
    </y-form-item>
    <y-form-item
      label="备注"
      prop="remark"
      :span="24">
      <el-input
        v-model="form.remark"
        type="textarea"
        placeholder="请输入备注" />
    </y-form-item>
  </y-form>
</template>

<script setup>
import { reactive } from 'vue'

const form = reactive({
  name: '',
  age: null,
  remark: ''
})

const rules = {
  name: [{ required: true, message: '请输入姓名', trigger: 'blur' }]
}
</script>

隐藏源码

config 联动

config 在表单字段变化时触发，参数为 (model, context)，context 包含 field、prevValue、newValue；static-fields 中的字段变化不会触发 config

采购类型

请选择采购类型

大类

请选择大类

小类

请选择小类

备注

<template>
  <y-form
    ref="formRef"
    :model="form"
    :rules="rules"
    :config="handleFormChange"
    :static-fields="['remark']"
    label-width="120px"
    :span="12"
    :gutter="24">
    <y-form-item
      label="采购类型"
      prop="type">
      <el-select
        v-model="form.type"
        placeholder="请选择采购类型"
        clearable
        style="width: 100%">
        <el-option
          v-for="item in typeOptions"
          :key="item.value"
          :label="item.label"
          :value="item.value" />
      </el-select>
    </y-form-item>
    <y-form-item
      label="大类"
      prop="category">
      <el-select
        v-model="form.category"
        placeholder="请选择大类"
        clearable
        style="width: 100%">
        <el-option
          v-for="item in categoryOptions"
          :key="item.value"
          :label="item.label"
          :value="item.value" />
      </el-select>
    </y-form-item>
    <y-form-item
      label="小类"
      prop="subCategory">
      <el-select
        v-model="form.subCategory"
        placeholder="请选择小类"
        clearable
        style="width: 100%">
        <el-option
          v-for="item in subCategoryOptions"
          :key="item.value"
          :label="item.label"
          :value="item.value" />
      </el-select>
    </y-form-item>
    <y-form-item
      label="备注"
      prop="remark"
      :span="24">
      <el-input
        v-model="form.remark"
        type="textarea"
        placeholder="不参与联动" />
    </y-form-item>
    <y-form-item :span="24">
      <el-button
        type="primary"
        @click="handleSubmit"
        >提交</el-button
      >
      <el-button @click="handleReset">重置</el-button>
    </y-form-item>
  </y-form>
</template>

<script setup>
import { reactive, ref } from 'vue'
import { ElMessage } from 'element-plus'

const formRef = ref()

const form = reactive({
  type: '',
  category: '',
  subCategory: '',
  remark: ''
})

const rules = {
  type: [{ required: true, message: '请选择采购类型', trigger: 'change' }]
}

const typeOptions = [
  { label: '耗材', value: 'consumable' },
  { label: '设备', value: 'equipment' }
]

const categoryOptions = ref([])
const subCategoryOptions = ref([])

const categoryMap = {
  consumable: [
    { label: '办公用品', value: 'office' },
    { label: '清洁用品', value: 'cleaning' }
  ],
  equipment: [
    { label: '电脑', value: 'computer' },
    { label: '手机', value: 'phone' }
  ]
}

const subCategoryMap = {
  'consumable-office': [
    { label: '文具', value: 'stationery' },
    { label: '纸张', value: 'paper' }
  ],
  'consumable-cleaning': [
    { label: '清洁剂', value: 'detergent' },
    { label: '纸巾', value: 'tissue' }
  ],
  'equipment-computer': [
    { label: '台式机', value: 'desktop' },
    { label: '笔记本', value: 'laptop' }
  ],
  'equipment-phone': [
    { label: '手机', value: 'mobile' },
    { label: '配件', value: 'accessory' }
  ]
}

const handleFormChange = (model, { field, newValue }) => {
  if (field === 'type') {
    model.category = ''
    model.subCategory = ''
    categoryOptions.value = newValue ? categoryMap[newValue] || [] : []
    subCategoryOptions.value = []
  }
  if (field === 'category') {
    model.subCategory = ''
    subCategoryOptions.value = newValue
      ? subCategoryMap[`${model.type}-${newValue}`] || []
      : []
  }
}

const handleSubmit = async () => {
  try {
    const data = await formRef.value.validateSync()
    ElMessage.success(`校验通过：${JSON.stringify(data)}`)
  } catch {
    ElMessage.error('校验失败')
  }
}

const handleReset = () => {
  formRef.value.resetFields()
  categoryOptions.value = []
  subCategoryOptions.value = []
}
</script>

隐藏源码

debounce 防抖

debounce 控制 config 队列处理的防抖时间（ms），0 表示不防抖、立即处理

防抖时间

0ms（无防抖）300ms

关键词

config 调用次数

0

<template>
  <y-form
    :model="form"
    :config="handleFormChange"
    :debounce="debounceMs"
    label-width="120px"
    :span="12"
    :gutter="24">
    <y-form-item label="防抖时间">
      <el-radio-group v-model="debounceMs">
        <el-radio :value="0">0ms（无防抖）</el-radio>
        <el-radio :value="300">300ms</el-radio>
      </el-radio-group>
    </y-form-item>
    <y-form-item
      label="关键词"
      prop="keyword">
      <el-input
        v-model="form.keyword"
        placeholder="快速输入测试防抖" />
    </y-form-item>
    <y-form-item
      label="config 调用次数"
      :span="24">
      <span>{{ configCallCount }}</span>
      <el-button
        size="small"
        style="margin-left: 12px"
        @click="configCallCount = 0"
        >重置计数</el-button
      >
    </y-form-item>
  </y-form>
</template>

<script setup>
import { reactive, ref } from 'vue'

const form = reactive({ keyword: '' })
const debounceMs = ref(0)
const configCallCount = ref(0)

const handleFormChange = () => {
  configCallCount.value += 1
}
</script>

隐藏源码

API

Attributes

支持 el-form 的全部属性及 el-row 的布局属性，写在 y-form 上即可，内部分发给对应子组件。下表列出常用项；未列出的 el-form 属性同样支持透传。

属性名	说明	类型	默认值
config	表单数据变化时的回调，参数见FormConfigFn Properties	function	—
static-fields	静态字段，变化时不触发 config	object	[]
debounce	config 队列处理防抖时间（ms），0 表示不防抖	number	300
span	y-form-item 默认栅格占位	number	24
row-class	行容器 class	string	''
row-style	行容器 style	object	{}
model	表单数据对象，同 el-form	object	{}
rules	表单校验规则，同 el-form	object	{}
label-width	标签宽度，同 el-form	string / number	—
label-position	标签位置，同 el-form	enum	'right'
inline	行内表单模式，同 el-form	boolean	false
gutter	栅格间隔，同 el-row	number	0
justify	水平排列方式，同 el-row	enum	'start'
align	垂直排列方式，同 el-row	enum	—
tag	自定义元素标签，同 el-row	string	'div'

FormConfigFn Properties

参数	说明	类型
model	当前表单数据	object
context	变化上下文	object
context.field	变化的字段名	string
context.prevValue	变化前的值	any
context.newValue	变化后的值	any

Events

事件名	说明	类型
validate	任一表单项校验后触发	function

Exposes

名称	说明	类型
validateSync	校验整个表单，通过 resolve(model)，失败 reject	function
validate	校验整个表单，支持传入 callback 或返回 Promise，同 el-form	function
validateField	校验指定字段，同 el-form	function
resetFields	重置指定字段为初始值并移除校验结果，不传则重置全部，同 el-form	function
clearValidate	移除指定字段的校验结果，不传则移除全部，同 el-form	function
scrollToField	滚动到指定字段，同 el-form	function
getField	获取指定字段的上下文，同 el-form	function
fields	所有表单项字段的上下文，同 el-form	object
setInitialValues	设置表单字段初始值，resetFields 时将重置到此值，同 el-form	function

Slots

名称	说明
default	表单内容，放置 y-form-item