跪拜 Guibai
← Back to the summary

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

Component demo Insert image description here Insert image description here

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:

  1. Without build-params, request parameters automatically concatenate filters + currentPage, pageSize
  2. Without api-adapter, the component reads res.object.list as the list and res.object.num as the total by default
  3. 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.

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:

3. Query & Clear (Reset) Query

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

7. Slot Customization (search items, table cells, operation buttons)

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

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

  1. Only supports Vue2, not compatible with Vue3; ElementUI and its styles must be imported first
  2. filters should not be passed as a literal each time; the component mutates this object in place, which affects reset logic
  3. Column auto-width logic: long content automatically enables hover tooltip, the character threshold can be adjusted via property
  4. 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.