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数组
1. 外部异步函数获取到值赋值到 ref
1. columns配置项里用 computed返回 ref 的 value

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

数据属性联动

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

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

表单多级数据的双向绑定

v0.1.7

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

表单配置项 v-model 修饰符的使用

对于输入框想添加.trim，.number 和 .lazy 这些修饰符，可以配置 columns中 fieldProps的modelModifiers属性。

参考 Vue 官网 v-model 饰符的使用

分组表单

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

group 配置参考 PlusFormGroupRow

分组表单动态隐藏

v0.1.4

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

分组表单自定义头部

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

分组表单自定义每一步内容

v0.1.25

PlusFormGroupRow 新增value属性，PlusForm 组件会自动根据 group 配置项的 name 生成对应的插槽，例如下面的配置项，则会自动生成名称叫做 [ plus-group-one ]的个插槽，插槽的生成规则就是固定 key 值 [ plus-group- ] 然后加上group配置项的 name。

表单单项插槽配置

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

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

特殊的

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

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

注意

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

自定义表单底部按钮

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

自定义表单项 (插槽)

注意

插槽的优先级低于 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 中值使用单花括号{}绑定。

html

<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 中值使用单花括号{}绑定。

html

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

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

自定义表单下一行的内容

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

自定义表单上一行的内容

v0.1.25

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

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

v0.0.7

注意

仅当PlusColumn的valueType 为 checkbox | radio | select |plus-radio之一时生效。
当PlusColumn的valueType 为select时，不建议定义label【无法回显】
当 fieldSlot函数和fieldChildrenSlot函数同时出现的时候，fieldSlot函数的优先级更高。

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

v0.0.3

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

所有内置的表单类型

Form API

Form Attributes

名称	说明	类型	默认值	是否必须
`model-value / v-model`	表单绑定值（尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题）	`object` FieldValues		否
`defaultValues`	点击重置按钮时赋值给表单	`object` FieldValues	`{}`	否
`columns`	表单配置信息	`array`PlusColumn[]	`[]`	否
`rowProps`	el-row 的 props	`object`RowProps		否
`colProps`	el-col 属性	`object`ColProps		否
`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`	否
`cardProps`v0.1.1	分组表单 el-card 的 props，`group`存在时生效，优先级低于`group`配置的每一项的`cardProps` PlusFormGroupRow	`object` ElCardProps	`false`	否
`submitText`	提交按钮文字	`string`	`提交`	否
`resetText`	重置按钮文字	`string`	`重置`	否
`prevent`v0.1.13	阻止 el-form 的默认提交表单行为	`boolean`	`false`	否
`collapseTransition`v0.1.15	是否需要表单变化动画，在PlusSearch和PlusStepsForm 组件中效果明显	`boolean`	`true`	否
`collapseDuration`v0.1.15	表单变化动画持续时长(单位：ms)	`number`	`300`	否
`clearable`v0.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，如下示例

示例：

模板中

html

<PlusForm @validate="handleValidate" />

setup 中

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

Form Slots

插槽名	说明	作用域插槽参数
`default`	表单的内容默认是 `PlusFormItem` 组件
`footer`	表单底部按钮	`{handleReset,handleSubmit}`
`tooltip-icon`v0.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}`
`plus-previous-*` v0.1.25	自定义渲染el-form-item 上一行额外的内容，组件会自动根据配置项的 `prop` 生成对应的插槽	`{column}`
`plus-group-*` v0.1.25	分组表单自定义每一步内容，组件会自动根据分组表单`group`配置项的 `name` 生成对应的插槽	`{title,columns,icon,index,name}`

Exposes

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

拿到 formInstance 后支持所有ElForm 方法

提示

如 validate,validateField等

Form 表单 ​

基础用法(默认通栏) ​

两列 ​

混合 ​

隐藏 label ​

异步（动态）数据用法 ​

数据属性联动 ​

表单多级数据的双向绑定 ​

表单配置项 v-model 修饰符的使用 ​

分组表单 ​

分组表单动态隐藏 ​

分组表单自定义头部 ​

分组表单自定义每一步内容 ​

表单单项插槽配置 ​

自定义表单底部按钮 ​

自定义表单项 (插槽) ​

自定义表单项 (renderField) ​

自定义表单项 (jsx/tsx) ​

自定义表单 label (插槽) ​

自定义表单 label (renderLabel) ​

自定义表单 label (jsx/tsx) ​

自定义表单下一行的内容 ​

自定义表单上一行的内容 ​

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

自定义 tooltip icon ​

所有内置的表单类型 ​

Form API ​

Form Attributes ​

Form Events ​

Form Slots ​

Exposes ​

Form 表单

基础用法(默认通栏)

两列

混合

隐藏 label

异步（动态）数据用法

数据属性联动

表单多级数据的双向绑定

表单配置项 v-model 修饰符的使用

分组表单

分组表单动态隐藏

分组表单自定义头部

分组表单自定义每一步内容

表单单项插槽配置

自定义表单底部按钮

自定义表单项 (插槽)

自定义表单项 (renderField)

自定义表单项 (jsx/tsx)

自定义表单 label (插槽)

自定义表单 label (renderLabel)

自定义表单 label (jsx/tsx)

自定义表单下一行的内容

自定义表单上一行的内容

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

自定义 tooltip icon

所有内置的表单类型

Form API

Form Attributes

Form Events

Form Slots

Exposes