@mc-markets/ui 1.0.91 → 1.0.92

package/README.md

@@ -10,14 +10,213 @@ Vue 3 组件库，基于 Element Plus 的自定义组件
 
 演示站点通过 GitHub Actions 自动构建和部署，展示了所有组件的使用方法和效果。
 
-## 🚀 快速开始
+## ✨ 特性
+
+- 🎨 基于 Element Plus，保持一致的设计语言
+- 🔧 支持全局注册和按需导入
+- 📦 智能组件注册，自动转换 Element Plus 组件前缀 (el- → m-)
+- 🚀 支持 unplugin-vue-components 自动导入
+- 💪 TypeScript 支持
+- 🎯 Tree-shaking 友好
+
+## 🚀 安装
 
-### 安装
 ```bash
-npm i @mc-markets/ui
+npm install @mc-markets/ui
+# 或
+yarn add @mc-markets/ui
+# 或
+pnpm add @mc-markets/ui
+```
+
+## 📦 使用方式
+
+### 方式一：全局注册（推荐快速上手）
+
+在 `main.js` 或 `main.ts` 中：
+
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+import McMarketsUI from '@mc-markets/ui'
+import '@mc-markets/ui/dist/style.css'
+
+const app = createApp(App)
+app.use(McMarketsUI)
+app.mount('#app')
+```
+
+### 方式二：手动按需导入
+
+```vue
+<template>
+  <m-button type="primary">按钮</m-button>
+  <m-input v-model="value" placeholder="请输入" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { MButton, MInput } from '@mc-markets/ui'
+import '@mc-markets/ui/dist/style.css'
+
+const value = ref('')
+</script>
+```
+
+### 方式三：自动按需导入（推荐）⭐
+
+使用 `unplugin-vue-components` 和 `unplugin-auto-import` 实现零配置按需导入：
+
+#### 1. 安装插件
+
+```bash
+npm install -D unplugin-vue-components unplugin-auto-import
+```
+
+#### 2. 配置 Vite
+
+在 `vite.config.js` 或 `vite.config.ts` 中：
+
+```javascript
+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 { McMarketsUIResolver, getMcMarketsUIImports } from '@mc-markets/ui/resolver'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    // 自动导入组件
+    Components({
+      resolvers: [
+        McMarketsUIResolver({
+          // prefix: 'm',        // 组件前缀，默认 'm'
+          // importStyle: true   // 自动导入样式，默认 true
+        })
+      ]
+    }),
+    // 自动导入 API
+    AutoImport({
+      imports: [
+        'vue',
+        getMcMarketsUIImports()  // 自动导入 Message, NotifiMessage 等 API
+      ],
+      dts: 'src/auto-imports.d.ts'
+    })
+  ]
+})
+```
+
+#### 3. 配置 Webpack（Vue CLI）
+
+在 `vue.config.js` 中：
+
+```javascript
+const AutoImport = require('unplugin-auto-import/webpack')
+const Components = require('unplugin-vue-components/webpack')
+const { McMarketsUIResolver, getMcMarketsUIImports } = require('@mc-markets/ui/resolver')
+
+module.exports = {
+  configureWebpack: {
+    plugins: [
+      Components({
+        resolvers: [McMarketsUIResolver()]
+      }),
+      AutoImport({
+        imports: [
+          'vue',
+          getMcMarketsUIImports()
+        ],
+        dts: 'src/auto-imports.d.ts'
+      })
+    ]
+  }
+}
 ```
 
-### 文档开发模式
+#### 4. 直接使用组件（无需手动导入）
+
+配置完成后，可以直接在模板中使用组件，无需手动导入：
+
+```vue
+<template>
+  <!-- 直接使用，无需导入 -->
+  <m-button type="primary" @click="showMessage">显示消息</m-button>
+  <m-input v-model="form.name" placeholder="请输入姓名" />
+  <m-select v-model="form.city">
+    <m-option label="北京" value="beijing" />
+    <m-option label="上海" value="shanghai" />
+  </m-select>
+  <m-date-picker v-model="form.date" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+// API 也会自动导入，可以直接使用
+const form = ref({
+  name: '',
+  city: '',
+  date: ''
+})
+
+const showMessage = () => {
+  // Message 已自动导入
+  Message.success('操作成功！')
+}
+</script>
+```
+
+## 🎯 智能组件系统
+
+本组件库实现了智能组件注册机制：
+
+1. **自定义组件优先**：如果定义了自定义组件（如 `MButton`），会使用自定义版本
+2. **Element Plus 回退**：未自定义的组件会自动从 Element Plus 导入
+3. **前缀转换**：自动将 `el-*` 转换为 `m-*`（如 `<el-button>` → `<m-button>`）
+4. **无缝集成**：可以混合使用自定义组件和 Element Plus 组件
+
+### 可用组件
+
+#### 自定义组件
+- `MIcon` - 图标
+- `MButton` - 按钮
+- `MInput` - 输入框
+- `MSelect` / `MOption` / `MOptionGroup` - 选择器
+- `MForm` / `MFormItem` - 表单
+- `MTable` / `MTableColumn` - 表格
+- `MDatePicker` - 日期选择器
+- `MPagination` - 分页
+- `MRadio` / `MRadioGroup` / `MRadioButton` - 单选框
+- `MSwitch` - 开关
+- `MTag` - 标签
+- `MAlert` - 警告
+- `MDialog` - 对话框
+- `MTooltip` - 文字提示
+- `MEmpty` - 空状态
+- `MBanner` - 横幅
+- `MTabs` / `MTabPane` - 标签页
+- `MTabCard` / `MTabCardItem` - 卡片标签页
+- `MBreadcrumb` - 面包屑导航
+
+#### Element Plus 组件（自动转换前缀）
+所有 Element Plus 组件都可以通过 `m-` 前缀使用，例如：
+- `MCarousel` / `MCarouselItem` - 走马灯
+- `MCascader` - 级联选择器
+- `MColorPicker` - 颜色选择器
+- `MTree` / `MTreeSelect` - 树形控件
+- `MUpload` - 上传
+- `MProgress` - 进度条
+- 等等...
+
+#### API 方法
+- `Message` - 消息提示
+- `NotifiMessage` - 通知消息
+- `MMessageBox` - 消息弹框
+
+## 🛠️ 文档开发
+
 ```bash
 # 安装依赖
 npm install
