wkjp-list-page 1.0.0 → 1.0.4

package/README.md

@@ -1,55 +1,321 @@
-# wkjp-common-list-page
+# wkjp-list-page
 
-基于 Vue2 + ElementUI 的通用列表组件，支持：
-- 配置化搜索区
-- 配置化表格列（含 slot）
-- 托管请求模式（api/buildParams/apiAdapter）
-- 列配置弹窗（显隐 + 拖拽排序）
+Vue 2 + Element UI 通用列表页组件 **`CommonListPage`**（标签 `common-list-page`）：搜索区、表格、分页；列表数据由组件通过 **`api`** 拉取并在内部维护分页与加载状态。
 
-## 安装
+**npm 当前版本：`2.2.0`**（`2.x` 起 **`api` 为必填**；**`auto-request` 默认 `false`**，首屏需自行 `fetchList` 或设为 `true`。）
+
+## 环境
+
+- `vue` ^2.6.14  
+- `element-ui` ^2.15.14（需引入 `element-ui/lib/theme-chalk/index.css`，并保证图标字体能被构建加载）
+
+## 安装与注册
 
 ```bash
-npm i wkjp-common-list-page
+npm i wkjp-list-page
 ```
 
-## 使用
-
 ```js
 import Vue from "vue";
 import ElementUI from "element-ui";
 import "element-ui/lib/theme-chalk/index.css";
-import CommonListPage from "wkjp-common-list-page";
+import CommonListPage from "wkjp-list-page";
 
 Vue.use(ElementUI);
 Vue.use(CommonListPage);
 ```
 
