wkjp-list-page 1.0.0 → 1.0.1

package/README.md

@@ -1,40 +1,206 @@
-# wkjp-common-list-page
+# wkjp-list-page
 
-基于 Vue2 + ElementUI 的通用列表组件，支持：
-- 配置化搜索区
-- 配置化表格列（含 slot）
-- 托管请求模式（api/buildParams/apiAdapter）
-- 列配置弹窗（显隐 + 拖拽排序）
+基于 **Vue 2** + **Element UI** 的通用列表页组件 `CommonListPage`：浮动标签搜索区、表格、分页、可选列配置弹窗、可选内置请求托管。
+
+## 环境要求
+
+- `vue` ^2.6.14
+- `element-ui` ^2.15.14（需引入主题样式 `theme-chalk`，并保证 **icon 字体 woff/ttf** 能被构建工具正确加载）
 
 ## 安装
 
 ```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);
 ```
 
-或按需引入：
+## 按需引入
 
 ```js
-import { CommonListPage } from "wkjp-common-list-page";
+import { CommonListPage } from "wkjp-list-page";
 
 export default {
   components: { CommonListPage }
 };
 ```
 
-## 基础示例
+---
+
+## Props（传参说明）
+
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `filters` | `Object` | 是 | — | 查询条件对象，与 `searchOption` 里各项的 `prop` 对应；组件会 **原地** `Vue.set` 更新字段，请传入可在父组件中改写的对象（勿用字面量每次新建）。 |
+| `searchOption` | `Array` | 否 | `[]` | 搜索项配置数组，见下文 **searchOption 项结构**。 |
+| `columns` | `Array` | 否 | `[]` | 表格列配置，见下文 **columns 列结构**。 |
+| `tableData` | `Array` | 否 | `[]` | **非托管模式**：表格数据。 |
+| `loading` | `Boolean` | 否 | `false` | **非托管模式**：加载状态。 |
+| `pagination` | `Object` \| `null` | 否 | `null` | **非托管模式**：`{ total, page, pageSize, pSizes? }`；为 `null` 时不显示分页。托管模式下可被用来 **合并** 覆盖内部分页初始值。 |
+| `tableAttrs` | `Object` | 否 | `{}` | 透传给 `el-table`（如 `stripe`、`border`、`height` 等）。 |
+| `api` | `Function` | 否 | `null` | **托管模式**：`(params) => Promise`，返回接口原始数据。 |
+| `buildParams` | `Function` | 否 | `null` | **托管模式**：`(filters, { page, pageSize }) => params`；不传则默认 `{ ...filters, currentPage, pageSize }`。 |
+| `apiAdapter` | `Function` | 否 | `null` | **托管模式**：`(res) => ({ list, total })`；不传则尝试解析 `res.object.list` / `res.object.num`。 |
+| `autoRequest` | `Boolean` | 否 | `true` | **托管模式**：是否在 `created` 时自动请求一次。 |
+| `enableColumnConfig` | `Boolean` | 否 | `false` | 是否显示「配置表单」按钮及列显隐/排序弹窗。 |
+| `tableHeaderBg` | `String` | 否 | `'#e5e9f2'` | 表头单元格背景色；内部合并进 `el-table` 的 `header-cell-style`。若同时在 `tableAttrs.header-cell-style` 里写了 `backgroundColor`，后者会覆盖同名属性（函数返回的对象会与底色合并）。 |
+| `showQueryButton` | `Boolean` | 否 | `true` | 是否在筛选条件后显示蓝色「查询」按钮。**非托管**：点击触发 `query` 事件；**托管**：点击执行 `fetchList({ resetPage: true })`。不需要时可设为 `false`。 |
+| `queryButtonText` | `String` | 否 | `'查询'` | 查询按钮文案。 |
+
+### 两种数据模式
+
+1. **非托管（外部控制数据）**  
+   不传 `api`。父组件传入 `tableData`、`loading`、`pagination`，并监听 `query` / `page-change` / `size-change` 自行请求。
+
+2. **托管（组件内请求）**  
+   传入 `api`（可选 `buildParams`、`apiAdapter`）。组件内部维护 `loading`、列表与分页；仍可通过事件与 `fetched` 做额外逻辑。父组件可通过 `ref` 调用实例方法 **`fetchList({ resetPage })`** 手动刷新。
+
+---
+
+## Events（事件）
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `query` | — | 非托管：搜索区 **回车** 或部分控件变更触发（见 `autoQuery`）。 |
+| `page-change` | `page: number` | 页码变化；托管时组件内部已拉数，仍会向外抛。 |
+| `size-change` | `size: number` | 每页条数变化；同上。 |
+| `fetched` | `{ list, total, page, pageSize, raw }` | **仅托管模式**：每次 `api` 成功返回后触发。 |
+| `columns-change` | `appliedColumns: Array` | 列配置弹窗点击确定后，返回当前生效列配置（含 `hidden`）。 |
+
+---
+
+## Slots（插槽）
+
+| 插槽名 | 作用域 / 参数 | 说明 |
+|--------|----------------|------|
+| `search-extra` | — | 搜索表单 **内置「查询」按钮之后** 的额外内容（如「重置」「导出」），再往后才是右侧「配置表单」（若开启）。 |
+| 动态名 | 由 `searchOption` 中 `type: 'slot'` 的 `slot` 字段指定 | 参数：`item`、`filters`。 |
+| 动态名 | 由 `columns` 中 `type: 'slot'` 的 `slot` 字段指定 | 参数：`row`、`scope`（与 `el-table-column` 的 `slot-scope` 一致）。 |
+
+**搜索区自定义示例：**
+
+```js
+// searchOption 中
+{ type: "slot", slot: "myFilter", prop: "x" /* 可选 */ }
+```
+
+```vue
+<common-list-page :search-option="searchOption" ...>
+  <template #myFilter="{ item, filters }">
+    <!-- 自定义内容，可读写 filters -->
+  </template>
+</common-list-page>
+```
+
+**列自定义示例：**
+
+```js
+// columns 中
+{ type: "slot", slot: "actions", label: "操作", width: 160, fixed: "right" }
+```
+
+```vue
+<template #actions="{ row }">
+  <el-button type="text" @click="onView(row)">详情</el-button>
+</template>
+```
+
+---
+
+## searchOption 单项结构
+
+每一项至少包含 `type`，按类型不同字段如下。
+
+### 通用字段
+
+| 字段 | 说明 |
+|------|------|
+| `type` | `'input'` \| `'select'` \| `'slot'` \| 日期类型见下 |
+| `prop` | 对应 `filters[prop]`，**建议必填**（`slot` 可省略） |
+| `label` | 浮动标签文案；与 `placeholder` 二选一，优先 `label` |
+| `placeholder` | 无 `label` 时作为浮动标签文案 |
+| `width` | 控件宽度（px 数字在模板里已拼成字符串） |
+| `value` | 可选；若存在则 **显示值优先** 于 `filters[prop]`（`resolveValue`） |
+| `autoQuery` | 默认 `true`；为 `false` 时变更后不自动 `query` / 内部 `fetchList` |
+| `onChange` | `(val) => void`，值变化时回调 |
+
+### `type: 'input'`
+
+| 字段 | 说明 |
+|------|------|
+| `maxlength` | 原生 maxlength |
+| `height` | 输入框高度，默认 `32px` |
+| `clearable` | 当前实现为 `FloatingInput`，无清空按钮属性（可按需扩展） |
+
+输入框仅 **回车** 时对外 `emit('query')`；输入过程只回写 `filters`。
+
+### `type: 'select'`
+
+| 字段 | 说明 |
+|------|------|
+| `options` | `[{ label, value }, ...]` |
+| `multiple` | 是否多选 |
+| `clearable` | 默认 `true`；设为 `false` 关闭清空 |
+| `filterable` | 可搜索 |
+| `disabled` | 禁用 |
+| `size` | Element `size` |
+
+### 日期类 `type`
+
+支持：`date`、`daterange`、`datetime`、`datetimerange`、`month`、`year`。
+
+| 字段 | 说明 |
+|------|------|
+| `valueFormat` | 默认 `'yyyy-MM-dd'` |
+| `startPlaceholder` / `endPlaceholder` | **范围**时两侧浮动文案，默认「开始日期」「结束日期」 |
+| `unlinkPanels` | 范围面板是否联动，默认 `true` |
+| `rangeSeparator` | 默认 `'至'` |
+| `editable` | 是否可键盘输入，默认 `false` |
+| `width` | 范围默认宽度约 `300px`，可加大避免拥挤 |
+
+### `type: 'slot'`
+
+| 字段 | 说明 |
+|------|------|
+| `slot` | 与父组件 `<template #[slot]>` 名称一致 |
+
+---
+
+## columns 列结构
+
+非 `slot` 列会 **整体 `v-bind` 到 `el-table-column`**，因此可直接使用 Element 文档中的列属性（`prop`、`label`、`width`、`minWidth`、`fixed`、`align` 等）。
+
+组件内部用 `slot-scope` 包了一层默认展示：文本来自 **`resolveCellText`**。
+
+| 字段 | 说明 |
+|------|------|
+| `type` | 不为 `'slot'` 时，也可为 `'index'` 等 Element 支持的列类型 |
+| `prop` | 字段名 |
+| `hidden` | `true` 隐藏列 |
+| `valueGetter` | `(row, index) => any` 自定义取值 |
+| `textFormatter` | `(value, row, index) => string` 格式化展示 |
+| `defaultText` | 空值时展示，默认展示为 `'--'` |
+| `type: 'slot'` | 必须同时提供 `slot`（插槽名），`type`/`slot` 不会透传给 `el-table-column` |
+
+### 列配置弹窗（`enableColumnConfig: true`）
+
+- `fixed: 'left' \| 'right'` 或 `configFixed: true` 的列视为 **固定列**，弹窗内 **不可拖拽换位**。
+- 弹窗内顺序：左固定 → 普通 → 右固定。
+- 确定后列上 `hidden` 与顺序会写入内部 `appliedColumns`，并 `columns-change` 通知父级。
+
+---
+
+## 完整示例（非托管）
 
 ```vue
 <template>
@@ -42,14 +208,97 @@ export default {
     :filters="filters"
     :search-option="searchOption"
     :columns="columns"
-    :api="apiFn"
-    :enable-column-config="true"
+    :table-data="list"
+    :loading="loading"
+    :pagination="pagination"
+    :table-attrs="{ stripe: true }"
+    :table-header-bg="tableHeaderBg"
+    show-query-button
+    @query="loadData"
+    @page-change="onPage"
+    @size-change="onSize"
   />
 </template>
+
+<script>
+export default {
+  data() {
+    return {
+      /** 表头背景色，可写死或随主题/皮肤切换 */
+      tableHeaderBg: "#eef2f8",
+      filters: { name: "", status: "", range: [] },
+      list: [],
+      loading: false,
+      pagination: { total: 0, page: 1, pageSize: 10, pSizes: [10, 20, 50] },
+      searchOption: [
+        { type: "input", prop: "name", placeholder: "姓名", autoQuery: false },
+        {
+          type: "select",
+          prop: "status",
+          placeholder: "状态",
+          options: [{ label: "启用", value: "1" }, { label: "禁用", value: "0" }],
+          autoQuery: false
+        },
+        {
+          type: "daterange",
+          prop: "range",
+          startPlaceholder: "开始日期",
+          endPlaceholder: "结束日期",
+          width: 380,
+          autoQuery: false
+        }
+      ],
+      columns: [
+        { type: "index", label: "#", width: 60 },
+        { prop: "name", label: "姓名", minWidth: 120 },
+        { type: "slot", slot: "op", label: "操作", width: 140, fixed: "right" }
+      ]
+    };
+  },
+  methods: {
+    loadData() { /* 请求并赋值 list、pagination */ },
+    onPage(p) { this.pagination.page = p; this.loadData(); },
+    onSize(s) { this.pagination.pageSize = s; this.pagination.page = 1; this.loadData(); }
+  }
+};
+</script>
+```
+
+## 托管示例
+
+```vue
+<common-list-page
+  :filters="filters"
+  :search-option="searchOption"
+  :columns="columns"
+  :api="fetchApi"
+  :build-params="buildParams"
+  :api-adapter="adapter"
+  @fetched="onFetched"
+/>
+```
+
+```js
+methods: {
+  fetchApi(params) {
+    return this.$http.get("/api/list", { params });
+  },
+  buildParams(filters, { page, pageSize }) {
+    return { ...filters, page, size: pageSize };
+  },
+  adapter(res) {
+    return { list: res.data.rows, total: res.data.total };
+  },
+  onFetched({ list, total }) { /* ... */ }
+}
 ```
 
