wkjp-list-page 1.0.10 → 1.0.12

package/README.md

@@ -2,7 +2,7 @@
 
 Vue 2 + Element UI 通用列表页组件 **`CommonListPage`**（标签 `common-list-page`）：搜索区、表格、分页；列表数据由组件通过 **`api`** 拉取并在内部维护分页与加载状态。
 
-**npm 当前版本：`2.2.0`**（`2.x` 起 **`api` 为必填**；**`auto-request` 默认 `false`**，首屏需自行 `fetchList` 或设为 `true`。）
+**npm 包：`wkjp-list-page`**（**`api` 为必填**；**`block-list-request` 默认 `false`** 时组件会正常发起列表请求；设为 **`true`** 则**拦截本组件内所有**对 `api` 的列表请求，需由父页面在适当时机 **`this.$refs.xxx.fetchList({ force: true })`** 主动拉表。）
 
 ## 环境
 
@@ -47,7 +47,6 @@ Vue.use(CommonListPage);
   :search-option="deviceListSearchOption"
   :columns="deviceListColumns"
   :api="deviceListApi"
-  :auto-request="true"
 />
 ```
 
@@ -73,7 +72,7 @@ deviceListApi(params) {
 
 - 发请求时带什么参数：不写 `build-params` 时，会把 **`filters` 里所有条件** 再加上 **当前第几页、每页几条**（字段名是 `currentPage`、`pageSize`，也会写回 `filters`）。若写了 `build-params`，则由你 **自己 return 整包参数**，既可改分页字段名，也可在 `filters` 之外 **单独加** 路由、父级状态等条件。
 - 接口返回怎么用：不写 `api-adapter` 时，认为列表在 **`res.object.list`**，总条数在 **`res.object.num`**。
-- **首屏列表**：默认 **`auto-request` 为 `false`**，进入页面**不会**自动调 `api`；需要一进页就查表时请加 **`:auto-request="true"`**，或在 `mounted` 里 **`this.$refs.deviceListRef.fetchList()`**。
+- **首屏列表**：默认 **`block-list-request` 为 `false`**，组件会照常 **`fetchList`**（含 `created`、查询、分页等）。若 **`block-list-request` 为 `true`**，上述内部调用**一律不请求** `api`；需要数据时请 **`this.$refs.xxx.fetchList({ force: true })`**（可带 **`resetPage: true`**）。
 
 下面这些是 **可选**：先照 §1 能跑起来，遇到对应场景再往组件上 **多绑一个属性** 即可。
 
@@ -204,13 +203,15 @@ deviceListTransformList(list) {
 }
 ```
 
-### 2.10 一进页面就要自动查一次
+### 2.10 完全由父页面控制列表请求（`block-list-request`）
 
-**情况：** 希望打开页面就和以前一样立刻拉列表（`created` 里自动 `fetchList`）。  
-**加：** `:auto-request="true"`  
-**说明：** 默认 **`auto-request` 为 `false`**，进页不请求；可在 `mounted` 里 `this.$refs.xxx.fetchList()`，或打开本开关。
+> **迁移：** 旧版曾使用 **`auto-request`** / **`autoRequest`**，已更名为 **`block-list-request`** / **`blockListRequest`**（为 **`true`** 时内部不调 `api`）。
 
-**补充：** `fetchList({ resetPage: true })` 会从第 1 页重新查；`false` 表示保持当前页。
+**情况：** 不希望列表组件在 **`created`、点查询、分页、`autoQuery`** 等场景里自动调 `api`，由外层统一请求或延后请求。  
+**加：** `:block-list-request="true"`  
+**说明：** 默认 **`block-list-request` 为 `false`**：不拦截，与往常一样。为 **`true`** 时，组件内部所有 **`fetchList` 都不会真正请求** `api`（**一次都不会**）。需要拉表时请 **`this.$refs.xxx.fetchList({ force: true })`**；从第一页重查可 **`fetchList({ force: true, resetPage: true })`**。
+
+**补充：** 带 **`force: true`** 时，仍可用 **`resetPage: true`** 从第一页重查；不带 `force` 且 `block-list-request` 为 `true` 时调用 `fetchList` 仍不会请求。
 
 ### 2.11 不想要「清除查询」，或想改按钮上的字
 