-或按需引入：
+按需引入：`import { CommonListPage } from "wkjp-list-page"`，在 `components` 里注册即可。
+
+---
+
+## 1. 默认就够用的写法
+
+日常列表页，**固定会写**的通常是：`ref`、`filters`、`search-option`、`columns`、`api`。  
+**`filters`** 为必填（查询条件对象，会被组件原地改写，不要每次用字面量新建）。**`api`** 为必填（返回 `Promise`，resolve 为接口原始 JSON）。
+
+**`search-option` 和 `filters` 各管什么？**  
+- **`search-option`**：像一张「表单说明书」——每一项写 **类型**（输入框/下拉/日期）、**文案**、**字段名叫什么**（`prop`）、宽度等。它 **不存你输入的值**。  
+- **`filters`**：才是真正 **存值** 的对象，键名要和 `search-option` 里每一项的 **`prop` 对上**。组件把 `el-form` 绑在它上面，你打字、选日期时改的都是这里；发请求时默认也会把这里面的键值带给接口；「清除查询」也是把这里 **恢复成刚进页时的快照**。  
+
+所以两个都要传：**一个说明长什么样，一个装当前筛出来的数据**；没有 `filters` 就没有统一的地方放这些值，也没法和父页面、路由、接口参数对齐。
+
+```vue
+<common-list-page
+  ref="deviceListRef"
+  :filters="deviceListFilters"
+  :search-option="deviceListSearchOption"
+  :columns="deviceListColumns"
+  :api="deviceListApi"
+  :auto-request="true"
+/>
+```
 
 ```js
-import { CommonListPage } from "wkjp-common-list-page";
+// data 示例（命名仅作示例，按你页面改）
+deviceListFilters: { keyword: "", status: "" },
+deviceListSearchOption: [
+  { type: "input", prop: "keyword", label: "关键词", autoQuery: false },
+  { type: "select", prop: "status", label: "状态", options: [{ label: "全部", value: "" }], autoQuery: false }
+],
+deviceListColumns: [
+  { type: "index", label: "#", width: 55 },
+  { prop: "name", label: "名称", minWidth: 140 }
+],
 
-export default {
-  components: { CommonListPage }
-};
+// methods
+deviceListApi(params) {
+  return this.$http.get("/api/device/list", { 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()`**。
+
+下面这些是 **可选**：先照 §1 能跑起来，遇到对应场景再往组件上 **多绑一个属性** 即可。
+
+---
+
+## 2. 按需求往上加
+
+每一段都是：**你可能遇到的情况 → 加什么 → 干什么用**。
+
+**阅读顺序：** 和界面更相关的（列配置、查询/清除、搜索折叠、表格样式、`search-extra`、**内置导出**）放在 **2.1～2.6**；和接口、数据流相关的放在 **2.7～2.11**；再往后是插槽、多选、分页选项。
+
+### 2.1 想让用户在页面上自己勾选显示哪些列、拖顺序
+
+**情况：** 运营想「配置表单」、列太多想藏起来。  
+**加：** 写上 **`enable-column-config`**（或 `:enable-column-config="true"`）  
+**作用：** 出现「配置表单」按钮和弹窗；左右固定列在弹窗里一般不让拖乱顺序。点确定会 **`columns-change`** 把当前列配置抛给父页面。
+
+### 2.2 不想要「查询」按钮，或想改按钮上的字
+
+**情况：** 全部自动查询、不需要单独点一下；或想把「查询」改成「搜索」。  
+**加：** `:show-query-button="false"` 或 `:query-button-text="'搜索'"`
+
+### 2.3 搜索条件太多，一屏排不下
+
+**情况：** 想默认只露前几项，其余用「展开查询 / 收起」收起来。  
+**加：** `:collapse-search="true"`；**`:search-visible-max`** 可省略，省略时默认只露出前 **6** 条查询项，其余用「展开查询 / 收起」。需要别的条数时再写数字（如 `4`）。  
+**可选：** `:expand-search-text`、`:fold-search-text` 改展开、收起两个词。
+
+### 2.4 想改表格条纹、边框、高度，或表头颜色
+
+**情况：** 和 Element 文档一样，想给 `el-table` 加属性、改表头底色。  
+**加：** `:table-attrs="{ stripe: true, border: true, height: 400 }"` 等；表头底色用 **`table-header-bg`**。若你在 `table-attrs` 里也写了表头背景，以 Element 合并结果为准。
+
+### 2.5 想在「查询 / 清除」右边加「设备入网」等自己的按钮
+
+**情况：** 和组件自带按钮排在一行，靠右。  
+**加：** 用插槽 **`search-extra`** 里写你的按钮（有「配置表单」时，设备入网一般在它左边那一块）。
 
 ```vue
-<template>
-  <common-list-page
-    :filters="filters"
-    :search-option="searchOption"
-    :columns="columns"
-    :api="apiFn"
-    :enable-column-config="true"
-  />
+<template #search-extra>
+  <el-button type="primary" plain @click="exportList">设备入网</el-button>
 </template>
 ```
 