-## 发布
+父组件刷新：`this.$refs.listRef.fetchList({ resetPage: true })`（需给组件加 `ref="listRef"`）。
+
+---
+
+## 发布 npm
 
-1. 修改 `package.json` 中 `name` 和 `version`
-2. 登录 npm：`npm login`
-3. 发布：`npm publish`
+1. 修改 `package.json` 的 `name`、`version`
+2. `npm login`
+3. `npm publish`（scoped 包需 `--access public`）

package/package.json

@@ -1,21 +1,44 @@
-{
-  "name": "wkjp-list-page",
-  "version": "1.0.0",
-  "description": "Vue2 + ElementUI CommonListPage component",
-  "main": "src/index.js",
-  "module": "src/index.js",
-  "files": [
-    "src"
-  ],
-  "keywords": [
-    "vue2",
-    "element-ui",
-    "table",
-    "list"
-  ],
-  "peerDependencies": {
-    "vue": "^2.6.14",
-    "element-ui": "^2.15.14"
-  },
-  "license": "MIT"
-}
+{
+  "name": "wkjp-list-page",
+  "version": "1.0.1",
+  "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"
+  ],
+  "keywords": [
+    "vue2",
+    "element-ui",
+    "table",
+    "list"
+  ],
+  "peerDependencies": {
+    "vue": "^2.6.14",
+    "element-ui": "^2.15.14"
+  },
+  "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": {}
+}