Table Search Page

一个基于 Naive UI 的增强表格组件，提供高级筛选、列配置持久化等实用功能。

功能特点

• 高级搜索与快速过滤
• 表格列配置持久化
• 自定义分页大小与迷你分页
• 数据导出功能
• 完全类型安全
• 路由参数同步
• 排序功能支持

安装

# 使用 npm 安装
npm install table-search-page

# 使用 yarn 安装
yarn add table-search-page

# 使用 pnpm 安装
pnpm add table-search-page

必要依赖

本组件依赖以下包，请确保已安装：

# 安装必要依赖
npm install naive-ui@^2.41.0 class-transformer@^0.5.1 class-validator@^0.14.1 lodash-es@^4.17.21 vue@^3.5.0 vue-router@^4.5.0

在主文件中引入样式:

// main.ts
import 'table-search-page/dist/style.css'

快速开始

基本用法

<template>
  <div>
    <!-- 引入搜索过滤组件 -->
    <QuickFilterInput
      v-model:value="searchParams"
      :filter-model="filterModel"
      @search="handleSearch"
    />
    
    <!-- 表格组件 -->
    <n-data-table
      :columns="columns"
      :data="paging.records"
      :loading="loading"
      :pagination="paginationProps"
      @update:sorter="handleSorter"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue'
import { NDataTable } from 'naive-ui'
import { 
  QuickFilterInput, 
  useNaiveTableSearchPage, 
  useFilterModel,
  useFilterParams,
  Pageable 
} from 'table-search-page'
import type { QuickQueryModel } from 'table-search-page'

// 定义查询参数类
class SearchParams extends Pageable {
  name?: string
  status?: number
}

// 搜索参数
const searchParams = reactive(new SearchParams())

// 过滤模型配置
const { filterModel } = useFilterModel<SearchParams>(() => ({
  name: {
    label: '名称',
    component: 'Input',
    componentProps: {
      placeholder: '请输入名称'
    }
  },
  status: {
    label: '状态',
    component: 'Select',
    componentProps: {
      options: [
        { label: '启用', value: 1 },
        { label: '禁用', value: 0 }
      ]
    }
  }
}))

// 表格列定义
const columns = [
  { title: 'ID', key: 'id', sorter: true },
  { title: '名称', key: 'name' },
  { title: '状态', key: 'status' },
  {
    title: '操作',
    key: 'actions',
    render: (row) => {
      return h(NButton, { onClick: () => handleEdit(row) }, { default: () => '编辑' })
    }
  }
]

// 使用表格分页 hook
const { 
  paging, 
  loading, 
  paginationProps, 
  refresh, 
  exportData,
  handleSorter
} = useNaiveTableSearchPage({
  cls: SearchParams,
  fetchBuilder: async (params) => {
    // 调用 API 获取数据
    const res = await api.getList(params)
    return res
  },
  // 高级配置选项
  tableSettingKey: 'demo-table',
  storeColumnSetting: true,
  showSizePicker: true,
  pageSizes: [10, 20, 50, 100],
  useMiniPagination: false,
  resetPageOnRefresh: true
})

// 搜索处理
const handleSearch = () => {
  refresh(true) // true表示重置页码
}

// 导出数据
const handleExport = () => {
  exportData({
    filename: '数据导出',
    callback: (data) => {
      // 可以在这里对数据进行转换
      return data
    }
  })
}

// 编辑处理
const handleEdit = (row) => {
  console.log('编辑行:', row)
}
</script>

API 文档

Hooks

useNaiveTableSearchPage

主要的表格分页控制 Hook，提供完整的表格功能。

const { 
  paging,            // 分页数据
  loading,           // 加载状态
  paginationProps,   // 分页属性配置
  miniPaginationProps, // 迷你分页属性配置
  refresh,           // 刷新数据
  exportData,        // 导出数据
  handleSorter,      // 排序处理
  changeSort,        // 改变排序
  resetSort,         // 重置排序
  changeLimit,       // 改变每页大小
  changePage         // 改变页码
} = useNaiveTableSearchPage(options)

