Form 表单

注意

表单v-model绑定的值尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题。 参考 reactive 的局限性

基础用法(默认通栏)

两列

混合

隐藏 label

表单整体的hasLabel 设置为 false 时, 隐藏 label。配置columns中的 hasLabel可以控制单个表单项的 label 是否显示， 优先级会更高。

异步（动态）数据用法

PlusColumn 配置中的 options 支持数组，computed 推荐，函数和 Promise。 PlusColumn 配置中的 fieldProps和formItemProps 支持对象 object，computed，函数和 Promise。

常见的使用场景是数据来自后端接口，这里调用后端接口，options 返回 OptionsRow[]数组即可。

提示

options 建议优先使用 computed，可防止用函数在columns配置项数据变更后函数重复执行的问题。

使用步骤为：

• 1. columns配置项外面定义一个 ref数组
• 2. 外部异步函数获取到值赋值到 ref
• 3. columns配置项里用 computed返回 ref 的 value

参考下面推荐写法代码示例。

数据属性联动

PlusColumn的fieldProps，formItemProps，options，hideInForm等根据数据变化，动态显示设置。

如下示例，点击状态选择框，当状态为已解决 时，要求1 多选框会变成 1 个可选， 名称 1，2 输入框会被禁用，标签 1 输入框会被隐藏，标签 2 输入框会变成必填。

表单多级数据的双向绑定

v0.1.7

columns中的 prop支持 x.y.z形式的 多（无限）级数据形式。

分组表单

配置 group 字段，则显示分组。配置 group 字段后，columns 则不在生效。

group 配置参考 PlusFormGroupRow

动态分组表单

v0.1.4

配置 PlusFormGroupRow[hideInGroup] 字段为true，隐藏当前分组，支持计算属性。

分组表单自定义头部

添加 group-header 插槽即可实现。

自定义表单底部按钮

组件提供 footer 插槽可以自定义表单底部，并提供默认的 提交方法、重置方法 的作用域插槽参数 {handleSubmit,handleReset}。

表单单项插槽配置

组件提供 fieldSlots 对象可以简易配置表单单项插槽， fieldSlots 的插槽配置是根据表单的 valueType 自动进行匹配的， 如：

• valueType 是 undefined(默认值)时，fieldSlots的插槽就是给 ElInput的。
• valueType 是 autocomplete时，fieldSlots的插槽就是给 ElAutocomplete的。
• 其他以此类推（特殊的除外）

特殊的

• valueType 是 checkbox时，fieldSlots的插槽就是给 ElCheckboxGroup 的。
• valueType 是 radio时，fieldSlots的插槽就是给 ElRadioGroup 的。

要实现更强大的自定义，请使用自定义表单项。

注意

valueType 的值对应的组件本身没有插槽时，fieldSlots不生效。

自定义表单项 (插槽)

注意

插槽 的优先级低于 renderField，高于 valueType。

PlusForm 组件会自动根据配置项的 prop 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 [ plus-field-name ]和 [ plus-field-status] 的两个插槽，插槽的生成规则就是 固定 key 值 [ plus-field- ] 然后加上 配置项的 prop。

import { PlusColumn } from 'plus-pro-components'

const tableConfig: PlusColumn[] = [
  {
    label: '名称',
    // 自动生成对应的插槽 'plus-field-name'
    prop: 'name'
  },
  {
    label: '状态',
    // 自动生成对应的插槽 'plus-field-status'
    prop: 'status'
  }
]

自定义表单项 (renderField)

注意

renderField 的优先级高于插槽。

自定义表单项的核心方法是定义 renderField方法， renderField 方法需要返回一个 VNode 或 String

提示

renderField 返回的值的props 和配置项的fieldProps会同时生效，renderField 返回的值的props优先级高于 fieldProps.

自定义表单项 (jsx/tsx)

注意

jsx/tsx 的使用需要将 vue 单文件组件的script的属性 lang设置为jsx或者tsx，jsx 中值使用单花括号{}绑定。

<script lang="tsx" setup></script>

jsx/tsx 的支持本质是jsx/tsx解析出来是VNode, 使用 renderField 函数自定义表单项。

自定义表单 label (插槽)

注意

插槽 的优先级低于 renderLabel，高于 label。

PlusForm 组件会自动根据配置项的 prop 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 [ plus-label-name ]和 [ plus-label-status] 的两个插槽，插槽的生成规则就是 固定 key 值 [ plus-label- ] 然后加上 配置项的 prop。

import { PlusColumn } from 'plus-pro-components'

const tableConfig: PlusColumn[] = [
  {
    label: '名称',
    // 自动生成对应的插槽 'plus-label-name'
    prop: 'name'
  },
  {
    label: '状态',
    // 自动生成对应的插槽 'plus-label-status'
    prop: 'status'
  }
]

自定义表单 label (renderLabel)

注意

renderLabel 的优先级高于插槽。

自定义表单项的核心方法是定义 renderLabel方法， renderLabel 方法需要返回一个 VNode 或 String

