@mc-markets/ui 1.1.0 → 1.1.2

package/README.md

@@ -17,6 +17,72 @@ Vue 3 组件库，基于 Element Plus 的自定义组件
 npm i @mc-markets/ui
 ```
 
+### 使用方式
+
+#### 方式一：完整导入（推荐用于演示）
+
+```js
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+import McMarketsUI from '@mc-markets/ui'
+import '@mc-markets/ui/dist/style'
+
+const app = createApp(App)
+app.use(McMarketsUI)
+app.mount('#app')
+```
+
+#### 方式二：自动导入（推荐用于生产）⭐
+
+使用 `unplugin-vue-components` 实现按需自动导入：
+
+```bash
+npm i -D unplugin-vue-components
+```
+
+```js
+// vite.config.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()]
+    })
+  ]
+})
+```
+
+然后就可以直接在模板中使用组件，无需手动导入：
+
+```vue
+<template>
+  <m-button type="primary">按钮</m-button>
+  <m-input v-model="value" />
+</template>
+```
+
+📘 详细配置请查看 [Resolver 使用指南](./RESOLVER_USAGE.md)
+
+#### 方式三：手动按需导入
+
+```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
 # 安装依赖

package/RESOLVER_USAGE.md

@@ -0,0 +1,286 @@
+# @mc-markets/ui Resolver 使用指南
+
+## 什么是 Resolver？
+
+Resolver 是 `unplugin-vue-components` 的一个功能，它可以自动识别和导入组件库的组件，无需手动导入。
+
+## 安装
+
+首先，确保你已经安装了必要的依赖：
+
+```bash
+npm install @mc-markets/ui
+npm install -D unplugin-vue-components
+```
+
+## 使用方法
+
+### Vite 配置
+
+#### ES 模块方式（推荐）
+
+在你的 `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
+        })
+      ]
+    })
+  ]
+})
+```
+
+#### CommonJS 方式
+
+如果你的配置文件使用 CommonJS 格式：
+
+```js
+const { defineConfig } = require('vite')
+const vue = require('@vitejs/plugin-vue')
+const Components = require('unplugin-vue-components/vite')
+const { McMarketsUiResolver } = require('@mc-markets/ui/resolver')
+
+module.exports = defineConfig({
+  plugins: [
+    vue(),
+    Components({
+      resolvers: [
+        McMarketsUiResolver({
+          importStyle: true,
+          styleType: 'css'
+        })
+      ]
+    })
+  ]
+})
+```
+
+> **💡 提示**: Resolver 自动支持 ES 模块和 CommonJS 两种格式，无需额外配置。
+
+### 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/)
+