joy-admin-components 0.1.35 → 0.1.37

package/README.md

@@ -1,26 +1,548 @@
 # Joy Admin Components
 
-基于Vue3和Element Plus的管理后台组件库
+基于 Vue 3、Element Plus 和 VxeTable 的管理后台组件库，提供了一套完整的后台管理系统解决方案。
 
-## 使用方法
+## 特性
 
-### 安装
+- 基于 Vue 3 Composition API
+- TypeScript 类型支持
+- 开箱即用的管理后台组件
+- 丰富的工具函数和 Hook
+- 完整的国际化支持（中英文）
+- VxeTable 自定义渲染器
+- Excel 导入导出功能
+
+## 依赖要求
+
+- Vue 3.3.4+
+- Element Plus 2.3.8+
+- VxeTable 4.12.0+
+- vue-i18n 9.10.1+
+
+## 安装
 
 ```bash
 npm install joy-admin-components
 ```
 
-### 全局注册
+或使用 yarn：
+
+```bash
+yarn add joy-admin-components
+```
+
+## 快速开始
+
+### 1. 配置国际化
+
+```js
+// main.js
+import { createApp } from 'vue';
+import { createI18n } from 'vue-i18n';
+import { setupI18n } from 'joy-admin-components';
+import App from './App.vue';
+
+// 创建 i18n 实例
+const i18n = createI18n({
+  legacy: false,
+  locale: 'zh_cn',
+  fallbackLocale: 'zh_cn',
+  messages: {
+    zh_cn: {},
+    en: {}
+  }
+});
+
+// 初始化组件库的国际化
+setupI18n(i18n);
+
+const app = createApp(App);
+app.use(i18n);
+app.mount('#app');
+```
+
+### 2. 注册 VxeTable 渲染器（可选）
+
+如果需要使用 VxeTable 的自定义渲染器：
 
 ```js
-import { createApp } from 'vue'
-import ElementPlus from 'element-plus'
-import 'element-plus/dist/index.css'
-import JoyAdminComponents from 'joy-admin-components'
-import App from './App.vue'
+import { registerVxeRenderers } from 'joy-admin-components';
 
-const app = createApp(App)
-app.use(ElementPlus)
-app.use(JoyAdminComponents)
-app.mount('#app')
+// 注册 VxeTable 渲染器
+registerVxeRenderers();
 ```
