@iswangh/element-plus-kit

Element Plus Kit - 基于 Element Plus 的 Vue 3 组件库。

✨ 特性

• 🎨 基于 Element Plus，保持一致的视觉风格
• 📦 支持按需安装，减少包体积
• 🔧 支持多种导入方式：全局导入、手动导入、按需引入
• 💪 完整的 TypeScript 类型支持
• 🎯 组件命名规范：所有组件以 W 开头（如 WForm、w-form）
• 📚 详细的文档和示例

📦 安装

安装全部组件

npm install @iswangh/element-plus-kit

按需安装单个组件

# 安装 Form 组件
npm install @iswangh/element-plus-kit-form

⚙️ 配置 Element Plus

Element Plus Kit 基于 Element Plus 构建，因此需要在使用 Element Plus Kit 的项目中配置 Element Plus 的全局属性（如语言、尺寸等）。

配置语言（中文）

Element Plus 默认使用英文，如果需要使用中文，需要在项目中配置：

方式一：通过 app.use() 配置（推荐）

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import ElementPlusKit from '@iswangh/element-plus-kit'
import App from './App.vue'
// 注意：WForm 组件已按需导入了所有内部使用的 Element Plus 组件样式，无需导入全局样式

const app = createApp(App)

// 配置 Element Plus 使用中文
app.use(ElementPlus, {
  locale: zhCn,
})

// 注册 Element Plus Kit
app.use(ElementPlusKit)

app.mount('#app')

方式二：通过 ConfigProvider 组件配置

<template>
  <el-config-provider :locale="zhCn" size="default">
    <App />
  </el-config-provider>
</template>

<script setup lang="ts">
import { ElConfigProvider } from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import App from './App.vue'
</script>

配置尺寸

可以通过 ConfigProvider 组件全局配置组件尺寸：

<template>
  <el-config-provider :locale="zhCn" size="large">
    <App />
  </el-config-provider>
</template>

可选值：'large'、'default'、'small'

其他配置

更多配置选项请参考 Element Plus ConfigProvider 文档

注意：Element Plus 的全局配置应在使用 Element Plus Kit 的项目中处理，而不是在组件库包中。这样可以保持组件库的灵活性，让不同的项目根据自身需求进行配置。

🚀 快速开始

方式一：全局导入

import { createApp } from 'vue'
import ElementPlusKit from '@iswangh/element-plus-kit'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlusKit)
app.mount('#app')

<template>
  <WForm :model="form" :form-items="formItems" />
</template>

方式二：手动导入

<script setup lang="ts">
import { ref } from 'vue'
import { WForm } from '@iswangh/element-plus-kit'
import type { FormItems } from '@iswangh/element-plus-kit'

const formItems: FormItems = [
  {
    prop: 'username',
    label: '用户名',
    compType: 'input',
  },
]

const form = ref({
  username: '',
})
</script>

<template>
  <WForm :model="form" :form-items="formItems" />
</template>

方式三：按需引入（推荐）

配置 unplugin-vue-components 和 unplugin-auto-import：

1. 安装依赖

npm install -D unplugin-vue-components unplugin-auto-import

2. 配置 Vite

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
import { ElementPlusKitResolver } from '@iswangh/element-plus-kit/resolver'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [
        // ElementPlusResolver 默认 importStyle 为 'css'，会自动导入模板中直接使用的 Element Plus 组件样式
        // 注意：WForm 组件内部使用的 Element Plus 组件样式已在组件包内按需导入，无需额外配置
        ElementPlusResolver(),
        ElementPlusKitResolver(), // ElementPlusKitResolver 同时支持 AutoImport 和 Components
      ],
      imports: ['vue'],
    }),
    Components({
      resolvers: [
        // ElementPlusResolver 默认 importStyle 为 'css'，会自动导入模板中直接使用的 Element Plus 组件样式
        // 注意：WForm 组件内部使用的 Element Plus 组件样式已在组件包内按需导入，无需额外配置
        ElementPlusResolver(),
        ElementPlusKitResolver(), // ElementPlusKitResolver 同时支持 AutoImport 和 Components
      ],
    }),
  ],
})

