BaseTable ​

BaseTable is a configuration-driven table component that wraps the project table implementation and adds a search form, header filters, toolbar buttons, selection, pagination, tree/lazy loading, virtual scrolling, right-click copy actions, and a rich instance API.

Basic Usage ​

Basic table rendering. BaseTable inserts a checkbox selection column and an index column by default. Set select-type="none" or no-index when you do not need them.

Search Form ​

Use topInputs to build the search form. If you do not provide search-method, the component emits search and you can update table-data yourself. If you provide search-method, BaseTable handles loading state, pagination params, and data assignment automatically. Use search-on-select-blur to control whether supported form controls trigger automatic search on blur or change.

Last search params
{}
Status
City (select-v2)
-

Header Filter ​

Set header-filter to enable column header filtering. Add a filter property to the column configuration to define the filter UI. BaseTable merges filter values into the final search params automatically.

Total 0
  • 1
Go to

Selection ​

Use selectType to control row selection. It supports 'checkbox', 'radio', and 'none'.

Pagination ​

Use search-method together with v-model:table-data to let BaseTable manage paging. default-page-size controls the initial page size, and page-sizes defines the selectable options.

No Data…
Total 0
  • 1
Go to

Virtual Scrolling ​

Set use-virtual to enable virtual scrolling for large datasets. Use row-height and estimated-row-height to tune the rendering behavior.

Editable Cells with Manual Validation ​

You can return EditCell from a column render function, then call the exposed validateCells() / clearCellValidate() methods on BaseTable to validate editable cells manually.

Search Modes ​

  • Manual mode: omit search-method, listen to search, and update table-data yourself.
  • Built-in request mode: provide search-method and preferably bind v-model:table-data. BaseTable reads response.result or response.page, then uses list / records and total when pagination is enabled.

Behavior Notes ​

  • BaseTable auto-generates an index column unless no-index is true.
  • The default select-type is 'checkbox', so a selection column is shown unless you set select-type="none".
  • When need-dropdown is enabled, the component hides the normal pagination footer and appends the next page automatically when the table scroll reaches the bottom.
  • search-on-select-blur is enabled by default. el-switch, el-date-picker, el-checkbox, and non-multiple el-select / el-select-v2 / el-cascader / el-input / el-autocomplete / el-input-number / v-input-number controls trigger automatic search on change; multiple controls in the latter group trigger search on blur after the value changes.
  • When show-cell-contextmenu is enabled, right-clicking a non-operation cell opens built-in copy actions for the current cell, column, row, and selected rows.
  • When you render EditCell inside a column render function, the cell automatically participates in validateCells() and clearCellValidate() because BaseTable provides the shared validation context.

API ​

BaseTable Attributes ​

Data and request ​

NameDescriptionTypeDefault
table-datadisplayed rows, supports v-model:table-dataarray[]
table-columnscolumn configuration arrayarray[]
search-methodrequest handler used by onSearch; BaseTable reads response.result or response.page, then parses list / records and totalFunction—
required-paramextra params merged into every search requestobjectnull
label-paramextra label mapping object passed to the internal table rendererobjectnull
before-searchhook before a search runs; return false to cancel the searchFunction() => true
after-searchhook after the request returns; return transformed data to replace the parsed resultFunction() => false
auto-searchcall onSearch() automatically after mountbooleanfalse
force-update-on-searchclear lazy tree cache and current table data before a new searchbooleanfalse
props-loadingexternal loading state merged with internal loading statebooleanfalse

Search form and filters ​

