@pungfe/element

@pungfe/element

基于 Vue 3 与 Element Plus 的组件库：在 Element Plus 之上提供带 X 前缀的封装组件（如 XButton、XForm、XTable），并可选注册一组进阶组件（请求表格、异步按钮、OSS 上传等）。

特性

• 与 Element Plus 对齐：封装层透传常用 Props / 事件，默认行为可通过全局配置微调（如按钮中文空格、表格溢出提示）。
• 基础组件：表单、表格、上传、分页等常用控件的 X 系列封装，开箱即用。
• 进阶组件（可选）：通过 install 的 advance: true 注册，适合列表请求、表单提交、OSS 等场景。
• 按需样式：提供 unplugin-vue-components 解析器，自动解析组件并引入对应 Element Plus 的 CSS 副作用路径。
• TypeScript：导出类型声明；为全局组件提供类型补充。
• 国际化：内置在 Element Plus 语言包上扩展的 en、zhCn、ar、th 文案。

环境要求

请与下列 peerDependencies 版本保持一致（或兼容范围）：

安装

npm i @pungfe/element element-plus vue

快速开始

全局注册插件（默认只注册基础组件）；同时引入本库样式（内含 Tailwind 等构建产物）：

import Element from '@pungfe/element'
import { createApp } from 'vue'
import App from './App.vue'

import '.../tailwind.css'
import '.../cover.css'

// 该组件库的style.css 建议放在tailwind入口css和项目覆盖css之后
import '@pungfe/element/style.css'

const app = createApp(App)

app.use(Element)

同时请确保 Element Plus 的样式已按需或全量引入（例如全量：import 'element-plus/dist/index.css'）；若仅用 unplugin-vue-components + 本库解析器，一般由解析器为各组件注入 Element Plus 的 CSS 副作用路径。

注册进阶组件

进阶组件包含如 XTableRequestNext、XFormRequestNext、XUploadOssNext 等，需显式开启：

app.use(Element, { advance: true })

全局配置 ElementConfig

安装时可传入 config，用于合并默认的按钮、表格等全局行为（具体字段见包内导出的 ElementConfig 类型）：

app.use(Element, {
  config: {
    button: { autoInsertSpace: false },
    table: { showOverflowTooltip: false }
    // oss: { ... } // 供上传等进阶能力使用
  }
})

国际化（Element Plus）

从本库导出扩展后的语言包，配合 el-config-provider 使用：

import { zhCn } from '@pungfe/element/locales'

// 在模板中：<el-config-provider :locale="zhCn">...</el-config-provider>

英文为 en。

按需引入（推荐）

使用 unplugin-vue-components 时，可引入解析器，自动处理组件与 Element Plus 样式副作用：

import ElementResolver from '@pungfe/element/resolver'
import Components from 'unplugin-vue-components/vite'

// vite.config.ts 示例
export default defineConfig({
  plugins: [
    Components({
      resolvers: [
        ElementResolver()
        // 若使用进阶组件：
        // ElementResolver({ advance: true })
      ]
    })
  ]
})

模板中直接使用 XButton、XTable 等即可；进阶组件解析需 ElementResolver({ advance: true })。

子路径导出

组件一览

基础：XButton、XCascader、XCheckbox、XConfigProvider、XDatePicker、XDialog、XForm、XFormItem、XInput、XInputNumber、XPagination、XSelect、XTable、XTabs、XTabPane、XUpload。

进阶（advance: true）：XButtonAsync、XButtonConfirm、XCascaderRequest、XFormFlex、XFormRequestNext、XRequest、XSelectRequest、XTableFlex、XTableRequestNext、XTableRequestConfigNext、XUploadOssNext。

本地开发

npm ci
npm run build    # 输出 dist
npm run fmt      # oxfmt 格式化
npm run lint     # Oxlint（含类型感知）
npm run typecheck
npm run test     # Vitest（watch）

发布流程可通过 npm run release（先构建再使用 bumpp 升版）完成；CI 在指向 main 的 Push / PR 上会执行 lint、typecheck、test 与 build。

静态按需导入

未使用 app.use 全局注册时，可从子路径具名导入基础或进阶组件（与解析器 from 一致）：@pungfe/element/basic、@pungfe/element/advance。

License

MIT License 2026 FP