schema-form

基于 Vue3 + Element Plus 的配置驱动表单组件，支持 JSX 语法和动态表单生成。

特性

• 📦 配置驱动 - 通过 Schema 配置即可生成复杂表单
• 🎯 类型安全 - 完整的 TypeScript 类型支持
• 🔌 完全解耦 - 不内置 Element Plus，用户自行引入
• 🎨 JSX 支持 - 支持在 JSX 中使用，提供 useForm Hook
• ⚡ 动态更新 - 支持运行时动态更新表单配置
• 🔄 双向绑定 - 支持 v-model 双向绑定

安装

npm install zhouyuejin1995/schema-form
# 或
pnpm add zhouyuejin1995/schema-form
# 或
yarn add zhouyuejin1995/schema-form

前提依赖

本组件依赖 Vue3 和 Element Plus，请确保已安装：

npm install vue@^3.2 element-plus @element-plus/icons-vue

快速开始

模板语法

<template>
  <SchemaForm
    :schemas="schemas"
    @submit="handleSubmit"
    @reset="handleReset"
  />
</template>

<script setup>
import { SchemaForm } from 'zhouyuejin1995/schema-form';
import 'zhouyuejin1995/schema-form/dist/style.css';
import { ElMessage } from 'element-plus';

const schemas = [
  {
    field: 'username',
    label: '用户名',
    component: 'Input',
    required: true,
    componentProps: {
      placeholder: '请输入用户名',
    },
  },
  {
    field: 'email',
    label: '邮箱',
    component: 'Input',
    rules: [
      { type: 'email', message: '请输入正确的邮箱格式' },
    ],
  },
  {
    field: 'status',
    label: '状态',
    component: 'Select',
    componentProps: {
      options: [
        { label: '启用', value: 1 },
        { label: '禁用', value: 0 },
      ],
    },
  },
];

function handleSubmit(values) {
  ElMessage.success('提交成功: ' + JSON.stringify(values));
}

function handleReset(values) {
  console.log('重置后的值:', values);
}
</script>

JSX 语法

import { useForm } from 'zhouyuejin1995/schema-form';

const [SchemaForm, formInstance] = useForm({
  schemas: [
    { field: 'name', label: '姓名', component: 'Input', required: true },
    { field: 'age', label: '年龄', component: 'InputNumber' },
  ],
  onSubmit: (values) => {
    console.log('提交:', values);
  },
});

export default {
  render() {
    return (
      <div>
        <SchemaForm />
        <button onClick={() => formInstance.setFieldsValue({ name: '张三' })}>
          设置值
        </button>
      </div>
    );
  },
};

API

SchemaForm Props

| 属性 | 说明 | 类型 | 默认值 | |------|------|------|--------| | schemas | 表单配置数组 | FormField[] | [] | | labelWidth | 标签宽度 | string \| number | '100px' | | disabled | 禁用表单 | boolean | false | | inline | 内联模式 | boolean | false | | showActionButtonGroup | 显示操作按钮组 | boolean | true | | showResetButton | 显示重置按钮 | boolean | true | | showSubmitButton | 显示提交按钮 | boolean | true | | autoValidateOnSetFields | 设置值时自动校验 | boolean | true |

FormField 配置

| 属性 | 说明 | 类型 | |------|------|------| | field | 字段名 | string | | label | 标签文本 | string \| function | | component | 组件类型 | ComponentType \| function | | componentProps | 组件属性 | object \| function | | rules | 验证规则 | FormItemRule[] | | required | 是否必填 | boolean \| function | | defaultValue | 默认值 | any | | vIf | 动态显示控制 | boolean \| function | | vShow | 动态可见性 | boolean \| function | | dynamicDisabled | 动态禁用 | boolean \| function |

支持的组件

• Input / InputTextArea / InputPassword / InputSearch
• InputNumber
• Select
• RadioGroup / Radio
• CheckboxGroup / Checkbox
• Switch
• Cascader
• DatePicker / DateRangePicker / MonthPicker / YearPicker
• TimePicker
• Slider
• Rate
• Upload
• Divider
• ColorPicker
• Transfer

useForm Hook

const [SchemaForm, formInstance] = useForm(options);

// formInstance 方法
formInstance.validate();           // 校验表单
formInstance.setFieldsValue({});   // 设置表单值
formInstance.getFieldsValue();     // 获取表单值
formInstance.resetFields();        // 重置表单
formInstance.updateSchema({});      // 更新 Schema

注册组件

本组件不内置 Element Plus 组件，需要手动注册：

自动注册（推荐）

import { registerElementPlusComponents } from 'zhouyuejin1995/schema-form';
import * as ElementPlus from 'element-plus';
import * as ElementPlusIconsVue from '@element-plus/icons-vue';

// 注册所有 Element Plus 组件
registerElementPlusComponents(ElementPlus, ElementPlusIconsVue);

手动注册

import { registerComponents } from 'zhouyuejin1995/schema-form';
import { ElInput, ElSelect } from 'element-plus';

registerComponents({
  Input: ElInput,
  Select: ElSelect,
});

License

MIT