wkjp-list-page 1.0.13 → 1.0.15

package/README.md

@@ -72,7 +72,7 @@ deviceListApi(params) {
 
 - 发请求时带什么参数：不写 `build-params` 时，会把 **`filters` 里所有条件** 再加上 **当前第几页、每页几条**（字段名是 `currentPage`、`pageSize`，也会写回 `filters`）。若写了 `build-params`，则由你 **自己 return 整包参数**，既可改分页字段名，也可在 `filters` 之外 **单独加** 路由、父级状态等条件。
 - 接口返回怎么用：不写 `api-adapter` 时，认为列表在 **`res.object.list`**，总条数在 **`res.object.num`**。
-- **首屏列表**：默认 **`block-list-request` 为 `false`**，组件会照常 **`fetchList`**（含 `created`、查询、分页等）。若 **`block-list-request` 为 `true`**，上述内部调用**一律不请求** `api`；需要数据时请 **`this.$refs.xxx.fetchList({ force: true })`**（可带 **`resetPage: true`**）。
+- **首屏列表**：默认 **`block-list-request` 为 `false`** 且 **`fetch-on-created` 为 `true`** 时，组件会在 **`created`** 里自动 **`fetchList`**。若 **`fetch-on-created` 为 `false`**，则不在 `created` 里请求，由父页面择机 **`fetchList`**。若 **`block-list-request` 为 `true`**，内部调用一律不请求 `api`；需要数据时请 **`this.$refs.xxx.fetchList({ force: true })`**（可带 **`resetPage: true`**）。
 
 下面这些是 **可选**：先照 §1 能跑起来，遇到对应场景再往组件上 **多绑一个属性** 即可。
 
@@ -82,7 +82,7 @@ deviceListApi(params) {
 
 每一段都是：**你可能遇到的情况 → 加什么 → 干什么用**。
 
-**阅读顺序：** 和界面更相关的（列配置、查询/清除、搜索折叠、表格样式、`search-extra`、**内置导出**）放在 **2.1～2.6**；和接口、数据流相关的放在 **2.7～2.11**；再往后是插槽、多选、分页选项。
+**阅读顺序：** 和界面更相关的（列配置、查询/清除、搜索折叠、表格样式、`search-extra`、**内置导出**）放在 **2.1～2.6**；和接口、数据流相关的放在 **2.7～2.10**（另见 **2.10.1** 首屏是否自动请求）；再往后是插槽、多选、分页选项。
 
 ### 2.1 想让用户在页面上自己勾选显示哪些列、拖顺序
 
@@ -213,6 +213,13 @@ deviceListTransformList(list) {
 
 **补充：** 带 **`force: true`** 时，仍可用 **`resetPage: true`** 从第一页重查；不带 `force` 且 `block-list-request` 为 `true` 时调用 `fetchList` 仍不会请求。
 
+### 2.10.1 首屏不在 `created` 里自动请求（`fetch-on-created`）
+
+**情况：** 首屏列表要由父页面**先**走别的流程（例如先选驾校、先拿路由参数再拼条件），不希望组件一进页就调 `api`。  
+**加：** `:fetch-on-created="false"`（默认 **`true`**，保持原先「`created` 即拉表」）。  
+**说明：** 为 **`false`** 时**仅跳过** `created` 里的那一次请求；点「查询」、分页、`autoQuery` 等仍会照常 `fetchList`。需要首屏数据时在合适时机 **`this.$refs.xxx.fetchList()`**（必要时带 **`resetPage: true`**）。  
+**与 `block-list-request`：** 后者为 **`true`** 会拦住**包括** `created` 在内的所有内部请求；若只想关掉首屏自动请求、其余仍交给组件，用 **`fetch-on-created`** 即可。
+
 ### 2.11 不想要「清除查询」，或想改按钮上的字
 
 **情况：** 没有「恢复初始条件」的需求；或想把文案改成「重置」。  
@@ -266,6 +273,7 @@ deviceListTransformList(list) {
 | `apiAdapter` | `null` | `(res) => ({ list, total })`。 |
 | `transformList` | `null` | 入表前改 `list`。 |
 | `blockListRequest` | `false` | **`true`**：拦截组件内所有列表请求（`fetchList` 不调 `api`）；拉表用 **`fetchList({ force: true })`**。**`false`**：不拦截，照常请求。 |
+| `fetchOnCreated` | `true` | **`false`**：不在 **`created`** 里自动发起首次列表请求，由父页面择机 **`fetchList`**；查询、分页、`autoQuery` 等仍照常。 |
 | `enableColumnConfig` | `false` | `true` 显示「配置表单」弹窗。 |
 | `showExport` | `false` | 为 `true` 且提供 `exportApi` 时，在搜索区右侧显示内置 **`exportFile`** 导出按钮。 |
 | `exportApi` | `null` | `(params, headers?) => Promise`，导出请求；成功返回需含 `success`、`object`（下载链接），与内置导出组件约定一致。 |
@@ -302,7 +310,7 @@ deviceListTransformList(list) {
 | `input` | **`clearable` 默认 `true`**（有内容时出现清除）；`false` 关闭。另有 `maxlength`、`height`；回车触发 `query` 事件（不自动 `fetchList`）；其它类型若设 `autoQuery: true` 则变更后自动查。 |
 | `select` | `options`（平铺选项）、`multiple`、`clearable`（默认 true）、`filterable`、`disabled`。 |
 | `cascader` | **`options`** 为级联树；**`props` 或 `cascaderProps`** 为 `el-cascader` 的字段映射；`filters[prop]` 为 **路径数组**；可选 `filterable`、`collapseTags`、`showAllLevels`、`separator`、`debounce`、`height`。 |
-| 日期范围 | **`daterange` 未传 `valueFormat` 时默认 `yyyy-MM-dd`**（`date` / `month` / `year` / `datetime` 等同理，与 Element 约定不符时请自行传 `valueFormat`）。**`startPlaceholder` / `endPlaceholder` 未传时默认「开始日期」「结束日期」**（与上浮文案一致）。**`unlinkPanels`** 默认 `true`（对应 Element `unlink-panels`，左右面板月份独立）；设为 `false` 则两面板联动。另有 `rangeSeparator`（默认「至」）；可选 **`gmtBeginKey` / `gmtEndKey`** 同步写带时间的起止字段。 |
+| 日期范围 | **`daterange` 未传 `valueFormat` 时默认 `yyyy-MM-dd`**（`date` / `month` / `year` / `datetime` 等同理，与 Element 约定不符时请自行传 `valueFormat`）。**`placeholders: [开始文案, 结束文案]`** 控制范围上浮文案，未传时默认「开始日期」「结束日期」（兼容旧写法 `startPlaceholder` / `endPlaceholder`）。**`unlinkPanels`** 默认 `true`（对应 Element `unlink-panels`，左右面板月份独立）；设为 `false` 则两面板联动。另有 `rangeSeparator`（默认「至」）；可选 **`gmtKeys: [beginFilterKey, endFilterKey]`** 同步写带 `00:00:00` / `23:59:59` 的起止字段（兼容 `gmtBeginKey` / `gmtEndKey`）。 |
 
 ---
 

package/package.json

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

package/src/components/CommonListPage.vue

@@ -216,6 +216,12 @@ export default {
      * 为 **`false`**（默认）：不拦截，行为与往常一样。
      */
     blockListRequest: { type: Boolean, default: false },
+    /**
+     * 是否在 **`created`** 时自动发起**首次**列表请求（内部调用 `fetchList`）。
+     * 默认 **`true`**（与历史行为一致）；为 **`false`** 时不在 `created` 里请求，首屏由父页面用其它方式准备好条件后再 **`this.$refs.xxx.fetchList()`**。
+     * 与 **`block-list-request`** 独立：后者拦截**所有**内部触发的 `fetchList`；若仅需关闭「一进页就请求」、查询/分页等仍交给组件，请用本项。
+     */
+    fetchOnCreated: { type: Boolean, default: true },
     /**
      * 可选：与内部分页合并，用于覆盖 `pSizes`、`pageSize` 等（如 `{ pSizes: [10, 20, 50] }`）。
      * 不传则使用组件内默认分页配置。
@@ -420,7 +426,9 @@ export default {
   created() {
     this.captureInitialFilters();
     this.applyInnerPaginationConfig();
-    this.fetchList();
+    if (this.fetchOnCreated) {
+      this.fetchList();
+    }
   },
   methods: {
     forwardSelectionChange(selection) {
@@ -493,14 +501,35 @@ export default {
       const text = (item.label || item.placeholder || "").trim();
       return text || " ";
     },
+    /** `placeholders: [开始, 结束]`；兼容 `startPlaceholder` / `endPlaceholder` */
+    resolveRangePlaceholders(item) {
+      if (Array.isArray(item.placeholders) && item.placeholders.length >= 2) {
+        return [
+          String(item.placeholders[0] != null ? item.placeholders[0] : "").trim(),
+          String(item.placeholders[1] != null ? item.placeholders[1] : "").trim()
+        ];
+      }
+      return [(item.startPlaceholder || "").trim(), (item.endPlaceholder || "").trim()];
+    },
     dateRangeStartText(item) {
-      const t = (item.startPlaceholder || "").trim();
+      const t = this.resolveRangePlaceholders(item)[0];
       return t || "开始日期";
     },
     dateRangeEndText(item) {
-      const t = (item.endPlaceholder || "").trim();
+      const t = this.resolveRangePlaceholders(item)[1];
       return t || "结束日期";
     },
+    /** `gmtKeys: [beginFilterKey, endFilterKey]`；兼容 `gmtBeginKey` / `gmtEndKey` */
+    resolveGmtKeys(item) {
+      if (Array.isArray(item.gmtKeys) && item.gmtKeys.length >= 2) {
+        const begin = item.gmtKeys[0];
+        const end = item.gmtKeys[1];
+        if (begin && end) return [begin, end];
+        return null;
+      }
+      if (item.gmtBeginKey && item.gmtEndKey) return [item.gmtBeginKey, item.gmtEndKey];
+      return null;
+    },
     resolveInputString(item) {
       if (!item.prop) return "";
       const v = this.filters[item.prop];
@@ -512,13 +541,16 @@ export default {
     },
     handleFieldChange(item, value) {
       if (item.prop) this.$set(this.filters, item.prop, value);
-      if (item.gmtBeginKey && item.gmtEndKey) {
+      const gmtKeys = this.resolveGmtKeys(item);
+      if (gmtKeys) {
+        const beginKey = gmtKeys[0];
+        const endKey = gmtKeys[1];
         if (Array.isArray(value) && value.length === 2 && value[0] && value[1]) {
-          this.$set(this.filters, item.gmtBeginKey, `${value[0]} 00:00:00`);
-          this.$set(this.filters, item.gmtEndKey, `${value[1]} 23:59:59`);
+          this.$set(this.filters, beginKey, `${value[0]} 00:00:00`);
+          this.$set(this.filters, endKey, `${value[1]} 23:59:59`);
         } else {
-          this.$set(this.filters, item.gmtBeginKey, "");
-          this.$set(this.filters, item.gmtEndKey, "");
+          this.$set(this.filters, beginKey, "");
+          this.$set(this.filters, endKey, "");
         }
       }
       if (typeof item.onChange === "function") item.onChange(value);
@@ -737,9 +769,9 @@ export default {
   align-items: center;
   width: 100%;
   box-sizing: border-box;
-  margin-bottom: 14px;
+  /*margin-bottom: 14px;*/
   padding-bottom: 14px;
-  border-bottom: 1px solid #f0f2f5;
+  /*border-bottom: 1px solid #f0f2f5;*/
 }
 
 /* 覆盖业务里 el-form-item.right 等 float，避免与右侧成组抢布局 */