模块

组成formkit系统的各个表单组件，以下模块若不是您的预期，您也可以自定义模块registerModule

cascader 级联选择器

当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。

Template

<formkit
    :config="[
        {
            type: 'cascader',
            label: '级联选择器',
            key: 'cascaderValue',
            options: options,
            props: { placeholder: '请选择数据', clearable: true }
        }
    ]"
    v-model="dataset">
</formkit>

TypeScript

<script setup lang="ts">
import formkit from 'element-plus-formkit';
import { ref, computed } from 'vue';

const dataset = ref({})

const options = ref([
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          { value: 'consistency', label: 'Consistency' },
          { value: 'feedback', label: 'Feedback' },
          { value: 'efficiency', label: 'Efficiency' },
          { value: 'controllability', label: 'Controllability' }
        ]
      }
    ]
  }
])
</script>

提示

原生ElCascader API请写入props内

input 输入框

输入框

<formkit
    :config="[
        {
            type: 'input',
            label: '姓名',
            key: 'password',
            props: { placeholder: '请输入姓名', clearable: true }
        }
    ]"
    v-model="dataset">
</formkit>

提示

原生ELinput API请写入props内

inputTag 输入标签框

输入标签框，InputTag 允许用户添加内容作为标签

提示

原生ELinputTag API请写入props内

注意

inputTag组件需要您本地的element-plus版本为2.13.3或以上版本

<formkit
    :config="[
        {
            type: 'inputTag',
            label: '标签',
            key: 'inputTag',
            props: {
                placeholder: '请输入标签',
                clearable: true,
                'collapse-tags': true,
                'collapse-tags-tooltip': true,
                'max-collapse-tags': 2
            }
        }
    ]"
    v-model="dataset">
</formkit>

<p v-if="dataset.inputTag">output: {{ dataset.inputTag }}</p>

mention 提及

用于在输入中提及某人或某事。

Props特有属性

名称	类型	说明	默认
valueKey	String	作为 value 唯一标识的键名，绑定值为对象类型时必填	id
labelKey	String	指定选项标签为选项对象的某个属性值	name
disabled	Boolean	是否禁用	false

