Skip to content

KvSearchTable ​

搜索表格场景组合组件,集成搜索栏、工具栏、状态反馈、表格和分页。

实时预览 ​

搜索表格组合

搜索、列设置、外观和刷新状态都可在预览区域中操作。

实时渲染
服务列表共 3 项
已刷新 0 次

Props ​

属性类型默认值必填说明
titlestring—否可选工具栏标题;未传、空字符串或纯空白时不显示
rowKeystring | ((row: T) => string | number)—是行唯一键
searchItemsSearchFormItem[]—是搜索项配置
searchModelRecord<string, unknown>—是搜索表单数据
columnsColumnOption<T>[]—是当前显示的列
columnChecksColumnOption<T>[]—是完整列设置
dataT[]—是当前页数据
loadingboolean—是加载状态
errorError | nullnull否请求错误
pagination{ current: number; size: number; total: number }—是分页状态
paginationOptionsKvTablePaginationOptions{ align: 'right' }否分页选项
toolbarOptionsPartial<KvTableToolbarOptions>{}否工具栏按钮显隐;默认只显示刷新和全屏
selectedCountnumber0否已选行数
messagesPartial<KevairyComponentMessages>{}否组件文案覆盖

空数据和请求失败时均保留表头,表格内容区只显示空数据图标和一行文字:成功但无数据时为“暂无数据”,请求失败时为“网络错误”。可通过 messages.emptyTitle 和 messages.errorTitle 覆盖文案。空态不显示说明或操作按钮,重新加载请使用工具栏的刷新按钮。

间距配置 ​

可在组件或其祖先上设置以下 CSS 变量;KvSearchTablePage 同样支持继承这些配置。默认搜索栏、表格卡片的内边距,以及搜索栏到卡片、工具栏到表格内容的间距均为 12px。

CSS 变量默认值说明
--kv-search-table-gap12px搜索栏与表格卡片之间的距离
--kv-search-table-card-padding-block12px表格卡片上下内边距
--kv-search-table-card-padding-inline12px表格卡片左右内边距
--kv-search-table-toolbar-gap12px工具栏与表格内容之间的距离

搜索栏内边距可通过 KvSearchBar 的 --kv-search-padding-block 和 --kv-search-padding-inline 配置。

搜索栏与表格卡片共用 --kv-container-radius,未设置时回退到 --el-border-radius-base(最终回退为 4px)。在组件或祖先上设置此变量即可统一容器圆角,不影响按钮和输入框的控件圆角;设为 0px 可显示直角。

v-model ​

名称类型默认值说明
showSearchBarbooleantrue是否显示搜索栏
fullscreenbooleanfalse是否全屏
appearanceTableAppearance默认外观表格外观

全屏切换内置展开与收起动效:进入约 280ms,退出约 220ms,收起后恢复原布局与触发按钮焦点。切换不会重新挂载表格,筛选输入、分页、选择和滚动状态保持;支持 Esc 退出。系统开启“减少动态效果”或浏览器不支持 Web Animations API 时直接切换,窗口尺寸变化时结束当前动效并使用最新布局。

Events ​

事件参数说明
update:searchModelRecord<string, unknown>搜索表单数据变化
update:columnChecksColumnOption<T>[]列设置变化
searchRecord<string, unknown>点击搜索
reset—点击重置
refresh—点击刷新
retry—兼容保留,默认界面不触发
selection-changeT[]行选择变化
sort-changeTableSortChange排序变化
size-changenumber每页条数变化
current-changenumber当前页变化
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>