@xlui/xux-ui 1.3.21 → 1.3.23

package/README.md

@@ -1,47 +1,157 @@
-# @xlui/xux-ui
+# 快速开始
 
-Vue3 电商组件库 - 专为电商平台打造的现代化 UI 组件库
+本指南将帮助您快速上手 XUX-UI 组件库，从安装到使用，让您在几分钟内就能开始构建现代化的电商应用。
 
-## 在线文档 [xux.xlcig.cn](https://xux.xlcig.cn)
+在线文档：[https://xux.xlcig.cn](https://xux.xlcig.cn)
+
+## 📌 版本说明
+
+当前版本：**1.3.22**
+
+::: tip 重要提示
+- ✅ 推荐使用最新版本，旧版本可能存在 Bug 和样式问题
+- ✅ 完整支持 Vue 3 项目和 UniApp 项目
+- ✅ 部分复杂组件基于 Element Plus 的 `ElPopover` 优化性能
+- ✅ 问题反馈：18569795073@163.com
+:::
+
+### 版本检查
+
+查看当前已安装版本：
+
+::: code-group
+
+```bash [pnpm]
+pnpm list @xlui/xux-ui
+```
+
+```bash [npm]
+npm list @xlui/xux-ui
+```
+
+:::
+
+### 版本更新
+
+如果已安装旧版本，使用以下命令更新：
+
+::: code-group
+
+```bash [pnpm]
+pnpm update @xlui/xux-ui
+```
+
+```bash [npm]
+npm update @xlui/xux-ui
+```
+
+```bash [yarn]
+yarn upgrade @xlui/xux-ui
+```
+
+:::
 
 ## 📦 安装
 
-```bash
-npm install @xlui/xux-ui
-# 或
+### 使用包管理器安装
+
+::: code-group
+
+```bash [pnpm]
 pnpm add @xlui/xux-ui
-# 或
-yarn add @xlui/xux-ui
 ```
 
-## 🚀 快速开始
+```bash [npm]
+npm install @xlui/xux-ui
+```
+
+```bash [yarn]
+yarn add @xlui/xux-ui  
+```
+
+:::
+
+::: tip 提示
+推荐使用 pnpm 作为包管理器，它更快且更节省磁盘空间。
+:::
+
+## 🚀 基础使用
 
 ### 按需引入（推荐）
 
+在 Vue 3 项目中按需导入组件：
+
 ```vue
 <template>
-  <div>
+  <div class="demo-container">
     <XButton type="primary">主要按钮</XButton>
-    <XCard title="商品卡片">
-      <p>卡片内容</p>
+    <XButton type="success">成功按钮</XButton>
+    <XButton type="warning">警告按钮</XButton>
+    <XButton type="danger">危险按钮</XButton>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { XButton } from '@xlui/xux-ui'
+</script>
+
+<style scoped>
+.demo-container {
+  display: flex;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+</style>
+```
+
+### 多个组件引入
+
+```vue
+<template>
+  <div>
+    <XCard title="商品信息">
+      <XInput v-model="productName" placeholder="请输入商品名称" />
+      <XButton type="primary" @click="handleSubmit">提交</XButton>
     </XCard>
   </div>
 </template>
 
 <script setup lang="ts">
-import { XButton, XCard } from '@xlui/xux-ui'
-import '@xlui/xux-ui/dist/index.css'
-// 或者使用别名
-// import '@xlui/xux-ui/style.css'
+import { ref } from 'vue'
+import { XButton, XCard, XInput } from '@xlui/xux-ui'
+
+const productName = ref('')
+
+const handleSubmit = () => {
+  console.log('商品名称:', productName.value)
+}
 </script>
 ```
 
-### 全局注册
+### 引入样式
 
-如果不想每次都引入，可以在 `main.ts` 中全局注册：
+组件样式已内置，但推荐在项目入口引入完整样式以获得更好的主题支持：
 
 ```ts
 // main.ts
+import '@xlui/xux-ui/dist/index.css'
+```
+
+::: tip 主题定制
+XUX-UI 支持完整的主题定制和深色/浅色模式切换。  
+📖 查看 [主题化配置](/components/theme-config) 了解详细的主题定制方案。
+:::
+
+## 🔧 Vue 3 项目配置
+
+### 方式一：全局注册所有组件
+
+如果不想每次都引入组件，可以在项目入口文件中全局注册所有组件：
+
+::: code-group
+
+```ts [main.ts]
+// main.ts
 import { createApp } from 'vue'
 import App from './App.vue'
 import * as XUXComponents from '@xlui/xux-ui'
@@ -59,44 +169,670 @@ Object.entries(XUXComponents).forEach(([name, component]) => {
 app.mount('#app')
 ```
 
-注册后即可直接使用：
+```js [main.js]
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+import * as XUXComponents from '@xlui/xux-ui'
+import '@xlui/xux-ui/dist/index.css'
+
+const app = createApp(App)
+
+// 全局注册所有组件
+Object.entries(XUXComponents).forEach(([name, component]) => {
+  if (name.startsWith('X')) {
+    app.component(name, component)
+  }
+})
+
+app.mount('#app')
+```
+
+:::
+
+### 方式二：全局注册常用组件
+
+::: code-group
+
+```ts [main.ts]
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import { XButton, XCard, XInput, XModal, XBadge, XSelect } from '@xlui/xux-ui'
+import '@xlui/xux-ui/dist/index.css'
+
+const app = createApp(App)
+
+// 只注册常用组件
+app.component('XButton', XButton)
+app.component('XCard', XCard)
+app.component('XInput', XInput)
+app.component('XModal', XModal)
+app.component('XBadge', XBadge)
+app.component('XSelect', XSelect)
+
+app.mount('#app')
+```
+
+```js [main.js]
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+import { XButton, XCard, XInput, XModal, XBadge, XSelect } from '@xlui/xux-ui'
+import '@xlui/xux-ui/dist/index.css'
+
+const app = createApp(App)
+
+// 只注册常用组件
+app.component('XButton', XButton)
+app.component('XCard', XCard)
+app.component('XInput', XInput)
+app.component('XModal', XModal)
+app.component('XBadge', XBadge)
+app.component('XSelect', XSelect)
+
+app.mount('#app')
+```
+
+:::
+
+### 使用全局组件
+
+注册后即可直接在模板中使用，无需导入：
+
+```vue
+<template>
+  <div>
+    <XButton type="primary">按钮</XButton>
+    <XCard title="商品卡片">
+      <XInput v-model="name" placeholder="请输入" />
+    </XCard>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+// 无需导入组件，直接使用
+const name = ref('')
+</script>
+```
+
+::: tip 建议
+推荐使用**按需引入**而不是全局注册，这样可以：
+- 减小打包体积（Tree Shaking）
+- 更清晰的依赖关系
+- 更好的 TypeScript 类型提示
+:::
+
+### 方式三：自动导入（推荐！最佳实践）
+
+使用 `unplugin-vue-components` 实现自动按需导入：
+
+**1. 安装依赖**
+
+::: code-group
+
+```bash [pnpm]
+pnpm add -D unplugin-vue-components
+```
+
+```bash [npm]
+npm install -D unplugin-vue-components
+```
+
+```bash [yarn]
+yarn add -D unplugin-vue-components
+```
+
+:::
+
+**2. 配置 vite.config.ts**
+
+::: code-group
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import Components from 'unplugin-vue-components/vite'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    Components({
+      resolvers: [
+        // 自定义解析器，自动导入 XUX 组件
+        (componentName) => {
+          if (componentName.startsWith('X')) {
+            return {
+              name: componentName,
+              from: '@xlui/xux-ui'
+            }
+          }
+        }
+      ],
+      dts: true // 自动生成类型声明文件
+    })
+  ]
+})
+```
+
+```js [vite.config.js]
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import Components from 'unplugin-vue-components/vite'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    Components({
+      resolvers: [
+        // 自定义解析器，自动导入 XUX 组件
+        (componentName) => {
+          if (componentName.startsWith('X')) {
+            return {
+              name: componentName,
+              from: '@xlui/xux-ui'
+            }
+          }
+        }
+      ],
+      dts: true // 自动生成类型声明文件
+    })
+  ]
+})
+```
+
+:::
+
+**3. 在项目入口文件中引入样式**
+
+::: code-group
+
+```ts [main.ts]
+import { createApp } from 'vue'
+import App from './App.vue'
+import '@xlui/xux-ui/dist/index.css'
+
+createApp(App).mount('#app')
+```
+
+```js [main.js]
+import { createApp } from 'vue'
+import App from './App.vue'
+import '@xlui/xux-ui/dist/index.css'
+
+createApp(App).mount('#app')
+```
+
+:::
+
+**4. 直接使用（无需导入）**
+
+```vue
+<template>
+  <div>
+    <XButton type="primary">按钮</XButton>
+    <XCard title="商品卡片">
+      <XInput v-model="name" placeholder="请输入" />
+    </XCard>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+// 无需导入组件，自动识别并导入
+const name = ref('')
+</script>
+```
+
+::: tip 最佳实践
+**推荐使用自动导入方式**，它结合了便利性和性能优势：
+- ✅ 无需手动导入，开发体验最佳
+- ✅ 按需打包，体积最小（Tree Shaking）
+- ✅ 自动生成 TypeScript 类型声明
+- ✅ 更清晰的依赖关系
+:::
+
+## 🚢 Nuxt 4 项目配置
+
+XUX 完美支持 Nuxt 4，提供三种配置方式：
+
+### 方式一：Nuxt 插件全局注册
+
+**1. 创建插件文件 `plugins/xux-ui.ts`**
+
+```ts
+// plugins/xux-ui.ts
+import * as XUXComponents from '@xlui/xux-ui'
+import '@xlui/xux-ui/dist/index.css'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  // 全局注册所有组件
+  Object.entries(XUXComponents).forEach(([name, component]) => {
+    if (name.startsWith('X')) {
+      nuxtApp.vueApp.component(name, component as any)
+    }
+  })
+})
+```
+
+**2. 直接使用**
 
 ```vue
 <template>
-  <XButton type="primary">按钮</XButton>
+  <div>
+    <XButton type="primary">主要按钮</XButton>
+    <XBadge :value="10">
+      <XButton>通知</XButton>
+    </XBadge>
+  </div>
 </template>
 
-<script setup>
-// 无需导入
+<script setup lang="ts">
+// 无需导入，直接使用
 </script>
 ```
 
-## 组件列表
+### 方式二：按需引入
+
+**1. 配置 `nuxt.config.ts`**
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  css: [
+    '@xlui/xux-ui/dist/index.css'
+  ],
+  
+  typescript: {
+    strict: true
+  }
+})
+```
+
+**2. 在组件中按需导入**
+
+```vue
+<template>
+  <div>
+    <XButton type="primary">主要按钮</XButton>
+    <XBadge :value="10">
+      <XButton>通知</XButton>
+    </XBadge>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { XButton, XBadge } from '@xlui/xux-ui'
+</script>
+```
 
-- [x] Button 按钮
-- [ ] Card 卡片
-- [ ] Input 输入框
-- [ ] ... 更多组件开发中
+### 方式三：自动导入（推荐！）
 
-## 开发
+**1. 安装依赖**
 
 ```bash
-# 安装依赖
-pnpm install
+pnpm add -D unplugin-vue-components
+```
+
+**2. 配置 `nuxt.config.ts`**
+
+```ts
+// nuxt.config.ts
+import Components from 'unplugin-vue-components/vite'
+
+export default defineNuxtConfig({
+  css: [
+    '@xlui/xux-ui/dist/index.css'
+  ],
+  
+  vite: {
+    plugins: [
+      Components({
+        resolvers: [
+          // 自定义解析器，自动导入 XUX 组件
+          (componentName) => {
+            if (componentName.startsWith('X')) {
+              return {
+                name: componentName,
+                from: '@xlui/xux-ui'
+              }
+            }
+          }
+        ],
+        dts: true // 自动生成类型声明文件
+      })
+    ]
+  },
+  
+  typescript: {
+    strict: true,
+    typeCheck: true
+  }
+})
+```
+
+**3. 直接使用（自动导入）**
+
+```vue
+<template>
+  <div>
+    <XButton type="primary">主要按钮</XButton>
+    <XBadge :value="10">
+      <XButton>通知</XButton>
+    </XBadge>
+    <XCard title="商品卡片">
+      <p>这是卡片内容</p>
+    </XCard>
+  </div>
+</template>
+
+<script setup lang="ts">
+// 无需导入，自动识别并导入
+// 自动生成 TypeScript 类型
+</script>
+```
+
+### Nuxt SSR 注意事项
+
+Nuxt 默认启用 SSR（服务端渲染），大部分组件都能正常工作。但如果遇到某些组件在服务端报错（如使用了 `window`、`document` 等浏览器 API），可以使用 `<ClientOnly>` 包裹：
+
+```vue
+<template>
+  <div>
+    <!-- 正常组件 -->
+    <XButton>按钮</XButton>
+    
+    <!-- 仅客户端渲染的组件 -->
+    <ClientOnly>
+      <XQrcode value="https://example.com" />
+    </ClientOnly>
+  </div>
+</template>
+```
+
+::: tip 推荐配置
+**Nuxt 4 推荐使用方式三（自动导入）**，它结合了便利性和性能优势：
+- ✅ 无需手动导入，开发体验最佳
+- ✅ 自动按需加载，打包体积小
+- ✅ 完美支持 SSR
+- ✅ 自动生成 TypeScript 类型
+:::
 
-# 开发模式
-pnpm dev
+## 🎨 使用工具函数
 
-# 构建
-pnpm build
+XUX 提供了一些实用工具函数，需要手动导入使用：
+
+### 消息提示
+
+```vue
+<script setup lang="ts">
+import { Msg } from '@xlui/xux-ui'
+
+// 成功提示
+Msg.success('操作成功！')
+
+// 错误提示
+Msg.error('操作失败！')
+
+// 警告提示
+Msg.warning('警告信息')
+
+// 信息提示
+Msg.info('提示信息')
+</script>
+```
+
+### 对话框
+
+```vue
+<script setup lang="ts">
+import { Alert } from '@xlui/xux-ui'
+
+// 确认对话框
+Alert.confirm({
+  title: '确认删除',
+  message: '确定要删除这条记录吗？',
+  onConfirm: () => {
+    console.log('确认删除')
+  },
+  onCancel: () => {
+    console.log('取消操作')
+  }
+})
+
+// 提示对话框
+Alert.show({
+  title: '提示',
+  message: '这是一条提示信息'
+})
+</script>
+```
+
+### 日期时间工具
+
+```vue
+<script setup lang="ts">
+import { DateTime } from '@xlui/xux-ui'
+
+// 格式化日期
+const formattedDate = DateTime.format(new Date(), 'YYYY-MM-DD HH:mm:ss')
+
+// 解析日期
+const date = DateTime.parse('2024-01-01')
+
+// 相对时间
+const relative = DateTime.fromNow(new Date())
+</script>
+```
+
+## 🎯 完整示例
+
+这是一个完整的电商商品卡片示例：
+
+```vue
+<template>
+  <div class="product-demo">
+    <XCard class="product-card">
+      <template #header>
+        <h3>商品信息</h3>
+      </template>
+      
+      <XThumbnailContainer :images="productImages" />
+      
+      <div class="product-info">
+        <XInput 
+          v-model="product.name" 
+          placeholder="商品名称"
+          label="名称"
+        />
+        
+        <XInput 
+          v-model="product.price" 
+          type="number"
+          placeholder="商品价格"
+          label="价格"
+        />
+        
+        <XSelect 
+          v-model="product.category"
+          :options="categories"
+          placeholder="选择分类"
+          label="分类"
+        />
+        
+        <XCheckboxes
+          v-model="product.tags"
+          :options="tagOptions"
+          label="标签"
+        />
+      </div>
+      
+      <template #footer>
+        <div class="actions">
+          <XButton @click="handleReset">重置</XButton>
+          <XButton type="primary" @click="handleSave">保存</XButton>
+        </div>
+      </template>
+    </XCard>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { 
+  XButton, 
+  XCard, 
+  XInput, 
+  XSelect, 
+  XCheckboxes,
+  XThumbnailContainer,
+  useMsg 
+} from '@xlui/xux-ui'
+
+const msg = useMsg()
+
+const product = ref({
+  name: '',
+  price: '',
+  category: '',
+  tags: []
+})
+
+const productImages = ref([
+  'https://via.placeholder.com/400x300',
+  'https://via.placeholder.com/400x300',
+])
+
+const categories = ref([
+  { label: '电子产品', value: 'electronics' },
+  { label: '服装', value: 'clothing' },
+  { label: '食品', value: 'food' },
+])
+
+const tagOptions = ref([
+  { label: '热销', value: 'hot' },
+  { label: '新品', value: 'new' },
+  { label: '折扣', value: 'discount' },
+])
+
+const handleSave = () => {
+  msg.success('保存成功！')
+  console.log('商品信息:', product.value)
+}
+
+const handleReset = () => {
+  product.value = {
+    name: '',
+    price: '',
+    category: '',
+    tags: []
+  }
+  msg.info('已重置')
+}
+</script>
+
+<style scoped>
+.product-demo {
+  max-width: 600px;
+  margin: 0 auto;
+  padding: 20px;
+}
+
+.product-info {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  margin: 20px 0;
+}
+
+.actions {
+  display: flex;
+  gap: 12px;
+  justify-content: flex-end;
+}
+</style>
 ```
 
-## 在线文档
+## 📚 组件列表
+
+XUX 提供了丰富的组件，涵盖电商场景的各种需求：
+
+### 基础组件
+- [Button 按钮](/components/button) - 常用的操作按钮
+- [Card 卡片](/components/card) - 信息展示卡片
+- [Input 输入框](/components/input) - 表单输入组件
+
+### 表单组件
+- [Select 选择器](/components/select) - 下拉选择
+- [Checkboxes 多选框](/components/checkboxes) - 多项选择
+- [CountrySelect 国家选择](/components/country-select) - 国家/地区选择
+
+### 展示组件
+- [Accordion 手风琴](/components/accordion) - 折叠面板
+- [Modal 弹窗](/components/modal) - 对话框
+- [Skeleton 骨架屏](/components/skeleton) - 加载占位
+- [ThumbnailContainer 缩略图容器](/components/thumbnail-container) - 图片展示
+
+### 反馈组件
+- [Msg 消息提示](/components/msg) - 全局提示
+
+## 🔗 相关链接
 
-访问 [在线 Demo](https://your-demo-url.com) 查看组件示例
+- [Gitee 仓库](https://gitee.com/leheya/xux)
+- [组件文档](/components/button)
+- [安装指南](/guide/installation)
+
+## ❓ 常见问题
+
+### 为什么组件没有显示？
+
+1. 确认已正确安装依赖
+2. 检查导入路径是否正确
+3. 确保 Vue 版本 >= 3.3.0
+
+### 如何自定义组件样式？
+
+所有组件都支持传入 `class` 和 `style` 属性，您可以：
+
+```vue
+<XButton class="custom-button" style="width: 200px">
+  自定义按钮
+</XButton>
+```
+
+或者使用 CSS 变量覆盖主题：
+
+```css
+.custom-button {
+  --x-color-primary: #ff6b6b;
+}
+```
+
+### TypeScript 支持
+
+XUX 完全支持 TypeScript，所有组件都有完整的类型定义：
+
+```vue
+<script setup lang="ts">
+import { XButton } from '@xlui/xux-ui'
+import type { ButtonProps } from '@xlui/xux-ui'
+
+const buttonProps: ButtonProps = {
+  type: 'primary',
+  size: 'large',
+  disabled: false
+}
+</script>
+```
 
-## License
+## 💡 下一步
 
-MIT
+- 浏览[组件文档](/components/button)了解更多组件用法
+- 查看上面的[主题定制](#主题定制)章节学习如何自定义主题
+- 访问 [Gitee 仓库](https://gitee.com/leheya/xux)反馈问题和建议
 
+开始使用 XUX，打造您的电商应用！🎉