Elplus Enhance

Appearance

Form 表单 ​

表单支持数组和表单配置，示例中大部分使用了对象配置

基础用法(数组配置) ​

基础用法(对象配置) ​

内置组件 ​

组件的props ​

下面的例子展示如果给组件添加props，props: (formInstance => Props) | Props 可以是函数或者是对象,item: (formInstance => Props) | Props； 以下带选项的组件：select、radio、checkbox可以通过设置 dataItemProps 来设置某项的props

插槽 ​

可以通过定义type:"slot"来实现插槽，作用域上可以获取formExpose上所有API

组件的插槽 ​

可以通过定义slots来实现组件的插槽，目前支持input、number、select、cascader和扩展组件

扩展组件 ​

自定义表单组件，只需要组件上实现 v-model 双向绑定，即可与表单一起使用。下面是一个很简单的选择图标的扩展组件的例子，你必须全局注册或在表单全局配置中局部注册该组件；表单给组件传入了formExpose上所有API和绑定了FromComponentOption的props和event

v1.0.2后, 也可以传入VNode或者返回VNode的方法

自定义选择图标组件代码
vue
<template>
  <div>
    <el-radio-group v-model="model" @change="emits('change', $event)">
      <el-radio value="search">
        <el-icon>
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" data-v-6fbb019e="">
            <path
              fill="currentColor"
              d="m795.904 750.72 124.992 124.928a32 32 0 0 1-45.248 45.248L750.656 795.904a416 416 0 1 1 45.248-45.248zM480 832a352 352 0 1 0 0-704 352 352 0 0 0 0 704"
            ></path>
          </svg>
        </el-icon>
      </el-radio>
      <el-radio value="house">
        <el-icon>
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" data-v-6fbb019e="">
            <path
              fill="currentColor"
              d="M192 413.952V896h640V413.952L512 147.328zM139.52 374.4l352-293.312a32 32 0 0 1 40.96 0l352 293.312A32 32 0 0 1 896 398.976V928a32 32 0 0 1-32 32H160a32 32 0 0 1-32-32V398.976a32 32 0 0 1 11.52-24.576"
            ></path>
          </svg>
        </el-icon>
      </el-radio>
    </el-radio-group>
  </div>
</template>

<script lang="ts" setup>
defineOptions({
  name: 'IconSelect'
})

const model = defineModel({ type: String })
const emits = defineEmits(['change'])
</script>

组件前置或者后置内容 ​

可以使用prepend和append定义组件前置和后置内容，使用componentPrepend和componentAppend定义全部组件的前置和后置内容

带数据选项的组件 ​

组件数据 ​

异步数据 ​

对于select、radio、checkbox、cascader类型组件，可以通过asyncData配置组件的异步数据,asyncData要求是一个函数，并返回Promise；异步数据可自行解析，详情请看异步数据解析器

props和数据的联动性 ​

组件间的数据联动 ​

组件的显示与隐藏 ​

表单验证(复杂验证) ​

当表单验证规则需要用到表单数据时，可以传入一个函数，函数返回类型为FormRules

Form Attributes ​

名称说明类型默认值
formProps原生 el-form 的 props，透传给内部 ElFormPartial<ElFormProps>{}
options表单配置，支持对象和数组两种写法（见 FormOptions）FormOptions{}
rules表单校验规则；也可传函数，参数为 FormInstanceFormRules | ((formInstance: FormInstance) => FormRules){}
model表单初始值（会拷贝一份作为内部 formData）Record<string, any>{}
autoGetAsyncData是否在组件挂载后自动拉取 asyncData；当表单在 Dialog 内使用时不会自动触发booleantrue
componentPrepend所有表单项统一前置内容(formExpose: FormInstance) => VNodenull
componentAppend所有表单项统一后置内容(formExpose: FormInstance) => VNodenull
rowPropsel-row 的 propsPartial<RowProps>null
colPropsel-col 的默认 props（会与单项 colProps 合并）Partial<ColProps>{}

FormOptions ​

FormOptions 支持两种结构：

  • FormMapOptions：对象写法，key 由对象键名自动生成
  • FormListOptions：数组写法，每一项必须显式提供 key
