sunyard-szyy-ui 0.8.1 → 0.8.2

package/README.md

@@ -10,7 +10,7 @@
 
 - 🚀 **Vue 3 + TypeScript** - 基于 Vue 3.5+ 和 TypeScript 5.6+
 - 📦 **Monorepo 架构** - 使用 pnpm workspace 管理
-- 🎨 **主题定制** - 支持 SCSS 变量和 CSS 变量双重定制
+- 🎨 **主题定制** - `base.css` 运行时覆盖 `--el-*`，并暴露 `--sy-*` 语义化变量
 - 🔥 **按需加载** - 支持自动按需导入，极致的打包体积
 - 📚 **完整文档** - 详细的使用文档和 API 说明
 - 💪 **TypeScript** - 完整的类型定义和类型推导
@@ -20,20 +20,27 @@
 ## 📦 安装
 
 ```bash
+# 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
+```
 
-# pnpm
-pnpm add sunyard-szyy-ui element-plus
+使用 Element Plus 图标组件时，可额外安装：
 
-# yarn
-yarn add sunyard-szyy-ui element-plus
+```bash
+pnpm add @element-plus/icons-vue
 ```
 
 ## 🚀 快速开始
 
 ### 全量引入
 
+适合快速原型；生产环境更推荐下方的自动按需引入。
+
 ```typescript
 // main.ts
 import { createApp } from 'vue';
@@ -54,8 +61,19 @@ app.mount('#app');
 
 ### 自动按需引入（推荐）
 
+**1. tsconfig.json** — `sunyard-szyy-ui/utils` 依赖 `exports` 子路径，需：
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "Bundler"
+  }
+}
+```
+
+**2. vite.config.ts**
+
 ```typescript
-// vite.config.ts
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
 import AutoImport from 'unplugin-auto-import/vite';
@@ -67,53 +85,62 @@ export default defineConfig({
   plugins: [
     vue(),
     AutoImport({
+      imports: ['vue', '@vueuse/core', 'pinia', 'vue-router'],
       resolvers: [
         ElementPlusResolver(),
-        SunyardSzyyUIAutoImportResolver() // SyMessage / SyMessageBox 等函数式 API 自动导入
+        SunyardSzyyUIAutoImportResolver()
+        // SyMessage / SyMessageBox / SyNotification / SyLoading / SyFeedback
       ],
-      // ⚠️ 参考添加：SunyardSzyyUIAutoImportResolver 内部使用 `name in obj` 判断，
-      // 因 JS 原型链导致 `constructor` 被误匹配，需手动排除
-      ignore: ['constructor']
+      ignore: ['constructor'],
+      dts: 'src/typings/auto-imports.d.ts'
     }),
-    // SY resolver 放在 EP 之前，确保 v-loading 指令优先走 SyLoadingDirective
     Components({
-      resolvers: [
-        ...SunyardSzyyUIResolver(), // 注意：返回数组，需要展开
-        ElementPlusResolver({ importStyle: 'sass' })
-      ]
+      resolvers: [...SunyardSzyyUIResolver(), ElementPlusResolver({ importStyle: 'sass' })],
+      dts: 'src/components.d.ts'
     })
   ],
   css: {
     preprocessorOptions: {
       scss: {
-        additionalData: `@use "sunyard-szyy-ui/theme-chalk/var.scss" as *;`
+        silenceDeprecations: ['import', 'legacy-js-api', 'color-functions']
       }
     }
   }
 });
 ```
 
+> SY resolver 须放在 `ElementPlusResolver` **之前**，以便 `v-loading` 优先解析为 `SyLoadingDirective`。
+
+**3. main.ts**
+
 ```typescript
-// 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`。
+
 ### 使用组件
 
 ```vue
 <template>
-  <div>
-    <SyInput v-model="keyword" placeholder="请输入关键词" />
-  </div>
+  <SyInput v-model="keyword" placeholder="请输入关键词" />
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue';
-
 const keyword = ref('');
 </script>
 ```
 
+按需模式下 `ref` 与 `SyInput` 可由 unplugin 自动导入，无需手写 import。
+
 ## 📚 包结构
 
 本项目采用 Monorepo 架构，包含以下子包：
@@ -122,7 +149,7 @@ const keyword = ref('');
 sunyard-szyy-ui/
 ├── @sunyard-szyy-ui/components   # Vue 组件
 ├── @sunyard-szyy-ui/hooks        # Composition API Hooks
-├── @sunyard-szyy-ui/utils        # 工具函数
+├── @sunyard-szyy-ui/utils        # 工具函数（含 Resolver）
 ├── @sunyard-szyy-ui/theme-chalk  # 样式主题
 └── sunyard-szyy-ui              # 主包（聚合导出）
 ```
@@ -134,7 +161,7 @@ sunyard-szyy-ui/
 | `sunyard-szyy-ui`              | 主包，包含所有功能    | ✅ 推荐   |
 | `@sunyard-szyy-ui/components`  | Vue 组件              | ✅ 可以   |
 | `@sunyard-szyy-ui/hooks`       | Composition API Hooks | ✅ 可以   |
-| `@sunyard-szyy-ui/utils`       | 工具函数              | ✅ 可以   |
+| `@sunyard-szyy-ui/utils`       | 工具函数、Resolver    | ✅ 可以   |
 | `@sunyard-szyy-ui/theme-chalk` | 样式主题              | ❌ 不推荐 |
 
 ## 📦 发布产物
@@ -156,7 +183,7 @@ sunyard-szyy-ui/
 │   └── utils/             # Utils 子包
 └── theme-chalk/           # 样式文件
     ├── index.css          # 完整样式
-    ├── base.css           # 基础样式
+    ├── base.css           # 主题基础入口（按需模式推荐）
     └── *.css              # 组件样式
 ```
 
@@ -177,3 +204,7 @@ sunyard-szyy-ui
 
 - `vue` ^3.0.0
 - `element-plus` ^2.0.0
+
+## 📖 更多文档
+
+完整接入、微前端与全局配置说明见仓库文档站或源码中的 `docs/guide/getting-started.md`、`docs/guide/usage.md`。