Fast-Table

Fast Table is a quick table template based on query-panel, pagination, table, and form components, designed to support rapid business development.

Overview

Fast-Table is designed to standardize the common page pattern of “search form + data table + pagination”, so list pages can be built with less repetitive wiring.

It is especially suitable for these scenarios:

• Standard query/list pages that need search, request handling, pagination, and table rendering.
• Business pages where column configuration, sorting, and batch selection should follow a consistent pattern.
• Admin pages with relatively stable API structure but still requiring slot-based extension points.

The component mainly provides these capabilities:

• Combines EzQueryPanel, EzTable, and EzPagination into one unified list-page template.
• Drives data fetching and table rendering through api, columns, params, and related configuration.
• Keeps extension points through header, form, free-area, and column slots.
• Encapsulates common pagination request patterns while remaining compatible with custom business parameters.

Basic Usage

INFO

If your business's basic request and the current component's pagination handling are not aligned, you can extract common methods and convert them into a new Promise to adapt to this component. You can also handle other business parameters besides pagination.

Combination Usage

Request Adaptation

INFO

You can use the header slot to quickly access selected items. The default value for row-key is id, which is essential when handling selected items.

Page States

INFO

The #error slot provides a retry method to re-initiate the request in error state. The stage parameter indicates at which stage the error occurred (beforeSearch, transformParams, api, responseAdapter).

Complete CRUD Page Pattern

Recommended Composition

1. Standard CRUD Query Area: Prefer EzQueryPanel + native el-form / el-form-item so the page structure stays explicit and easy to maintain
2. Data Model: Use QueryParams<T> as unified query param type, including current / size / asc / desc base fields
3. Param Prefill: After prefilling from URL or external state, call captureInitialParams() to record as new baseline
4. Batch Actions: Get selectIds and selectList through #header slot for batch delete, export, etc.
5. Edit Dialog: Use EzDialog + EzDynamicForm combination for unified form configuration style
6. Page States: Customize empty data and error state display through #empty and #error slots

If parts of the query area need reuse, prefer extracting el-form-item-level field fragments or field factories instead of turning the entire query area into a configuration-driven model.

Data Flow Best Practices

• Param Sync: Use v-model:params for two-way binding, form and pagination state sync automatically
• Column Input: Always pass columns explicitly; add v-model:columns only when you need to receive updates from the column settings tool
• Fixed Column Guardrail: When any column uses fixed: 'left'/'right', explicitly set width or min-width on the remaining data columns to avoid header/body misalignment in narrow or scrollable layouts
• Reset Baseline: Component auto-captures initial params on mount, reset() restores to that baseline
• External Prefill: After prefilling from route or cache, call captureInitialParams() to update baseline
• Query Timing: Call search() after create/edit success to reset to page 1, call query() after delete to stay on current page

TypeScript Template Typing

If your page depends on strong row / column inference inside table column slots, prefer creating a typed alias with createTypedFastTable<T, P>() and use that alias in the template.

import { createTypedFastTable } from 'ez-ui'
import type { QueryParams } from 'ez-ui'

interface Item {
	id: string
	name: string
}

const TypedFastTable = createTypedFastTable<Item, QueryParams<Partial<Item>>>()

This keeps row stable as Item in slots such as #operations and #status, which is more reliable in strict TypeScript template checking.

List Page Mutation Conventions

• Create/Edit Success: Close the dialog and call search() so the list returns to page 1 and reloads fresh data
• Delete Success: Prefer query() to keep current-page semantics and avoid unnecessary pagination reset
• Batch Delete: Use query() by default as well; switch to search() only when your business flow explicitly wants to jump back to page 1
• Dialog Close Timing: Prefer closing the dialog only after a successful submit; keep the form open on failure so users can correct and retry

Properties

Property	Description	Type	Default
api	Quick API service	Promise<Response>	-
before-search	Side-effect hook before querying; receives current query params	(params) => Promise<void>	-
transform-params	Request param transform hook; return value becomes the final api input	(params) => QueryParams | Promise<QueryParams>	Deep clone of current params
response-adapter	Response adapter hook that converts API output into page data	(response) => Page | Promise<Page>	Built-in support for { code, data: { records, total } }
columns / v-model:columns	Table column config. columns is required; use v-model:columns when you also want column-setting updates	Table-Columns	-
v-model:loading	Asynchronous request status	boolean	false
v-model:params	Query parameters for the form, two-way bound with pagination info	QueryParams	{ current: 1, size: 10 }
row-key	Unique key field for each row	enum	'id'
column-tool	Whether to show the column settings button	boolean	true
border	Whether to show table borders	boolean	true
...	Other properties, passed directly to ez-table	-	-

