PageQueryTable

路径：frontend/src/components/table/page-query-table/PageQueryTable.vue

导出：import PageQueryTable from '@/components/table/page-query-table'，类型见同目录 page-query-table.props.ts、page-query-table.types.ts。

封装目标

把列表页常见结构固化为一层：

搜索区（可选）：声明式字段配置，或 search-main / search-extra 插槽。
工具栏（可选）：toolbar 插槽。
表格区：传入 columns + tableData 使用内置 NDataTable，或 #table 完全自定义。
分页区：itemCount + v-model:page + v-model:page-size，或 #pagination 自定义。

布局与响应式（栅格列数、标签位置、断点）由 usePageQueryTable 计算，样式类名以 pqt- / page-query-table 为前缀。

与模型的绑定（defineModel）

绑定	说明
`v-model:query`	搜索表单双向绑定对象，字段名与 `searchFields[].key` 一致
`v-model:expanded`	「展开」区是否展开（有 `searchFieldsExtra` 或 `search-extra` 时）
`v-model:page`	当前页码
`v-model:pageSize`	每页条数

声明式搜索：`searchFields` / `searchFieldsExtra`

每一项为 PageSearchField（page-query-table.types.ts）：

字段	说明
`key`	对应 `query` 上的属性名
`label`	表单项标签
`type`	`input`（默认）、`select`、`daterange`
`options`	`type === 'select'` 时的 Naive `SelectOption[]`
`placeholder`	占位符
`clearable`	默认 `true`
`valueFormat`	`daterange` 时传给日期控件的格式化串

主区字段放在 searchFields；额外字段放在 searchFieldsExtra，主区旁会出现「展开 / 收起」。

主要 props（节选）

完整定义见 page-query-table.props.ts。

Prop	默认值	说明
`colsPerRow`	`3`	每行搜索项列数；会与断点上限合并（窄屏列数变少）
`stickySearch`	`false`	搜索卡片 `position: sticky` 顶吸
`fill`	`true`	是否占满父级 flex 高度（表格区域可滚动）
`searchLabelWidth`	`88`	搜索表单项标签宽度（非 xs）
`columns`	—	Naive `DataTableColumns`
`tableData`	`[]`	表格数据
`loading`	`false`	加载中
`rowKey`	`'id'`	行主键字段名或函数
`itemCount`	—	总条数；与内置分页同时使用时必传
`pageSizes`	`[10,20,50]`	分页可选每页条数
`formFeedbackHeight`	`0`	表单项校验提示高度 CSS 变量，紧凑为 `0`
`responsive`	`true`	是否按断点压缩列数
`tableMinHeight`	—	表格外包层最小高度（数字视为 px）
`tableMaxHeight`	—	`NDataTable` 的 `max-height`，超出后表体滚动

事件

事件	说明
`search`	点击默认「查询」
`reset`	点击默认「重置」（仅发事件，不自动清 `query`，由页面处理）

插槽

插槽	说明
`search-main`	未配置 `searchFields` 时自定义主搜索区
`search-extra`	展开区自定义（可与 `searchFieldsExtra` 二选一逻辑见源码）
`search-actions`	覆盖默认「查询 / 重置 / 展开」按钮
`toolbar`	表格上方右侧工具区
`table`	完全自定义表格（此时忽略内置 `NDataTable`）
`pagination`	完全自定义分页

典型用法（声明式 + useListFetch）

与 useListFetch 配合时，将 searchParam、page、pageSize、displayRows（或 tableData）、getLoading、itemCount 绑定到表格即可。示例（节选）：

vue

<script setup lang="ts">
import PageQueryTable, { type PageSearchField } from '@/components/table/page-query-table';
import { useListFetch } from '@/composables/list';
import type { DataTableColumns } from 'naive-ui';

const searchExpanded = ref(false);
const { displayRows, getLoading, searchParam, search, reset, page, pageSize, pageable, getTableList } =
  useListFetch({ /* ... */ });

const searchFields: PageSearchField[] = [
  { key: 'name', label: '名称', type: 'input' },
];

const columns: DataTableColumns = [/* ... */];

onMounted(() => getTableList());
</script>

<template>
  <PageQueryTable
    v-model:query="searchParam"
    v-model:expanded="searchExpanded"
    v-model:page="page"
    v-model:page-size="pageSize"
    :search-fields="searchFields"
    :columns="columns"
    :table-data="displayRows"
    :loading="getLoading"
    :item-count="pageable.total"
    @search="search"
    @reset="reset"
  />
</template>

子组件：PageQueryTableSearchForm

文件：PageQueryTableSearchForm.vue。

不单独对外导出为公共 API，由 PageQueryTable 在声明式模式下使用。内部通过 useQueryModelFields 读写 query：input/select 用字符串，daterange 用长度为 2 的数组（与 PageSearchField 一致）。

PageQueryTable ​

封装目标 ​

与模型的绑定（defineModel） ​

声明式搜索：searchFields / searchFieldsExtra ​

主要 props（节选） ​

事件 ​

插槽 ​

典型用法（声明式 + useListFetch） ​

子组件：PageQueryTableSearchForm ​