-## 发布
+### 2.6 列表上要「导出」按钮，并直接调你们的导出接口
+
+**情况：** 不想自己在 `search-extra` 里手写导出按钮，希望组件内置一个，和「配置表单」一样摆在右侧。  
+**加：** **`show-export`**（或 `:show-export="true"`）+ **`:export-api="你的导出方法"`**  
+**作用：** 内部嵌现有 **`exportFile`** 组件。点击导出时，会把当前 **`filters` 展开**，并带上 **`currentPage: 1`、`pageSize: 999999999`**（与原先 `exportFile` 行为一致），再调用你的 **`export-api`**；返回需为 **`{ success: true, object: '文件下载地址' }`**，失败则 **`success: false`** 并带 **`message`**。
+
+```vue
+<common-list-page
+  show-export
+  :export-api="exportDeviceList"
+  ...
+/>
+```
+
+```js
+exportDeviceList(params, headers) {
+  return this.$http.post("/api/device/export", params, { headers: headers || {} });
+}
+```
+
+**可选：** `export-button-text`、`export-button-type`（同导出组件的按钮类型）、`export-disabled`、`export-headers`、`export-before`（`(querys) => boolean`，返回 `false` 则不调接口）、`export-max-limit`（与当前列表 `total` 比较，超出则只提示不导出）。
+
+> 与 **§2.5 `search-extra` 里自己写导出** 可以并存；内置导出在 **`search-extra` 与「配置表单」之间**。
+
+### 2.7 接口里不叫 `list` / `num`，组件认不出来
+
+**情况：** 你们后端可能是 `data.records`、`data.total` 之类，和默认的 `object.list` / `object.num` 对不上。  
+**加：** `:api-adapter="你的函数"`  
+**作用：** 告诉组件「从整包返回里，哪一块是表格数据、哪一个是总数」。函数返回 `{ list, total }` 就行。
+
+```vue
+:api-adapter="deviceListApiAdapter"
+```
+
+```js
+deviceListApiAdapter(res) {
+  return { list: res.data.records, total: res.data.total };
+}
+```
+
+### 2.8 自己拼请求参数（改分页字段名、或单独加条件）
+
+**情况 ①：** 后端要的分页字段不叫 `currentPage` / `pageSize`，例如要 `pageNo`、`limit`。  
+**情况 ②：** 除了搜索区里的 `filters`，还想 **多带一些接口要的字段**（例如路由里的 `id`、父页面里的菜单编码、写死的业务类型、从别处算出来的标志位等），这些不一定要出现在表单里。
+
+**加：** `:build-params="你的函数"`  
+**作用：** 完全由你决定「这次请求最终发给后端的参数对象」长什么样。第一个参数是当前 **`filters`**（和搜索区同步），第二个是 **`{ page, pageSize }`**（组件内当前页、每页条数）。你可以 **`{ ...filters, ... }`** 再随便加键、删键、改名。
+
+```vue
+:build-params="deviceListBuildParams"
+```
+
+```js
+// 只改分页字段名
+deviceListBuildParams(filters, { page, pageSize }) {
+  return { ...filters, pageNo: page, limit: pageSize };
+}
+
+// 在 filters 之外再拼查询条件（示例：路由 id + 固定类型）
+deviceListBuildParams(filters, { page, pageSize }) {
+  return {
+    ...filters,
+    pageNo: page,
+    limit: pageSize,
+    deptId: this.$route.params.deptId,
+    bizType: "DEVICE"
+  };
+}
+```
+
+### 2.9 数据拿到了，想在进表格前统一改一改每一行
+
+**情况：** 想在列表上加一列展示字段、补默认值、把枚举转成中文等。  
+**加：** `:transform-list="你的函数"`  
+**作用：** 在写入表格前处理 `list`；**记得 return 一个数组**（可以返回新数组，也可以改完再 return）。
+
+```vue
+:transform-list="deviceListTransformList"
+```
+
+```js
+deviceListTransformList(list) {
+  return list.map((row) => ({ ...row, label: row.name || "--" }));
+}
+```
+
+### 2.10 一进页面就要自动查一次
+
+**情况：** 希望打开页面就和以前一样立刻拉列表（`created` 里自动 `fetchList`）。  
+**加：** `:auto-request="true"`  
+**说明：** 默认 **`auto-request` 为 `false`**，进页不请求；可在 `mounted` 里 `this.$refs.xxx.fetchList()`，或打开本开关。
+
+**补充：** `fetchList({ resetPage: true })` 会从第 1 页重新查；`false` 表示保持当前页。
+
+### 2.11 不想要「清除查询」，或想改按钮上的字
+
+**情况：** 没有「恢复初始条件」的需求；或想把文案改成「重置」。  
+**说明：** 「清除」会把筛选条件 **恢复成刚进这个页面时的样子**，再自动查一遍；**不会**把「展开查询 / 收起」强制收回去，保持你当前的展开状态。  
+**加：** `:show-clear-query-button="false"` 或 `:clear-query-button-text="'重置条件'"`
+
+### 2.12 某一个筛选项或某一列表格格，组件自带类型不够用
+
+**情况：** 要自己写一个日期联动、树选择、复杂输入；或操作列里一堆按钮。  
+**加：**  
+- 搜索：`searchOption` 里 **`type: 'slot'`**，写好 **`slot` 名字**；父页面 **`<template #同名="{ item, filters }">`**。  
+- 表格列：`columns` 里 **`type: 'slot'`** + **`slot`**；父页面 **`<template #同名="{ row, scope }">`**。
+
+### 2.13 表格要打勾多选
+
+**情况：** 批量删除、批量导出。  
+**加：** `columns` 里加一列 **`{ type: 'selection', width: 48 }`**，并监听 **`@selection-change`**。
+
+### 2.14 只想改分页器里「每页多少条」那几个选项
+
+**情况：** 下拉只要 10、20、50，不要默认一长串。  
+**加：** `:pagination="{ pSizes: [10, 20, 50] }"`  
+**说明：** 这里的 **`pagination` 只用来合并进组件内部分页**（改 `pSizes` 等），不是让你自己维护当前第几页、总条数——那些仍是组件内部根据接口结果在管。
+
+---
+
+## 3. 事件一览
+
+| 事件 | 说明 |
+|------|------|
+| `query` | 仅 **输入框回车** 时触发（便于校验等）；点「查询」、筛选项变更等由内部 **`fetchList`** 完成。 |
+| `clear-query` | 点「清除查询」并恢复条件、发起请求之后；不改变搜索区「展开/收起」状态。 |
+| `page-change` / `size-change` | 分页变化；组件已请求，事件仍抛出。 |
+| `selection-change` | 表格多选变化。 |
+| `fetched` | 每次 `api` 成功，参数 `{ list, total, page, pageSize, raw }`。 |
+| `columns-change` | **仅开启列配置**：弹窗确定后，当前列配置数组。 |
+
+---
+
+## 4. Props 速查
+
+| Prop | 默认 | 说明 |
+|------|------|------|
+| `filters` | （必填） | 查询条件，与 `searchOption` 的 `prop` 对应。 |
+| `searchOption` | `[]` | 搜索项配置。 |
+| `columns` | `[]` | 表格列配置。 |
+| `api` | （必填） | `(params) => Promise`，内部请求、分页、`loading`。 |
+| `pagination` | `null` | 可选，与内部分页对象合并（如只传 `{ pSizes: [...] }`）。 |
+| `buildParams` | `null` | 自定义整包请求参数；可改分页字段名，也可在 `filters` 外追加条件。 |
+| `apiAdapter` | `null` | `(res) => ({ list, total })`。 |
+| `transformList` | `null` | 入表前改 `list`。 |
+| `autoRequest` | `false` | 为 `true` 时在 `created` 自动请求一次；默认不请求，需自行 `fetchList` 或打开本项。 |
+| `enableColumnConfig` | `false` | `true` 显示「配置表单」弹窗。 |
+| `showExport` | `false` | 为 `true` 且提供 `exportApi` 时，在搜索区右侧显示内置 **`exportFile`** 导出按钮。 |
+| `exportApi` | `null` | `(params, headers?) => Promise`，导出请求；成功返回需含 `success`、`object`（下载链接），与内置导出组件约定一致。 |
+| `exportButtonText` | `导出` | 导出按钮文案。 |
+| `exportButtonType` | `primary` | 导出按钮 `type`（同 `exportFile` 的 `import-component-type`）。 |
+| `exportDisabled` | `false` | 是否禁用导出按钮。 |
+| `exportHeaders` | `null` | 导出请求的额外请求头。 |
+| `exportBefore` | `null` | `(querys) => boolean`，返回 `false` 则中止导出。 |
+| `exportMaxLimit` | `null` | 若设置：当前列表 `total` 超过该值则提示不导出。 |
+| `tableAttrs` | `{}` | 透传 `el-table`。 |
+| `tableHeaderBg` | `#e5e9f2` | 表头背景色。 |
+| `showQueryButton` | `true` | 是否显示查询按钮。 |
+| `queryButtonText` | `查询` | 查询按钮文案。 |
+| `showClearQueryButton` | `true` | 是否显示清除查询。 |
+| `clearQueryButtonText` | `清除查询` | 清除按钮文案。 |
+| `collapseSearch` | `false` | 为 `true` 时启用搜索区折叠。 |
+| `searchVisibleMax` | `null` | 折叠时默认展示条数；**未传且已开启 `collapse-search` 时按 6**；显式传 ≤0 则不折叠。 |
+| `expandSearchText` / `foldSearchText` | 展开查询 / 收起 | 折叠按钮文案。 |
+
+---
+
+## 5. searchOption 项（常用）
+
+每项必有 **`type`**，常用：`input`、`select`、`cascader`、`slot`，以及日期：`date`、`daterange`、`datetime`、`datetimerange`、`month`、`year`。
+
+| 字段 | 说明 |
+|------|------|
+| `prop` | 对应 `filters[prop]`（`slot` 可省略）。 |
+| `label` / `placeholder` | 浮动标签，优先 `label`。 |
+| `width` | 宽度（数字，内部会加 `px`）。 |
+| `autoQuery` | 默认 `true`；`false` 时变更后不自动查（需点查询或回车）。 |
+| `onChange` | `(val) => void`。 |
+| `input` | `maxlength`、`height`。回车触发 `query` 事件（不自动 `fetchList`，需自行处理或依赖其它筛选项的 `autoQuery`）。 |
+| `select` | `options`（平铺选项）、`multiple`、`clearable`（默认 true）、`filterable`、`disabled`。 |
+| `cascader` | **`options`** 为级联树；**`props` 或 `cascaderProps`** 为 `el-cascader` 的字段映射；`filters[prop]` 为 **路径数组**；可选 `filterable`、`collapseTags`、`showAllLevels`、`separator`、`debounce`、`height`。 |
+| 日期范围 | `valueFormat`（默认 `yyyy-MM-dd`）、`startPlaceholder`、`endPlaceholder`；可选 **`gmtBeginKey` / `gmtEndKey`** 同步写带时间的起止字段。 |
+
+---
+
+## 6. columns 列（常用）
+
+非 `slot` 列会 **透传** 到 `el-table-column`（`prop`、`label`、`width`、`fixed` 等）。  
+内置列类型 **`selection` / `index` / `expand`** 不做自定义单元格包装。
+
+| 字段 | 说明 |
+|------|------|
+| `type: 'slot'` + `slot` | 自定义列，父组件具名插槽。 |
+| `hidden` | 隐藏。 |
+| `valueGetter` / `textFormatter` / `defaultText` | 展示用（非 slot 列）。 |
+
+---
+
+## 7. 发布 npm
 
