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 | {} |
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.
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.
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 tosearch, and updatetable-datayourself. - Built-in request mode: provide
search-methodand preferably bindv-model:table-data. BaseTable readsresponse.resultorresponse.page, then useslist/recordsandtotalwhen pagination is enabled.
Behavior Notes
- BaseTable auto-generates an index column unless
no-indexistrue. - The default
select-typeis'checkbox', so a selection column is shown unless you setselect-type="none". - When
need-dropdownis enabled, the component hides the normal pagination footer and appends the next page automatically when the table scroll reaches the bottom. search-on-select-bluris enabled by default.el-switch,el-date-picker,el-checkbox, and non-multipleel-select/el-select-v2/el-cascader/el-input/el-autocomplete/el-input-number/v-input-numbercontrols trigger automatic search on change; multiple controls in the latter group trigger search on blur after the value changes.- When
show-cell-contextmenuis enabled, right-clicking a non-operation cell opens built-in copy actions for the current cell, column, row, and selected rows. - When you render
EditCellinside a columnrenderfunction, the cell automatically participates invalidateCells()andclearCellValidate()because BaseTable provides the shared validation context.
API
BaseTable Attributes
Data and request
| Name | Description | Type | Default |
|---|---|---|---|
| table-data | displayed rows, supports v-model:table-data | array | [] |
| table-columns | column configuration array | array | [] |
| search-method | request handler used by onSearch; BaseTable reads response.result or response.page, then parses list / records and total | Function | — |
| required-param | extra params merged into every search request | object | null |
| label-param | extra label mapping object passed to the internal table renderer | object | null |
| before-search | hook before a search runs; return false to cancel the search | Function | () => true |
| after-search | hook after the request returns; return transformed data to replace the parsed result | Function | () => false |
| auto-search | call onSearch() automatically after mount | boolean | false |
| force-update-on-search | clear lazy tree cache and current table data before a new search | boolean | false |
| props-loading | external loading state merged with internal loading state | boolean | false |
Search form and filters
| Name | Description | Type | Default |
|---|---|---|---|
| top-inputs | top search form configuration, using the same item schema as the internal VForm | array | [] |
| top-rules | validation rules for the top search form | object | {} |
| has-search | show the search button; when false, input/select changes can trigger search directly | boolean | false |
| has-reset | show the reset button | boolean | true |
| has-refresh | show the refresh button in the top-right area; when enabled, restTopInputs() only resets form values before re-searching | boolean | false |
| search-button-icon | render the search and reset buttons with icons | boolean | false |
| search-on-select-blur | when 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 blur | boolean | true |
| search-permit | permission value passed to v-permit on search and reset buttons | string | '' |
| header-filter | enable column header filter controls | boolean | false |
| no-air-search | require at least one non-empty search condition before searching | boolean | false |
| multi-line-mode | controls how multi-line textarea search values are submitted; pass 'array' to keep an array, or pass a delimiter string such as ';' to join the values | boolean / string | ';' |
Selection, tree, and row behavior
| Name | Description | Type | Default |
|---|---|---|---|
| select-type | selection mode, set to 'none' to disable the selection column | enum | 'checkbox' |
| selectable | controls whether a row can be selected | Function | — |
| header-selectable | controls whether the header select-all checkbox is available | Function | — |
| row-key | unique row key, required for tree data, lazy loading, and expand-row-keys | string | — |
| row-click | add row-click styling and enable row-click selection behavior in checkbox mode | boolean | false |
| expand-row | expand-row renderer; when provided, BaseTable inserts an expand column automatically | Function | — |
| expand-row-keys | keys of rows that should be expanded initially | array | — |
| default-expand-all | whether all rows are expanded by default; when expand-row is not provided, BaseTable falls back to tree-config.expandAll | boolean | false |
| lazy | enable lazy tree loading | boolean | false |
| load | lazy load handler for child nodes | Function | — |
| tree-config | tree structure configuration | object | { children: 'children', hasChildren: 'hasChildren', iconClose: 'el-icon-arrow-right', iconOpen: 'el-icon-arrow-down', expandAll: true } |
| only-sort-lazy-nodes | in lazy mode, sort only the already loaded child nodes | boolean | false |
| no-one-click-expand | disable one-click expand behavior in the internal table | boolean | false |
| show-cell-contextmenu | enable the built-in right-click copy menu for cells and rows | boolean | false |
Layout and display
| Name | Description | Type | Default |
|---|---|---|---|
| size | forwarded table/form size; an empty string means inherit from the parent context | enum | '' |
| no-data-text | custom empty text shown by the internal table | string | '' |
| is-show-pagination | show the pagination footer | boolean | true |
| default-page-size | initial page size; when set to 0, BaseTable uses the first value from page-sizes | number | 0 |
| page-sizes | selectable page size options | array | [100, 200, 500, 2000] |
| pager-count | number of visible pagers | number | 5 |
| show-selected-number | show selected row count in the pagination component | boolean | true |
| need-dropdown | enable append-on-scroll loading instead of the normal pagination footer | boolean | false |
| use-virtual | enable virtual scrolling | boolean | false |
| row-height | row height used by virtual scrolling | number | 32 |
| estimated-row-height | estimated row height for dynamic-height virtual rows | number | — |
| table-height | fixed table height | number | — |
| max-height | maximum table height | number | — |
| table-height-minus | value subtracted from the auto-calculated table height | number | 0 |
| auto-height | let the internal table manage height automatically | boolean | false |
| tab-level | tab nesting level used when recalculating table height inside nested tabs | number | 1 |
| need-scroll-top-left | restore remembered scroll position after layout or paging updates | boolean | true |
| no-padding | remove the default outer padding | boolean | false |
| has-border | control border styling | boolean | false |
| is-stripe | enable striped rows | boolean | false |
| no-hover-effect | disable row hover effect | boolean | false |
| allow-drag-last-column | allow resizing the last column | boolean | false |
| no-index | disable the auto-generated index column | boolean | false |
| middle-buttons | built-in middle toolbar button configuration array; supports normal buttons, badge buttons, and dropdown buttons | array | [] |
Cell and column customization
| Name | Description | Type | Default |
|---|---|---|---|
| cell-class-name | custom cell class name | string / Function | — |
| cell-style | custom cell style | object / Function | — |
| row-class-name | custom row class name | string / Function | — |
| span-method | custom merged-cell method | Function | () => {} |
| colspan-prop-name | extra prop name passed to the internal merge-cell logic | string | '' |
| custom-sort-method | custom sort handler; when provided, BaseTable does not build the default sidx / order params | Function | — |
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 usestimeToObject - splits time ranges into custom fields when a field uses
timeToSplit
BaseTable Events
| Name | Description | Type |
|---|---|---|
| update:table-data | emitted when BaseTable writes the current table data; used by v-model:table-data | Function |
| search | emitted when a search is triggered and search-method does not return a handled result payload | Function |
| search-callback | emitted after built-in request parsing succeeds | Function |
| reset | emitted before a reset search is executed | Function |
| top-inputs-change | emitted when a top form field changes | Function |
| sort-change | forwarded sort-change event | Function |
| selection-change | emitted when the selected rows change | Function |
| select | emitted when a row selection state changes | Function |
| select-all | emitted when the select-all state changes | Function |
| row-click | emitted when a non-operation row is clicked | Function |
| current-change | emitted when the current row changes | Function |
| expand-change | forwarded expand-change event | Function |
| header-dragend | forwarded header-dragend event | Function |
| cell-mouse-enter | forwarded cell-mouse-enter event | Function |
| cell-mouse-leave | forwarded cell-mouse-leave event | Function |
BaseTable Slots
Except paginationLeft, all toolbar-related slots receive the same slot props:
{ selectRows, currentRow, inputsData, inputsDataDealed }
| Name | Description |
|---|---|
| custom | custom content rendered above the top search area |
| formButton | extra buttons rendered at the end of the expanded top form |
| inLineformButton | extra buttons rendered inline with the top form, both in expanded and collapsed states |
| topLeft | custom content rendered in the left area below the top form |
| topRight | custom content rendered in the right area below the top form |
| default | custom content rendered in the middle toolbar area after the built-in middleButtons |
| paginationLeft | custom content rendered on the left side of the pagination bar |
BaseTable Exposes
Methods
| Name | Description | Type |
|---|---|---|
| onSearch | debounced search method used by the component | Function |
| onReset | reset search params and trigger a new search | Function |
| restTopInputs | reset only the top form values, then search again according to has-refresh behavior | Function |
| getInputsData | get the current raw search form model | Function |
| setInputsData | set search form values programmatically | Function |
| getSelectRows | get the current selected rows | Function |
| getSelecRowsWithSort | get selected rows in the current rendered order | Function |
| getSortedTableData | get the current rendered table data, optionally flattened from tree data | Function |
| clearSelection | clear all selection, or clear only the specified rows | Function |
| addSelection | select the specified rows | Function |
| getCurrentRow | get the current radio-selected row | Function |
| setCurrentRow | set the current radio-selected row | Function |
| validateCells | validate registered cell editors | Function |
| clearCellValidate | clear validation state for registered cell editors | Function |
| loadTableData | replace the current table data | Function |
| doLayout | trigger internal table layout recalculation | Function |
| setTableHeight | recalculate the table height | Function |
| clearSort | clear the current sort state | Function |
| handleResize | manually recalculate the table height when the surrounding layout changes | Function |
| rememberScrollingPosition | remember current scroll position for later restoration | Function |
Refs and reactive state
| Name | Description | Type |
|---|---|---|
| VTableBase | internal table component ref | object |
| searchForm | top search form ref | object |
| inputsData | raw search form model | object |
| inputsDataDealed | normalized search params derived from inputsData | object |
| selectRows | selected rows ref | array |
| currentRow | current row ref | object |
| tableLoading | internal loading ref | boolean |
| pageNum | current page ref | number |
| pageSize | current page size ref | number |
| total | total count ref | number |
| lastSearchData | last submitted search params | object |
| lazyTreeNodeMapCache | cached lazy-loaded child node data keyed by row-key | object |
$_resizeHandler is also exposed as a deprecated alias of handleResize for backward compatibility.