+
+### 3. 使用组件
+
+组件支持按需导入：
+
+```vue
+<template>
+  <ListPage
+    id="userList"
+    :api="getUserList"
+    :searchForm="searchForm"
+  >
+    <vxe-column field="name" title="用户名" />
+    <vxe-column field="email" title="邮箱" />
+  </ListPage>
+</template>
+
+<script setup>
+import { ListPage } from 'joy-admin-components';
+
+const searchForm = {
+  items: [
+    { key: 'name', type: 'input', name: '用户名', value: '' }
+  ]
+};
+
+async function getUserList(params) {
+  // 调用 API 获取数据
+  return {
+    data: [],
+    total: 0
+  };
+}
+</script>
+```
+
+## 组件列表
+
+### ListPage - 列表页面组件
+
+一个功能完整的列表页面组件，集成了搜索、表格、分页等功能。
+
+[ListPage](src/components/ListPage/index.vue:1)
+
+**主要 Props：**
+
+| 参数 | 说明 | 类型 | 必填 | 默认值 |
+|------|------|------|------|--------|
+| id | 表格唯一标识 | string | 是 | - |
+| api | 获取数据的 API 函数 | Function | 否 | - |
+| data | 静态数据（不使用 API 时） | Array | 否 | [] |
+| searchForm | 搜索表单配置 | Object | 是 | - |
+| immediate | 是否立即请求数据 | boolean | 否 | true |
+| loading | 加载状态 | boolean | 否 | false |
+
+**searchForm 配置：**
+
+```js
+{
+  items: [
+    {
+      key: 'field',         // 字段名
+      type: 'input',        // 类型：input/select/date/custom
+      name: '字段名称',      // 显示名称
+      value: '',            // 默认值
+      option: {}            // 其他选项
+    }
+  ],
+  showSearch: true,        // 是否显示搜索栏
+  showPage: true,          // 是否显示分页
+  showCheckBox: true,      // 是否显示复选框
+  showShadow: true         // 是否显示阴影
+}
+```
+
+**插槽：**
+
+- `search-bar-btn`: 搜索栏按钮区域
+- `table-header-left`: 表格头部左侧区域
+- `default`: 表格列定义
+
+**示例：**
+
+```vue
+<ListPage
+  id="productList"
+  :api="getProducts"
+  :searchForm="{
+    items: [
+      { key: 'name', type: 'input', name: '产品名称', value: '' },
+      { key: 'status', type: 'select', name: '状态', value: '', option: {
+        options: [
+          { label: '在售', value: 1 },
+          { label: '下架', value: 2 }
+        ]
+      }}
+    ]
+  }"
+>
+  <vxe-column field="name" title="产品名称" />
+  <vxe-column field="price" title="价格" />
+</ListPage>
+```
+
+### SearchBar - 搜索栏组件
+
+独立的搜索栏组件，支持多种输入类型。
+
+[SearchBar](src/components/SearchBar/index.vue:1)
+
+**Props：**
+
+| 参数 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| form | 表单配置 | Object | 是 |
+
+**事件：**
+
+- `confirm`: 点击筛选按钮
+- `reset`: 点击重置按钮
+- `visibleChange`: 展开/收起状态变化
+
+**表单项类型：**
+
+- `input`: 文本输入框
+- `select`: 下拉选择（使用 CmpDictionary）
+- `date`: 日期选择器
+- `custom`: 自定义渲染
+
+**示例：**
+
+```vue
+<SearchBar
+  :form="{
+    items: [
+      { key: 'keyword', type: 'input', name: '关键词', value: '' },
+      { key: 'createTime', type: 'date', name: '创建时间', value: '', dateType: 'daterange' }
+    ]
+  }"
+  @confirm="handleSearch"
+  @reset="handleReset"
+>
+  <template #btn>
+    <el-button>自定义按钮</el-button>
+  </template>
+</SearchBar>
+```
+
+### LayOutForm - 布局表单组件
+
+自动布局的表单组件。
+
+[LayOutForm](src/components/LayOutForm/index.vue:1)
+
+### CmpDictionary - 字典选择器
+
+支持静态选项和动态加载的选择器组件。
+
+[CmpDictionary](src/components/CmpDictionary/index.vue:1)
+
+### CmpIcon - 图标组件
+
+Element Plus 图标包装组件，简化图标使用。
+
+[CmpIcon](src/components/CmpIcon/index.vue:1)
+
+**Props：**
+
+| 参数 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| name | 图标名称 | string | 是 |
+
+**示例：**
+
+```vue
+<template>
+  <CmpIcon name="Edit" />
+  <CmpIcon name="Delete" />
+  <CmpIcon name="Search" />
+</template>
+
+<script setup>
+import { CmpIcon } from 'joy-admin-components';
+</script>
+```
+
+### ConfrimButton - 确认按钮
+
+带二次确认的操作按钮。
+
+[ConfrimButton](src/components/ConfrimButton/index.vue:1)
+
+### ImportButton - 导入按钮
+
+Excel 文件导入按钮。
+
+[ImportButton](src/components/ImportButton/index.vue:1)
+
+### DownExcelTemp - 下载模板按钮
+
+Excel 模板下载按钮。
+
+[DownExcelTemp](src/components/DownExcelTemp/index.vue:1)
+
+## 工具函数
+
+### 验证工具
+
+```js
+import { creatValidator } from 'joy-admin-components';
+
+// 创建表单验证器
+const validator = creatValidator(rules);
+```
+
+### 加密工具
+
+```js
+import { crypto } from 'joy-admin-components';
+
+// 使用加密功能
+const encrypted = crypto.encrypt(data);
+const decrypted = crypto.decrypt(encrypted);
+```
+
+### Excel 工具
+
+```js
+import { importExcel, exportExcel } from 'joy-admin-components';
+
+// 导入 Excel
+const data = await importExcel(file);
+
+// 导出 Excel
+exportExcel(data, 'filename.xlsx');
+```
+
+### 通用工具函数
+
+```js
+import {
+  sleep,                  // 延迟执行
+  _toRaw,                // 转换为原始对象
+  arrayToTree,           // 数组转树形结构
+  stringToArray,         // 字符串转数组
+  StatusMap,             // 状态映射类
+  arrToStatusMap,        // 数组转状态映射
+  stripHtmlTags,         // 移除 HTML 标签
+  unicode2Str,           // Unicode 转字符串
+  checkFileSize,         // 检查文件大小
+  createListPageId,      // 创建列表页 ID
+  createImportFields,    // 创建导入字段配置
+  getValueBykey          // 根据 key 获取值
+} from 'joy-admin-components';
+```
+
+### Hook 函数
+
+```js
+import {
+  useRequest,            // 请求 Hook
+  useDatePicker,         // 日期选择器 Hook
+  _typeOf,               // 类型判断
+  useI18nReState,        // 国际化响应式状态
+  getLocaleValue,        // 获取本地化值
+  useState,              // Vuex state Hook
+  useGetters,            // Vuex getters Hook
+  useActions             // Vuex actions Hook
+} from 'joy-admin-components';
+```
+
+## VxeTable 渲染器
+
+`registerVxeRenderers` 提供了 5 种常用的 VxeTable 自定义渲染器，简化数据展示逻辑。
+
+### 注册渲染器
+
+在应用入口文件中注册：
+
+```js
+import { registerVxeRenderers } from 'joy-admin-components';
+
+// 注册 VxeTable 渲染器
+registerVxeRenderers();
+```
+
+### 内置渲染器
+
+| 渲染器 | 说明 | 使用场景 |
+|--------|------|----------|
+| **Enum** | 枚举值渲染器 | 状态、类型等枚举数据，支持彩色标签 |
+| **InputNumber** | 数字输入渲染器 | 表格内直接编辑数字 |
+| **TrueFalse** | 布尔值渲染器 | 是/否、真/假等布尔值，自动国际化 |
+| **I18n** | 国际化渲染器 | 根据语言环境自动切换字段 |
+| **Link** | 跳转链接渲染器 | 可点击跳转的链接，支持多个链接 |
+
+### 详细文档
+
+每个渲染器的详细参数、配置选项和高级用法，请查看：
+
+📖 [VxeTable 渲染器完整文档](registerVxeRenderers.md)
+
+## 国际化
+
+组件库内置完整的国际化支持，详细使用说明请查看：[国际化文档](README-i18n.md)
+
+**快速配置：**
+
+```js
+import { createI18n } from 'vue-i18n';
+import { setupI18n } from 'joy-admin-components';
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'zh_cn',
+  messages: { zh_cn: {}, en: {} }
+});
+
+setupI18n(i18n);
+```
+
+**切换语言：**
+
+```js
+import { useI18n } from 'vue-i18n';
+
+const { locale } = useI18n();
+locale.value = 'en'; // 切换为英文
+```
+
+## TypeScript 支持
+
+所有组件和函数都包含 TypeScript 类型定义：
+
+```ts
+import type { SearchFormConfig } from 'joy-admin-components';
+
+const searchForm: SearchFormConfig = {
+  items: [
+    { key: 'name', type: 'input', name: '名称', value: '' }
+  ]
+};
+```
+
+## 完整示例
+
+```vue
+<template>
+  <div class="page">
+    <ListPage
+      id="userManagement"
+      :api="getUserList"
+      :searchForm="searchForm"
+      @selection-change="handleSelectionChange"
+    >
+      <template #search-bar-btn>
+        <el-button type="primary" @click="handleAdd">新增用户</el-button>
+        <ImportButton :api="importUsers" @success="refresh" />
+        <DownExcelTemp :template="userTemplate" />
+      </template>
+
+      <vxe-column field="id" title="ID" width="80" />
+
+      <vxe-column
+        field="name"
+        title="用户名"
+        cell-render="I18n"
+        :cell-render-data="{ fieldEn: 'nameEn' }"
+      />
+
+      <vxe-column
+        field="status"
+        title="状态"
+        cell-render="Enum"
+        :cell-render-data="{ enum: statusEnum }"
+      />
+
+      <vxe-column
+        field="isActive"
+        title="是否激活"
+        cell-render="TrueFalse"
+      />
+
+      <vxe-column title="操作" width="150">
+        <template #default="{ row }">
+          <el-button text @click="handleEdit(row)">编辑</el-button>
+          <ConfrimButton
+            text
+            type="danger"
+            @confirm="handleDelete(row.id)"
+          >
+            删除
+          </ConfrimButton>
+        </template>
+      </vxe-column>
+    </ListPage>
+  </div>
+</template>
+
+<script setup>
+import {
+  ListPage,
+  ImportButton,
+  DownExcelTemp,
+  ConfrimButton,
+  registerVxeRenderers
+} from 'joy-admin-components';
+import { ref } from 'vue';
+
+// 注册 VxeTable 渲染器
+registerVxeRenderers();
+
+// 搜索表单配置
+const searchForm = {
+  items: [
+    { key: 'name', type: 'input', name: '用户名', value: '' },
+    { key: 'status', type: 'select', name: '状态', value: '', option: {
+      options: [
+        { label: '启用', value: 1 },
+        { label: '禁用', value: 2 }
+      ]
+    }},
+    { key: 'createTime', type: 'date', name: '创建时间', value: '', dateType: 'daterange' }
+  ]
+};
+
+// 状态枚举
+const statusEnum = {
+  getName: (value) => ({ 1: '启用', 2: '禁用' }[value] || '-'),
+  getTag: (value) => ({ 1: 'success', 2: 'danger' }[value] || 'info')
+};
+
+// API 函数
+async function getUserList(params) {
+  const response = await fetch('/api/users', {
+    method: 'POST',
+    body: JSON.stringify(params)
+  });
+  return response.json();
+}
+
+// 事件处理
+function handleSelectionChange(selection) {
+  console.log('选中的数据：', selection);
+}
+
+function handleAdd() {
+  // 新增用户逻辑
+}
+
+function handleEdit(row) {
+  // 编辑用户逻辑
+}
+
+function handleDelete(id) {
+  // 删除用户逻辑
+}
+</script>
+```
+
+## 浏览器支持
+
+- Chrome >= 87
+- Firefox >= 78
+- Safari >= 14
+- Edge >= 88
+
+## 更多文档
+
+- [国际化使用说明](README-i18n.md)
+- [VxeTable 渲染器文档](docs/registerVxeRenderers.md)
+
+## License
+
+MIT