@hz_yujin/vue2-base-table

@hz_yujin/vue2-base-table

基于 Vue 2.6 / 2.7 + Element UI + vxe-table 的 ProTable 组件库。

• Vue 2.7：直接使用内置 Composition API
• Vue 2.6：需安装并注册 @vue/composition-api（老项目如已安装可直接复用）

能力概览

安装

Vue 2.7

npm install @hz_yujin/vue2-base-table element-ui vxe-table@3.8.28 xe-utils

Vue 2.6（如 2.6.14）

npm install @hz_yujin/vue2-base-table element-ui vxe-table@3.8.28 xe-utils @vue/composition-api

老项目若已有 @vue/composition-api，无需重复安装。

注册

Vue 2.7

import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
import VXETable from 'vxe-table'
import 'vxe-table/lib/style.css'
import Vue2BaseTable from '@hz_yujin/vue2-base-table'
import '@hz_yujin/vue2-base-table/style.css'

Vue.use(ElementUI)
Vue.use(VXETable)
// 宿主布局层级较高时可：Vue.use(Vue2BaseTable, { zIndex: 4000 })
Vue.use(Vue2BaseTable)

Vue 2.6

import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
import VXETable from 'vxe-table'
import 'vxe-table/lib/style.css'
import Vue2BaseTable from '@hz_yujin/vue2-base-table'
import '@hz_yujin/vue2-base-table/style.css'

// 必须在表格插件之前注册
Vue.use(VueCompositionAPI)
Vue.use(ElementUI)
Vue.use(VXETable)
Vue.use(Vue2BaseTable)

Vue CLI 3 工程如遇 ESM 解析问题，可在 vue.config.js 中加入： transpileDependencies: ['@hz_yujin/vue2-base-table', 'vue-demi']

全局注册组件名：ProTable、ProSearchForm、ProPageTable、ProDialog。支持 prefix、zIndex，例如 Vue.use(Vue2BaseTable, { prefix: 'Hz', zIndex: 4000 })。

ProPageTable（推荐入口）

搜索区 + ProTable 的页面级组合。业务侧通常配合 useProTableRequest 做远程分页 / 排序 / 筛选。

快速开始

<template>
  <ProPageTable
    :search-fields="searchFields"
    :search-model.sync="searchModel"
    :columns="columns"
    :data="data"
    :loading="loading"
    :pagination="pagination"
    storage-key="user-list"
    selection
    @search="handleSearch"
    @reset="handleReset"
    @page-change="handlePageChange"
    @sort-change="handleSortChange"
    @filter-change="handleFilterChange"
    @refresh="loadData"
  >
    <template #action="{ row }">
      <el-button type="text" size="mini" @click="onEdit(row)">编辑</el-button>
    </template>
  </ProPageTable>
</template>

<script>
import { useProTableRequest } from '@hz_yujin/vue2-base-table'

export default {
  setup() {
    const columns = [
      { field: 'name', title: '姓名', minWidth: 120, sortable: true, search: true },
      {
        field: 'status',
        title: '状态',
        width: 100,
        valueType: 'tag',
        valueEnum: {
          启用: { text: '启用', status: 'success' },
          禁用: { text: '禁用', status: 'info' },
        },
        filters: [
          { label: '启用', value: '启用' },
          { label: '禁用', value: '禁用' },
        ],
        search: { type: 'select' },
      },
      { field: 'createdAt', title: '创建时间', minWidth: 160, valueType: 'datetime' },
      { field: 'action', title: '操作', width: 100, fixed: 'right', slot: 'action' },
    ]

    const {
      searchFields,
      searchModel,
      data,
      loading,
      pagination,
      loadData,
      handleSearch,
      handleReset,
      handlePageChange,
      handleSortChange,
      handleFilterChange,
    } = useProTableRequest({
      columns,
      storageKey: 'user-list',
      fetcher: async ({ currentPage, pageSize, form, sort, filters, signal }) => {
        // 返回 { list, total }；可用 signal 取消过期请求
        const res = await api.fetchUsers({ currentPage, pageSize, form, sort, filters, signal })
        return { list: res.list, total: res.total }
      },
    })

    function onEdit(row) {
      // ...
    }

    return {
      columns,
      searchFields,
      searchModel,
      data,
      loading,
      pagination,
      loadData,
      handleSearch,
      handleReset,
      handlePageChange,
      handleSortChange,
      handleFilterChange,
      onEdit,
    }
  },
}
</script>

排序 / 筛选均为 remote：点击表头后会触发 sort-change / filter-change，需业务重新请求数据（useProTableRequest 已内置处理）。

Props（搜索区）

Props（表格区，透传 ProTable）

Events

Slots

ProTable

纯表格（无搜索区）。Props / Events / Slots 与上表「表格区」一致；pagination 默认 false。

额外事件：row-click、zoom、custom、edit-closed、edit-activated。

实例方法

this.$refs.table.getCheckboxRecords()
this.$refs.table.clearSelection()

列配置 columns

操作列约定：field / slot 为 action，或标题为「操作」，或 cardAction: true 时，自动关闭排序与拖拽改宽。

valueType

自定义：

import { registerValueType } from '@hz_yujin/vue2-base-table'

registerValueType('score', {
  format: (v) => (v == null || v === '' ? '—' : `${Number(v).toFixed(1)} 分`),
})

列示例