NameDescriptionTypeDefault
top-inputstop search form configuration, using the same item schema as the internal VFormarray[]
top-rulesvalidation rules for the top search formobject{}
has-searchshow the search button; when false, input/select changes can trigger search directlybooleanfalse
has-resetshow the reset buttonbooleantrue
has-refreshshow the refresh button in the top-right area; when enabled, restTopInputs() only resets form values before re-searchingbooleanfalse
search-button-iconrender the search and reset buttons with iconsbooleanfalse
search-on-select-blurwhen enabled, supported controls trigger automatic search: el-switch, el-date-picker, el-checkbox, and non-multiple el-select / el-select-v2 / el-cascader / el-input / el-autocomplete / el-input-number / v-input-number on change, multiple controls in the latter group on blurbooleantrue
search-permitpermission value passed to v-permit on search and reset buttonsstring''
header-filterenable column header filter controlsbooleanfalse
no-air-searchrequire at least one non-empty search condition before searchingbooleanfalse
multi-line-modecontrols how multi-line textarea search values are submitted; pass 'array' to keep an array, or pass a delimiter string such as ';' to join the valuesboolean / string';'

Selection, tree, and row behavior ​

NameDescriptionTypeDefault
select-typeselection mode, set to 'none' to disable the selection columnenum'checkbox'
selectablecontrols whether a row can be selectedFunction—
header-selectablecontrols whether the header select-all checkbox is availableFunction—
row-keyunique row key, required for tree data, lazy loading, and expand-row-keysstring—
row-clickadd row-click styling and enable row-click selection behavior in checkbox modebooleanfalse
expand-rowexpand-row renderer; when provided, BaseTable inserts an expand column automaticallyFunction—
expand-row-keyskeys of rows that should be expanded initiallyarray—
default-expand-allwhether all rows are expanded by default; when expand-row is not provided, BaseTable falls back to tree-config.expandAllbooleanfalse
lazyenable lazy tree loadingbooleanfalse
loadlazy load handler for child nodesFunction—
tree-configtree structure configurationobject{ children: 'children', hasChildren: 'hasChildren', iconClose: 'el-icon-arrow-right', iconOpen: 'el-icon-arrow-down', expandAll: true }
only-sort-lazy-nodesin lazy mode, sort only the already loaded child nodesbooleanfalse
no-one-click-expanddisable one-click expand behavior in the internal tablebooleanfalse
show-cell-contextmenuenable the built-in right-click copy menu for cells and rowsbooleanfalse

Layout and display ​

NameDescriptionTypeDefault
sizeforwarded table/form size; an empty string means inherit from the parent contextenum''
no-data-textcustom empty text shown by the internal tablestring''
is-show-paginationshow the pagination footerbooleantrue
default-page-sizeinitial page size; when set to 0, BaseTable uses the first value from page-sizesnumber0
page-sizesselectable page size optionsarray[100, 200, 500, 2000]
pager-countnumber of visible pagersnumber5
show-selected-numbershow selected row count in the pagination componentbooleantrue
need-dropdownenable append-on-scroll loading instead of the normal pagination footerbooleanfalse
use-virtualenable virtual scrollingbooleanfalse
row-heightrow height used by virtual scrollingnumber32
estimated-row-heightestimated row height for dynamic-height virtual rowsnumber—
table-heightfixed table heightnumber—
max-heightmaximum table heightnumber—
table-height-minusvalue subtracted from the auto-calculated table heightnumber0
auto-heightlet the internal table manage height automaticallybooleanfalse
tab-leveltab nesting level used when recalculating table height inside nested tabsnumber1
need-scroll-top-leftrestore remembered scroll position after layout or paging updatesbooleantrue
no-paddingremove the default outer paddingbooleanfalse
has-bordercontrol border stylingbooleanfalse
is-stripeenable striped rowsbooleanfalse
no-hover-effectdisable row hover effectbooleanfalse
allow-drag-last-columnallow resizing the last columnbooleanfalse
no-indexdisable the auto-generated index columnbooleanfalse
middle-buttonsbuilt-in middle toolbar button configuration array; supports normal buttons, badge buttons, and dropdown buttonsarray[]

Cell and column customization ​

NameDescriptionTypeDefault
cell-class-namecustom cell class namestring / Function—
cell-stylecustom cell styleobject / Function—
row-class-namecustom row class namestring / Function—
span-methodcustom merged-cell methodFunction() => {}
colspan-prop-nameextra prop name passed to the internal merge-cell logicstring''
custom-sort-methodcustom sort handler; when provided, BaseTable does not build the default sidx / order paramsFunction—

