Skip to content

Form 表单

注意

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

基础用法(默认通栏)

两列

混合

隐藏 label

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

异步(动态)数据用法

PlusColumn 配置中的 options 支持数组,computed,函数和 Promise。 PlusColumn 配置中的 fieldPropsformItemProps 支持对象 object,computed,函数和 Promise。

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

数据属性联动

PlusColumnfieldPropsformItemPropsoptionshideInForm等根据数据变化,动态显示设置。

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

表单多级数据的双向绑定

v0.1.7

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

分组表单

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

动态分组表单

v0.1.4

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

分组表单自定义头部

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

自定义表单底部按钮

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

表单单项插槽配置

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

  • valueTypeundefined(默认值)时,fieldSlots的插槽就是给 ElInput的。
  • valueTypeautocomplete时,fieldSlots的插槽就是给 ElAutocomplete的。
  • 其他以此类推(特殊的除外)

特殊的

  • valueTypecheckbox时,fieldSlots的插槽就是给 ElCheckboxGroup 的。
  • valueTyperadio时,fieldSlots的插槽就是给 ElRadioGroup 的。

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

注意

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

自定义表单项 (插槽)

注意

插槽 的优先级低于 renderField,高于 valueType

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

ts
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 方法需要返回一个 VNodeString

提示

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

自定义表单项 (jsx/tsx)

注意

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

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

ts
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 方法需要返回一个 VNodeString

自定义表单 label (jsx/tsx)

注意

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

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

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

自定义表单下一行的内容

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

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

v0.0.7

注意

  • 仅当PlusColumnvalueTypecheckbox | radio | select |plus-radio之一时生效。

  • PlusColumnvalueTypeselect时,不建议定义label【无法回显】

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

PlusColumn提供 fieldChildrenSlot 函数可整体自定义表单每一项的子项,PlusColumnoptions中提供 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[][]
rowPropsel-row 的 propsobjectRowProps
colPropsel-col 属性objectColProps
labelWidthel-form 的 labelWidthstring80px
labelPositionel-form 的 labelPositionstring left
labelSuffixel-form 的 labelSuffixstring:
hasErrorTip是否需要校验 message 提示booleantrue
hasFooter是否需要底部按钮booleantrue
footerAlign底部按钮对齐方式string left
hasReset是否需要底部按钮 重置booleantrue
hasLabel是否显示 label,值为falselabelWidth会被设置为0,labelSuffix 会被设置为''booleantrue
submitLoading确定按钮 loadingbooleanfalse
rules表单校验object FormRules{}
group分组表单配置false / (array PlusFormGroupRow[] )false
cardPropsv0.1.1分组表单 el-card 的 props,group存在时生效 ,优先级低于group配置的每一项的cardProps PlusFormGroupRowobject ElCardPropsfalse
submitText提交按钮文字string提交
resetText重置按钮文字string重置
...............

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

提示

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

Form Events

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

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

提示

如 el-form 的 validate,如下示例

示例:

模板中

html
<PlusForm @validate="handleValidate" />

setup 中

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

Form Slots

插槽名说明作用域插槽参数
default表单的内容 默认是 PlusFormItem 组件
footer表单底部按钮{handleReset,handleSubmit}
tooltip-iconv0.0.3tooltip icon
group-header分组表单头部,配置 group 字段时生效。{title,columns,icon}
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

名称说明类型
formInstanceel-form 实例object
handleReset表单默认的重置方法function
handleSubmit表单默认的提交方法,有校验的话,校验成功返回true,失败返回falsefunction

拿到 formInstance 后支持所有ElForm 方法

提示

validate,validateField