-1. 修改 `package.json` 中 `name` 和 `version`
-2. 登录 npm：`npm login`
-3. 发布：`npm publish`
+递增 `package.json` 的 `version` 后执行 `npm publish`（已发布版本不可覆盖）。

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "wkjp-list-page",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "Vue2 + ElementUI CommonListPage component",
   "main": "src/index.js",
   "module": "src/index.js",
+  "scripts": {
+    "dev": "webpack-dev-server --config webpack.demo.js --mode development --open",
+    "build:demo": "webpack --config webpack.demo.js --mode production"
+  },
   "files": [
     "src"
   ],
@@ -17,5 +21,26 @@
     "vue": "^2.6.14",
     "element-ui": "^2.15.14"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "babel-core": "^6.26.3",
+    "babel-loader": "^6.2.10",
+    "css-loader": "^0.28.11",
+    "element-ui": "^2.15.14",
+    "html-webpack-plugin": "^4.5.2",
+    "style-loader": "^1.3.0",
+    "file-loader": "^6.2.0",
+    "url-loader": "^4.1.1",
+    "vue": "^2.7.16",
+    "vue-hot-reload-api": "^2.3.4",
+    "vue-loader": "^15.10.2",
+    "vue-style-loader": "^4.1.3",
+    "vue-template-compiler": "^2.7.16",
+    "webpack": "^4.47.0",
+    "webpack-cli": "^3.3.12",
+    "webpack-dev-server": "^3.11.3"
+  },
+  "dependencies": {
+    "qs": "^6.13.0"
+  }
 }