Form

ElForm 表单增强

提示

支持 element-plus 的 Form 表单组件，以及本组件库的组件。建议优先使用本组件库的组件

使用

当 fields 绑定的是一个具有响应式的数组时，数组的变动会影响表单变动（及动态表单）。如果不需要动态表单推荐绑定一个普通数组，

基础用法

支持动态 Rules，动态禁用，动态显示功能。支持字段名称多层级（name.value 最终会解析成 {name: {value: null}}）

内置 Label

提示

目前支持 n-input n-select n-date-picker 组件

分组使用

添加 group 属性进行分组

提示

只支持一级分组，不支持嵌套。并且在开启收起展开的时候，只会收起item组件，不会收起卡片和块组件。点下面的展开查看问题

网格

与使用 el-row 和 el-col 组件相同 (el-col 对应 field)，通过相关配置可以自由地组合布局。

Props

Name	Description	Type	Options	Default
v-model	绑定值	object	-	-
fields	表单项配置，参考下面 fields 属性	array	-	-
action	操作项按钮配置，参考下面 action属性	object	-	-
inner-label	是否使用内置 label 模式，element-plus 组件无效	boolean	-	false
enter-on-submit	输入框回车触发提交按钮点击事件，如果开启则自定义的 onKeyup事件无效	boolean		false
validate-on-submit	点击提交按钮的时候校验表单，拦截并提示校验不通过的内容	boolean		true
first-auto-focus	进入页面第一个输入框是否获取焦点，只有第一个元素是 input 的时候有效	boolean		true
show-more	是否显示更多，需要配合limit使用，如果需要记住状态需要配置 RouteName，我们会把 RouteName 做为保存在浏览器中的 key	boolean		false
limit	最多显示多少个field项，showMore=true的时候有效	number		4
highlight-error	表单验证不通过的时候输入框是否高亮	boolean	-	true
highlight-required	表单必填项输入框是否高亮	boolean	-	true
gutter	el-row 栅格间隔，如果定义了group属性默认一个group属性就是一个el-row标签	number	-	0
justify	el-row flex 布局下的水平排列方式，如果定义了group属性默认一个group属性就是一个el-row标签	string	start / end / center / space-around / space-between	start
align	el-rowflex 布局下的垂直排列方式，如果定义了group属性默认一个group属性就是一个el-row标签	string	top / middle / bottom	top
field-adaptive	表单项自适应栅格系统，开启后会自动添加{ md: 8, xl: 6, sm: 12, xs: 24 }属性	boolean	-	false
fixed-action	是否把表单的操作按钮固定在左边，查询表单的时候很有用	boolean	-	false
enter-next	回车是否跳转到下一个元素	boolean	-	true
scroll-to-error	校验不通过示范滚动当第一个错误项	boolean	-	true
field-map-to-time	用于将表单内时间区域的应设成 2 个字段,见下方说明	[string, [string, string], string?,boolean?][]	-	-
fiexd-error-message	是否固定验证失败消息在右下角	boolean	-	false
remote-field	是否远程加载 field，如果远程加载 field 需要设置为 true	boolean	-	false

支持 el-form 的所有属性

fieldMapToTime

代码片段来源 Vben Admin

将表单内时间区域的值映射成 2 个字段

如果表单内有时间区间组件，获取到的值是一个数组，但是往往我们传递到后台需要是 2 个字段

fieldMapToTime: [
  // data为时间组件在表单内的字段，startTime，endTime为转化后的开始时间于结束时间
  // 'YYYY-MM-DD'为时间格式，参考moment
  ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'],
  // 支持多个字段
  ['datetime1', ['startTime1', 'endTime1'], 'YYYY-MM-DD HH:mm:ss'],
  // 支持开始时间和结束时间，如果设置了第四个参数，那么第三个参数会默认为：YYYY-MM-DD HH:mm:ss
  ['datetime2', ['startTime2', 'endTime2'], 'YYYY-MM-DD', true],
],


// fieldMapToTime没写的时候表单获取到的值
{
  datetime: [Date(),Date()]
}
//  ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'],之后
{
    datetime: [Date(),Date()],
    startTime: '2020-08-12',
    endTime: '2020-08-15',
}

// ['datetime2', ['startTime2', 'endTime2'], 'YYYY-MM-DD', true]
{
    datetime2: [Date(),Date()],
    startTime2: "2022-06-15 00:00:00",
    endTime2: "2022-07-15 23:59:59"
}

fields Props

Name	Description	Type	Options	Default
prop	表单域 model 字段， 在使用 validate、resetFields 方法的情况下，该属性是必填的	string	-	-
label	标签	string	-	-
component	当前项对应的组件，可以直接传入局部组件，支持elment-plus Form 表单组件	string / Component	-	-
props	传递的对应的组件的参数	object	-	-
show	是否显示该item项	boolean		TRUE
if-show	动态控制是否显示item项。返回 true 渲染，false 不渲染	Function(modelValue):boolean	-	-
if-disabled	动态控制禁用状态	Function(modelValue):boolean	-	-
if-rules	动态校验规则，返回最新的rules数组	Function(modelValue,rules):Array[FormItemRule]	-	-
default-value	默认值	string / number / boolean / array / object	-	-
show-helper	是否显示提示图标，自定义头部插槽的时候无效	boolean	-	FALSE
helper-message	提示内容，show-helper为真的时候有效	string / string[]	-	-
extra-message	给Form item添加额外信息和帮助信息	string	-	-
group	分组，请参考group属性	object	-	-
span	栅格占据的列数。el-col的属性，每个 item 就是一个el-col	number	-	24
offset	栅格左侧的间隔格数。el-col的属性，每个 item 就是一个el-col	number	-	0
push	栅格向右移动格数。el-col的属性，每个 item 就是一个el-col	number	-	0
pull	栅格向左移动格数。el-col的属性，每个 item 就是一个el-col	number	-	0
xs	<768px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
sm	≥768px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
md	≥992px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
lg	≥1200px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
xl	≥1920px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
customClass	自定义ELFormItem样式	string	-	-