options 配置项：

| 属性名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | cls | ClassConstructor | 是 | 查询参数类构造器 | | fetchBuilder | Function | 是 | 数据获取函数 | | tableSettingKey | String | 否 | 表格配置存储键名 | | storeColumnSetting | Boolean | 否 | 是否存储列配置到本地 | | showSizePicker | Boolean | 否 | 是否显示分页大小选择器 | | pageSizes | Number[] | 否 | 分页大小选项 | | useMiniPagination | Boolean | 否 | 是否使用小型分页 | | resetPageOnRefresh | Boolean | 否 | 刷新时是否重置页码 | | watchRoute | Boolean | 否 | 是否监听路由变化 | | filterModelBuild | Function | 否 | 过滤模型构建函数 | | fetchParamsBuilder | Function | 否 | 请求参数构建函数 | | paramsBuilder | Function | 否 | 路由参数构建函数 | | errorBuilder | Function | 否 | 错误处理函数 | | validateParams | Function | 否 | 参数验证函数 | | listBuilder | Function | 否 | 列表数据构建函数 |

useFilterModel

用于定义搜索表单模型。

const { filterModel } = useFilterModel<SearchParams>(() => ({
  // 配置过滤字段
  fieldName: {
    label: '字段标签',
    component: '组件名称',
    componentProps: { /* 组件属性 */ }
  }
}))

useFilterParams

用于处理过滤参数。

const { getFilterParams } = useFilterParams<SearchParams>(SearchParams)

usePage

用于基础分页控制。

const { 
  pagination,
  loading,
  changePage,
  changeLimit,
  changeSort
} = usePage(options)

useTableExpand

用于表格展开行功能。

const { 
  expandedRowKeys,
  handleExpandClick,
  handleExpandAll
} = useTableExpand()

组件

QuickFilterInput

快速过滤输入组件。

<QuickFilterInput
  v-model:value="searchParams"
  :filter-model="filterModel"
  @search="handleSearch"
  @reset="handleReset"
/>

属性：

| 属性名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | value | Object | 是 | 搜索参数对象 | | filter-model | Object | 是 | 过滤模型配置 | | label-width | Number, String | 否 | 标签宽度 | | show-reset | Boolean | 否 | 是否显示重置按钮 | | search-immediate | Boolean | 否 | 是否立即搜索 |

事件：

| 事件名 | 说明 | | --- | --- | | search | 点击搜索按钮时触发 | | reset | 点击重置按钮时触发 | | update:value | 更新值时触发 |

类型定义

组件提供完整的 TypeScript 类型定义，确保代码编写的类型安全。主要类型包括：

• IPageable: 分页接口
• Pageable: 分页实现类
• QuickQueryModel: 快速查询模型
• QuickQueryModelItem: 快速查询模型项
• RestfulResult: RESTful 结果类型
• Pagination: 分页结果类型

高级用法

列设置持久化

通过设置 storeColumnSetting 和 tableSettingKey，可以启用列配置持久化：

const { paging, loading } = useNaiveTableSearchPage({
  // ...
  tableSettingKey: 'unique-table-key',
  storeColumnSetting: true
})

自定义导出数据

exportData({
  filename: '导出文件名',
  callback: (data) => {
    // 数据处理逻辑
    return data.map(item => ({
      id: item.id,
      name: item.name,
      // 添加自定义字段或转换数据
      statusText: item.status === 1 ? '启用' : '禁用'
    }))
  }
})

路由同步查询参数

组件默认支持与路由查询参数同步，可通过 watchRoute 选项控制：

const { paging } = useNaiveTableSearchPage({
  // ...
  watchRoute: true // 默认为 true
})

版本更新

请查看 CHANGELOG.md 了解版本变更历史。

许可证

MIT