外观
KvSearchTable
搜索表格场景组合组件,集成搜索栏、工具栏、状态反馈、表格和分页。
实时预览
搜索表格组合
搜索、列设置、外观和刷新状态都可在预览区域中操作。
Total 3Go to
- 1
Props
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
title | string | — | 否 | 可选工具栏标题;未传、空字符串或纯空白时不显示 |
rowKey | string | ((row: T) => string | number) | — | 是 | 行唯一键 |
searchItems | SearchFormItem[] | — | 是 | 搜索项配置 |
searchModel | Record<string, unknown> | — | 是 | 搜索表单数据 |
columns | ColumnOption<T>[] | — | 是 | 当前显示的列 |
columnChecks | ColumnOption<T>[] | — | 是 | 完整列设置 |
data | T[] | — | 是 | 当前页数据 |
loading | boolean | — | 是 | 加载状态 |
error | Error | null | null | 否 | 请求错误 |
pagination | { current: number; size: number; total: number } | — | 是 | 分页状态 |
paginationOptions | KvTablePaginationOptions | { align: 'right' } | 否 | 分页选项 |
toolbarOptions | Partial<KvTableToolbarOptions> | {} | 否 | 工具栏按钮显隐;默认只显示刷新和全屏 |
selectedCount | number | 0 | 否 | 已选行数 |
messages | Partial<KevairyComponentMessages> | {} | 否 | 组件文案覆盖 |
空数据和请求失败时均保留表头,表格内容区只显示空数据图标和一行文字:成功但无数据时为“暂无数据”,请求失败时为“网络错误”。可通过 messages.emptyTitle 和 messages.errorTitle 覆盖文案。空态不显示说明或操作按钮,重新加载请使用工具栏的刷新按钮。
间距配置
可在组件或其祖先上设置以下 CSS 变量;KvSearchTablePage 同样支持继承这些配置。默认搜索栏、表格卡片的内边距,以及搜索栏到卡片、工具栏到表格内容的间距均为 12px。
| CSS 变量 | 默认值 | 说明 |
|---|---|---|
--kv-search-table-gap | 12px | 搜索栏与表格卡片之间的距离 |
--kv-search-table-card-padding-block | 12px | 表格卡片上下内边距 |
--kv-search-table-card-padding-inline | 12px | 表格卡片左右内边距 |
--kv-search-table-toolbar-gap | 12px | 工具栏与表格内容之间的距离 |
搜索栏内边距可通过 KvSearchBar 的 --kv-search-padding-block 和 --kv-search-padding-inline 配置。
搜索栏与表格卡片共用 --kv-container-radius,未设置时回退到 --el-border-radius-base(最终回退为 4px)。在组件或祖先上设置此变量即可统一容器圆角,不影响按钮和输入框的控件圆角;设为 0px 可显示直角。
v-model
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
showSearchBar | boolean | true | 是否显示搜索栏 |
fullscreen | boolean | false | 是否全屏 |
appearance | TableAppearance | 默认外观 | 表格外观 |
全屏切换内置展开与收起动效:进入约 280ms,退出约 220ms,收起后恢复原布局与触发按钮焦点。切换不会重新挂载表格,筛选输入、分页、选择和滚动状态保持;支持 Esc 退出。系统开启“减少动态效果”或浏览器不支持 Web Animations API 时直接切换,窗口尺寸变化时结束当前动效并使用最新布局。
Events
| 事件 | 参数 | 说明 |
|---|---|---|
update:searchModel | Record<string, unknown> | 搜索表单数据变化 |
update:columnChecks | ColumnOption<T>[] | 列设置变化 |
search | Record<string, unknown> | 点击搜索 |
reset | — | 点击重置 |
refresh | — | 点击刷新 |
retry | — | 兼容保留,默认界面不触发 |
selection-change | T[] | 行选择变化 |
sort-change | TableSortChange | 排序变化 |
size-change | number | 每页条数变化 |
current-change | number | 当前页变化 |
scroll-top | — | 翻页后滚动到顶部 |
Slots
toolbar-left / toolbar-right 中插入的按钮统一使用 8px 间距,与内置工具按钮一致;直接插入按钮即可,不要叠加外边距或间距容器。详见 插槽按钮间距规范。
| 插槽 | 说明 |
|---|---|
toolbar-left | 数量统计之后的左侧扩展 |
toolbar-right | 工具栏右侧扩展 |
bulk-actions | 选中行后的批量操作 |
[column.prop] | 单元格插槽,列配置 useSlot: true 时生效 |
[column.prop]-header | 表头插槽,列配置 useHeaderSlot: true 时生效 |
示例代码
vue
<script setup>
import { ref } from 'vue'
import { KvSearchTable } from '@kevairy/components'
const searchModel = ref({ keyword: '' })
const searchItems = [{ key: 'keyword', label: '关键词', type: 'input' }]
const columns = ref([
{ prop: 'id', label: 'ID' },
{ prop: 'name', label: '名称' }
])
const columnChecks = ref([
{ prop: 'id', label: 'ID', visible: true },
{ prop: 'name', label: '名称', visible: true }
])
const data = ref([
{ id: 1, name: 'Item 1' },
{ id: 2, name: 'Item 2' }
])
const pagination = ref({ current: 1, size: 10, total: 2 })
const handleSearch = (params) => {
console.log(params)
}
</script>
<template>
<KvSearchTable
title="列表"
row-key="id"
:search-items="searchItems"
v-model:search-model="searchModel"
:columns="columns"
:column-checks="columnChecks"
:data="data"
:loading="false"
:pagination="pagination"
@search="handleSearch"
/>
</template>