<formkit
    :config="[
        {
            type: 'mention',
            label: '提及',
            key: 'mention',
            props: { placeholder: '请输入', clearable: true, type: 'textarea', rows: 4 },
            hint: '输入@提及某人或某事',
            events: {
                'search': (event) => {
                    console.log('search event:', event);
                },
                'select': (event) => {
                    console.log('select event:', event);
                },
                'whole-remove': (event) => {
                    console.log('whole-remove event:', event);
                }
            },
            options: [
                { name: '选项一', id: 1 },
                { name: '选项二', id: 2 },
                { name: '选项三', id: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

<p v-if="dataset.mention">output: {{ dataset.mention }}</p>

mention也可通过requester字段用于动态获取options

<formkit
    :config="[
        {
            type: 'mention',
            label: '提及',
            key: 'mention1',
            props: { placeholder: '请输入', clearable: true },
            hint: '输入@提及某人或某事',
            requester: fetchOptions,
            handler: (response: any) => response?.items || []
        }
    ]"
    v-model="dataset">
</formkit>

提示

原生ElMention API请写入props内

switch 开关

表示两种相互对立的状态间的切换，多用于触发「开/关」。

<formkit
    :config="[
        {
            type: 'switch',
            label: '开关',
            key: 'switchValue',
            props: {
                inlinePrompt: true,
                activeText: '完整展示多个内容',
                inactiveText: '多个内容'
            }
        }
    ]"
    v-model="dataset">
</formkit>

提示

原生ElSwitch API请写入props内

select 选择器

select选择器, 当选项过多时，使用下拉菜单展示并选择内容。

Props特有属性

名称	类型	说明	默认
onChoose	Function	选择器选择项改变时触发的回调函数，参数为选择项的值、选择项的标签、所有选项	null

<formkit
    :config="[
        {
            type: 'select',
            label: '选择器',
            key: 'select1',
            props: { placeholder: '请选择', clearable: true },
            options: [
                { name: '选项一', id: 1 },
                { name: '选项二', id: 2 },
                { name: '选项三', id: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

Select也可通过requester字段用于动态获取options

Template

<el-button @click="changeRequester" type="primary" size="small" style="margin-bottom: 10px">
    切换Requester (当前: {{ currentRequester === fetchOptions ? '原始' : '新' }})
</el-button>

<formkit
    :config="selectConfig"
    v-model="dataset">
</formkit>

TypeScript

<script setup lang="ts">
import formkit from 'element-plus-formkit';
import { ref, computed } from 'vue';

const dataset = ref({})

function fetchOptions() {
    return new Promise((r, j) => {
        setTimeout(() => {
           r({
            code: 200,
            items: [
                { name: '选择项一', id: 1 },
                { name: '选择项二', id: 2 },
                { name: '选择项三', id: 3 }
            ]
           })
        }, 1000)
    })
}

function fetchOptionsNew() {
    return new Promise((r, j) => {
        setTimeout(() => {
           r({
            code: 200,
            items: [
                { name: '新选项 A', id: 'A' },
                { name: '新选项 B', id: 'B' }
            ]
           })
        }, 1000)
    })
}

const currentRequester = ref(fetchOptions)
const selectConfig = computed(() => [
    {
        type: 'select',
        label: '选择器',
        key: 'select1',
        props: { placeholder: '请选择', clearable: true },
        requester: currentRequester.value,
        handler: (response: any) => response?.items || []
    }
])

function changeRequester() {
    currentRequester.value = currentRequester.value === fetchOptions ? fetchOptionsNew : fetchOptions
}
</script>

handler作为额外的辅助字段，它会在requester完成后调用，用于将requester的返回值处理成ELselect option可执行的值，当然如果您的requester返回值符合ELselect option期望类型便不需要使用它。

checkbox 多选框

在一组备选项中进行多选。

此模块也可搭配requester动态获取数据项方法，远程获取数据动态替换options属性值，当然也可以传入handler作为数据处理函数

<formkit
    :config="[
        {
            type: 'checkbox',
            label: '多选框',
            key: 'checkbox',
            options: [
                { name: '选项一', id: 1 },
                { name: '选项二', id: 2 },
                { name: '选项三', id: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

showAllCheck属性用以表示 checkbox 的不确定状态，一般用于实现全选的效果

output:

<formkit
    :config="[
        {
            type: 'checkbox',
            label: '全选多选框',
            key: 'checkbox',
            props: { showAllCheck: true },
            options: [
                { name: '选项一', id: 1 },
                { name: '选项二', id: 2 },
                { name: '选项三', id: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

搭配requester动态获取数据项方法的checkbox模块

Template

<formkit
    :config="[
        {
            type: 'checkbox',
            label: '全选多选框',
            key: 'checkbox',
            props: { showAllCheck: true },
            requester: fetchOptions,
            handler: (response: any) => response?.items || []
        }
    ]"
    v-model="dataset">
</formkit>

TypeScript

<script setup lang="ts">
import formkit from 'element-plus-formkit';
import { ref, computed } from 'vue';

const dataset = ref({})

function fetchOptions() {
    return new Promise((r, j) => {
        setTimeout(() => {
           r({
            code: 200,
            items: [
                { name: '选择项一', id: 1 },
                { name: '选择项二', id: 2 },
                { name: '选择项三', id: 3 }
            ]
           })
        }, 1000)
    })
}
</script>

radio 单选框

在一组备选项中进行单选

此模块可搭配requester动态获取数据项方法，远程获取数据动态替换options属性值，当然也可以传入handler作为数据处理函数

radio模块主体使用了ELRadio，借助props我们可以将需要的参数传递给ELRadio Attributes的参数

Props特有属性

名称	类型	说明	默认
type	String	单选框形态，可选值：button（按钮radio）、default（常规radio）	default
valueKey	String	作为 value 唯一标识的键名，绑定值为对象类型时必填	id
labelKey	String	指定选项标签为选项对象的某个属性值	name

output:

<formkit
    :config="[
        {
            type: 'radio',
            label: '单选框',
            key: 'radio',
            options: [
                { name: '选项一', id: 1 },
                { name: '选项二', id: 2 },
                { name: '选项三', id: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

output: {{ dataset.radio }}

提示

当然当您的options需要通过动态获取时，您依旧可以使用requester配合handler辅助完成，详细参考select requester

inputNumber 数字输入框

数字输入框, 仅允许输入标准的数字值，可定义范围。详细api参数请参照ElInputNumber API

output:

<formkit
    :config="[
        {
            type: 'inputNumber',
            label: '步进输入',
            key: 'inputNumber',
            props: {
                min: 0,
                max: 10,
                style: { width: '100%' },
                prefix: '前缀',
                suffix: '后缀'
            }
        }
    ]"
    v-model="dataset">
</formkit>

output: {{ dataset.inputNumber }}

注意

当您需要使用ElInputNumber 原生API时，需要包裹props使用

address 地址选择器

具有层级的区域地址选择器, 使用此模块需要传入requester作为数据源，当然也可以传入handler作为数据处理函数

address模块主体使用了ELCascader，借助props我们可以将需要的参数传递给ELCascader Attributes的参数

Props特有属性

名称	类型	说明	默认
level	Number	地址选择器可选择的层级,注意level是从0开始，例如: 0=>省份选择、1=>省份、城市选择	1
cascaderProps	Object	address使用了ELCascader，cascaderProps参数为需要传递给ELCascader cascaderprops的参数	{}
valueKey	String	作为 value 唯一标识的键名，绑定值为对象类型时必填	id
labelKey	String	指定选项标签为选项对象的某个属性值	name

output:

<formkit
    :config="[
        {
            type: 'address',
            label: '地址选择器',
            key: 'address',
            requester: (pid: number) => {
                return fetchOptions()
            },
            handler: (response: any) => response?.items || [],
            props: {
                style: { width: '50%' },
                level: 2,
                placeholder: '请选择地址'
            }
        }
    ]"
    v-model="dataset">
</formkit>
output: {{ dataset.address }}

文字弹出层模块选择器

此模块可搭配requester动态获取数据项方法，远程获取数据动态替换options属性值，当然也可以传入handler作为数据处理函数

popover模块主体使用了ELPopover，借助props参数我们可以将需要的参数传递给ELPopover Attributes的参数

Props特有属性

名称	类型	说明	默认
props	Object	需要的参数传递给ELCascader cascaderpanel-api的参数	id
valueKey	String	作为 value 唯一标识的键名，绑定值为对象类型时必填	id
labelKey	String	指定选项标签为选项对象的某个属性值	name
loading	Boolean	是否正在从远程获取数据	false

<formkit
    :config="[
        {
            type: 'popover',
            label: '文字弹出层',
            key: 'popover',
            props: {
                placeholder: '请点击选择',
                props: { multiple: true }
            },
            options: [
                { name: '选项一', id: 1, children: [{ name: '选项一-1', id: 11 }] },
                { name: '选项二', id: 2 },
                { name: '选项三', id: 3 }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

提示

当然当您的options需要通过动态获取时，您依旧可以使用requester配合handler辅助完成，详细参考select requester

remoteSearchSelect 远程查询

具备远程查询功能的select下拉选择器, 使用此模块需要传入requester作为远程查询数据源，当然也可以传入handler作为数据处理函数

remoteSearchSelect模块主体使用了ELSelect，借助props我们可以将需要的参数传递给ELSelect Attributes的参数

Props特有属性

名称	类型	说明	默认
valueKey	String	作为 value 唯一标识的键名，绑定值为对象类型时必填	id
labelKey	String	指定选项标签为选项对象的某个属性值	name
initialValue	any	初始值；通常用作数据回显，当模块运行时会首先检测此值是否存在，若存在则将此值作为参数运行`props.requester`	-
onChoose	Function	选中项时的回调	null

输出 remoteSearchSelect:

输出 onChooseCallback:

Template

<formkit
    :config="[
        {
            type: 'remoteSearchSelect',
            label: '远程查询选择器',
            key: 'remoteSearchSelect',
            props: {
                labelKey: 'name',
                valueKey: 'id',
                initialValue: null,
                placeholder: '请输入查询内容',
                requester: (searchName: string) => fetchOptions(),
                handler: (response: any) => response?.items || [],
                onChoose: (item: any) => dataset.onChooseCallback = item
            }
        }
    ]"
    v-model="dataset">
</formkit>

Script

<script setup lang="ts">
import formkit from 'element-plus-formkit';
import { ref, computed } from 'vue';

const dataset = ref({})

function fetchOptions() {
    return new Promise((r, j) => {
        setTimeout(() => {
           r({
            code: 200,
            items: [
                { name: '选择项一', id: 1 },
                { name: '选择项二', id: 2 },
                { name: '选择项三', id: 3 }
            ]
           })
        }, 1000)
    })
}
</script>

通常对于数据进行远程加载的选择器对于默认数据处理通常难以控制，因为通常后端处理数据查询需要接受item.name但数据绑定通常为item.id，为此我们引入一个新的参数(initialValue)来进行控制, 当initialValue参数不为空时，我们会在组件完成加载后立即将initialValue作为形参调取您提供的requester

rate 评分

评分选择器，用于评分

<formkit
    :config="[
        {
            type: 'rate',
            label: '评分',
            key: 'rate',
            props: { 'allow-half': false, colors: ['#F7BA2A', '#F7BA2A', '#F7BA2A'], size: 'large' }
        }
    ]"
    v-model="dataset">
</formkit>

提示

原生ELRate API请写入props内

datePicker 日期选择器

用于选择或输入日期

输出：-

<formkit
    :config="[
        {
            type: 'datePicker',
            label: '日期选择器',
            key: 'datePickerValue',
            props: { valueFormat: 'YYYY-MM-DD', placeholder: '点击选择日期' }
        }
    ]"
    v-model="dataset">
</formkit>

<p>输出：{{ dataset.datePickerValue || "-" }}</p>

提示

原生ElDatePicker API请写入props内

timePicker 时间选择器

用于选择或输入日期

输出：-

<formkit
    :config="[
        {
            type: 'timePicker',
            label: '时间选择器',
            key: 'timePickerValue',
            props: { placeholder: '点击选择时间' }
        }
    ]"
    v-model="dataset">
</formkit>

<p>输出：{{ dataset.timePickerValue || "-" }}</p>

提示

原生ElTimePicker API请写入props内

timeSelect 时间选择

用于选择或输入日期

可用时间范围是 00:00-23:59

输出：-

<formkit
    :config="[
        {
            type: 'timeSelect',
            label: '时间选择',
            key: 'timeSelectValue',
            props: { placeholder: '点击时间选择', start: '08:30', end: '18:30' }
        }
    ]"
    v-model="dataset">
</formkit>

<p>输出：{{ dataset.timeSelectValue || "-" }}</p>

提示

原生ElTimeSelect API请写入props内

upload 上传器

通过点击上传文件。

Props特有属性

名称	类型	说明	默认
limit	Number	上传文件数量限制	1
autoUpload	Boolean	是否自动上传	true
isCustom	Boolean	是否自定义上传	false
beforeUpload	Function	上传前的回调函数，用于对上传文件进行预处理	null
afterUpload	Function	上传后的回调函数，用于对上传文件进行后续处理	null
accept	String	接受的文件类型，例如：'.jpg,.png', 若要统一某一类文件类型，例如图片，则可以写为'image/*'	-
width	Number	上传按钮的宽度	80
height	Number	上传按钮的高度	80
fileSize	Number	上传文件大小限制，单位为MB, 默认值0表示不限制	0

上传器的使用，需要配置setConfigure upload

template

<formkit
    :config="[
        {
            type: 'upload',
            label: '上传器',
            key: 'uploadValue',
            props: {
                limit: 4,
                width: 100,
                height: 80,
                afterUpload: (response) => {
                    return response.data
                }
            }
        }
    ]"
    v-model="dataset">
</formkit>

typescript

<script setup lang="ts">
import formkit, { setConfigure } from 'element-plus-formkit';
import type { UploadRequesterOptions } from 'element-plus-formkit/types/formkit-types'
import { ref, computed } from 'vue';

const dataset = ref({})

setConfigure('upload', async (file: File, options: UploadRequesterOptions) => {
    const url = URL.createObjectURL(file)
    return new Promise((r, j) => {
        setTimeout(() => {
           r({
                code: 200,
                data: url || "https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg"
           })
        }, 2000)
    })
})
</script>

slider 滑块

滑块选择器

通过拖动滑块在一个固定区间内进行选择

Output: -

<formkit
    :config="[
        {
            type: 'slider',
            label: '滑块选择器',
            key: 'sliderValue',
            props: {
                range: true,
                marks: {
                    0: '0°C',
                    8: '8°C',
                    37: '37°C',
                    50: {
                        style: {
                        color: '#1989FA',
                        },
                        label: '50%',
                    }
                }
            }
        }
    ]"
    v-model="dataset">
</formkit>

提示

原生ElSlider API请写入props内

treeSelect 树形选择

含有下拉菜单的树形选择器，结合了 el-tree 和 el-select 两个组件的功能。

Props特有属性

名称	类型	说明	默认
valueKey	String	作为 value 唯一标识的键名，绑定值为对象类型时必填	id
labelKey	String	指定选项标签为选项对象的某个属性值	name

Output: -

<formkit
    :config="[
        {
            type: 'treeSelect',
            label: '树形选择器',
            key: 'treeSelectValue',
            props: {
                'render-after-expand': false,
                style: { width: '240px' },
                labelKey: 'label',
                valueKey: 'value'
            },
            options: [
                {
                    value: '1',
                    label: 'Level one 1',
                    children: [
                        {
                            value: '1-1',
                            label: 'Level two 1-1',
                            children: [
                                {
                                    value: '1-1-1',
                                    label: 'Level three 1-1-1'
                                }
                            ]
                        }
                    ]
                },
                {
                    value: '2',
                    label: 'Level one 2',
                    children: [
                        {
                            value: '2-1',
                            label: 'Level two 2-1',
                            children: [
                                {
                                    value: '2-1-1',
                                    label: 'Level three 2-1-1'
                                }
                            ]
                        }
                    ]
                },
                {
                    value: '3',
                    label: 'Level one 3',
                    children: [
                        {
                            value: '3-1',
                            label: 'Level two 3-1',
                            children: [
                                {
                                    value: '3-1-1',
                                    label: 'Level three 3-1-1'
                                }
                            ]
                        },
                        {
                            value: '3-2',
                            label: 'Level two 3-2',
                            children: [
                                {
                                    value: '3-2-1',
                                    label: 'Level three 3-2-1'
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]"
    v-model="dataset">
</formkit>

<p>Output: {{ dataset.treeSelectValue || "-" }}</p>

treeSelect也可通过requester字段用于动态获取options

template

<formkit
    :config="[
        {
            type: 'treeSelect',
            label: '树形选择器',
            key: 'treeSelectValue',
            props: {
                labelKey: 'label',
                valueKey: 'value'
            },
            requester: fetchTreeSelectOptions,
            handler: (response: any) => response?.items || []
        }
    ]"
    v-model="dataset">
</formkit>

script

import formkit from 'element-plus-formkit';

const dataset = ref({})

function fetchTreeSelectOptions() {
    return new Promise((r, j) => {
        setTimeout(() => {
           r({
            code: 200,
            items: [
                {
                    value: '1',
                    label: 'Level one 1',
                    children: [
                        {
                            value: '1-1',
                            label: 'Level two 1-1',
                            children: [
                                {
                                    value: '1-1-1',
                                    label: 'Level three 1-1-1'
                                }
                            ]
                        }
                    ]
                },
                {
                    value: '2',
                    label: 'Level one 2',
                    children: [
                        {
                            value: '2-1',
                            label: 'Level two 2-1',
                            children: [
                                {
                                    value: '2-1-1',
                                    label: 'Level three 2-1-1'
                                }
                            ]
                        }
                    ]
                },
                {
                    value: '3',
                    label: 'Level one 3',
                    children: [
                        {
                            value: '3-1',
                            label: 'Level two 3-1',
                            children: [
                                {
                                    value: '3-1-1',
                                    label: 'Level three 3-1-1'
                                }
                            ]
                        },
                        {
                            value: '3-2',
                            label: 'Level two 3-2',
                            children: [
                                {
                                    value: '3-2-1',
                                    label: 'Level three 3-2-1'
                                }
                            ]
                        }
                    ]
                }
            ]
           })
        }, 1000)
    })
}

提示

原生ElTreeSelect API请写入props内