@mc-markets/ui 1.0.91 → 1.0.93

package/QUICK_START.md

@@ -0,0 +1,379 @@
+# 🚀 快速入门指南
+
+## 项目初始化
+
+### 1. 创建 Vue 3 项目
+
+```bash
+# 使用 Vite 创建项目
+npm create vite@latest my-project -- --template vue
+cd my-project
+
+# 或使用 Vue CLI
+npm install -g @vue/cli
+vue create my-project
+cd my-project
+```
+
+### 2. 安装依赖
+
+```bash
+# 安装组件库
+npm install @mc-markets/ui
+
+# 安装自动导入插件（推荐）
+npm install -D unplugin-vue-components unplugin-auto-import
+```
+
+### 3. 配置 Vite
+
+创建或修改 `vite.config.js`：
+
+```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()]
+    }),
+    AutoImport({
+      imports: ['vue', getMcMarketsUIImports()],
+      dts: 'src/auto-imports.d.ts'
+    })
+  ]
+})
+```
+
+### 4. 更新 TypeScript 配置（如果使用 TS）
+
+修改 `tsconfig.json`，添加生成的类型文件：
+
+```json
+{
+  "compilerOptions": {
+    // ... 其他配置
+  },
+  "include": [
+    "src/**/*",
+    "src/auto-imports.d.ts",
+    "src/components.d.ts"
+  ]
+}
+```
+
+### 5. 创建示例页面
+
+创建 `src/App.vue`：
+
+```vue
+<template>
+  <div class="app">
+    <h1>@mc-markets/ui 示例</h1>
+    
+    <!-- 表单示例 -->
+    <m-form :model="form" label-width="100px">
+      <m-form-item label="用户名">
+        <m-input v-model="form.username" placeholder="请输入用户名" clearable />
+      </m-form-item>
+      
+      <m-form-item label="城市">
+        <m-select v-model="form.city" placeholder="请选择城市">
+          <m-option label="北京" value="beijing" />
+          <m-option label="上海" value="shanghai" />
+          <m-option label="深圳" value="shenzhen" />
+        </m-select>
+      </m-form-item>
+      
+      <m-form-item label="日期">
+        <m-date-picker v-model="form.date" placeholder="选择日期" />
+      </m-form-item>
+      
+      <m-form-item label="启用状态">
+        <m-switch v-model="form.enabled" />
+      </m-form-item>
+      
+      <m-form-item>
+        <m-button type="primary" @click="handleSubmit">提交</m-button>
+        <m-button @click="handleReset">重置</m-button>
+      </m-form-item>
+    </m-form>
+    
+    <!-- 表格示例 -->
+    <m-table :data="tableData" style="margin-top: 20px;">
+      <m-table-column prop="name" label="姓名" width="180" />
+      <m-table-column prop="age" label="年龄" width="180" />
+      <m-table-column prop="address" label="地址" />
+      <m-table-column label="操作" width="150">
+        <template #default="{ row }">
+          <m-button size="small" @click="handleEdit(row)">编辑</m-button>
+          <m-button size="small" type="danger" @click="handleDelete(row)">
+            删除
+          </m-button>
+        </template>
+      </m-table-column>
+    </m-table>
+    
+    <!-- 分页示例 -->
+    <m-pagination
+      v-model:current-page="currentPage"
+      v-model:page-size="pageSize"
+      :total="100"
+      layout="prev, pager, next"
+      style="margin-top: 20px;"
+    />
+  </div>
+</template>
+
+<script setup>
+// 无需导入任何东西！
+// ref, reactive 等 Vue API 已自动导入
+// Message 等组件库 API 已自动导入
+// 组件也已自动导入，直接在模板中使用即可
+
+const form = reactive({
+  username: '',
+  city: '',
+  date: '',
+  enabled: false
+})
+
+const tableData = ref([
+  { name: '张三', age: 28, address: '北京市朝阳区' },
+  { name: '李四', age: 32, address: '上海市浦东新区' },
+  { name: '王五', age: 25, address: '深圳市南山区' }
+])
+
+const currentPage = ref(1)
+const pageSize = ref(10)
+
+const handleSubmit = () => {
+  console.log('表单数据:', form)
+  Message.success('提交成功！')
+}
+
+const handleReset = () => {
+  Object.assign(form, {
+    username: '',
+    city: '',
+    date: '',
+    enabled: false
+  })
+  Message.info('已重置')
+}
+
+const handleEdit = (row) => {
+  console.log('编辑:', row)
+  Message.info(`编辑 ${row.name}`)
+}
+
+const handleDelete = async (row) => {
+  try {
+    await MMessageBox.confirm(`确定删除 ${row.name} 吗？`, '提示')
+    Message.success('删除成功')
+  } catch {
+    Message.info('已取消删除')
+  }
+}
+</script>
+
+<style scoped>
+.app {
+  padding: 20px;
+  max-width: 1200px;
+  margin: 0 auto;
+}
+
+h1 {
+  margin-bottom: 20px;
+  color: #333;
+}
+</style>
+```
+
+### 6. 运行项目
+
+```bash
+npm run dev
+```
+
+## 项目结构
+
+推荐的项目结构：
+
+```
+my-project/
+├── src/
+│   ├── assets/              # 静态资源
+│   ├── components/          # 业务组件
+│   ├── views/               # 页面组件
+│   ├── router/              # 路由配置
+│   ├── store/               # 状态管理
+│   ├── utils/               # 工具函数
+│   ├── App.vue              # 根组件
+│   ├── main.js              # 入口文件
+│   ├── auto-imports.d.ts    # 自动生成的 API 类型
+│   └── components.d.ts      # 自动生成的组件类型
+├── public/                  # 公共资源
+├── index.html              # HTML 模板
+├── vite.config.js          # Vite 配置
+├── package.json            # 项目配置
+└── tsconfig.json           # TypeScript 配置（可选）
+```
+
+## 常用示例
+
+### 对话框示例
+
+```vue
+<template>
+  <m-button @click="dialogVisible = true">打开对话框</m-button>
+  
+  <m-dialog v-model="dialogVisible" title="提示">
+    <span>这是一段信息</span>
+    <template #footer>
+      <m-button @click="dialogVisible = false">取消</m-button>
+      <m-button type="primary" @click="handleConfirm">确定</m-button>
+    </template>
+  </m-dialog>
+</template>
+
+<script setup>
+const dialogVisible = ref(false)
+
+const handleConfirm = () => {
+  dialogVisible.value = false
+  Message.success('操作成功')
+}
+</script>
+```
+
+### 标签页示例
+
+```vue
+<template>
+  <m-tabs v-model="activeTab">
+    <m-tab-pane label="用户管理" name="user">
+      用户管理内容
+    </m-tab-pane>
+    <m-tab-pane label="配置管理" name="config">
+      配置管理内容
+    </m-tab-pane>
+    <m-tab-pane label="角色管理" name="role">
+      角色管理内容
+    </m-tab-pane>
+  </m-tabs>
+</template>
+
+<script setup>
+const activeTab = ref('user')
+</script>
+```
+
+### 单选框组示例
+
+```vue
+<template>
+  <m-radio-group v-model="radio">
+    <m-radio label="1">选项 1</m-radio>
+    <m-radio label="2">选项 2</m-radio>
+    <m-radio label="3">选项 3</m-radio>
+  </m-radio-group>
+  
+  <div style="margin-top: 10px;">
+    <m-radio-group v-model="radioButton">
+      <m-radio-button label="北京" />
+      <m-radio-button label="上海" />
+      <m-radio-button label="深圳" />
+    </m-radio-group>
+  </div>
+</template>
+
+<script setup>
+const radio = ref('1')
+const radioButton = ref('北京')
+</script>
+```
+
+### 消息提示示例
+
+```vue
+<template>
+  <m-button @click="Message.success('成功消息')">成功</m-button>
+  <m-button @click="Message.warning('警告消息')">警告</m-button>
+  <m-button @click="Message.info('信息消息')">信息</m-button>
+  <m-button @click="Message.error('错误消息')">错误</m-button>
+</template>
+
+<script setup>
+// Message 已自动导入，直接使用即可
+</script>
+```
+
+### 通知示例
+
+```vue
+<template>
+  <m-button @click="showNotification">显示通知</m-button>
+</template>
+
+<script setup>
+const showNotification = () => {
+  NotifiMessage({
+    title: '通知标题',
+    message: '这是通知内容',
+    type: 'success',
+    duration: 3000
+  })
+}
+</script>
+```
+
+## 更多示例
+
+访问 [在线演示](https://daboluoxigua.github.io/mc-markets-ui/) 查看完整的组件示例和 API 文档。
+
+## 下一步
+
+- 📖 阅读 [使用指南](./USAGE_GUIDE.md) 了解更多高级用法
+- 🎨 查看 [在线演示](https://daboluoxigua.github.io/mc-markets-ui/) 了解所有组件
+- 💡 参考 [配置示例](./vite.config.example.js) 优化你的配置
+
+## 常见问题
+
+### Q: 为什么组件样式没有生效？
+
+确保 `McMarketsUIResolver` 的 `importStyle` 选项为 `true`（默认），或手动导入样式：
+
+```javascript
+// main.js
+import '@mc-markets/ui/dist/style.css'
+```
+
+### Q: TypeScript 类型提示不工作？
+
+1. 确保 `tsconfig.json` 包含了生成的 `.d.ts` 文件
+2. 重启 IDE
+3. 运行一次 `npm run dev` 生成类型文件
+
+### Q: 如何使用 Element Plus 的其他组件？
+
+所有 Element Plus 组件都可以通过 `m-` 前缀使用，会自动转换。例如：
+
+```vue
+<m-carousel>
+  <m-carousel-item>内容 1</m-carousel-item>
+  <m-carousel-item>内容 2</m-carousel-item>
+</m-carousel>
+```
+
+## 获取帮助
+
+- [GitHub Issues](https://github.com/daboluoxigua/mc-markets-ui/issues)
+- [npm 主页](https://www.npmjs.com/package/@mc-markets/ui)
+

package/README.md

@@ -10,14 +10,239 @@ 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
+```
+
+## 📦 使用方式
+
+### 方式一：全局注册（推荐快速上手）
+
+在 `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 i @mc-markets/ui
+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: 'css'     // 样式导入方式：'css' | 'scss' | false，默认 'css'
+        })
+      ]
+    }),
+    // 自动导入 API
+    AutoImport({
+      imports: [
+        'vue',
+        getMcMarketsUIImports()  // 自动导入 Message, NotifiMessage 等 API
+      ],
+      dts: 'src/auto-imports.d.ts'
+    })
+  ]
+})
+```
+
+#### 3. 导入样式（推荐）
+
+在 `main.js` 或 `main.ts` 中导入样式：
+
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+// 导入组件库样式
+import '@mc-markets/ui/dist/style.css'
+
+createApp(App).mount('#app')
+```
+
+**其他样式导入方式：**
+
+```javascript
+// 方式1：导入编译后的 CSS（推荐，体积更小）
+import '@mc-markets/ui/dist/style.css'
+
+// 方式2：导入 SCSS 源文件（可自定义变量）
+import '@mc-markets/ui/packages/styles/index.scss'
+
+// 方式3：通过 resolver 自动导入（会在第一个组件导入时自动引入）
+// 在 vite.config.js 中配置 importStyle: 'css'
+```
+
+#### 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/resolver')
+
+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" />
+</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 +250,20 @@ npm install
 # 启动开发服务器
 npm run dev
 
-# 构建发布
+# 构建组件库
+npm run build
+
+# 构建演示站点
+npm run build:demo
+
+# 发布到 npm
 npm run publish:lib
 ```
+
+## 📄 License
+
+MIT
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！