Form 表单

ElFormPro 的诞生是为了减少表单中的重复代码。并通过 schema 帮助我们快速地开发一个表单。

基础用法

通过 schema 快速生成表单

自定义插槽

通过 key、slot 和 fieldProps.slots 对应插槽名称

自定义 label 和 type

ElFormItem 的 label 和 type 支持 h 函数渲染。

Rules 校验

使用 rules 配置字段校验规则来验证用户的输入是否符合规范。

API

ElFormPro 在 Element Plus 的 Form 上进行了一层封装，支持了一些预设，并且封装了一些行为。这里只列出与 Element Plus Form 不同和部分原始的 API。

Props

属性	说明	类型	默认值
schema	表单配置	FormProSchemaItem[]	-
model	表单数据	Record<string, any>	-
formConfig	全局配置	FormProConfig	-

FormProConfig

属性	说明	类型	默认值
labelPosition	标签位置；支持字符串或响应式对象，对象配置见下方	string / object	{ base: 'top', md: 'right' }
buttonAlign	底部按钮区域水平对齐方式	string	'right'
buttons	提交、重置、取消按钮配置	FormProButtons	-
row	分栏间隔	object	{ gutter: 18 }
col	栅格列配置	number / FormProColProps	24
actionCol	操作按钮栅格列配置	number / FormProColProps	-

labelPosition 对象配置

labelPosition 传入对象时，可按断点配置标签位置；未命中的断点会沿用前一个有效值，base 作为基础回退值。

属性	说明	类型
base	基础标签位置，所有断点未配置时使用	string
xs	视口宽度 < 768px 时使用	string
sm	视口宽度 ≥ 768px 时使用	string
md	视口宽度 ≥ 992px 时使用	string
lg	视口宽度 ≥ 1200px 时使用	string
xl	视口宽度 ≥ 1920px 时使用	string

更多属性请参考 Element Plus Form API

FormProSchemaItem

属性	说明	类型	默认值
key	字段名，唯一性；组合字段容器可省略	string	-
label	标签文本	string / Function	-
type	字段组件类型；tree 需 Element Plus 2.1.8+，mention 需 Element Plus 2.8.0+，inputTag 需 Element Plus 2.9.0+	enum / Component	input
formItemProps	透传给 ElFormItem 的属性	object	-
fieldProps	透传给 type 组件的属性	object	-
defaultValue	字段初始值	any	-
col	栅格列配置	number / FormProColProps	24
rules	校验规则	FormItemRule[]	-
hidden	是否隐藏	boolean	false
slot	自定义插槽	string	-
children	子字段配置，用于组合字段	FormProSchemaItem[]	-
separator	子字段之间显示的分隔符	string	''

更多属性请参考 Element Plus FormItem API

布局配置

通过 formConfig 设置表单与栅格布局：

const formConfig: FormProConfig = {
  labelPosition: 'right',
  labelWidth: 90,
  buttonAlign: 'right',
  row: { gutter: 18 },
  col: 8,
  actionCol: 12,
  buttons: {
    submit: {
      text: '查询',
      type: 'primary',
    },
    reset: {
      text: '重置',
    },
  },
}

col、actionCol 和 schema 项的 col 都支持数字简写；需要偏移或响应式配置时仍使用对象形式：

const formConfig: FormProConfig = {
  col: 12,
  actionCol: { span: 6, offset: 18 },
}

const schema = [
  { key: 'name', label: '名称', col: { span: 8, md: 6 } },
]

更多格栅布局配置请参考 Element Plus Layout

按钮配置

buttons 用来配置表单底部的提交、重置和取消按钮。默认显示“提交”和“重置”

const formConfig: FormProConfig = {
  buttons: {
    submit: { text: '搜索', type: 'primary' },
    reset: { text: '清空' },
    cancel: { text: '返回' },
  },
}

隐藏按钮时传 false

const formConfig: FormProConfig = {
  buttons: {
    submit: false,
    reset: false,
  },
}

需要完全自定义按钮区域时，使用 buttons 插槽

<template>
  <ElFormPro :schema="schema">
    <template #buttons>
      <ElButton @click="save">保存</ElButton>
      <ElButton @click="close">关闭</ElButton>
    </template>
  </ElFormPro>
</template>

更多按钮 API 配置请参考 Element Plus Button

Form Exposes

方法名	说明	类型
validate	校验整个表单	Function
validateField	校验指定字段	Function
resetFields	重置字段与校验状态	Function
clearValidate	清除校验结果	Function
scrollToError	滚动到首个错误字段	Function
getValues	获取当前表单值	Function
setState	更新表单配置	Function