3. 使用组件

<script setup lang="ts">
// 无需手动导入，组件会自动导入
import type { FormItems } from '@iswangh/element-plus-kit'

const formItems: FormItems = [
  {
    prop: 'username',
    label: '用户名',
    compType: 'input',
  },
]

const form = ref({
  username: '',
})
</script>

<template>
  <!-- WForm 会自动导入 -->
  <WForm :model="form" :form-items="formItems" />
</template>

📚 组件列表

Form 表单组件

动态表单组件，支持通过配置快速生成表单。

• 包名: @iswangh/element-plus-kit-form
• 组件名: WForm
• 文档: Form 组件文档

🔧 Resolver 配置

ElementPlusKitResolver

统一解析器，同时支持 unplugin-vue-components 和 unplugin-auto-import。

用于组件自动导入（unplugin-vue-components）：

import { ElementPlusKitResolver } from '@iswangh/element-plus-kit/resolver'
import Components from 'unplugin-vue-components/vite'

Components({
  resolvers: [
    ElementPlusKitResolver(),
  ],
})

用于 API 自动导入（unplugin-auto-import）：

import { ElementPlusKitResolver } from '@iswangh/element-plus-kit/resolver'
import AutoImport from 'unplugin-auto-import/vite'

AutoImport({
  resolvers: [
    ElementPlusKitResolver(), // 同一个解析器可以同时用于两种插件
  ],
})

同时使用（推荐）：

import { ElementPlusKitResolver } from '@iswangh/element-plus-kit/resolver'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'

AutoImport({
  resolvers: [ElementPlusKitResolver()],
})

Components({
  resolvers: [ElementPlusKitResolver()],
})

📖 API 文档

全局安装函数

import ElementPlusKit from '@iswangh/element-plus-kit'

app.use(ElementPlusKit)

组件导出

import { WForm } from '@iswangh/element-plus-kit'

类型导出

import type {
  FormActionConfig,
  FormItemEventExtendedParams,
  FormItems,
} from '@iswangh/element-plus-kit'

💡 使用示例

基础表单

<script setup lang="ts">
import { ref } from 'vue'
import { WForm } from '@iswangh/element-plus-kit'
import type { FormItems } from '@iswangh/element-plus-kit'

const formItems: FormItems = [
  {
    prop: 'username',
    label: '用户名',
    compType: 'input',
    rules: [
      { required: true, message: '请输入用户名', trigger: 'blur' },
    ],
  },
  {
    prop: 'email',
    label: '邮箱',
    compType: 'input',
    compProps: {
      type: 'email',
    },
    rules: [
      { required: true, message: '请输入邮箱', trigger: 'blur' },
      { type: 'email', message: '请输入正确的邮箱格式', trigger: 'blur' },
    ],
  },
]

const form = ref({
  username: '',
  email: '',
})
</script>

<template>
  <WForm :model="form" :form-items="formItems" />
</template>

带操作按钮的表单

<script setup lang="ts">
import { ref } from 'vue'
import { WForm } from '@iswangh/element-plus-kit'
import type { FormItems, FormActionConfig } from '@iswangh/element-plus-kit'

const formItems: FormItems = [
  {
    prop: 'keyword',
    label: '关键词',
    compType: 'input',
  },
]

const actionConfig: FormActionConfig = {
  buttons: ['search', 'reset'],
}

const form = ref({
  keyword: '',
})

const onSearch = () => {
  console.log('搜索:', form.value)
}

const onReset = () => {
  form.value.keyword = ''
  console.log('重置表单')
}
</script>

<template>
  <WForm
    :model="form"
    :form-items="formItems"
    :action-config="actionConfig"
    @search="onSearch"
    @reset="onReset"
  />
</template>

🔗 相关链接

• Form 组件文档
• 核心工具包文档
• Element Plus 文档
• Gitee 仓库
• GitHub 仓库

📄 许可证

本项目采用 Apache License 2.0 开源协议。

更多信息请查看项目根目录的 LICENSE 文件。