关于 Fields

支持 el-form-item 的所有属性

props 的属性将全部传递给 component 指定的组件

• 对于存在连字符的属性，可以通过字符串包裹或者转换为驼峰结构
• 通过 slots 可以向组件传递简单的渲染函数
• 对于事件需要通过 on[Event] 驼峰这种形式绑定。如：change -> onChange, input -> onInput

import { markRaw } from 'vue'
import { Search } from '@element-plus/icons-vue'
props: {
  clearable: true,
  'prefix-icon': markRaw(Search),
  suffixIcon: markRaw(Search),
  slots: {
    prefix: () => h('ElIcon', { icon: markRaw(Search) }),
    append: () => '搜索'
  },
  onChange: e => console.log(e),
}

group Props

Name	Description	Type	Options	Default
card	是否卡片模式，false 块状模式	boolean	-	false
title	标题	string	-	-
border	是否显示边框，只在卡片模式下生效	boolean	-	false
shawod	是否显示阴影，只在卡片模式下生效	boolean	-	false
className	样式类名	string	-	-
ifShow	动态显示组，不配置或者函数返回true的时候才显示	(modelValue: T) => boolean	-	-
children	分组下的fields属性	array	-	[]

分组不支持嵌套，可查看分组示例

action Props

该表单项栅格系统默认为：{ md: 8, xl: 6, sm: 12, xs: 24 }

Name	Description	Type	Options	Default
submit	是否显示 submit 按钮	boolean	-	true
submitText	submit 按钮显示的文字	string	-	提交
submitProps	submit 按钮的配置，参考 el-button	object	-
reset	是否显示 reset 按钮	boolean	-	true
resetText	是否显示 reset 按钮显示的文字	string	-	重置
resetProps	reset 按钮的配置，参考 el-button	object	-	-
align	对齐方式	string	left / right / center	-
span	栅格占据的列数。el-col的属性，每个 item 就是一个el-col	number	-	24
offset	栅格左侧的间隔格数。el-col的属性，每个 item 就是一个el-col	number	-	0
push	栅格向右移动格数。el-col的属性，每个 item 就是一个el-col	number	-	0
pull	栅格向左移动格数。el-col的属性，每个 item 就是一个el-col	number	-	0
xs	<768px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
sm	≥768px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
md	≥992px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
lg	≥1200px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-
xl	≥1920px 响应式栅格数或者栅格属性对象。el-col的属性，每个 item 就是一个el-col	number / object	-	-

Events

Name	Description	Parameters
submit	submit 被点击后触发，使用done()函数来关闭loading状态	done, isValid, invalidFields
reset	reset 按钮被点击后触发	-
nextDone	回车跳转到下一个元素开启后，最后一个元素回车后回调事件	-
validate	任一表单项被校验后触发	被校验的表单项 prop 值, isValid, invalidFields

Methods

Name	Description	Parameters
submitForm	手工调用提交表单事件	() => void
resetForm	清空表单所有数据，除非在 field 字段设置了默认值（defaultValue）	() => void
getDefaultValues	获取 field 设置了默认值（defaultValue）的数据	() => Record<string, unknown>
setErrors	设置表单错误信息	(fields: ValidateError[]) => void
resetEnterNextEvent	重置回车下一个元素下标。在你有动态 item 的时候可以使用它来重置回车顺序	() => void

提示

如果使用 typescript 可以从组件中导出 FormExpose 提供更好的类型推导。参考如下在 setup 中使用

<template>
  <n-form ref="ruleForm" v-model="form" :fields="fields" />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import type { FormExpose } from 'element-pro'

export default defineComponent({
  setup() {
    const ruleForm = ref<FormExpose>({} as FormExpose)

    function clearValidate() {
      ruleForm.value.clearValidate()
    }

    return { ruleForm, clearValidate }
  }
})
</script>

Slots

Name	Description
-	按钮节点之前的内容
form-before	字段开始之前的内容
form-after	按钮节点之后的内容
action-before	在重置按钮之前的内容
action-after	在提交按钮之后的内容，如果开启更多按钮则在更多按钮前面
[prop]	当前这项的 Form Item 的内容，参数为{ item, value, setValue }
[prop]-label	当前这项的标签文本的内容，参数为 { item }
[prop]-error	当前这项的自定义表单校验信息的显示方式，参数为 { error, item }

提示

[prop] 为 fields 中定义的 prop

TypeScript 定义

export declare function defineFormFields<T = any>(fileds: Array<FormField<T>>): Array<FormField<T>>
export declare function defineFormGropuFileds<T = ExternalParam>(
  fileds: FormGroup<T>[]
): FormGroup<T>[]
export declare function defineFormActions(action: FormAction): FormAction
export declare const defineFormMethod: () => Ref<FormExpose>

interface ValidateError {
  message: string
  field: string
}