前言
后台管理系统里列表页是高频页面,搜索栏、表格、分页、查询重置、加载状态、接口请求这些样板代码每次重复编写,非常低效。
基于 Vue2 + ElementUI 封装 wkjp-list-page(组件标签:<common-list-page>),组件内部接管列表请求、分页、loading 状态,业务侧只需要配置,不用重复写 el-search、el-table、el-pagination。
组件能力:✅ 搜索条件收起 / 展开 ✅搜索条件标题浮动上方 ✅ 动态表头配置(显示隐藏、拖拽排序) ✅ 查询 & 重置 ✅ 内置导出 ✅ 自定义插槽 ✅ 父页面控制请求时机 ✅ 自带埋点上报。
内部多个业务项目接入,npm 累计下载 9k+,稳定版本 1.0.55,MIT 协议。
组件信息
- 包名:
wkjp-list-page - 组件标签:
<common-list-page> - 版本:
1.0.55 - 协议:MIT
- 环境要求:
vue ^2.6.14、element-ui ^2.15.14 - 安装:
npm i wkjp-list-page
组件展示
一、快速安装
# 安装
npm i wkjp-list-page
# 锁定稳定版本(业务项目推荐)
npm i wkjp-list-page@1.0.55
二、引入方式
方式 1:全局引入(项目所有页面直接使用,推荐)
// main.js
import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
Vue.use(ElementUI)
import WkjpListPage from 'wkjp-list-page'
import 'wkjp-list-page/dist/wkjp-list-page.css'
Vue.use(WkjpListPage)
方式 2:局部引入(仅单个页面使用)
<script>
import WkjpListPage from 'wkjp-list-page'
import 'wkjp-list-page/dist/wkjp-list-page.css'
export default {
components: { WkjpListPage }
}
</script>
三、最简完整示例
核心概念区分:
search-option:搜索表单说明书,配置表单项类型、label、prop,不存值
filters:查询条件存储对象,和 prop 一一对应,表单双向绑定,重置、查询都基于它
api:必填,列表请求函数,返回 Promise;组件内部自动处理 loading、分页、请求
<template>
<common-list-page
ref="deviceListRef"
:filters="deviceListFilters"
:search-option="deviceListSearchOption"
:columns="deviceListColumns"
:api="deviceListApi"
/>
</template>
<script>
export default {
data() {
return {
// 查询条件存储对象
deviceListFilters: {
keyword: "",
status: ""
},
// 搜索栏配置
deviceListSearchOption: [
{ type: "input", prop: "keyword", label: "关键词" },
{
type: "select",
prop: "status",
label: "状态",
options: [{ label: "全部", value: "" }, { label: "启用", value: 1 }, { label: "禁用", value: 0 }],
autoQuery: true
}
],
// 表格列配置
deviceListColumns: [
{ type: "index", label: "#", width: 55 },
{ prop: "name", label: "名称", minWidth: 140 },
{ prop: "status", label: "状态" }
]
}
},
methods: {
// 列表接口,params由组件自动拼接(filters + currentPage + pageSize)
deviceListApi(params) {
return this.$http.get("/api/device/list", { params });
}
}
}
</script>
默认约定:
- 不配置
build-params,请求参数自动拼接filters+currentPage、pageSize - 不配置
api-adapter,默认读取接口返回res.object.list列表、res.object.num总数 - 默认
fetch-on-created=true,组件创建后自动拉取首屏列表
四、核心特色能力(你要的:收起查询、动态表格等)
1. 搜索条件展开 / 收起(折叠查询)
查询项多,一屏放不下自动折叠,默认超过 6 条自动出现「展开查询 / 收起查询」
collapse-search:true强制开启,false关闭;不传自动根据条数判断search-visible-max:修改自动折叠阈值(默认 6)expand-search-text/fold-search-text:自定义展开、收起文案
<common-list-page
:collapse-search="true"
:search-visible-max="4"
expand-search-text="更多查询"
fold-search-text="收起查询"
...
/>
2. 动态表头配置(用户自主控制列)
列数量≥10 列时,表格右上角自动出现齿轮【配置字段】;支持:
- 勾选控制列显隐、拖拽调整列顺序
- 固定列不可关闭、不可拖拽
enable-column-config:true强制开启 /false强制关闭- 监听
@columns-change获取用户修改后的列配置
<common-list-page :enable-column-config="true" @columns-change="handleColumnsChange" ... />
3. 查询 & 清除(重置)查询
show-query-button:是否显示查询按钮,支持自定义文案query-button-textshow-clear-query-button:是否显示清除按钮,自定义文案clear-query-button-text
清除查询逻辑:恢复页面初始化时的 filters 快照,自动重新查询,不会改变搜索区展开 / 收起状态
<common-list-page
query-button-text="搜索"
clear-query-button-text="重置条件"
...
/>
4. 内置导出按钮
无需自己写导出按钮,组件内置导出,自动携带当前筛选条件
<common-list-page show-export :export-api="exportDeviceList" ... />
exportDeviceList(params) {
return this.$http.post("/api/device/export", params)
}
5. 父页面接管请求(block-list-request)
block-list-request="true":拦截组件内部所有自动请求(查询、分页、首屏都不会调 api)
手动触发拉取:
// 拉取数据,resetPage: true 回到第一页
this.$refs.deviceListRef.fetchList({ force: true, resetPage: true })
区分:fetch-on-created=false 仅关闭首屏自动请求,分页、查询依旧自动请求;适合先拿路由参数再查询场景。
6. 自定义请求参数、适配后端返回结构
build-params:自定义最终请求参数,修改分页字段名、追加路由 / 父页面参数api-adapter:适配后端返回格式(比如后端返回res.data.records / res.data.total)
<common-list-page :api-adapter="apiAdapter" :build-params="buildParams" ... />
apiAdapter(res) {
return { list: res.data.records, total: res.data.total }
},
buildParams(filters, { page, pageSize }) {
return {
...filters,
pageNo: page,
limit: pageSize,
deptId: this.$route.params.deptId
}
}
7. 插槽自定义(搜索项、表格单元格、操作按钮)
- search-option 配置
type:slot,自定义复杂筛选项(树选择、日期联动) - columns 配置
type:slot,自定义操作列、复杂单元格 search-extra插槽:在查询按钮右侧追加自定义按钮
<template #search-extra>
<el-button type="primary">新增设备</el-button>
</template>
8. 内置埋点统计(track 事件)
组件自带百度统计上报,自动统计:展开查询、收起查询、配置字段、重置查询;
同时抛出 @track 事件,方便对接 Clarity、自研埋点 SDK
<common-list-page track-page-key="设备列表" @track="onListTrack" ... />
9. 表格多选、分页自定义
- 列配置
{type:'selection',width:48}开启多选,监听@selection-change pagination="{pSizes:[10,20,50]}"自定义分页下拉条数
五、常用事件汇总
表格
| 事件 | 说明 |
|---|---|
| query | 输入框回车触发 |
| clear-query | 点击清除查询,重置完成后触发 |
| fetched | 接口请求成功,返回 list、total、原始返回值 |
| selection-change | 多选勾选变化 |
| columns-change | 用户修改表头配置后触发 |
| track | 埋点事件,统计搜索折叠、表头配置、重置操作 |
六、踩坑 & 注意事项
- 只支持 Vue2,不兼容 Vue3;必须提前引入 ElementUI 和样式
filters不要每次传字面量,组件会原地修改这个对象,会影响重置逻辑- 列自动宽逻辑:超长内容自动开启悬浮提示,可通过属性调整字符阈值
- 组件内部维护 loading,不用业务自己写加载状态
七、结语
这个组件把后台列表通用逻辑封装,业务开发只需要写配置和接口,大幅减少重复样板代码。同系列还有其他自研 npm 组件:ribbon-color、dynamic-customization-form、ll-time-range、vue-scrolling、dynamic-tablelist-colums,后续会持续分享。