@joooooooooojo/kform

📦 安装

npm install @joooooooooojo/kform
# or
yarn add @joooooooooojo/kform
# or
pnpm add @joooooooooojo/kform

说明

KForm是一个配置优先的表单组件，它是基于Vue3，ElementPlus的el-form组件进行封装的，所以在使用KForm之前，请详细阅读ElementPlus的表单组件文档。

全局注册（src/main.ts）

import { createApp } from "vue";
import App from "./App.vue";
import KForm from "@joooooooooojo/kform";
import "@joooooooooojo/kform/dist/style.css";
const app = createApp(App);

// 组件依赖于ElementPlus，所以需要先安装ElementPlus
// import ElementPlus from 'element-plus'
// app.use(ElementPlus)

app.use(KForm);
app.mount("#app");

类型声明（src/components.d.ts）

如果您在使用volar，那么可以在tsconfig.json中添加以下配置

{
  "compilerOptions": {
    // ...
    "types": ["@joooooooooojo/kform/global"]
  }
}

如果您在使用webstorm，那么可以在main.ts同层级下的声明文件中添加以下配置

import KForm  from '@joooooooooojo/kform'
declare module "@vue/runtime-core" {
  export interface GlobalComponents {
    KForm:  typeof KForm
  }
}

使用示例

import {ref} from "vue";
import {InputPropsPayload, ISelectPropsPayload, KFormItemProps} from "@joooooooooojo/kform";

const form = ref({
  username: '',
  password: '',
  gender: 0
})
const options:Array<KFormItemProps> = [
  {
    type: 'input',
    label: '用户名',
    prop: 'username',
    payload:{
      placeholder: '请输入用户名',
    } as InputPropsPayload
  },
  {
    type: 'input',
    label: '密码',
    prop: 'password',
    payload:{
      placeholder: '请输入密码',
      type: 'password'
    } as InputPropsPayload
  },
  {
    type: 'select',
    label: '性别',
    prop: 'gender',
    payload:{
      options() {
          return [
          {label: '男', value: 0},
          {label: '女', value: 1}
        ]
      },
      clearable:true,
      multiple:true,
      onChange(value) {
        console.log(value)
      },
    } as ISelectPropsPayload
  },
  {
    type: 'custom',
    slotName: 'avatar',
  }
]


<template>
  <KForm v-model="form" width="600px" :options="options" :label-width="120" label-position="top">
    <template v-slot:avatar>
      <img src="https://avatars.githubusercontent.com/u/20628032?v=4" alt="avatar" />
    </template>
  </KForm>
</template>

动态表单使用示例

const root = (): KDynamicFormItemProps => {
  return {
    rowKey: "row-1",
    parent: null,
    label: "客户名称",
    prop: "name",
    next: clientType
  };
};
const clientType = (formValue?: T): KDynamicFormItemProps => {
  return {
    rowKey: "row-1",
    parent: root,
    label: "客户类型",
    prop: "type",
    type: "select",
    payload: {
      options: [
        {
          label: "企业",
          value: 0
        },
        {
          label: "个人",
          value: 1
        }
      ]
    } as ISelectPropsPayload,
    next: formValue.type === 0 ? code : null
  };
};

const code = (): KDynamicFormItemProps => {
  return {
    rowKey: "row-2",
    childrenNum: 2,
    parent: clientType,
    label: "企业信用代码",
    prop: "code",
    next: null
  };
};

<KForm v-model="baseForm" :dynamic-options="root"></KForm>

表单类型

Property	Type	Description
width	string	表单宽度 默认100%
options	Array<KFormItemProps>	表单项配置
dynamicOptions	() => Arrayable<KDynamicFormItemProps>	动态表单配置项
modelValue	Record<string, any>	表单数据模型
rules	FormRules	表单校验规则
labelPosition	KLabelPosition	表单标签位置
labelWidth	string or number	标签的长度，例如 '50px',传入number类型默认为px单位。 作为 Form 直接子元素的 form-item 会继承该值。 可以使用 auto。
labelSuffix	string	表单域标签的后缀
hideRequiredAsterisk	boolean	是否显示必填字段的标签旁边的红色星号
requiredAsteriskPosition	KRequiredAsteriskPosition	星号的位置
inlineMessage	boolean	是否以行内形式展示校验信息
statusIcon	boolean	是否在输入框中显示校验结果反馈图标
validateOnRuleChange	boolean	是否在 rules 属性改变后立即触发一次验证
size	KFormItemSize	用于控制该表单内组件的尺寸
disabled	boolean	是否禁用该表单内的所有组件
scrollToError	boolean	当校验失败时，是否滚动到第一个错误表单项
scrollIntoViewOptions	object or boolean	当校验有失败结果时，滚动到第一个失败的表单项目 可通过 scrollIntoView 配置
onValidate	() => void	表单校验触发时调用

表单项属性

Property	Type	Description
prop	string	和element原 prop不同只允许填写字符串，同时充当键名和校验的prop
label	string	文本标签
width	string | number	表单项宽度
labelWidth	string | number	标签宽度
required	boolean	是否必填
rules	Arrayable<FormItemRule>	表单项校验规则 如果您不想根据输入事件触发验证器，在相应的输入类型组件上设置validate-event属性为 false
error	string	表单域验证错误时的提示信息。设置该值会导致表单验证状态变为 error，并显示该错误信息
showMessage	boolean	是否展示错误提示
inlineMessage	boolean	是否在行内显示校验信息
size	string	表单项下组件尺寸
for	string	与原生for作用相同
validateState	string	表单项的校验状态
children	Array<KFormItemProps<T>>	子表单项。一维表单纵向排列，设置children后表单为二维，渲染到此处时将children中的表单项时横向排列
childrenNum	number	指定每行表单项数量(如果不传则按照children的长度设置列数)
rowKey	string	子表单项Key值，设置children时需要设置
type	KFormItemPropsType	表单项类型
tooltip	string	tooltip提示，不传则不提示
show	boolean | ((formValue: T) => boolean)	是否展示 默认展示，传入函数时formValue为表单数据
payload	any	载荷，不同表单项类型有不同载荷，使用时手动指定特定类型
slotName	string	插槽