Form 表单组件

element-plusForm 组件进行封装,支持 element-plus 的所有表单组件,并额外扩展了一些功能。

Form 组件位于 src/components/Form

注意

推荐使用 tsx 来使用 Form 组件。

用法

目前支持的表单组件,你可以在 在线预览 中看到。

基础用法

<script setup lang="ts">
import { Form, FormSchema } from '@/components/Form'
import { reactive } from 'vue'

const schema = reactive<FormSchema[]>([
  {
    field: 'field1',
    label: 'input',
    component: 'Input'
  }
])
</script>

<template>
  <Form :schema="schema" />
</template>

useForm

对于复杂的场景,可以配合 useForm 来使用。

如果想看更复杂点的例子,请在线预览

<script setup lang="tsx">
import { Form, FormSchema } from '@/components/Form'
import { reactive } from 'vue'
import { useForm } from '@/hooks/web/useForm'

const schema = reactive<FormSchema[]>([
  {
    field: 'field1',
    label: 'input',
    component: 'Input'
  }
])

const { formRegister } = useForm()
</script>

<template>
  <Form :schema="schema" @register="formRegister" />
</template>

参数介绍

const { formRegister, formMethods } = useForm()

register

formRegister 用于注册 useForm,如果需要使用 useForm 提供的 api,必须将 formRegister 传入组件的 onRegister

formMethods

方法名说明回调参数
setValues用于设置表单值(data: Recordable) => void
setProps用于设置表单属性(props: Recordable) => void
delSchema用于删除表单结构(field: string) => void
addSchema用于新增表单结构(formSchema: FormSchema, index?: number) => void
setSchema用于编辑表单结构(schemaProps: FormSetPropsType[]) => void
getFormData用于获取表单数据<T = Recordable>() => Promise<T>
getComponentExpose用于获取表单组件实例,如 ElInput 实例(field: string) => any
getFormItemExpose用于获取 formItem 组件实例(field: string) => Promise<ComponentRef<typeof ElFormItem>>
getElFormExpose用于获取 elForm 组件实例(field: string) => Promise<ComponentRef<typeof ElForm>>
getFormExpose用于获取二次封装的 Form 组件实例() => Promise<ComponentRef<typeof Form>>

Form 属性

除以下参数外,还支持 element-plusForm 所有属性,详见

属性说明类型可选值默认值
schema生成 Form 的布局结构数组,详见FormSchema-[]
isCol是否需要栅格布局boolean-true
model表单数据对象Recordable-{}
autoSetPlaceholder是否自动设置 placeholderboolean-true
isCustom是否自定义内容boolean-false
labelWidth表单 label 宽度string/number-auto

Schema

属性说明类型可选值默认值
field唯一值,必填项string--
label标题string--
colPropselement-plus 的 col 组件属性ColProps--
componentProps表单组件子属性,详见any--
formItemPropselement-plus 的 form-item 组件属性,详见FormItemProps--
component需要渲染的表单子组件ComponentName--
value表单子组件初始值any--
hidden表单子组件是否隐藏boolean--
remove表单子组件是否隐藏,如果为true,会连同值一同删除,类似v-ifboolean--
optionApi加载 options 方法() => Promise<any>--

ComponentProps

componentProps的类型有: InputComponentProps AutocompleteComponentProps InputNumberComponentProps SelectComponentProps SelectV2ComponentProps CascaderComponentProps SwitchComponentProps RateComponentProps ColorPickerComponentProps TransferComponentProps RadioGroupComponentProps RadioButtonComponentProps DividerComponentProps DatePickerComponentProps DateTimePickerComponentProps TimePickerComponentProps InputPasswordComponentProps TreeSelectComponentProps UploadComponentProps any

基本上每个表单组件都有 slots 的插槽对象,用于自定义插槽,如 InputComponentProps :

slots?: {
  prefix?: (...args: any[]) => JSX.Element | null
  suffix?: (...args: any[]) => JSX.Element | null
  prepend?: (...args: any[]) => JSX.Element | null
  append?: (...args: any[]) => JSX.Element | null
}

如果需要监听组件事件,如 change 事件,每个 ComponentProps 基本上都有 on 对象用来接收事件,如 InputComponentProps :

on?: {
  blur?: (event: FocusEvent) => void
  focus?: (event: FocusEvent) => void
  change?: (value: string | number) => void
  clear?: () => void
  input?: (value: string | number) => void
}

FormItemProps

除了以下属性,还支持 element-plus 中的 FormItem 的所有属性

属性说明类型可选值默认值
slotsFormItem的插槽Object--
style子表单项的样式CSSProperties--

Form 方法

方法名说明回调参数
setValues用于设置表单值(data: Recordable) => void
setProps用于设置表单属性(props: Recordable) => void
delSchema用于删除表单结构(field: string) => void
addSchema用于新增表单结构(formSchema: FormSchema, index?: number) => void
setSchema用于编辑表单结构(schemaProps: FormSetPropsType[]) => void
getComponentExpose用于获取表单子组件的实例,如 ElInput 实例(field: string) => any
getFormItemExpose用于获取 FormItem 组件的实例() => Promise<typeof FormItem>

如何新增表单子组件

当项目中内置的表单组件不满足需求时,可以自行添加组件进去。

  1. src/components/Form/src/types/index.tsComponentName 添加你组件名称。
  2. src/components/Form/src/helper/componentMap.ts 引入你自己的组件,并在 componentMap 对象中添加键值对即可。
  3. 如果想要更好的类型提示,可以把自定义组件的类型也添加到 componentProps