Search Parameter Normalization ​

Before BaseTable sends or emits search params, it applies the following normalization rules:

  • merges top form values, header filter values, required-param, pagination params, and sort params
  • trims string values and removes null, undefined, and empty values
  • joins arrays into strings when a field is marked with valueIsString
  • converts values into arrays when a field is marked with valueArray
  • converts time ranges into { startDate, endDate } when a field uses timeToObject
  • splits time ranges into custom fields when a field uses timeToSplit

BaseTable Events ​

NameDescriptionType
update:table-dataemitted when BaseTable writes the current table data; used by v-model:table-dataFunction
searchemitted when a search is triggered and search-method does not return a handled result payloadFunction
search-callbackemitted after built-in request parsing succeedsFunction
resetemitted before a reset search is executedFunction
top-inputs-changeemitted when a top form field changesFunction
sort-changeforwarded sort-change eventFunction
selection-changeemitted when the selected rows changeFunction
selectemitted when a row selection state changesFunction
select-allemitted when the select-all state changesFunction
row-clickemitted when a non-operation row is clickedFunction
current-changeemitted when the current row changesFunction
expand-changeforwarded expand-change eventFunction
header-dragendforwarded header-dragend eventFunction
cell-mouse-enterforwarded cell-mouse-enter eventFunction
cell-mouse-leaveforwarded cell-mouse-leave eventFunction

BaseTable Slots ​

Except paginationLeft, all toolbar-related slots receive the same slot props:

{ selectRows, currentRow, inputsData, inputsDataDealed }

NameDescription
customcustom content rendered above the top search area
formButtonextra buttons rendered at the end of the expanded top form
inLineformButtonextra buttons rendered inline with the top form, both in expanded and collapsed states
topLeftcustom content rendered in the left area below the top form
topRightcustom content rendered in the right area below the top form
defaultcustom content rendered in the middle toolbar area after the built-in middleButtons
paginationLeftcustom content rendered on the left side of the pagination bar

BaseTable Exposes ​

Methods ​

NameDescriptionType
onSearchdebounced search method used by the componentFunction
onResetreset search params and trigger a new searchFunction
restTopInputsreset only the top form values, then search again according to has-refresh behaviorFunction
getInputsDataget the current raw search form modelFunction
setInputsDataset search form values programmaticallyFunction
getSelectRowsget the current selected rowsFunction
getSelecRowsWithSortget selected rows in the current rendered orderFunction
getSortedTableDataget the current rendered table data, optionally flattened from tree dataFunction
clearSelectionclear all selection, or clear only the specified rowsFunction
addSelectionselect the specified rowsFunction
getCurrentRowget the current radio-selected rowFunction
setCurrentRowset the current radio-selected rowFunction
validateCellsvalidate registered cell editorsFunction
clearCellValidateclear validation state for registered cell editorsFunction
loadTableDatareplace the current table dataFunction
doLayouttrigger internal table layout recalculationFunction
setTableHeightrecalculate the table heightFunction
clearSortclear the current sort stateFunction
handleResizemanually recalculate the table height when the surrounding layout changesFunction
rememberScrollingPositionremember current scroll position for later restorationFunction

Refs and reactive state ​

NameDescriptionType
VTableBaseinternal table component refobject
searchFormtop search form refobject
inputsDataraw search form modelobject
inputsDataDealednormalized search params derived from inputsDataobject
selectRowsselected rows refarray
currentRowcurrent row refobject
tableLoadinginternal loading refboolean
pageNumcurrent page refnumber
pageSizecurrent page size refnumber
totaltotal count refnumber
lastSearchDatalast submitted search paramsobject
lazyTreeNodeMapCachecached lazy-loaded child node data keyed by row-keyobject

$_resizeHandler is also exposed as a deprecated alias of handleResize for backward compatibility.

Source ​

Docs