@byan99/vue-base-table

基于 Vue 3 + TypeScript 的可复用表格组件库，基于 VXE Table Grid，提供搜索表单与状态持久化能力：

• ProPageTable — 搜索 + 表格一体化（推荐）
• ProTable — 高级表格
• ProSearchForm — 可折叠搜索表单

安装

npm install @byan99/vue-base-table element-plus vxe-table vxe-pc-ui

注册依赖

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import VxeUIBase from 'vxe-pc-ui'
import 'vxe-pc-ui/lib/style.css'
import VxeUITable from 'vxe-table'
import 'vxe-table/lib/style.css'

const app = createApp(App)
app.use(ElementPlus)
app.use(VxeUIBase)
app.use(VxeUITable)
app.mount('#app')

ProPageTable 用法（推荐）

搜索 + 表格一体化组件，适合业务页面直接复用：

<script setup lang="ts">
import { reactive } from 'vue'
import {
  ProPageTable,
  createSearchModel,
  type ProTableColumn,
  type SearchField,
} from '@byan99/vue-base-table'

const searchFields: SearchField[] = [
  { key: 'keyword', label: '关键词', type: 'input', placeholder: '请输入' },
  { key: 'role', label: '角色', type: 'select', options: [...] },
]

const searchForm = reactive(createSearchModel(searchFields))
const columns: ProTableColumn[] = [...]
const data = ref([])
const pagination = ref({ currentPage: 1, pageSize: 10, total: 0 })
</script>

<template>
  <ProPageTable
    v-model:search-model="searchForm"
    :search-fields="searchFields"
    :columns="columns"
    :data="data"
    :pagination="pagination"
    row-key="id"
    selection="checkbox"
    @search="loadData"
    @reset="loadData"
    @page-change="onPageChange"
  />
</template>

ProSearchForm 单独使用

仅需搜索区域时：

<ProSearchForm
  v-model="searchForm"
  :fields="searchFields"
  @search="handleSearch"
  @reset="handleReset"
/>

SearchField 支持的 type

| type | 说明 | 默认值 | |------|------|--------| | input | 文本输入（默认） | '' | | textarea | 多行文本 | '' | | number | 数字输入 | undefined | | select | 下拉单选 | '' | | select-multiple | 下拉多选 | [] | | date | 日期 | '' | | date-range | 日期范围 | [] | | datetime | 日期时间 | '' | | datetime-range | 日期时间范围 | [] | | time | 时间 | '' | | time-range | 时间范围 | [] | | month | 月份 | '' | | year | 年份 | '' | | cascader | 级联选择 | [] | | tree-select | 树形选择 | '' | | radio | 单选框 | '' | | radio-button | 单选按钮 | '' | | checkbox | 单个复选框 | false | | checkbox-group | 复选框组 | [] | | switch | 开关 | false | | autocomplete | 自动补全 | '' | | slot | 完全自定义（使用插槽） | - |

未覆盖的场景可使用 type: 'slot' 或 #fieldKey 插槽自定义控件。

状态持久化

传入 storage-key 后，自动将表格配置保存到 localStorage，刷新页面后恢复：

<ProPageTable
  storage-key="user-management"
  :columns="columns"
  :data="data"
  :pagination="pagination"
  @page-change="onPageChange"
/>

| 持久化项 | 说明 | |----------|------| | 列显隐 / 列宽 / 列顺序 / 冻结 | vxe customConfig.storage | | 排序字段与升序/降序 | 自动保存与恢复 | | 每页条数 | pagination.pageSize | | 搜索区展开/收起 | 高级搜索折叠状态 |

细粒度配置：

persist={{
  storageKey: 'user-list',
  storage: 'local',      // 或 'session'
  column: true,
  sort: true,
  pagination: true,
  searchExpanded: true,
}}

清除缓存：tableRef.clearPersist()

<script setup lang="ts">
import { ref } from 'vue'
import { ProTable } from '@byan99/vue-base-table'
import type { ProTableColumn } from '@byan99/vue-base-table'

interface UserRow {
  id: number
  name: string
  role: string
  status: string
}

const columns: ProTableColumn<UserRow>[] = [
  { field: 'name', title: '姓名', sortable: true },
  { field: 'role', title: '角色', filters: [{ label: '管理员', value: '管理员' }] },
  { field: 'status', title: '状态', slot: 'status' },
  { field: 'action', title: '操作', slot: 'action', fixed: 'right' },
]

const data = ref<UserRow[]>([...])
const pagination = ref({ currentPage: 1, pageSize: 10, total: 100 })
</script>

<template>
  <ProTable
    :columns="columns"
    :data="data"
    row-key="id"
    selection="checkbox"
    :pagination="pagination"
    :height="400"
    @page-change="({ currentPage, pageSize }) => { pagination.currentPage = currentPage; pagination.pageSize = pageSize }"
    @selection-change="({ records }) => console.log(records)"
  >
    <template #toolbar-left>
      <button>新增</button>
    </template>
    <template #status="{ row }">
      <span>{{ row.status }}</span>
    </template>
    <template #action>
      <button>编辑</button>
    </template>
  </ProTable>
</template>

ProTable 特性

| 能力 | 说明 | |------|------| | 序号列 | show-seq 默认开启 | | 行选择 | selection="checkbox" 或 "radio" | | 排序 / 筛选 | 列配置 sortable、filters | | 分页 | pagination 配置 | | 工具栏 | 刷新、全屏、列自定义 | | 树形表格 | tree-config 配置 | | 虚拟滚动 | virtual-scroll | | 远程数据 | request 函数 + proxy 模式 | | 列宽拖拽 | resizable 默认开启 | | 插槽 | #columnSlot、#toolbar-left、#toolbar-right |

本地开发

npm run dev

构建组件库

npm run build:lib