sunyard-szyy-ui

企业级 Vue 3 组件库 - 基于 Element Plus 的二次封装

✨ 特性

• 🚀 Vue 3 + TypeScript - 基于 Vue 3.5+ 和 TypeScript 5.6+
• 📦 Monorepo 架构 - 使用 pnpm workspace 管理
• 🎨 主题定制 - base.css 运行时覆盖 --el-*，并暴露 --sy-* 语义化变量
• 🔥 按需加载 - 支持自动按需导入，极致的打包体积
• 📚 完整文档 - 详细的使用文档和 API 说明
• 💪 TypeScript - 完整的类型定义和类型推导
• 🌲 Tree-shaking - 支持 ES Module，自动 tree-shaking
• ⚡️ 高性能 - 基于 Element Plus，性能卓越

📦 安装

# pnpm（推荐）
pnpm add sunyard-szyy-ui element-plus
pnpm add -D sass unplugin-auto-import unplugin-vue-components

# npm
npm install sunyard-szyy-ui element-plus
npm install -D sass unplugin-auto-import unplugin-vue-components

使用 Element Plus 图标组件时，可额外安装：

pnpm add @element-plus/icons-vue

🚀 快速开始

全量引入

适合快速原型；生产环境更推荐下方的自动按需引入。

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

import SunyardSzyyUI from 'sunyard-szyy-ui';
import 'sunyard-szyy-ui/theme-chalk/index.css';

import App from './App.vue';

const app = createApp(App);

app.use(ElementPlus);
app.use(SunyardSzyyUI);
app.mount('#app');

自动按需引入（推荐）

1. tsconfig.json — sunyard-szyy-ui/utils 依赖 exports 子路径，需：

{
  "compilerOptions": {
    "moduleResolution": "Bundler"
  }
}

2. 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 { SunyardSzyyUIResolver, SunyardSzyyUIAutoImportResolver } from 'sunyard-szyy-ui/utils';

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      imports: ['vue', '@vueuse/core', 'pinia', 'vue-router'],
      resolvers: [
        ElementPlusResolver(),
        SunyardSzyyUIAutoImportResolver()
        // SyMessage / SyMessageBox / SyNotification / SyLoading / SyFeedback
      ],
      ignore: ['constructor'],
      dts: 'src/typings/auto-imports.d.ts'
    }),
    Components({
      resolvers: [...SunyardSzyyUIResolver(), ElementPlusResolver({ importStyle: 'sass' })],
      dts: 'src/components.d.ts'
    })
  ],
  css: {
    preprocessorOptions: {
      scss: {
        silenceDeprecations: ['import', 'legacy-js-api', 'color-functions']
      }
    }
  }
});

SY resolver 须放在 ElementPlusResolver 之前，以便 v-loading 优先解析为 SyLoadingDirective。

3. main.ts

import { createApp } from 'vue';

// 按需模式下不要引入 element-plus/dist/index.css
import 'sunyard-szyy-ui/theme-chalk/base.css';

import App from './App.vue';

createApp(App).mount('#app');

• 只需 base.css：运行时覆盖 --el-*，并暴露 --sy-*；组件与函数式 API 样式由 Resolver 自动注入。
• 默认不要在 Vite 里用 scss.additionalData 注入 var.scss；业务工程以 base.css 为准。更完整说明见仓库 docs/guide/getting-started.md。

使用组件

<template>
  <SyInput v-model="keyword" placeholder="请输入关键词" />
</template>

<script setup lang="ts">
const keyword = ref('');
</script>

按需模式下 ref 与 SyInput 可由 unplugin 自动导入，无需手写 import。

📚 包结构

本项目采用 Monorepo 架构，包含以下子包：

sunyard-szyy-ui/
├── @sunyard-szyy-ui/components   # Vue 组件
├── @sunyard-szyy-ui/hooks        # Composition API Hooks
├── @sunyard-szyy-ui/utils        # 工具函数（含 Resolver）
├── @sunyard-szyy-ui/theme-chalk  # 样式主题
└── sunyard-szyy-ui              # 主包（聚合导出）

子包说明

| 包名 | 说明 | 独立使用 | | ------------------------------ | --------------------- | --------- | | sunyard-szyy-ui | 主包，包含所有功能 | ✅ 推荐 | | @sunyard-szyy-ui/components | Vue 组件 | ✅ 可以 | | @sunyard-szyy-ui/hooks | Composition API Hooks | ✅ 可以 | | @sunyard-szyy-ui/utils | 工具函数、Resolver | ✅ 可以 | | @sunyard-szyy-ui/theme-chalk | 样式主题 | ❌ 不推荐 |

📦 发布产物

安装 sunyard-szyy-ui 后，包含以下内容：

sunyard-szyy-ui/
├── es/                    # ESM 格式
│   ├── index.mjs
│   └── index.d.ts
├── lib/                   # CJS 格式
│   ├── index.js
│   └── index.d.ts
├── dist/                  # UMD 格式 + 子包
│   ├── index.full.js      # UMD bundle
│   ├── index.full.mjs     # ESM bundle
│   ├── hooks/             # Hooks 子包
│   └── utils/             # Utils 子包
└── theme-chalk/           # 样式文件
    ├── index.css          # 完整样式
    ├── base.css           # 主题基础入口（按需模式推荐）
    └── *.css              # 组件样式

🤝 依赖关系

sunyard-szyy-ui
├── @sunyard-szyy-ui/components
│   ├── @sunyard-szyy-ui/hooks
│   │   └── @sunyard-szyy-ui/utils
│   └── @sunyard-szyy-ui/utils
├── @sunyard-szyy-ui/hooks
│   └── @sunyard-szyy-ui/utils
└── @sunyard-szyy-ui/utils

外部依赖（Peer Dependencies）：

• vue ^3.0.0
• element-plus ^2.0.0

📖 更多文档

完整接入、微前端与全局配置说明见仓库文档站或源码中的 docs/guide/getting-started.md、docs/guide/usage.md。