@@ -235,7 +236,7 @@ deviceListTransformList(list) {
 **情况：** 下拉只要 10、20、50，不要默认一长串。  
 **加：** `:pagination="{ pSizes: [10, 20, 50] }"`  
 **说明：** 这里的 **`pagination` 只用来合并进组件内部分页**（改 `pSizes` 等），不是让你自己维护当前第几页、总条数——那些仍是组件内部根据接口结果在管。  
-**隐藏分页条：** 当 **`total` 不大于 `pSizes` 中的最小值**（例如共 3 条、最小每页 10 条）时，不再渲染底部分页器，避免无意义的「每页条数」与翻页。
+**分页 `layout`：** 当 **`total` 不大于 `pSizes` 中的最小值**（例如共 3 条、最小每页 10 条）时，**不显示「每页条数」下拉与「前往页」**，只保留总数与翻页；数据超过一页时再显示完整分页控件。
 
 ---
 
@@ -264,7 +265,7 @@ deviceListTransformList(list) {
 | `buildParams` | `null` | 自定义整包请求参数；可改分页字段名，也可在 `filters` 外追加条件。 |
 | `apiAdapter` | `null` | `(res) => ({ list, total })`。 |
 | `transformList` | `null` | 入表前改 `list`。 |
-| `autoRequest` | `false` | 为 `true` 时在 `created` 自动请求一次；默认不请求，需自行 `fetchList` 或打开本项。 |
+| `blockListRequest` | `false` | **`true`**：拦截组件内所有列表请求（`fetchList` 不调 `api`）；拉表用 **`fetchList({ force: true })`**。**`false`**：不拦截，照常请求。 |
 | `enableColumnConfig` | `false` | `true` 显示「配置表单」弹窗。 |
 | `showExport` | `false` | 为 `true` 且提供 `exportApi` 时，在搜索区右侧显示内置 **`exportFile`** 导出按钮。 |
 | `exportApi` | `null` | `(params, headers?) => Promise`，导出请求；成功返回需含 `success`、`object`（下载链接），与内置导出组件约定一致。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wkjp-list-page",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Vue2 + ElementUI CommonListPage component",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/components/CommonListPage.vue

@@ -137,15 +137,15 @@
     </el-table>
 
     <el-pagination
-      v-if="showPaginationBar"
+      v-if="innerPagination"
       background
       :total="innerPagination.total"
       :current-page="innerPagination.page"
       :page-size="innerPagination.pageSize"
       :page-sizes="innerPagination.pSizes || [10, 50, 100, 200]"
+      :layout="paginationLayout"
       @size-change="handleSizeChange"
       @current-change="handlePageChange"
-      layout="total, sizes, prev, pager, next, jumper"
     ></el-pagination>
 
     <el-dialog
@@ -210,8 +210,12 @@ export default {
     apiAdapter: { type: Function, default: null },
     /** 写入表格前：`(list, rawRes) => list`，须返回数组 */
     transformList: { type: Function, default: null },
-    /** 是否在 `created` 时自动请求一次；默认不请求，需自行 `fetchList` 或设 `true` */
-    autoRequest: { type: Boolean, default: false },
+    /**
+     * 为 **`true`** 时：**阻止本组件发起的所有列表请求**（`created`、查询、分页、`autoQuery` 等内部 `fetchList` 均不调 `api`）。
+     * 父页面需要拉表时，请 **`this.$refs.xxx.fetchList({ force: true })`**（可配合 **`resetPage: true`**）。
+     * 为 **`false`**（默认）：不拦截，行为与往常一样。
+     */
+    blockListRequest: { type: Boolean, default: false },
     /**
      * 可选：与内部分页合并，用于覆盖 `pSizes`、`pageSize` 等（如 `{ pSizes: [10, 20, 50] }`）。
      * 不传则使用组件内默认分页配置。
@@ -346,10 +350,15 @@ export default {
       const nums = sizes.map((n) => Number(n)).filter((n) => Number.isFinite(n) && n > 0);
       return nums.length ? Math.min.apply(null, nums) : 10;
     },
-    /** 总数不超过「每页条数」选项里的最小值时，不展示分页条（单页即可看完） */
-    showPaginationBar() {
-      if (!this.innerPagination) return false;
-      return this.innerPagination.total > this.paginationMinPageSize;
+    /**
+     * 当 **`total` 不大于 `pSizes` 最小值**（单页即可装下）时，从 `layout` 去掉 **`sizes`**（每页条数）与 **`jumper`**（前往页），
+     * 仍保留 **总数、上一页、页码、下一页**；多页时再显示完整布局。
+     */
+    paginationLayout() {
+      if (!this.innerPagination) return "total, prev, pager, next";
+      const full = "total, sizes, prev, pager, next, jumper";
+      if (this.innerPagination.total > this.paginationMinPageSize) return full;
+      return "total, prev, pager, next";
     },
     exportQuerys() {
       return this.filters && typeof this.filters === "object" ? this.filters : {};
@@ -411,7 +420,7 @@ export default {
   created() {
     this.captureInitialFilters();
     this.applyInnerPaginationConfig();
-    if (this.autoRequest) this.fetchList();
+    this.fetchList();
   },
   methods: {
     forwardSelectionChange(selection) {
@@ -616,7 +625,13 @@ export default {
       }
       return { list: [], total: 0 };
     },
-    fetchList({ resetPage = false } = {}) {
+    fetchList(opts) {
+      const o = opts && typeof opts === "object" ? opts : {};
+      const resetPage = o.resetPage === true;
+      const force = o.force === true;
+      if (this.blockListRequest && !force) {
+        return Promise.resolve();
+      }
       if (resetPage) this.innerPagination.page = 1;
       this.syncPaginationToFilters();
       const params = this.buildRequestParams();