自定义表单 label (jsx/tsx)

注意

jsx/tsx 的使用需要将 vue 单文件组件的script的属性 lang设置为jsx或者tsx，jsx 中值使用单花括号{}绑定。

<script lang="tsx" setup></script>

jsx/tsx 的支持本质是jsx/tsx解析出来是VNode, 使用 renderField 函数自定义表单项。

自定义表单下一行的内容

支持 renderExtra 渲染函数，支持 jsx/tsx，支持插槽，插槽的生成规则就是 固定 key 值 [ plus-extra- ] 然后加上 配置项的 prop。

自定义表单每一项子项的内容

v0.0.7

注意

• 仅当PlusColumn的valueType 为 checkbox | radio | select |plus-radio之一时生效。

• 当PlusColumn的valueType 为select时，不建议定义label【无法回显】

• 当 fieldSlot函数 和fieldChildrenSlot函数同时出现的时候，fieldSlot函数的优先级更高。

PlusColumn提供 fieldChildrenSlot 函数可整体自定义表单每一项的子项，PlusColumn的options中提供 fieldSlot 函数可单独自定义表单每一项子项的内容。

自定义 tooltip icon

v0.0.3

使用tooltip-icon插槽 可自定义 tooltip icon。

所有内置的表单类型

Form API

Form Attributes

名称	说明	类型	默认值	是否必须
model-value / v-model	表单绑定值 （尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题）	object FieldValues		否
defaultValues	点击重置按钮时 赋值给表单	object FieldValues	{}	否
columns	表单配置信息	arrayPlusColumn[]	[]	否
rowProps	el-row 的 props	objectRowProps		否
colProps	el-col 属性	objectColProps		否
labelWidth	el-form 的 labelWidth	string	80px	否
labelPosition	el-form 的 labelPosition	string	left	否
labelSuffix	el-form 的 labelSuffix	string	:	否
hasErrorTip	是否需要校验 message 提示	boolean	true	否
hasFooter	是否需要底部按钮	boolean	true	否
footerAlign	底部按钮对齐方式	string	left	否
hasReset	是否需要底部按钮 重置	boolean	true	否
hasLabel	是否显示 label，值为false时labelWidth会被设置为0，labelSuffix 会被设置为''	boolean	true	否
submitLoading	确定按钮 loading	boolean	false	否
rules	表单校验	object FormRules	{}	否
group	分组表单配置	false / (array PlusFormGroupRow[] )	false	否
cardPropsv0.1.1	分组表单 el-card 的 props，group存在时生效 ，优先级低于group配置的每一项的cardProps PlusFormGroupRow	object ElCardProps	false	否
submitText	提交按钮文字	string	提交	否
resetText	重置按钮文字	string	重置	否
preventv0.1.13	阻止 el-form 的默认提交表单行为	boolean	false	否
collapseTransitionv0.1.15	是否需要表单变化动画，在PlusSearch和PlusStepsForm 组件中效果明显	boolean	true	否
collapseTransitionv0.1.15	表单变化动画持续时长(单位：ms)	number	300	否
clearablev0.1.18	表单内所有表单项的是否可清除，会显示清除图标，优先级低于配置项的 PlusColumn[fieldProps]里的clearable	boolean	true	否
...	...	...	...	...

...表示同时支持所有ElForm Attributes

提示

ElForm 的 model 参数已在组件内部处理，一般不需要传。

Form Events

名称	说明	类型
submit	点击提交按钮校验通过触发的事件	function
change	表单变化触发的事件	function
reset	点击重置按钮触发的事件	function
submitError	点击提交按钮校验不通过触发的事件	function
...	...	...

...表示同时支持所有ElForm Events

提示

如 el-form 的 validate，如下示例

示例：

模板中

<PlusForm @validate="handleValidate" />

setup 中

const handleValidate = (prop: FormItemProp, isValid: boolean, message: string) => {
  console.log(dropdownItem)
}

Form Slots

插槽名	说明	作用域插槽参数
default	表单的内容 默认是 PlusFormItem 组件
footer	表单底部按钮	{handleReset,handleSubmit}
tooltip-iconv0.0.3	tooltip icon
group-header	分组表单头部，配置 group 字段时生效。	{title,columns,icon,index} v0.1.17 新增index
plus-field-*	自定义表单项，组件会自动根据配置项的 prop 生成对应的插槽	{prop,label,fieldProps,valueType,column}
plus-label-*	自定义表单项 label，组件会自动根据配置项的 prop 生成对应的插槽	{prop,label,fieldProps,valueType,column}
plus-extra-*	自定义渲染 el-form-item 下一行额外的内容，组件会自动根据配置项的 prop 生成对应的插槽	{column}

Exposes

名称	说明	类型
formInstance	el-form 实例	object
handleReset	表单默认的重置方法，同时会清空校验	function
handleSubmit	表单默认的提交方法，有校验的话，校验成功返回true，失败返回false	function

拿到 formInstance 后支持所有ElForm 方法

提示

如 validate,validateField等