跪拜 Guibai
← All articles
Frontend

wkjp-list-page: One Config Object Runs Your Vue2 Admin List Pages

By 码农机器 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Teams maintaining Vue2 admin panels can cut hours of repetitive CRUD list wiring down to a config object and a single API function. The pattern also pushes for standardized response shapes and request parameters, which is often the messiest part of list pages, though it locks you into Vue2 at a time when most new work has moved to Vue3 or other frameworks.

Summary

wkjp-list-page is a Vue2 + ElementUI component that replaces the repetitive list page boilerplate in admin systems. It takes over the API request, pagination, and loading state, so the business side only supplies a configuration object for the search bar and table columns, plus a request function. The package ships with features like collapsible search fields, dynamic column configuration with drag-to-sort, built-in export, custom slots, and parent-controlled request timing.

Two configuration concepts keep the component flexible: `search-option` describes the search form schema (field types, labels, prop names) without storing values, while `filters` holds the actual query conditions and is two-way bound to the form. An `api-adapter` handles non-standard backend response shapes, and `build-params` lets teams reshape the outgoing request payload, including pagination field names and extra route parameters.

It's been integrated into multiple internal projects, with over 9k cumulative npm downloads and a stable version at 1.0.55 under the MIT license. The component is explicitly Vue2-only and requires ElementUI to be imported first. It also includes built-in tracking events for Baidu Analytics and a `@track` event for other analytics SDKs.

Takeaways
— wkjp-list-page is a Vue2 + ElementUI component with the tag `<common-list-page>`, stable version 1.0.55, MIT licensed, and over 9k cumulative npm downloads.
— It requires Vue ^2.6.14 and Element UI ^2.15.14; it does not support Vue3.
— The component handles list request, pagination, and loading state internally, so the business only writes search-option, filters, columns, and an api function.
— Default API response shape is `res.object.list` for the array and `res.object.num` for the total; `api-adapter` can remap other shapes.
— `build-params` customizes the outgoing request parameters, including pagination field names and additional route or parent-page data.
— Search collapses automatically when there are more than 6 items, configurable via `search-visible-max`; the expand/collapse labels are customizable.
— Dynamic column configuration appears automatically when there are 10 or more columns, allowing users to hide/show and drag-reorder columns; fixed columns can't be altered.
— Built-in export uses `show-export` and an `export-api` function, carrying the current filters.
— `block-list-request` lets the parent component control all API calls, and `fetchList({ force: true, resetPage: true })` manually triggers fetch with optional page reset.
— Clear query resets to a snapshot of initial filters and re-queries without changing the search area's expand/collapse state.
— The component emits `@track` events and includes Baidu Analytics reporting for expand, collapse, column config, and reset operations.
— The `filters` object is mutated in place, so it should not be passed as a fresh literal each render to avoid breaking reset behavior.
Conclusions

Separating the search form schema (`search-option`) from the state object (`filters`) is a clean pattern that makes the component reusable without tight coupling to the form implementation.

The heavy reliance on `build-params` and `api-adapter` reflects a practical reality: backend response shapes and pagination conventions vary wildly across teams, and a generic list component needs explicit escape hatches.

Being Vue2-only with a fragile dependency on ElementUI means this component is ideal for internal legacy systems but not a candidate for new projects, which is a common fate for well-honed internal tooling.

The built-in tracking and export features show that admin list pages carry non-trivial cross-cutting concerns beyond rendering a table; folding them into the component reduces the chance of inconsistent implementations across pages.

Concepts & terms
search-option
The configuration array that describes the search form fields (type, label, prop) for a list page. It defines the schema but does not hold any values; actual query data lives in the `filters` object.
filters
The reactive object that stores the current query conditions, keyed by the prop names defined in search-option. It is two-way bound to the search form and is what gets passed along when the user queries or resets.
api-adapter
A function that maps a backend API response to the uniform shape `{ list, total }` that the component expects, letting it work with various response conventions like `res.data.records` and `res.data.total`.
build-params
A function that takes the current filters and pagination info and returns the final request parameters. It allows teams to rename pagination fields, add route parameters, or append other context before the API call.
block-list-request
A boolean prop that, when set to true, prevents the component from automatically firing list requests (first page, query, or pagination). The parent page then manually calls `fetchList()` through a ref to control when data loads.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