@mc-markets/ui 1.0.101 → 1.1.1

package/README.md

@@ -10,263 +10,80 @@ Vue 3 组件库，基于 Element Plus 的自定义组件
 
 演示站点通过 GitHub Actions 自动构建和部署，展示了所有组件的使用方法和效果。
 
-## ✨ 特性
-
-- 🎨 基于 Element Plus，保持一致的设计语言
-- 🔧 支持全局注册和按需导入
-- 📦 智能组件注册，自动转换 Element Plus 组件前缀 (el- → m-)
-- 🚀 支持 unplugin-vue-components 自动导入
-- 💪 TypeScript 支持
-- 🎯 Tree-shaking 友好
-
-## 🚀 安装
+## 🚀 快速开始
 
+### 安装
 ```bash
-npm install @mc-markets/ui
-# 或
-yarn add @mc-markets/ui
-# 或
-pnpm add @mc-markets/ui
+npm i @mc-markets/ui
 ```
 
-## 📦 使用方式
-
-### 方式一：全局注册（推荐快速上手）
+### 使用方式
 
-在 `main.js` 或 `main.ts` 中：
+#### 方式一：完整导入（推荐用于演示）
 
-```javascript
+```js
+// main.js
 import { createApp } from 'vue'
 import App from './App.vue'
 import McMarketsUI from '@mc-markets/ui'
-import '@mc-markets/ui/dist/style.css'
+import '@mc-markets/ui/dist/style'
 
 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. 安装插件
+使用 `unplugin-vue-components` 实现按需自动导入：
 
 ```bash
-npm install -D unplugin-vue-components unplugin-auto-import
+npm i -D unplugin-vue-components
 ```
 
-#### 2. 配置 Vite
-
-在 `vite.config.js` 或 `vite.config.ts` 中：
-
-```javascript
+```js
+// 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'
+import { McMarketsUiResolver } from '@mc-markets/ui/resolver'
 
 export default defineConfig({
   plugins: [
     vue(),
-    // 自动导入组件
     Components({
-      resolvers: [
-        McMarketsUIResolver({
-          // prefix: 'm',           // 组件前缀，默认 'm'
-          // importStyle: 'css'     // 样式导入方式：'css' | 'scss' | false，默认 'css'
-        })
-      ]
-    }),
-    // 自动导入 API
-    AutoImport({
-      imports: [
-        'vue',
-        getMcMarketsUIImports()  // 自动导入 Message, NotifiMessage 等 API
-      ],
-      dts: 'src/auto-imports.d.ts'
+      resolvers: [McMarketsUiResolver()]
     })
   ]
 })
 ```
 
-#### 3. 导入样式（推荐）
-
-在 `main.js` 或 `main.ts` 中导入样式：
-
-```javascript
-import { createApp } from 'vue'
-import App from './App.vue'
-
-// 导入组件库样式（必需）
-import '@mc-markets/ui/dist/style.css'
-
-// 导入字体图标样式（如果使用图标组件）
-import '@mc-markets/ui/styles/font'
-import '@mc-markets/ui/styles/colorfont'
-
-createApp(App).mount('#app')
-```
-
-**自动导入样式（推荐）：**
-
-配置 resolver 的 `importStyle: 'css'` 后，会自动导入以下文件：
-- `@mc-markets/ui/dist/style.css` - 主样式文件
-- `@mc-markets/ui/styles/font` - 字体图标样式
-- `@mc-markets/ui/styles/colorfont` - 彩色字体图标样式
-
-```javascript
-// vite.config.js
-McMarketsUIResolver({
-  importStyle: 'css'  // 自动导入所有必需的样式
-})
-```
-
-**其他样式导入方式：**
-
-```javascript
-// 方式1：导入编译后的 CSS（推荐，体积更小）
-import '@mc-markets/ui/dist/style.css'
-
-// 方式2：导入独立 SCSS 文件（不依赖 Element Plus，推荐）
-import '@mc-markets/ui/styles/standalone'
-
-// 方式3：导入 SCSS 源文件（包含自定义变量）
-import '@mc-markets/ui/styles/index'
-
-// 方式4：手动导入所有样式
-import '@mc-markets/ui/dist/style.css'
-import '@mc-markets/ui/styles/font'
-import '@mc-markets/ui/styles/colorfont'
-```
-
-#### 4. 配置 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')
-
-module.exports = {
-  configureWebpack: {
-    plugins: [
-      Components({
-        resolvers: [McMarketsUIResolver()]
-      }),
-      AutoImport({
-        imports: [
-          'vue',
-          getMcMarketsUIImports()
-        ],
-        dts: 'src/auto-imports.d.ts'
-      })
-    ]
-  }
-}
-```
-
-#### 5. 直接使用组件（无需手动导入）
-
-配置完成后，可以直接在模板中使用组件，无需手动导入：
+然后就可以直接在模板中使用组件，无需手动导入：
 
 ```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" />
+  <m-button type="primary">按钮</m-button>
+  <m-input v-model="value" />
 </template>
-
-<script setup>
-import { ref } from 'vue'
-
-// API 也会自动导入，可以直接使用
-const form = ref({
-  name: '',
-  city: '',
-  date: ''
-})
-
-const showMessage = () => {
-  // Message 已自动导入
-  Message.success('操作成功！')
-}
-</script>
 ```
 