const columns = [
  { type: 'expand', width: 48, slot: 'expand' },
  { field: 'name', title: '姓名', minWidth: 120, sortable: true, search: true },
  {
    field: 'dept',
    title: '部门',
    minWidth: 100,
    filters: [
      { label: '研发', value: '研发' },
      { label: '产品', value: '产品' },
    ],
  },
  {
    field: 'status',
    title: '状态',
    width: 90,
    valueType: 'tag',
    valueEnum: {
      启用: { text: '启用', status: 'success' },
      禁用: { text: '禁用', status: 'info' },
    },
  },
  { field: 'amount', title: '金额', width: 110, align: 'right', valueType: 'money' },
  { field: 'createdAt', title: '创建时间', minWidth: 160, valueType: 'datetime' },
  { field: 'action', title: '操作', width: 140, fixed: 'right', slot: 'action' },
]

搜索字段

用于 ProPageTable 的 searchFields / ProSearchForm 的 fields。

控件类型

从列生成搜索字段

列上配置 search 后，useProTableRequest / buildSearchFieldsFromColumns 会自动生成搜索项：

• search: true → 有 filters 则为 select，否则 input
• search: { key?, label?, type?, placeholder?, width?, options?, defaultValue?, props? } → 覆盖默认

显式传入的 searchFields 会与列生成结果按 key 合并（显式优先）。

useProTableRequest

Composition API 受控请求封装。

选项

fetcher 参数：

{
  currentPage: number
  pageSize: number
  form: Record<string, unknown>   // 搜索模型快照
  sort: { field: string | null, order: 'asc' | 'desc' | null }
  filters: Record<string, Array<string | number | boolean>>  // field -> values
  signal: AbortSignal             // 新请求会 abort 上一次
}

返回值

工具栏 toolbar

<ProPageTable
  :toolbar="{ export: true, print: true, zoom: false }"
  ...
/>

分页 pagination

常用字段：currentPage、pageSize、total、pageSizes、pagerCount、layouts。

ProPageTable 默认开启分页对象；ProTable 默认关闭。

持久化 storageKey / persist

传入 storageKey 即开启默认持久化（localStorage，键前缀 pro-table:state:）。

<ProPageTable
  storage-key="user-list"
  :persist="{ storage: 'session', search: false }"
  ...
/>

persist: false 关闭全部持久化。实例方法 clearPersist() 可清除当前键状态。

选择 / 批量 / 骨架 / 移动端

选择

<ProTable selection reserve-selection row-key="id" ... />
<!-- 或 selection="radio" -->

跨页多选必须：selection 为 checkbox，且 row-key 为字符串字段名，并开启 reserve-selection。

批量操作

<ProPageTable
  selection
  :batch-actions="{ clearable: true, selectedText: '已选' }"
  ...
>
  <template #batch-actions="{ selected, clear }">
    <el-button type="danger" size="mini" @click="onBatchDelete(selected)">
      删除 {{ selected.length }} 项
    </el-button>
  </template>
</ProPageTable>

骨架屏 skeleton

移动端卡片 mobileCard

窄屏或容器过窄时自动切卡片列表。

树表 / 行内编辑

<ProTable
  :data="treeData"
  :columns="columns"
  :tree-config="{ children: 'children', expandAll: false }"
  :edit-config="{ trigger: 'click', mode: 'cell' }"
  @edit-save="onEditSave"
/>

列上设置 treeNode: true 指定树节点列；editRender: { name: 'input' } 开启该列编辑。

ProSearchForm

可单独使用的搜索表单。

事件：input、search、reset。

扩展 API

import {
  registerValueType,
  registerValueTypes,
  registerSearchField,
  registerSearchFields,
  setProTableDefaults,
  buildSearchFieldsFromColumns,
  createSearchModel,
} from '@hz_yujin/vue2-base-table'

// 自定义搜索控件
registerSearchField('my-picker', MyPickerComponent)

// 全局默认（按需）
setProTableDefaults({ /* ... */ })

按需引入

import {
  ProPageTable,
  ProTable,
  ProSearchForm,
  ProDialog,
  useProTableRequest,
} from '@hz_yujin/vue2-base-table'
import '@hz_yujin/vue2-base-table/style.css'

ProDialog

与表格并列使用的弹框封装，不内嵌在 ProTable 中。基于 el-dialog，统一圆角、标题栏与底部操作区样式。

基础用法

<template>
  <div>
    <el-button type="primary" @click="visible = true">打开</el-button>

    <ProDialog
      v-model="visible"
      title="编辑用户"
      size="medium"
      :confirm-loading="saving"
      @confirm="handleSave"
      @cancel="visible = false"
    >
      <el-form label-width="80px" size="small">
        <!-- 表单内容 -->
      </el-form>
    </ProDialog>
  </div>
</template>

<script>
export default {
  data() {
    return { visible: false, saving: false }
  },
  methods: {
    async handleSave() {
      this.saving = true
      try {
        // await api.save(...)
        this.visible = false
      } finally {
        this.saving = false
      }
    },
  },
}
</script>

也可用 :visible.sync="visible" 控制显隐（与 v-model 二选一即可）。

Props

层级约定

若宿主顶栏 / 抽屉 / 无界遮罩等高于默认起点，在入口抬高即可（MessageBox 会自动跟着抬）：

import Vue2BaseTable, {
  setPopupZIndexBase,
  getPopupLayerZIndex,
} from '@hz_yujin/vue2-base-table'
import '@hz_yujin/vue2-base-table/style.css'

// 方式一：插件选项（推荐）
Vue.use(ElementUI, { zIndex: 12000 })
Vue.use(Vue2BaseTable, { zIndex: 12000 })
// → Dialog 自 12000 起；MessageBox≈13900；Message≈14000

// 方式二：显式 API
setPopupZIndexBase(12000)
const { messageBox } = getPopupLayerZIndex()

业务弹层用 ProDialog；删改确认继续用 $confirm / MessageBox。

size 与宽度对照

Events

Slots