@@ -25,6 +224,20 @@ npm install
 # 启动开发服务器
 npm run dev
 
-# 构建发布
+# 构建组件库
+npm run build
+
+# 构建演示站点
+npm run build:demo
+
+# 发布到 npm
 npm run publish:lib
 ```
+
+## 📄 License
+
+MIT
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！

package/USAGE_GUIDE.md

@@ -0,0 +1,339 @@
+# @mc-markets/ui 使用指南
+
+## 自动按需导入配置示例
+
+### Vite 项目完整配置示例
+
+```javascript
+// vite.config.js
+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 { McMarketsUIResolver, getMcMarketsUIImports } from '@mc-markets/ui/resolver'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    
+    // 自动导入组件
+    Components({
+      resolvers: [
+        // 自定义配置
+        McMarketsUIResolver({
+          prefix: 'm',        // 组件前缀，默认 'm'
+          importStyle: true   // 自动导入样式，默认 true
+        })
+      ],
+      // 生成类型声明文件
+      dts: 'src/components.d.ts',
+      // 自动导入的组件目录
+      dirs: ['src/components'],
+      // 组件的有效文件扩展名
+      extensions: ['vue'],
+    }),
+    
+    // 自动导入 API
+    AutoImport({
+      imports: [
+        'vue',
+        'vue-router',
+        // 自动导入 @mc-markets/ui 的 API
+        getMcMarketsUIImports()
+      ],
+      // 生成类型声明文件
+      dts: 'src/auto-imports.d.ts',
+      // 自动导入 Vue 相关函数
+      eslintrc: {
+        enabled: true, // 生成 ESLint 配置
+      },
+    })
+  ]
+})
+```
+
+### TypeScript 配置
+
+确保 `tsconfig.json` 包含生成的类型声明文件：
+
+```json
+{
+  "compilerOptions": {
+    // ... 其他配置
+  },
+  "include": [
+    "src/**/*",
+    "src/auto-imports.d.ts",
+    "src/components.d.ts"
+  ]
+}
+```
+
+### 使用示例
+
+配置完成后，可以直接使用组件和 API，无需手动导入：
+
+```vue
+<template>
+  <div class="container">
+    <!-- 组件自动导入 -->
+    <m-button type="primary" @click="handleClick">
+      点击我
+    </m-button>
+    
+    <m-input 
+      v-model="formData.username" 
+      placeholder="请输入用户名"
+      clearable
+    />
+    
+    <m-select v-model="formData.city" placeholder="请选择城市">
+      <m-option label="北京" value="beijing" />
+      <m-option label="上海" value="shanghai" />
+      <m-option label="深圳" value="shenzhen" />
+    </m-select>
+    
+    <m-date-picker 
+      v-model="formData.date" 
+      type="date"
+      placeholder="选择日期"
+    />
+    
+    <m-table :data="tableData">
+      <m-table-column prop="name" label="姓名" />
+      <m-table-column prop="age" label="年龄" />
+    </m-table>
+  </div>
+</template>
+
+<script setup>
+// ref, reactive 等 Vue API 自动导入
+// Message, NotifiMessage 等 UI API 自动导入
+const formData = reactive({
+  username: '',
+  city: '',
+  date: ''
+})
+
+const tableData = ref([
+  { name: '张三', age: 28 },
+  { name: '李四', age: 32 }
+])
+
+// 直接使用 Message API，无需导入
+const handleClick = () => {
+  Message.success('操作成功！')
+}
+
+// 使用 NotifiMessage
+const showNotification = () => {
+  NotifiMessage({
+    title: '通知',
+    message: '这是一条通知消息',
+    type: 'success'
+  })
+}
+
+// 使用 MessageBox
+const showConfirm = async () => {
+  try {
+    await MMessageBox.confirm('确定要删除吗？', '提示')
+    Message.success('已删除')
+  } catch {
+    Message.info('已取消')
+  }
+}
+</script>
+```
+
+## Webpack/Vue CLI 项目配置
+
+### 安装依赖
+
+```bash
+npm install -D unplugin-auto-import unplugin-vue-components
+```
+
+### 配置
+
+```javascript
+// vue.config.js
+const AutoImport = require('unplugin-auto-import/webpack')
+const Components = require('unplugin-vue-components/webpack')
+const { McMarketsUIResolver, getMcMarketsUIImports } = require('@mc-markets/ui/resolver')
+
+module.exports = {
+  configureWebpack: {
+    plugins: [
+      Components({
+        resolvers: [McMarketsUIResolver()],
+        dts: 'src/components.d.ts'
+      }),
+      AutoImport({
+        imports: [
+          'vue',
+          'vue-router',
+          getMcMarketsUIImports()
+        ],
+        dts: 'src/auto-imports.d.ts',
+        eslintrc: {
+          enabled: true
+        }
+      })
+    ]
+  }
+}
+```
+
+## Nuxt 3 项目配置
+
+```javascript
+// nuxt.config.ts
+import { McMarketsUIResolver, getMcMarketsUIImports } from '@mc-markets/ui/resolver'
+
+export default defineNuxtConfig({
+  modules: [
+    ['unplugin-vue-components/nuxt', {
+      resolvers: [McMarketsUIResolver()]
+    }],
+    ['unplugin-auto-import/nuxt', {
+      imports: [
+        'vue',
+        getMcMarketsUIImports()
+      ]
+    }]
+  ]
+})
+```
+
+## 混合使用自定义组件和 Element Plus 组件
+
+由于智能注册机制，你可以混合使用：
+
+```vue
+<template>
+  <!-- 使用自定义的 MButton -->
+  <m-button type="primary">自定义按钮</m-button>
+  
+  <!-- 使用转换前缀后的 Element Plus 组件 -->
+  <m-carousel height="200px">
+    <m-carousel-item v-for="item in 4" :key="item">
+      <h3>{{ item }}</h3>
+    </m-carousel-item>
+  </m-carousel>
+  
+  <!-- 使用 Element Plus 的 Tree 组件 -->
+  <m-tree :data="treeData" />
+  
+  <!-- 使用自定义的 Table 组件 -->
+  <m-table :data="tableData">
+    <m-table-column prop="name" label="姓名" />
+  </m-table>
+</template>
+```
+
+## 常见问题
+
+### Q: 为什么组件没有自动导入？
+
+**A:** 检查以下几点：
+1. 确保已正确安装和配置 `unplugin-vue-components` 和 `unplugin-auto-import`
+2. 重启开发服务器
+3. 检查组件名称是否以 `M` 或 `m-` 开头
+4. 查看生成的 `components.d.ts` 文件确认组件已注册
+
+### Q: TypeScript 类型提示不生效？
+
+**A:** 
+1. 确保 `tsconfig.json` 包含了生成的 `.d.ts` 文件
+2. 重启 VS Code 或 IDE
+3. 运行 `npm run dev` 让插件生成类型文件
+
+### Q: 样式没有加载？
+
+**A:**
+1. 如果使用自动导入，确保 `McMarketsUIResolver` 的 `importStyle` 选项为 `true`（默认）
+2. 或者手动在 `main.js` 中导入：
+   ```javascript
+   import '@mc-markets/ui/dist/style.css'
+   ```
+
+### Q: 如何使用 Element Plus 的原始组件？
+
+**A:** 有两种方式：
+1. 使用 `m-` 前缀（推荐）：`<m-carousel>`
+2. 手动导入原始组件：
+   ```javascript
+   import { ElCarousel } from 'element-plus'
+   ```
+
+### Q: 如何自定义组件前缀？
+
+**A:** 在 resolver 配置中修改：
+```javascript
+McMarketsUIResolver({
+  prefix: 'custom' // 将前缀改为 'custom'
+})
+```
+
+## 高级配置
+
+### 按需加载样式
+
+如果你想更精细地控制样式加载：
+
+```javascript
+Components({
+  resolvers: [
+    McMarketsUIResolver({
+      importStyle: false  // 禁用自动导入样式
+    })
+  ]
+})
+```
+
+然后在需要的地方手动导入：
+```javascript
+import '@mc-markets/ui/dist/style.css'
+```
+
+### 结合 Element Plus 使用
+
+如果你的项目同时使用 Element Plus 和本组件库：
+
+```javascript
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
+import { McMarketsUIResolver } from '@mc-markets/ui/resolver'
+
+Components({
+  resolvers: [
+    McMarketsUIResolver(),      // 优先使用自定义组件
+    ElementPlusResolver()       // 回退到 Element Plus
+  ]
+})
+```
+
+## 性能优化建议
+
+1. **启用 Tree Shaking**：使用自动导入可以实现最佳的 Tree Shaking 效果
+2. **按需加载**：只导入使用的组件，减小打包体积
+3. **生产环境优化**：
+   ```javascript
+   build: {
+     minify: 'terser',
+     terserOptions: {
+       compress: {
+         drop_console: true,
+         drop_debugger: true
+       }
+     }
+   }
+   ```
+
+## 更多资源
+
+- [在线演示](https://daboluoxigua.github.io/mc-markets-ui/)
+- [npm 仓库](https://www.npmjs.com/package/@mc-markets/ui)
+- [GitHub](https://github.com/daboluoxigua/mc-markets-ui)
+- [Element Plus 文档](https://element-plus.org/)
+