-## 🎯 智能组件系统
-
-本组件库实现了智能组件注册机制：
+📘 详细配置请查看 [Resolver 使用指南](./RESOLVER_USAGE.md)
 
-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` - 消息弹框
+```vue
+<script setup>
+import { MButton, MInput } from '@mc-markets/ui'
+import '@mc-markets/ui/dist/style'
+</script>
 
-## 🛠️ 文档开发
+<template>
+  <m-button type="primary">按钮</m-button>
+  <m-input v-model="value" />
+</template>
+```
 
+### 文档开发模式
 ```bash
 # 安装依赖
 npm install
@@ -274,20 +91,6 @@ npm install
 # 启动开发服务器
 npm run dev
 
-# 构建组件库
-npm run build
-
-# 构建演示站点
-npm run build:demo
-
-# 发布到 npm
+# 构建发布
 npm run publish:lib
 ```
-
-## 📄 License
-
-MIT
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request！

package/RESOLVER_USAGE.md

@@ -0,0 +1,257 @@
+# @mc-markets/ui Resolver 使用指南
+
+## 什么是 Resolver？
+
+Resolver 是 `unplugin-vue-components` 的一个功能，它可以自动识别和导入组件库的组件，无需手动导入。
+
+## 安装
+
+首先，确保你已经安装了必要的依赖：
+
+```bash
+npm install @mc-markets/ui
+npm install -D unplugin-vue-components
+```
+
+## 使用方法
+
+### Vite 配置
+
+在你的 `vite.config.js` 或 `vite.config.ts` 中：
+
+```js
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import Components from 'unplugin-vue-components/vite'
+import { McMarketsUiResolver } from '@mc-markets/ui/resolver'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    Components({
+      resolvers: [
+        McMarketsUiResolver({
+          importStyle: true,      // 自动导入样式
+          styleType: 'css',       // 样式类型: 'css' | 'scss'
+          fallbackToElementPlus: false  // 是否回退到 Element Plus
+        })
+      ]
+    })
+  ]
+})
+```
+
+### Webpack 配置
+
+在你的 `webpack.config.js` 中：
+
+```js
+const Components = require('unplugin-vue-components/webpack')
+const { McMarketsUiResolver } = require('@mc-markets/ui/resolver')
+
+module.exports = {
+  plugins: [
+    Components({
+      resolvers: [McMarketsUiResolver()]
+    })
+  ]
+}
+```
+
+### Rollup 配置
+
+```js
+import Components from 'unplugin-vue-components/rollup'
+import { McMarketsUiResolver } from '@mc-markets/ui/resolver'
+
+export default {
+  plugins: [
+    Components({
+      resolvers: [McMarketsUiResolver()]
+    })
+  ]
+}
+```
+
+## 配置选项
+
+### importStyle
+
+- **类型**: `boolean`
+- **默认值**: `true`
+- **说明**: 是否自动导入样式文件
+
+```js
+McMarketsUiResolver({
+  importStyle: true  // 会自动导入组件样式
+})
+```
+
+### styleType
+
+- **类型**: `'css' | 'scss'`
+- **默认值**: `'css'`
+- **说明**: 样式文件类型
+
+```js
+// 使用 CSS 样式（打包后的）
+McMarketsUiResolver({
+  styleType: 'css'  // 导入 @mc-markets/ui/dist/style
+})
+
+// 使用 SCSS 样式（源文件）
+McMarketsUiResolver({
+  styleType: 'scss'  // 导入 @mc-markets/ui/styles/index
+})
+```
+
+如果使用 `scss`，需要确保项目中配置了 SCSS 处理器。
+
+### fallbackToElementPlus
+
+- **类型**: `boolean`
+- **默认值**: `false`
+- **说明**: 对于未自定义的组件，是否回退到 Element Plus
+
+```js
+McMarketsUiResolver({
+  fallbackToElementPlus: true
+})
+```
+
+当设置为 `true` 时，如果使用了 `@mc-markets/ui` 未自定义的组件（如 `MCard`），会尝试从库中导入转换后的 Element Plus 组件。
+
+## 使用示例
+
+配置好 resolver 后，你可以直接在模板中使用组件，无需手动导入：
+
+```vue
+<template>
+  <div>
+    <!-- 自动导入 MButton -->
+    <m-button type="primary">主要按钮</m-button>
+    
+    <!-- 自动导入 MInput -->
+    <m-input v-model="value" placeholder="请输入" />
+    
+    <!-- 自动导入 MDialog -->
+    <m-dialog v-model="visible" title="对话框">
+      <p>对话框内容</p>
+    </m-dialog>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const value = ref('')
+const visible = ref(false)
+</script>
+```
+
+## 与其他 Resolver 一起使用
+
+你可以同时使用多个 resolver：
+
+```js
+import { defineConfig } from 'vite'
+import Components from 'unplugin-vue-components/vite'
+import {
+  McMarketsUiResolver
+} from '@mc-markets/ui/resolver'
+import {
+  ElementPlusResolver,
+  VantResolver
+} from 'unplugin-vue-components/resolvers'
+
+export default defineConfig({
+  plugins: [
+    Components({
+      resolvers: [
+        McMarketsUiResolver(),
+        ElementPlusResolver(),  // Element Plus 组件
+        VantResolver()          // Vant 组件
+      ]
+    })
+  ]
+})
+```
+
+## 支持的组件
+
+目前支持自动导入的自定义组件包括：
+
+- `MIcon` - 图标
+- `MButton` - 按钮
+- `MInput` - 输入框
+- `MForm` - 表单
+- `MFormItem` - 表单项
+- `MTooltip` - 文字提示
+- `MSelect` - 选择器
+- `MOption` - 选项
+- `MOptionGroup` - 选项组
+- `MPagination` - 分页
+- `MRadio` - 单选框
+- `MRadioGroup` - 单选框组
+- `MRadioButton` - 单选按钮
+- `MSwitch` - 开关
+- `MTag` - 标签
+- `MAlert` - 警告
+- `MDialog` - 对话框
+- `MNotification` - 通知
+- `MMessage` - 消息提示
+- `MNotifiMessage` - 通知消息
+- `MDatePicker` - 日期选择器
+- `MEmpty` - 空状态
+- `MTable` - 表格
+- `MTableColumn` - 表格列
+- `MBanner` - 横幅
+- `MTabs` - 标签页
+- `MTabPane` - 标签面板
+- `MTabCard` - 标签卡片
+- `MTabCardItem` - 标签卡片项
+- `MBreadcrumb` - 面包屑
+
+## 注意事项
+
+1. **组件前缀**: 所有组件必须使用 `M` 前缀（如 `MButton`、`MInput`）才能被 resolver 识别。
+
+2. **样式导入**: 
+   - 如果使用 `styleType: 'css'`，会导入打包后的 CSS 文件
+   - 如果使用 `styleType: 'scss'`，会导入源 SCSS 文件，需要项目支持 SCSS
+
+3. **按需加载**: Resolver 会自动实现按需加载，只导入你使用的组件。
+
+4. **类型支持**: Resolver 提供了完整的 TypeScript 类型定义。
+
+## 常见问题
+
+### Q: 组件没有被自动导入？
+
+A: 请确保：
+1. 组件名称使用了 `M` 前缀（如 `<m-button>`）
+2. Vite/Webpack 配置正确
+3. 重启开发服务器
+
+### Q: 样式没有生效？
+
+A: 请检查：
+1. `importStyle` 选项是否设置为 `true`
+2. 如果使用 `styleType: 'scss'`，确保项目配置了 SCSS 处理器
+
+### Q: 可以和 Element Plus 一起使用吗？
+
+A: 可以！你可以同时使用 `McMarketsUiResolver` 和 `ElementPlusResolver`：
+
+```js
+resolvers: [
+  McMarketsUiResolver(),
+  ElementPlusResolver()
+]
+```
+
+## 更多资源
+
+- [unplugin-vue-components 文档](https://github.com/antfu/unplugin-vue-components)
+- [@mc-markets/ui 文档](https://daboluoxigua.github.io/mc-markets-ui/)
+