自研组件】Vue2 + ElementUI 通用列表页封装 wkjp-list-page,一套配置搞定搜索、动态表格、分页、增删改

0 阅读4分钟

前言

后台管理系统里列表页是高频页面,搜索栏、表格、分页、查询重置、加载状态、接口请求这些样板代码每次重复编写,非常低效。 基于 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>

默认约定:

  1. 不配置 build-params,请求参数自动拼接 filters + currentPage、pageSize
  2. 不配置 api-adapter,默认读取接口返回 res.object.list 列表、res.object.num 总数
  3. 默认 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-text
  • show-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埋点事件,统计搜索折叠、表头配置、重置操作

六、踩坑 & 注意事项

  1. 只支持 Vue2,不兼容 Vue3;必须提前引入 ElementUI 和样式
  2. filters 不要每次传字面量,组件会原地修改这个对象,会影响重置逻辑
  3. 列自动宽逻辑:超长内容自动开启悬浮提示,可通过属性调整字符阈值
  4. 组件内部维护 loading,不用业务自己写加载状态

七、结语

这个组件把后台列表通用逻辑封装,业务开发只需要写配置和接口,大幅减少重复样板代码。同系列还有其他自研 npm 组件:ribbon-color、dynamic-customization-form、ll-time-range、vue-scrolling、dynamic-tablelist-colums,后续会持续分享。