joy-admin-components 0.2.76 → 0.2.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joy-admin-components",
-  "version": "0.2.76",
+  "version": "0.2.78",
   "main": "./dist/joy-admin-components.umd.js",
   "module": "./dist/joy-admin-components.es.js",
   "types": "./src/index.d.ts",
@@ -42,8 +42,8 @@
     "vue": "^3.5.29",
     "vue-i18n": "^11.3.0",
     "vuex": "^4.1.0",
-    "vxe-pc-ui": "4.4.26",
-    "vxe-table": "4.12.0"
+    "vxe-pc-ui": "^4.4.26",
+    "vxe-table": "^4.12.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.5",
@@ -55,7 +55,7 @@
     "vue-i18n": "^11.3.0",
     "vue-router": "4.5.0",
     "vuex": "^4.1.0",
-    "vxe-pc-ui": "4.4.26",
-    "vxe-table": "4.12.0"
+    "vxe-pc-ui": "^4.4.26",
+    "vxe-table": "^4.12.0"
   }
 }

package/src/components/ListPage/README.md

@@ -0,0 +1,273 @@
+# ListPage 全局配置使用指南
+
+## 快速开始
+
+### 1. 在项目入口配置一次（main.js）
+
+```js
+import { setListPageConfig } from 'joy-admin-components';
+
+// 配置全局分页参数（根据后端接口规范配置）
+setListPageConfig({
+  // 分页参数名
+  pageNoKey: 'pageNum',      // 页码参数名，默认 'pageNo'
+  pageSizeKey: 'pageSize',   // 每页条数参数名，默认 'pageSize'
+
+  // 分页默认值
+  defaultPageSize: 10,       // 默认每页条数，默认 10
+  pageSizes: [10, 20, 50, 100],  // 分页选项，默认 [10, 50, 100, 500]
+
+  // 响应数据字段映射（支持多种格式，按优先级尝试）
+  responseDataKeys: {
+    rows: ['data', 'list', 'rows'],    // 数据列表字段，默认 ['rows', 'records']
+    total: ['totalCount', 'total'],    // 总条数字段，默认 ['totalRows', 'total']
+  },
+
+  // UI 功能默认配置
+  showSearch: true,          // 是否显示搜索栏，默认 false
+  showPage: true,            // 是否显示分页，默认 false
+  showShadow: true,          // 是否显示阴影，默认 false
+  showCheckBox: true,        // 是否显示复选框列，默认 false
+  enableCellCopy: true,      // 是否启用单元格复制，默认 true
+});
+```
+
+### 2. 组件中无需再传配置参数
+
+```vue
+<template>
+  <!-- 之前：每次都要传各种配置 -->
+  <ListPage
+    :api="getListApi"
+    :searchForm="{
+      pageNoKey: 'pageNum',    // ❌ 不需要了！
+      showSearch: true,        // ❌ 不需要了！
+      showPage: true,          // ❌ 不需要了！
+      showCheckBox: true,      // ❌ 不需要了！
+      items: []
+    }"
+  />
+
+  <!-- 现在：直接使用，自动采用全局配置 -->
+  <ListPage
+    :api="getListApi"
+    :searchForm="{ items: [] }"
+  />
+</template>
+```
+
+## 配置项详解
+
+### 完整配置项
+
+```js
+setListPageConfig({
+  // === 请求参数配置 ===
+  pageNoKey: 'pageNo',           // 页码参数名
+  pageSizeKey: 'pageSize',       // 每页条数参数名
+
+  // === 默认值配置 ===
+  defaultPageSize: 10,           // 默认每页显示条数
+  pageSizes: [10, 50, 100, 500], // 分页器下拉选项
+
+  // === 响应数据字段映射 ===
+  responseDataKeys: {
+    rows: ['rows', 'records'],      // 数据列表字段名（优先级从左到右）
+    total: ['totalRows', 'total'],  // 总条数字段名
+  },
+
+  // === UI 功能默认配置 ===
+  showSearch: false,             // 是否显示搜索栏
+  showPage: false,               // 是否显示分页
+  showShadow: false,             // 是否显示阴影
+  showCheckBox: false,           // 是否显示复选框列
+  enableCellCopy: true,          // 是否启用单元格复制功能
+});
+```
+
+### 按需覆盖（特殊场景）
+
+如果某个页面的配置与全局配置不同，可以单独覆盖：
+
+```vue
+<template>
+  <!-- 覆盖分页参数名 -->
+  <ListPage
+    :api="getListApi"
+    :searchForm="{
+      pageNoKey: 'page',        // 覆盖全局的 pageNoKey
+      pageSizeKey: 'limit',     // 覆盖全局的 pageSizeKey
+      items: []
+    }"
+  />
+
+  <!-- 覆盖分页默认值和选项 -->
+  <ListPage
+    :api="getListApi"
+    :searchForm="{
+      defaultPageSize: 50,      // 覆盖默认每页条数
+      pageSizes: [50, 100],     // 覆盖分页选项
+      items: []
+    }"
+  />
+
+  <!-- 覆盖 UI 功能配置 -->
+  <ListPage
+    :api="getListApi"
+    :searchForm="{
+      showSearch: false,        // 这个表格不显示搜索栏
+      showCheckBox: false,      // 这个表格不显示复选框
+      enableCellCopy: false,    // 这个表格禁用单元格复制
+      items: []
+    }"
+  />
+</template>
+```
+
+## 常见后端接口格式示例
+
+### 示例 1：标准格式
+
+**接口规范：**
+- 请求：`{ pageNo: 1, pageSize: 10 }`
+- 响应：`{ code: 200, data: { rows: [], total: 100 } }`
+
+**配置：**
+```js
+// 默认配置，无需额外设置
+setListPageConfig({
+  pageNoKey: 'pageNo',
+  pageSizeKey: 'pageSize',
+  responseDataKeys: {
+    rows: ['rows', 'records'],
+    total: ['totalRows', 'total'],
+  },
+});
+```
+
+### 示例 2：自定义格式
+
+**接口规范：**
+- 请求：`{ pageNum: 1, limit: 10 }`
+- 响应：`{ code: 0, data: { list: [], totalCount: 100 } }`
+
+**配置：**
+```js
+setListPageConfig({
+  pageNoKey: 'pageNum',
+  pageSizeKey: 'limit',
+  responseDataKeys: {
+    rows: ['list'],
+    total: ['totalCount'],
+  },
+});
+```
+
+### 示例 3：兼容多种格式
+
+**接口规范：**
+- 有的接口返回 `rows`，有的返回 `records`，还有的返回 `list`
+- 有的接口返回 `total`，有的返回 `totalCount`
+
+**配置：**
+```js
+setListPageConfig({
+  responseDataKeys: {
+    // 按优先级尝试，找到第一个存在的字段
+    rows: ['list', 'rows', 'records', 'data'],
+    total: ['totalCount', 'total', 'totalRows'],
+  },
+});
+```
+
+## API 文档
+
+### setListPageConfig(config)
+
+设置全局配置。
+
+**参数：**
+- `config` (Object) - 配置对象
+  - `pageNoKey` (String) - 页码参数名
+  - `pageSizeKey` (String) - 每页条数参数名
+  - `defaultPageSize` (Number) - 默认每页条数
+  - `pageSizes` (Array\<Number\>) - 分页选项
+  - `responseDataKeys` (Object) - 响应数据字段映射
+    - `rows` (Array\<String\>) - 数据列表字段名
+    - `total` (Array\<String\>) - 总条数字段名
+  - `showSearch` (Boolean) - 是否显示搜索栏
+  - `showPage` (Boolean) - 是否显示分页
+  - `showShadow` (Boolean) - 是否显示阴影
+  - `showCheckBox` (Boolean) - 是否显示复选框列
+  - `enableCellCopy` (Boolean) - 是否启用单元格复制功能
+
+**示例：**
+```js
+setListPageConfig({
+  pageNoKey: 'pageNum',
+  defaultPageSize: 20,
+});
+```
+
+### getListPageConfig()
+
+获取当前全局配置。
+
+**返回：**
+- (Object) 当前配置对象
+
+**示例：**
+```js
+const config = getListPageConfig();
+console.log(config.pageNoKey); // 'pageNo'
+```
+
+### resetListPageConfig()
+
+重置为默认配置。
+
+**示例：**
+```js
+resetListPageConfig();
+```
+
+## 优势
+
+✅ **配置一次，全项目生效** - 不用每个页面都传分页参数和 UI 配置
+✅ **灵活覆盖** - 特殊场景可单独配置
+✅ **兼容多种接口格式** - 支持配置多个字段名按优先级尝试
+✅ **统一管理** - 所有表格的默认行为统一管理，易于维护
+✅ **向后兼容** - 不影响现有代码
+
+## 典型使用场景
+
+### 场景 1：全项目表格都需要搜索、分页和复选框
+
+```js
+// main.js - 全局配置
+setListPageConfig({
+  showSearch: true,
+  showPage: true,
+  showCheckBox: true,
+});
+```
+
+```vue
+<!-- 各个页面中 - 简洁！ -->
+<ListPage :api="getUserList" :searchForm="{ items: searchItems }" />
+<ListPage :api="getOrderList" :searchForm="{ items: searchItems }" />
+```
+
+### 场景 2：个别页面不需要某些功能
+
+```vue
+<!-- 某个简单的查看页面，只需要展示数据 -->
+<ListPage
+  :api="getLogList"
+  :searchForm="{
+    showSearch: false,   // 不需要搜索
+    showCheckBox: false, // 不需要复选框
+    items: []
+  }"
+/>
+```