wkjp-list-page: One Config Object Runs Your Vue2 Admin List Pages
Custom Component] Vue2 + ElementUI Universal List Page Encapsulation wkjp-list-page: One Config for Search, Dynamic Table, Pagination, CRUD
Introduction
In admin systems, list pages are the most frequent page type. The boilerplate code for search bar, table, pagination, query/reset, loading state, and API requests gets rewritten every time, which is very inefficient.
Based on Vue2 + ElementUI, this encapsulates wkjp-list-page (component tag: <common-list-page>). The component takes over list requests, pagination, and loading states internally, so the business side only needs configuration, without repeatedly writing el-search, el-table, or el-pagination.
Component capabilities: ✅ Search condition collapse/expand ✅ Search condition title floats above ✅ Dynamic column configuration (show/hide, drag-to-sort) ✅ Query & Reset ✅ Built-in export ✅ Custom slots ✅ Parent page controls request timing ✅ Built-in tracking/reporting.
It has been integrated into multiple internal business projects, with over 9k cumulative npm downloads. The stable version is 1.0.55, MIT license.
Component Information
- Package name:
wkjp-list-page - Component tag:
<common-list-page> - Version:
1.0.55 - License: MIT
- Environment requirements:
vue ^2.6.14,element-ui ^2.15.14 - Install:
npm i wkjp-list-page
Component demo
1. Quick Install
# Install
npm i wkjp-list-page
# Pin stable version (recommended for business projects)
npm i [email protected]
2. Import Methods
Method 1: Global Import (all pages use directly, recommended)
// 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)
Method 2: Local Import (use in a single page)
<script>
import WkjpListPage from 'wkjp-list-page'
import 'wkjp-list-page/dist/wkjp-list-page.css'
export default {
components: { WkjpListPage }
}
</script>
3. Minimal Complete Example
Core concept distinction:
search-option: the search form specification, configures form item type, label, prop, does not store values
filters: the query condition storage object, one-to-one with prop, two-way bound to the form, reset and query are based on it
api: required, the list request function, returns a Promise; the component handles loading, pagination, and request automatically internally
<template>
<common-list-page
ref="deviceListRef"
:filters="deviceListFilters"
:search-option="deviceListSearchOption"
:columns="deviceListColumns"
:api="deviceListApi"
/>
</template>
<script>
export default {
data() {
return {
// Query condition storage object
deviceListFilters: {
keyword: "",
status: ""
},
// Search bar configuration
deviceListSearchOption: [
{ type: "input", prop: "keyword", label: "关键词" },
{
type: "select",
prop: "status",
label: "状态",
options: [{ label: "全部", value: "" }, { label: "启用", value: 1 }, { label: "禁用", value: 0 }],
autoQuery: true
}
],
// Table column configuration
deviceListColumns: [
{ type: "index", label: "#", width: 55 },
{ prop: "name", label: "名称", minWidth: 140 },
{ prop: "status", label: "状态" }
]
}
},
methods: {
// List API, params are auto-composed by the component (filters + currentPage + pageSize)
deviceListApi(params) {
return this.$http.get("/api/device/list", { params });
}
}
}
</script>
Default conventions:
- Without
build-params, request parameters automatically concatenatefilters+currentPage, pageSize - Without
api-adapter, the component readsres.object.listas the list andres.object.numas the total by default - Default
fetch-on-created=true, the component automatically fetches the first page when created
4. Core Feature Capabilities (what you wanted: collapsible query, dynamic table, etc.)
1. Search Conditions Expand / Collapse (foldable query)
When there are many query items that don't fit on one screen, they auto-fold. By default, if more than 6 items exist, an "Expand Query / Collapse Query" toggle appears automatically.
collapse-search:trueforces it on,falseturns it off; when omitted, it auto-determines based on item countsearch-visible-max: change the auto-fold threshold (default 6)expand-search-text/fold-search-text: customize the expand and collapse labels<common-list-page :collapse-search="true" :search-visible-max="4" expand-search-text="更多查询" fold-search-text="收起查询" ... />
2. Dynamic Column Headers (user-controlled columns)
When there are 10 or more columns, a gear icon [Configure Fields] appears in the top-right corner of the table; supports:
Checkbox to control column visibility, drag to reorder columns
Fixed columns cannot be hidden or dragged
enable-column-config:trueforces it on /falseforces it offListen for
@columns-changeto get the user's modified column configuration<common-list-page :enable-column-config="true" @columns-change="handleColumnsChange" ... />
3. Query & Clear (Reset) Query
show-query-button: whether to show the query button, supports custom textquery-button-textshow-clear-query-button: whether to show the clear button, custom textclear-query-button-text
Clear query logic: restores the filters snapshot from page initialization, automatically re-queries, does not change the search area's expand/collapse state
<common-list-page
query-button-text="搜索"
clear-query-button-text="重置条件"
...
/>
4. Built-in Export Button
No need to write an export button; the component includes export and automatically carries the current filter conditions
<common-list-page show-export :export-api="exportDeviceList" ... />
exportDeviceList(params) {
return this.$http.post("/api/device/export", params)
}
5. Parent Page Takes Over Requests (block-list-request)
block-list-request="true": intercepts all internal automatic requests (query, pagination, first page won't call the API)
Manually trigger fetching:
// Fetch data, resetPage: true returns to first page
this.$refs.deviceListRef.fetchList({ force: true, resetPage: true })
Distinction: fetch-on-created=false only disables the first-screen auto request, pagination and query remain auto-requested; suitable for scenarios where you need to read route parameters first.
6. Custom Request Parameters and Adapting Backend Response Structure
build-params: customize the final request parameters, modify pagination field names, append route/parent-page parametersapi-adapter: adapt to the backend response format (e.g., if backend returnsres.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. Slot Customization (search items, table cells, operation buttons)
Set
type:slotin search-option for complex search fields (tree select, date ranges with linkage)Set
type:slotin columns for operation columns or complex cellssearch-extraslot: append custom buttons to the right of the query button<template #search-extra> 新增设备
8. Built-in Tracking Statistics (track event)
The component includes Baidu Analytics reporting; it automatically counts expand query, collapse query, configure fields, and reset query;
It also emits a @track event for integration with Clarity or custom tracking SDKs
<common-list-page track-page-key="设备列表" @track="onListTrack" ... />
9. Table Multi-select and Pagination Customization
- Column config
{type:'selection',width:48}enables multi-select, listen for@selection-change pagination="{pSizes:[10,20,50]}"custom pagination dropdown sizes
5. Common Events Summary
Table
| Event | Description |
|---|---|
| query | Triggered on Enter in input |
| clear-query | Triggered after clear query, after reset completes |
| fetched | On successful API request, returns list, total, raw response |
| selection-change | Triggered when multi-select changes |
| columns-change | Triggered after user modifies column header config |
| track | Tracking event, counts search collapse, column header config, reset operations |
6. Pitfalls & Notes
- Only supports Vue2, not compatible with Vue3; ElementUI and its styles must be imported first
filtersshould not be passed as a literal each time; the component mutates this object in place, which affects reset logic- Column auto-width logic: long content automatically enables hover tooltip, the character threshold can be adjusted via property
- The component maintains loading internally, so the business doesn't need to write loading states
7. Conclusion
This component encapsulates the common logic of admin list pages; business development only needs to write configuration and API functions, greatly reducing repetitive boilerplate code. Other self-built npm components in the same series: ribbon-color, dynamic-customization-form, ll-time-range, vue-scrolling, dynamic-tablelist-colums, and more will be shared later.