中文 | English

要查看实时示例和文档，请访问文档。

安装项目

pnpm add element-plus-formkit@latest

使用

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import 'element-plus-formkit/dist/index.css'

const app = createApp(App);

app.mount('#app');

基本使用

在页面中使用 Formkit 组件

<template>
  <FormKit :config="config" v-model="FormData" />
</template>

<script setup lang="ts">
import { FormKit } from 'element-plus-formkit'

const FormData = reactive({})

const config = ref([
  {
    type: 'input',
    key: 'name',
    label: '姓名'
  },
  {
    type: 'select',
    key: 'class',
    label: '班级',
    options: []
  }
])
</script>

registerModule

Formkit 允许您注册自定义组件

import { registerModule } from 'element-plus-formkit';

import CustomEditor from './components/CustomEditor.vue'
registerModule('customEditor', CustomEditor)

// formkit item config
{
    type: 'customEditor', // Using custom modules
    key: 'content',
    label: 'Article'
}

setConfigure

Formkit 接受大量全局配置参数，如文件上传网络地址等。

// 设置全局配置（可在安装前或安装后设置）
import { setConfigure } from 'element-plus-formkit'
import type { UploadRequesterOptions } from 'element-plus-formkit/types/formkit-types'
import 'element-plus-formkit/dist/index.css'

setConfigure('upload', async (file: File, options: UploadRequesterOptions) => {
    const UploadFormData = new FormData()
    UploadFormData.append('file', file)
    const response = await useAxios().post("/default/oss/upload", UploadFormData, {
        headers: { 'Content-Type': 'multipart/form-data' },
        onUploadProgress: (progressEvent) => {
            const total = progressEvent.total || 1,
                loaded = progressEvent.loaded;
            options.onProgress?.({ total, loaded })
        }
    })
    return response
})

请注意，formkit 依赖于 elementplus 表单进行开发，您需要在系统中引入 elementplus。

Component Attributes

| 参数 | 说明 | 类型 | 默认值 | | -------- | :----- | :----: | :----: | | model-value / v-model | 组件绑定数据源 | Object | {} | config | 表单配置项，详细config配置参数参考下方config Attributes | Array | [] | disabled | 禁用整个表单 | Boolean | false
| labelPosition | 表单项label对齐规则，参照ElementPlus Form Attributes | String | top
| labelWidth | 表单项标题宽度（此参数仅在labelPosition为left、right时生效，为top时会自动忽略） | Number | 125 | columns | 每行显示多少列表单项 | Number / String | 5
| size | 用于控制该表单内组件的尺寸（可选值: '' / 'large' / 'default' / 'small'） | String | mini | rows | 参照ElementPlus Row API | String | top

注意： columns设置为字符串'auto'后label-width将失效，失效后的计算结果为0px

Config Attributes

| 参数 | 说明 | 可选值 | 类型 | 案例 | -------- | :-----: | :----: | :----: | :----: | | label | 表单项名称 | - | String | - | type | 该表单项类型 | 可自行配置，默认见下Config type explain | String | - | disabled | 该表单项是否禁用 | true / false | boolean | - | keys | 表单项key值(该项应该和后台返回该表单项的字段对应，方便将修改后的数据与后台直接交互) | - | String | - | span | 当前项栅格占据的列数 | 24 | number | 24 | labelWidth | 标签的长度，例如 '50px'。 作为 Form 直接子元素的 form-item 会继承该值。 可以使用 auto。 | - | string / number | '' | rules | 表单项校验规则，为空不校验 | - | Array | - | options | select、cascader等组件的操作项 | - | Array | options: [{ name: '全天营业', id: 'ALL' }] | requester | 该表单项需要进行远程数据加载的自定义请求 | - | Promise | requester: useAxios().get('/default/shop/category-tree') | handler | 配合远程数据加载，处理远程数据 | - | Function | handler: (response: any) => Array.isArray(response) ? response : [] | props | 直接绑定到组件上的参数 | - | Object | props: { placeholder: '请输入店铺编码', max: 10 } | visible | 该表单项显示需要关联的字段 | - | Object | visible: { key: "showid", value: 0 }表示表单内字段showid的值为0时该项不显示 | events | 接受组件事件 | - | Object | - | hint | 在当前行下方显示提示文本 | - | string | -

Config type explain

| 关键字 | 说明 | 备注 | -------- | :-----: | :----: | | input | 输入框 | - | select | 下拉选择框 | - | datePicker | 日期时间选择器 | 文档 | timePicker | 时间选择器 | 文档 | cascader | 级联选择器 | 文档 | remoteSearchSelect | 带远程搜索功能的input | 参数回显请使用initialValue字段 | address | 地址选择器 | 内部fetchAddressData方法需要修改API接口 | checkbox | 多选框 | - | radio | 单选框 | - | inputNumber | 数字输入框 | - | upload | 文件上传 | 需要在utils/upload.class.ts修改uploadUrl | rate | 评分 | 文档

FormKit Slots

| 插槽名 | 说明 | 参数 | -------- | :-----: | :-----: | | prepend | 输入框前置内容 | - | append | 表单项后置内容 | - | content | 表单平级内容 | configs => 配置项 | ${config.keys} | 表单项内容组件平级内容 | row => 当前config项、value => 组件绑定值

Exposes

| 名称 | 说明 | 参数 | 类型 | -------- | :-----: | :-----: | :-----: | | validate | 立即校验表单项 | openTips => 校验失败是否弹出提示 | Promise | clearValidate | 清除表单校验项 | - | Function