INFO

Other attributes of fast-table are passed to ez-table, and finally to el-table.

INFO

If request params need a second processing step, prefer transformParams. It receives a deep-cloned copy of the current params, so you can trim fields, split date ranges, remove empty values, or rename keys without mutating the query model shown on the page.

Use beforeSearch for side effects instead, such as analytics, guards, or syncing external page state.

INFO

If your API response does not follow a { code, data: { records, total } } shape, prefer adapting it with responseAdapter instead of wrapping the API in page-level fake responses.

INFO

Remote sorting no longer accepts the implicit sortable: 'custom' convention. Declare sortMode: 'remote' on the column explicitly, and use sortField when the backend field name differs from the column prop.

QueryParams

Property Name	Description	Type	Required	Default
current	Current page number, two-way binding with pagination config	number	No	1
size	Number of items displayed per page, two-way binding with pagination config	number	No	10
desc	Custom descending sort field	string	No	-
asc	Custom ascending sort field	string	No	-
...	Other properties, business-specific parameters	Record	No	-

Sorting Guide

Scenario	Column config	Behavior
Local sorting	sortable: true or custom sortMethod	Sorts only the current table data and does not trigger FastTable queries
Remote sorting	sortMode: 'remote', optional sortField	FastTable writes asc/desc and triggers a new query

WARNING

Local sorting in FastTable only affects the current page data already rendered in the table. If your data comes from remote pagination, this is not a true whole-dataset sort. For full sorting, prefer remote sorting or sort the local dataset before paginating it.

Slots

Slot Name	Description	Type
${prop}	Data column slot, same as ez-table	object
form	Query-area content slot	object
header	Area above the table	object
freeArea	Free area between form and table	object
empty	Empty data state slot	-
error	Error state slot	object

Events

Event Name	Description	Parameters
update:columns	Listen for column config changes, usually triggered by the column settings tool	Function
update:loading	Monitor asynchronous request status	Function
update:params	Monitor changes in query parameters	Function
changePage	Page size or current page changes, can determine the type of change based on value	Function
reset	Triggered when the reset button is clicked	Function
query	Triggered after data loading completes	Function
...	Other events passed directly to ez-table	-

INFO

Other events of fast-table are passed to ez-table, and eventually to el-table.

Methods

Method Name	Description	Type
getTableRef	Get el-table instance	Function
query	Directly trigger api call	Function
search	Trigger api call and reset current to 1	Function
patchParams	Partially update query params	Function
replaceParams	Replace the whole query params object	Function
reset	Restore current baseline params and re-query	Function
captureInitialParams	Save current params as the reset baseline	Function
doLayout	Recalculate the table layout	Function
clearError	Clear error state	Function
getErrorState	Get current error state	Function

INFO

reset() restores the current recorded baseline params and then triggers a query. A baseline is captured automatically on mount. If the page fills query params from outside later, call captureInitialParams() to record the new baseline.

INFO

The form and freeArea slots now receive a unified scope, so custom query areas can directly call search(), reset(), query(), or captureInitialParams() without wiring extra refs.

INFO

Use patchParams() for partial query updates. Use replaceParams() when restoring a whole parameter set from route state, cache, or external page state. This is a better long-term boundary than mutating params directly.

INFO

FastTable now uses a built-in latest-request-wins strategy. When query, pagination, or remote sorting are triggered in quick succession, older responses will not overwrite the newest result.

INFO

The #empty slot customizes the empty-data display. Since it reuses the underlying el-table empty slot, no extra slot scope is provided here. If you need to re-query from the empty state, call the component expose or an outer page-level handler directly.

The #error slot is for customizing the error state display. The slot scope provides error (error object), stage (error stage), params (params when error occurred), and retry (retry method).

The error state uses a “keep current table data and append an error prompt” strategy by default instead of replacing the whole table content area. That means if the previous request succeeded and the next request fails, the table keeps showing the last successful data until a later successful request replaces it.

When an error state exists, the #empty slot will not render at the same time. Empty state is shown only when the table has no data and there is no current error.