ts
export type FormOptions = FormMapOptions | FormListOptions

FormMapOptions ​

ts
export type FormMapOptions = {
  [key: string]: FormMapOption
}

FormMapOption 可为：

  • string（等价于 { type: 'input', label: string }）
  • Omit<FormInputOption, 'key'>
  • Omit<FormNumberOption, 'key'>
  • Omit<FormSelectOption, 'key'>
  • Omit<FormRadioOption, 'key'>
  • Omit<FormCheckboxOption, 'key'>
  • Omit<FormSwitchOption, 'key'>
  • Omit<FormCascaderOption, 'key'>
  • Omit<FormDateOption, 'key'>
  • Omit<FormSlotOption, 'key'>
  • Omit<FormExtendOption, 'key'>

FormListOptions ​

ts
export type FormListOptions = Array<FormListOption>

FormListOption 为以下联合类型：

  • FormInputOption
  • FormNumberOption
  • FormSelectOption
  • FormRadioOption
  • FormCheckboxOption
  • FormSwitchOption
  • FormCascaderOption
  • FormDateOption
  • FormSlotOption
  • FormExtendOption

FormComponentOption ​

FormComponentOption 是大多数组件项共享的基础配置：

名称说明类型必填默认值
key字段标识（对象写法会自动注入）string是-
type组件类型string是-
labelel-form-item 标签文本string否key
props组件 props，支持对象或函数Partial<Record<string, any>> | ((formInstance: FormInstance) => Partial<Record<string, any>>)否{}
show是否显示该项boolean | ((formExpose: FormInstance) => boolean)否true
colProps当前项 el-col 配置Partial<ColProps>否{}
formItemProps当前项 el-form-item 配置Partial<FormItemProps>否{}
event组件事件映射(instance: FormInstance) => Record<string, Function>否{}
slots组件插槽映射(instance: FormInstance) => Record<string, VNode>否{}
prepend当前项前置内容(formExpose: FormInstance) => VNode | VNode否-
append当前项后置内容(formExpose: FormInstance) => VNode | VNode否-
warpCss组件包裹层样式（.elh-form-item__component-wrap）CSSProperties否{}
data选项数据（下拉/单选/多选/级联）Array<any> | Record<string, any>否[]
labelGetter选项标签解析器(item: any, index: string | number) => any否-
valueGetter选项值解析器(item: any, index: string | number) => any否-
asyncData异步选项数据函数(instance: FormInstance, ...args: any[]) => Promise<any>否-
dataItemProps选项项级 propsPartial<Record<string, any>> | ((formInstance: FormInstance, data: any, dataItem: any, index: string | number) => Partial<Record<string, any>>)否{}

WARNING

限制说明：

  • input / number 不支持：data、labelGetter、valueGetter、asyncData、dataItemProps
  • cascader 仅支持：data、asyncData，不支持：labelGetter、valueGetter、dataItemProps

FormRadioOption ​

名称说明类型必填默认值
button是否使用按钮样式单选boolean否false

FormCheckboxOption ​

名称说明类型必填默认值
button是否使用按钮样式多选boolean否false

FormExtendOption ​

名称说明类型必填默认值
component扩展组件定义string | VNode | ((formInstance: FormInstance) => VNode | null)是-

Form Expose ​

表单通过 defineExpose 暴露 FormInstance：

名称说明类型
formData当前表单数据（响应式）Record<string, any>
model传入的原始 modelRecord<string, any>
elForm内部 ElForm 实例引用MaybeRef<ElFormInstance>
componentData组件选项数据（来自 data / asyncData）Record<string, any>
getData触发表单校验并返回数据；校验失败时 reject(fields)<T = any>() => Promise<T>
setData合并设置表单数据（浅合并）(data: Record<string, any>) => void
resetData重置表单字段（调用 elForm.resetFields()）() => void
getAsyncData批量拉取异步选项数据；不传时拉取全部含 asyncData 的项(key?: string | string[]) => void
execAsyncDataFunc执行指定字段的 asyncData，支持透传参数(key: string, ...args: any[]) => void
clearComponentData清空指定字段的选项数据，并将对应 formData[key] 置为 undefined(key: string | string[]) => void

MIT Licensed.