table-grid-plugin

table-grid-plugin

开箱即用的 Vue3 高性能数据表格组件（XDataGrid）。

纯 div 实现 · 自研虚拟滚动内核 · 运行时零依赖（仅依赖 vue）· 百万级数据流畅渲染 · 移动端自动切换为卡片浏览。渲染层统一使用 TSX（h 函数），不依赖任何底层表格库。

内置能力：虚拟滚动 / 树形表格（含懒加载）/ 多级表头 / 固定列与表头 / 单选·多选·树形级联选择 / 单元格合并 / 展开行 / 排序 / 列筛选 / 分页（本地与远程）/ 滚动加载更多（load-more）/ 表尾合计 / 单元格编辑 / 对象字段（点路径 key）/ 工具栏（列设置·搜索·通用操作按钮）/ 提示框 Tooltip / 列设置缓存（IndexedDB）/ 骨架屏 / 移动端卡片模式。

目录

• table-grid-plugin
  • 目录
  • 1. 安装
  • 2. 引入（快速开始）
    • 2.1 全局注册（推荐）
    • 2.2 局部使用组件
    • 2.3 Composition API：useTable
  • 3. 演示 Demo
  • 4. API 文档
    • 4.1 Props 参数表
    • 4.2 ColumnConfig 列配置
    • 4.3 ToolbarConfig 工具栏配置
    • 4.4 ToolbarAction 操作按钮
    • 4.5 TableAction 操作列按钮
    • 4.6 Pagination 分页配置
    • 4.7 LoadMoreConfig 加载更多配置
    • 4.8 FooterSummaryConfig 合计配置
    • 4.9 TreeProps 树形配置
    • 4.10 CardFieldConfig 卡片字段配置
    • 4.11 ArrayMergeConfig 数组合并配置
    • 4.12 事件
    • 4.13 实例方法
    • 4.14 插槽 Slots
    • 4.15 类型定义
  • 5. 功能详解
    • 5.1 百万级数据渲染（虚拟滚动）
    • 5.2 列配置与多级表头
    • 5.3 固定列 / 固定表头
    • 5.4 树形表格与懒加载
    • 5.5 选择（多选 / 单选 / 全选 / 树形级联）
    • 5.6 排序
    • 5.7 列筛选
    • 5.8 分页
    • 5.9 表尾合计统计行
    • 5.10 单元格编辑
    • 5.11 工具栏
    • 5.12 提示框 Tooltip
    • 5.13 单元格合并
    • 5.14 展开行
    • 5.15 列设置与缓存
    • 5.16 远程数据模式
    • 5.17 加载态 / 骨架屏 / 空态
    • 5.18 移动端卡片模式
    • 5.19 密度 / 斑马纹 / 行高 / 边框
    • 5.20 事件与实例方法
    • 5.21 滚动到底部加载更多（load-more）
    • 5.21.1 数据加载方式切换
    • 5.22 对象字段（点路径 key）
    • 5.23 数组对象自动合并
  • 6. 主题定制（CSS 变量）
  • 7. 国际化（i18n）
    • 7.1 文本词典翻译（推荐）
    • 7.2 切换机制与内置语言包（key 型）
    • 7.3 语言包结构
  • 8. 浏览器兼容性
  • 9. 常见问题 FAQ
  • License

1. 安装

npm i table-grid-plugin

vue（≥ 3.2）作为唯一的 peerDependency，安装本插件前请确认目标项目已安装 Vue3。

2. 引入（快速开始）

2.1 全局注册（推荐）

// main.ts
import { createApp } from 'vue'
import XDataGrid from 'table-grid-plugin'
// 样式随组件按需引入（sideEffects 已声明 scss）
import 'table-grid-plugin/dist/table-grid-plugin.css'
import App from './App.vue'

const app = createApp(App)
app.use(XDataGrid) // 自动注册为全局组件 <XDataGrid />
app.mount('#app')

2.2 局部使用组件

<script setup>
import XDataGrid from 'table-grid-plugin'

const columns = [
  { key: 'name', label: '姓名', width: 140, fixed: 'left' },
  { key: 'age', label: '年龄', width: 100, sortable: true },
  { key: 'city', label: '城市', width: 140, filterable: true }
]
const data = [
  { id: 1, name: '张三', age: 18, city: '北京' },
  { id: 2, name: '李四', age: 22, city: '上海' }
]
</script>

<template>
  <XDataGrid
    :columns="columns"
    :data="data"
    row-key="id"
    style="height: 400px"
  />
</template>

组件必须给定一个确定的高度（容器高度或 height 属性），虚拟滚动依此计算可视行区间。

2.3 Composition API：useTable

useTable 提供与组件同源的响应式状态，可脱离组件单独使用（如自建视图层或后台逻辑复用）：

import { ref } from 'vue'
import { useTable } from 'table-grid-plugin'

const columns = ref([{ key: 'name', label: '姓名', width: 140 }])
const data = ref([{ id: 1, name: '张三' }])
const containerRef = ref<HTMLElement | null>(null)

const state = useTable(
  { columns, data, rowKey: 'id' } as any,
  () => {},
  containerRef
)
// state.scroller.range.value → 当前可视行区间
// state.selection.getSelectedRows() → 选中行

3. 演示 Demo

仓库 demo/ 目录内置完整演示项目，覆盖下方全部功能点，每个示例对应右侧「代码参考」栏：

启动演示：

npm i
npm run demo:dev        # 本地开发（默认 http://localhost:5177）
npm run demo:build      # 构建产物输出到 demo-dist/

4. API 文档

4.1 Props 参数表

所有属性均非响应式强关联，声明即生效。

4.2 ColumnConfig 列配置

4.3 ToolbarConfig 工具栏配置

4.4 ToolbarAction 操作按钮

4.45 TableAction 操作列按钮

在列配置 ColumnConfig.actions 中声明（见 5.24）。每个按钮即一个 TableAction：

4.5 Pagination 分页配置

4.6 LoadMoreConfig 加载更多配置

提供 loadMore 对象即启用「滚动到底部自动加载更多」：滚动条滚动到距底部阈值内触发 load-more 回调，动态查询下一页并追加到 data 自动累加为大表格；该模式下自动隐藏分页条（无需「下一页」按钮）。

4.7 FooterSummaryConfig 合计配置

FooterStatsField：

4.9 TreeProps 树形配置

4.9 CardFieldConfig 卡片字段配置

4.14 ArrayMergeConfig 数组合并配置

arrayMerge 接受 boolean 或如下对象：

4.9 事件

4.11 实例方法

通过组件 ref 访问：

4.14 插槽 Slots

插槽优先级高于 cellRender / headerRender。控制列（selection/expand/index）的点击事件已被组件内部接管。

4.15 类型定义

import type {
  TableProps, TableEvents, TableInstance, SelectionInfo,
  ColumnConfig, TreeProps, SpanMethod, SpanCellContext,
  TableRowRecord, RowKeyResolver, CardFieldConfig,
  ThemeTokens, SelectMode, SortInfo, FilterState,
  Pagination, LoadMoreConfig, FooterSummaryConfig, ToolbarConfig, ToolbarAction, TableAction
} from 'table-grid-plugin'

SelectionInfo（selection-change 回调与 getSelectionInfo() 的返回值，区分「完全选中」与「半选」）：

interface SelectionInfo {
  /** 完全选中节点键 */
  checkedKeys: Array<string | number>
  /** 半选（部分选中）节点键 */
  indeterminateKeys: Array<string | number>
  /** 完全选中节点的原始数据（含被级联选中的父级与其下级） */
  checked: TableRowRecord[]
  /** 半选（通常为父级）节点的原始数据 */
  indeterminate: TableRowRecord[]
  /** 快捷字段：完全选中节点原始数据，等价于 checked */
  selection: TableRowRecord[]
}

5. 功能详解

5.1 百万级数据渲染（虚拟滚动）

不含原生 <table>，Body 基于行高做数学定位，仅渲染可视区间 + 缓冲行，滚动复杂度为 O(1)。

<XDataGrid
  :columns="columns"
  :data="100000Rows"   <!-- 十万行即可流畅，百万级亦无压力 -->
  row-key="id"
  stripe
  :loading="loading"
  :skeleton="skeleton"
  :density="'compact'"
  :row-height="44"
/>

5.2 列配置与多级表头

叶子的 children 自动生成多级表头，宽度按子树叶子累计。

const columns = [
  { key: 'name', label: '姓名', width: 140 },
  {
    label: '成绩（多级）',
    children: [
      { key: 'chinese', label: '语文', width: 110 },
      { key: 'math', label: '数学', width: 110 },
      { key: 'english', label: '英语', width: 110 }
    ]
  }
]

5.3 固定列 / 固定表头

const columns = [
  { key: 'name', label: '姓名', width: 140, fixed: 'left' },
  { key: 'age', label: '年龄', width: 100 },
  // ...中间滚动列
  { key: 'action', label: '操作', width: 120, fixed: 'right' }
]

5.4 树形表格与懒加载

通过 treeProps 指定 children 字段；懒加载场景用 lazy + loadChildren。

<XDataGrid :columns="columns" :data="treeData" row-key="id" :tree-props="treeProps">
</XDataGrid>

const treeProps = {
  children: 'children',                 // 子节点字段名（默认 'children'）
  hasChildren: 'hasChildren',           // 存在子节点字段（懒加载占位判断）
  lazy: true,                           // 是否懒加载
  loadChildren: async (row) => {
    const res = await fetch('/api/children?id=' + row.id)
    return res.json()
  }
}

5.5 选择（多选 / 单选 / 全选 / 树形级联）

普通扁平数据选择：

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  select-mode="multiple"
  :selectable="row => !row.disabled"
  @selection-change="onChange"
>
</XDataGrid>

// selection-change 回调收到完整选择信息，区分「完全选中」与「半选」
function onChange({ checked, checkedKeys, indeterminate, indeterminateKeys, selection }) {
  console.log('完全选中(含级联)节点数', checked.length)
  console.log('半选父级数', indeterminate.length)
  console.log('完全选中原始数据', checked)
}

树形级联选择（默认关联模式）：

<XDataGrid
  :columns="columns"
  :data="treeData"
  row-key="id"
  select-mode="multiple"
  :default-checked-keys="[11]"          <!-- 默认选中 11，自动连带选中下级并归约父级 -->
  :check-strictly="false"               <!-- 省略即默认：上下级关联选择 -->
  @selection-change="onChange"
>
</XDataGrid>

const gridRef = ref(null)
function readSelection() {
  const info = gridRef.value?.getSelectionInfo()  // 手动获取
  console.log(info.checkedKeys, info.indeterminateKeys)
}

5.6 排序

列配置 sortable: true 即显示上/下三角（点上=升序、点下=降序、再次点击清除）。

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  :default-sort="[{ key: 'amount', order: 'desc' }]"
  :sort-mode="'local'"     <!-- 本地排序（默认）；remote 则触发事件由外层处理 -->
  @sort-change="onSortChange"
>
</XDataGrid>

function onSortChange({ key, order }) {
  // order：'asc' 上箭头升序 / 'desc' 下箭头降序 / null 清除
}

5.7 列筛选

列配置 filterable: true 即显示筛选图标，点击弹出候选下拉。

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  :filter-mode="'local'"        <!-- 本地筛选（默认）；remote 触发事件由外层处理 -->
  :column-filters="[{ key: 'city', values: ['北京'] }]"
  @filter-change="onFilterChange"
>
</XDataGrid>

const columns = [
  {
    key: 'city', label: '城市',
    filterable: true,
    filterOptions: ['北京', '上海', '广州'], // 候选；缺省取该列全部去重值
    filterMultiple: true                     // 多选筛选
  }
]
function onFilterChange({ key, filters }) {
  // key：触发筛选的字段；filters：当前全部筛选条件
}

5.8 分页

提供 pagination 对象即启用分页。

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  :pagination="{ pageSize: 20, pageSizes: [10, 20, 50], current: 1 }"
  @page-change="onPageChange"
>
</XDataGrid>

id 同时用于列设置缓存（5.15）与分页页码持久化——二者以独立子键存储，互不冲突：

<XDataGrid
  id="order-table"
  :columns="columns"
  :data="data"
  row-key="id"
  :pagination="{ pageSize: 20, pageSizes: [10, 20, 50] }"
  @page-change="onPageChange"
>
</XDataGrid>

5.9 表尾合计统计行

showFooter 开启合计行；两种配置来源：

A. 可配置统计行（推荐）：footerSummary 支持多字段、多统计方式：

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  show-footer
  :footer-summary="footerSummary"
>
</XDataGrid>

const footerSummary = {
  label: '合计',
  fields: [
    { field: 'amount', formatter: (v) => '¥' + Number(v).toLocaleString() },  // 默认求和
    { field: 'progress', method: 'average' },                                  // 平均
    { field: 'id', method: { type: 'sum', multiplier: 0.5 } },                 // 系数求和（每行值 × 0.5 再累积）
    { field: 'status', fn: (rows) => rows.filter((r) => r.status === '已完成').length } // 自定义函数
  ]
}

B. 列级配置（旧）：列 summable: true 默认求和；或传入 { type, custom, formatter } 聚合对象。

5.10 单元格编辑

列配置 editable: true + 组件 editable 启用后，双击单元格进入编辑（回车提交 / 失焦提交 / Esc 取消）。

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  editable
  @edit-change="onEditChange"
>
</XDataGrid>

const columns = [
  {
    key: 'amount', label: '金额(元)',
    editable: true,
    editType: 'number',                      // 数字输入，提交自动 Number()
    editRules: (v) => Number.isFinite(Number(v))
      ? { pass: true }
      : { pass: false, message: '请输入数字' } // 校验失败不入库
  }
]
function onEditChange({ row, column, value, trigger }) {
  // trigger：'double-click' 进入 / 'enter' 回车 / 'blur' 失焦
}

5.11 工具栏

提供 toolbar 对象即显示顶部工具栏（零依赖，苹果风描边按钮）。

<XDataGrid
  ref="tableRef"
  :columns="columns"
  :data="data"
  row-key="id"
  :toolbar="toolbar"
  @toolbar-search="onToolbarSearch"
  @toolbar-action="onToolbarAction"
>
  <template #toolbar-title>订单明细</template>
</XDataGrid>

import 导出Icon from '@/icons/export.svg?raw'   // ?raw 内联 SVG 作为图标

const toolbar = reactive({
  columnSetting: true,   // 列设置入口（打开全局抽屉）
  search: true,          // 搜索按钮（触发 @toolbar-search）
  buttonNames: true,     // 按钮名开关（控制操作按钮文字显隐）
  actions: [
    {
      key: 'export', label: '导出', icon: 导出Icon, iconSize: 12,
      loading: () => exporting.value,            // 响应式 loading（旋转图标 + 禁用）
      onClick: async (action, event) => { /* 自定义点击，替代全局 toolbar-action */ }
    },
    {
      key: 'delete', label: '删除',
      icon: () => h('svg', { viewBox: '0 0 24 24' }, [h('path', { d: '...' })]),
      disabled: () => checkedKeys.value.length === 0,   // 未勾选即禁用
      onClick: (action, event) => alert('删除')
    }
  ]
})

// 搜索按钮：使用方自行实现交互（点击后展开本地搜索栏）
function onToolbarSearch() {
  searchBar.value = !searchBar.value
  tableRef.value?.setSearch(keyword.value)   // 本地关键词过滤（可不清除时传 ''）
}

5.12 提示框 Tooltip

悬停单元格弹出 Teleport 到 body 的暗色卡片浮层，智能定位（贴边自动翻转 + 方向箭头），不超出表格容器与视口。支持四种配置方式：

<XDataGrid :columns="columns" :data="data" row-key="id">
  <!-- 方式四（优先级最高）：插槽自定义浮层内容 -->
  <template #tip-name="{ row }">
    <div>{{ row.name }} · {{ row.city }} · {{ row.desc }}</div>
  </template>
</XDataGrid>

const columns = [
  { key: 'name', label: '姓名', width: 100 },
  {
    key: 'remark', label: '备注', minWidth: 180,
    showOverflow: 'tooltip',   // ① 溢出省略，悬停显示全文 + 一键复制
  },
  {
    key: 'desc', label: '描述', width: 110,
    showTooltip: true,         // ② 强制开启，未截断也显示
  },
  {
    key: 'tip', label: '提示', width: 130,
    tipRenderer: ({ row }) =>  // ③ 列级渲染函数返回自定义浮层
      h('div', { style: 'display:grid;gap:4px' }, [h('span', row.tip), h('span', row.name)]),
  }
]

5.13 单元格合并

通过 spanMethod 返回 { rowspan, colspan }。连续同名合并需自行扫描数据。

function spanMethod({ rowIndex, columnIndex, rowCount, columnCount, row }) {
  if (columnIndex === 1) {
    return { rowspan: groupSpan(rowIndex) } // 返回 0 表示被前一行吞噬
  }
  if (columnIndex === 4) {
    return { colspan: 2 }                    // 横向合并（顶端对齐）
  }
  return undefined
}

5.14 展开行

两种触发方式：

• 显式展开列：配置 { type: 'expand' } 列，行内出现「展开/收起」按钮；
• 隐式触发：:expandable="true" 且未配置 expand 列时，首个数据列自动挂上展开箭头。

<XDataGrid
  ref="gridRef"
  :columns="columns"
  :data="data"
  row-key="id"
  expandable
  @expand-change="(row, expanded) => { if (expanded) loadDetail(row) }"
>
  <!-- 展开行全宽内容：订单明细 / 子表 / 图表等（高度自适应插槽内容） -->
  <template #expand-row="{ row }">
    <div class="expand-detail">
      <div>订单号：{{ row.order }}</div>
      <div v-for="d in row.detail" :key="d.goods">{{ d.goods }} ×{{ d.qty }} ¥{{ d.price }}</div>
    </div>
  </template>
</XDataGrid>

const columns = [
  { type: 'expand', width: 60, align: 'center' },   // 展开按钮列
  { key: 'order', label: '订单号', width: 150 },
  { key: 'amount', label: '金额(元)', width: 140, align: 'right' },
]

// 展开回调：可在此动态调用接口更新插槽数据（row 为引用，赋值即触发插槽更新）
async function loadDetail(row) {
  const detail = await fetchDetail(row.id)      // 模拟请求接口
  row.detail = detail                            // 更新后高度自动重新测量
}

5.15 列设置与缓存

通过工具栏「列设置」入口打开列设置抽屉：复选框控制字段显隐、拖拽调整非固定字段顺序（固定列锚定不可拖）。

抽屉挂载位置由顶层 columnMount 配置（默认 'container'）：

• 'container'（默认）：挂载到表格容器内部，遮罩/面板局限于表格区域，与表格形成一个整体单元；
• 'body'：挂载到 <body>，全屏全局抽屉。

<XDataGrid
  ref="gridRef"
  id="demo-columns"          <!-- 配置 id 启用 IndexedDB 缓存 -->
  :columns="columns"
  :data="data"
  row-key="id"
  :column-mount="'container'"
  :toolbar="{ columnSetting: true }"
>
</XDataGrid>

// 实例方法控制列显隐与顺序
gridRef.value?.hideColumn('status')            // 隐藏某列
gridRef.value?.showColumn('status')            // 显示某列
gridRef.value?.setHiddenColumns(['status'])    // 批量隐藏
gridRef.value?.setColumnOrder(['id', 'name', 'amount', 'city']) // 列顺序

5.16 远程数据模式

sort-mode='remote'、filter-mode='remote'、pagination.remote=true 时，组件只触发事件，数据由外层请求后回填。

<XDataGrid
  :columns="columns"
  :data="pageRows"
  row-key="id"
  :loading="loading"
  :sort-mode="'remote'"
  :filter-mode="'remote'"
  :pagination="pagination"
  :default-sort="[{ key: 'amount', order: 'desc' }]"
  :column-filters="[{ key: 'city', values: ['北京'] }]"
  @sort-change="onSortChange"
  @filter-change="onFilterChange"
  @page-change="onPageChange"
>
</XDataGrid>

const pagination = ref({ pageSize: 20, current: 1, remote: true, total: 0 })

async function fetchData({ sort, filters, page, pageSize }) {
  loading.value = true
  const res = await api.query({ sort, filters, page, pageSize })
  pageRows.value = res.list
  pagination.value.total = res.total
  loading.value = false
}

function onSortChange({ sort }) {
  pagination.value.current = 1
  fetchData({ sort, filters, page: 1, pageSize: pagination.value.pageSize })
}
function onPageChange({ current, pageSize }) {
  fetchData({ sort, filters, page: current, pageSize })
}

5.17 加载态 / 骨架屏 / 空态

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  :loading="loading"
  :skeleton="skeleton"        <!-- true 时 loading 显示骨架屏（默认转圈） -->
  empty-text="暂无数据"        <!-- 空数据文案（默认内置图标+文案的美化空态） -->
>
  <template #empty>            <!-- 自定义空态：表头保留，仅表体内容区为空 -->
    <div style="text-align: center; padding: 24px">
      <p>暂无关联数据</p>
      <button @click="loadData">加载示例数据</button>
    </div>
  </template>
</XDataGrid>

5.18 移动端卡片模式

容器宽度 ≤ mobileBreakpoint 时自动切换为卡片逐条浏览（按容器宽度而非屏幕宽度判定）。默认断点 500px，可通过 mobile-breakpoint 自定义。

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  :mobile-breakpoint="900"
  :card-props="cardProps"
  :toolbar="toolbar"
  :pagination="pagination"
  @card-change="onCardChange"
>
</XDataGrid>

const cardProps = {
  fields: ['name', 'product', 'amount', 'city', 'status'], // 展示顺序
  labelMap: { amount: '金额(元)', product: '商品名称' },     // 自定义标签
  visibleFields: ['id', 'name', 'city', 'product', 'amount', 'status'] // 字段过滤
}
function onCardChange({ index, row }) {
  console.log('当前卡片：', index + 1, row)
}

5.19 密度 / 斑马纹 / 行高 / 边框

<XDataGrid
  :columns="columns"
  :data="data"
  row-key="id"
  :density="'compact'"
  stripe
  :row-height="44"
  :show-row-hover="true"
  :border="true"
>
</XDataGrid>

5.20 事件与实例方法

完整事件见 4.12 事件，实例方法见 4.13 实例方法。典型组合使用：

<XDataGrid
  ref="gridRef"
  :columns="columns"
  :data="data"
  row-key="id"
  @row-click="(row, index, evt) => …"
  @row-dbl-click="(row, index, evt) => …"
  @header-click="(column, evt) => …"
  @scroll="({ scrollLeft, scrollTop }) => …"
  @selection-change="(info) => …"
  @sort-change="({ key, order }) => …"
  @edit-change="({ row, column, value }) => …"
  @expand-change="(row, expanded) => …"
>
</XDataGrid>

const gridRef = ref(null)
gridRef.value?.scrollTo(60)                  // 滚动到第 60 个虚拟行
gridRef.value?.toggleRowSelection(row, true) // 切换某行选择
gridRef.value?.setCurrentPage(2)             // 设置当前页
gridRef.value?.sortBy('amount', 'desc')      // 按字段排序
gridRef.value?.setColumnWidth('name', 220)   // 更新列宽
gridRef.value?.clearSort()                   // 清空排序
gridRef.value?.clearFilter()                 // 清空筛选

5.21 滚动到底部加载更多（load-more）

滚动条滚动到距底部阈值内自动触发回调，动态查询下一页数据并追加到 data，自动累加形成大表格数据（虚拟滚动承载，累计万级 / 十万级仍流畅）。该模式下自动隐藏分页条，无需「下一页」按钮。

<XDataGrid
  :columns="columns"
  :data="rows"
  row-key="id"
  :load-more="loadMore"
  @load-more="fetchNextPage"
>
</XDataGrid>

const rows = ref([])
const loadMore = ref({ loading: false, finished: false, threshold: 60, total: 400, pageSize: 40 })

async function fetchNextPage() {
  if (loadMore.value.finished || loadMore.value.loading) return
  loadMore.value.loading = true
  const chunk = await api.queryNextPage()   // 动态查询下一页
  rows.value.push(...chunk)                 // 追加到 data，自动累加大表格
  loadMore.value.loading = false            // 置回 false 才允许再次触发
  if (noMore) loadMore.value.finished = true // 无更多数据，停止触发并显示「已加载全部数据」
}

该进度分页条仅桌面表格模式展示（移动端卡片为顺序浏览）。数据无需持久化，加载进度随会话即时计算。

5.21.1 数据加载方式切换

当配置了 pagination（分页信息）后，除了固定的远程分页显示外，还可以在「列设置」抽屉中默认提供「数据加载方式」切换，让使用方在「分页显示」与「动态加载显示」之间自由切换：

• 分页（page，默认）：常规分页显示，点击页码/上一页/下一页触发 page-change{current,pageSize}，外层按页替换数据；
• 动态加载（scroll）：底部展示「加载进度分页条」，滚动条滚动到距底部 40px 内触发 page-change{current,pageSize}（与分页回调完全一致），外层按页追加数据并自动累积为大表格（虚拟滚动承载）；已加载页码可点击滚动到该页首行、未加载页码置灰禁点。重置/清空数据后，已加载的页码随同归零（起始仅第 1 页已加载）。

<XDataGrid
  :columns="columns"
  :data="rows"
  row-key="id"
  :pagination="pagination"     <!-- 配置分页信息即可在「列设置」抽屉切换加载方式 -->
  :load-mode="loadMode"        <!-- 'page' 分页显示 / 'scroll' 动态加载（默认 'page'） -->
  :toolbar="{ columnSetting: true }"
  @page-change="onPageChange"          <!-- 统一回调（两种模式一致） -->
  @load-mode-change="onLoadModeChange" <!-- 抽屉切换加载方式时触发 -->
>
</XDataGrid>

const pagination = { pageSize: 40, total: 4000, remote: true }
const loadMode = ref('scroll') // 默认动态加载，可经抽屉切换

function onPageChange({ current }) {
  const chunk = api.queryPage(current)             // 按页查询
  if (loadMode.value === 'scroll') {
    rows.value.push(...chunk)      // 动态加载：追加累积
  } else {
    rows.value = chunk            // 分页：按页替换
  }
}
function onLoadModeChange(mode) {
  loadMode.value = mode
  loadFirstPage()                 // 切换后回到第 1 页重新加载
}
// 重置：清空数据后已加载页码随同归零（起始仅第 1 页已加载）
function reset() {
  rows.value = []
  loadFirstPage()
}

5.22 对象字段（点路径 key）

列 key 支持「点路径」形式，直接读取行数据中的嵌套对象字段。数据为 { name: '张三', chengjie: { yw: 92, sx: 88 } } 时，配置 { key: 'chengjie.yw' } 即读取 chengjie.yw 的值。

// 数据
const rows = ref([
  { id: 1, name: '张三', chengjie: { yw: 92, sx: 88, yy: 95 } },
  { id: 2, name: '李四', chengjie: { yw: 78, sx: 96, yy: 82 } },
])
// 列配置：key 使用点路径读取嵌套对象字段
const columns = [
  { type: 'index', label: '#', width: 60, align: 'center' },
  { key: 'name', label: '学生', width: 120, fixed: 'left', align: 'center' },
  { key: 'chengjie.yw', label: '语文', width: 110, align: 'center', sortable: true, editable: true, summable: true },
  { key: 'chengjie.sx', label: '数学', width: 110, align: 'center', sortable: true, editable: true, summable: true },
  { key: 'chengjie.yy', label: '英语', width: 110, align: 'center', sortable: true, editable: true, summable: true },
]

<XDataGrid :columns="columns" :data="rows" row-key="id" :show-footer="true" editable>
</XDataGrid>

5.23 数组对象自动合并

把「数组嵌套对象」数据按数组项展开为多子行，并对非数组合并列做纵向 rowspan 合并，适合「一对多」明细（如一个订单多行商品、一位学生多个科目）。

数据结构：

const rows = ref([
  { id: 1, name: '张三', cls: '一班', cj: [
      { xk: '语文', cj: 90 },
      { xk: '数学', cj: 100 },
    ] },
  { id: 2, name: '李四', cls: '一班', cj: [{ xk: '英语', cj: 88 }] },
])

列配置：数组列用「点路径」key，首个段为数组字段，其余段为数组项字段。

const columns = [
  { key: 'name', label: '姓名', width: 110, fixed: 'left' },
  { key: 'cls', label: '班级', width: 90 },
  { key: 'cj.xk', label: '学科', width: 120 },   // 数组列：展开后逐项显示学科
  { key: 'cj.cj', label: '成绩', width: 90 },    // 数组列
  { key: 'remark', label: '备注', minWidth: 160 },
]

启用（全量合并）：

<XDataGrid :columns="columns" :data="rows" row-key="id" :array-merge="true" />

启用（仅合并姓名列，其余非数组列逐子行重复展示）：

<XDataGrid :columns="columns" :data="rows" row-key="id" :array-merge="{ mergeColumns: ['name'] }" />

5.24 操作列与列自定义插槽

A. 操作列（actions）

在列配置 columns 中某列的 actions 数组声明操作按钮（TableAction）。最适合「详情 / 修改 / 删除 / 审批」等业务操作；按钮可基于当前行数据做权限显隐（visible）与状态禁用（disabled）。

<XDataGrid :columns="columns" :data="rows" row-key="id" @action="onAction" />

<script setup>
const columns = [
  { key: 'name', label: '姓名' },
  {
    key: 'ops',
    label: '操作',
    fixed: 'right',
    actionLimit: 2,   // 最多直接展示 2 个（默认即 2），超出收进「更多 ⋯」
    actions: [
      { key: 'detail', label: '详情' },           // 触发统一 @action
      { key: 'edit', label: '修改', type: 'primary',
        onClick: (row) => openEdit(row) },      // 自带点击逻辑
      { key: 'approve', label: '审批', type: 'success',
        visible: (row) => row.status === '进行中' },   // 权限 / 行判定
      { key: 'remove', label: '删除', type: 'danger',
        disabled: (row) => row.status === '已完成',    // 状态禁用
        onClick: (row) => confirm('确认删除？') || false }, // false 阻止事件
      { key: 'copy', label: '复制' },
    ],
  },
]

function onAction({ key, row }) {
  // 未配置 onClick（或返回非 false）的按钮统一在此处理
  console.log(key, row)
}
<\/script>

B. 列自定义插槽（slotName）

列默认以 key 作为单元格插槽名。配置 slotName 后，该列改用 #<slotName> 插槽渲染任意自定义内容（图片、徽章、混合富文本等），未提供对应插槽时回落到列 key 取值。

<XDataGrid :columns="columns" :data="rows" row-key="id">
  <template #avatar="{ row }">
    
    <span>{{ row.name }}</span>
  </template>
  <template #status="{ row }">
    <span class="tag" :class="`is-${row.tag}`">{{ row.status }}</span>
  </template>
</XDataGrid>

<script setup>
const columns = [
  { key: 'name', label: '姓名', slotName: 'avatar' },   // 用 #avatar 插槽渲染头像
  { key: 'status', label: '状态', slotName: 'status' },  // 用 #status 插槽渲染徽章
]
<\/script>

6. 主题定制（CSS 变量）

所有主题通过 CSS 变量（--tbl-*）暴露，可全局覆盖或按 .tbl-root 作用域覆盖。字体渲染沿用 Element UI 默认策略，不强制自定义字体栈。

.tbl-root {
  --tbl-primary-color: #409eff;       /* 品牌色 */
  --tbl-header-bg: #f5f7fa;           /* 表头背景 */
  --tbl-body-bg: #ffffff;             /* 表体背景 */
  --tbl-row-hover-bg: #f5f7fa;        /* 行悬停 */
  --tbl-row-selected-bg: #ecf5ff;     /* 选中行 */
  --tbl-stripe-even-bg: #fafafa;      /* 斑马纹 */
  --tbl-border-color: #ebeef5;        /* 分割线 */
  --tbl-text-color: #303133;          /* 主文本 */
  --tbl-text-secondary-color: #909399;/* 次要文本 */
  --tbl-font-size: 14px;              /* 字号 */
  --tbl-cell-padding: 0 12px;         /* 单元格内边距 */
  --tbl-fixed-shadow: 6px 0 12px -6px rgba(0,0,0,.15);      /* 左固定阴影 */
  --tbl-fixed-shadow-inv: -6px 0 12px -6px rgba(0,0,0,.15); /* 右固定阴影 */
  --tbl-control-selection-w: 48px;    /* 选择列宽 */
  --tbl-control-expand-w: 48px;       /* 展开列宽 */
  --tbl-control-index-w: 56px;        /* 序号列宽 */
  --tbl-tree-indent: 16px;            /* 树缩进/级 */
  --tbl-action-icon-size: 14px;       /* 工具栏操作按钮图标尺寸 */
}

6.1 主题颜色可配置（API）

交互元素（复选框 / 单选 / 开关 / 排序 / 筛选 / 分页）的品牌色跟随 --tbl-primary-color，默认值保持组件蓝色 #409eff。通过「全局主题」或「实例 theme prop」两种方式配置，颜色变更对所有已渲染与新渲染的表格实时生效。

import { setGlobalTheme, getGlobalTheme, resetGlobalTheme } from 'table-grid-plugin'

// 全局主题：对所有表格（已渲染 + 新渲染）实时生效
setGlobalTheme({ primaryColor: '#f56c6c' })   // 传子集即局部覆盖
const snap = getGlobalTheme()                  // 读取当前全局主题快照
resetGlobalTheme()                             // 恢复组件默认蓝色

<!-- 实例级覆盖：仅当前表格生效，优先级高于全局主题 -->
<XDataGrid :columns="columns" :data="rows" row-key="id"
  :theme="{ primaryColor: '#67c23a' }" />

ThemeTokens 各键（颜色即可配置）：

优先级：实例 theme prop（根节点内联）> 全局主题（注入 <style>）> SCSS 默认变量。二者可叠加：全局设品牌色，单个表格用 theme prop 局部覆盖。

7. 国际化（i18n）

7.1 文本词典翻译（推荐）：翻表头 / 按钮 / 分页等公共内容

默认语言为中文，label 即 key：传入目标语言译文词典即可翻译表头 label 以及分页、按钮、空态等内置公共文案；表体数据不翻译。切回中文时直接显示 label（中文为「无效语言包」，无需也不应收录）。

// 词典：语言码 -> { 中文文本: 译文 }
const dict = {
  en: { 姓名: 'Name', 部门: 'Department', 得分: 'Score', 评级: 'Grade' },
}

import { setLocale, setTranslations, setSystemLocale, lang, tr } from 'table-grid-plugin'

setTranslations(dict)                     // 全局注册词典，所有表格实时生效
setLocale({ lang: 'en-US', autoSystem: false })  // 切英文（切中文→直显 label）
setSystemLocale(false)                    // 关闭系统语言自动跟随
setLocale({ lang: 'zh-CN', autoSystem: false })  // 回中文
tr('姓名')                                // 按当前语言翻译：'Name'（中文下返回'姓名'）

表格列使用纯中文 label（即翻译 key）：

<XDataGrid
  :columns="[{ key:'name', label:'姓名' }, { key:'dept', label:'部门' }]"
  :data="rows" row-key="id"
/>

表格级可用 translations prop 做实例覆盖（粒度最优先），便于同一页面多语言差异：

<XDataGrid :columns="columns" :data="rows" row-key="id"
  :translations="{ en: { 姓名: 'Name', 部门: 'Department', 得分: 'Score', 评级: 'Rating' } }" />

内置已预置一份「中→英」默认词典（分页 / 空态 / 列设置 / 搜索 / 合计等公共文案开箱即英文）；用户 setTranslations / :translations 词典优先覆盖。

7.2 切换机制与内置语言包（key 型，进阶）

默认语言为中文，且不自动跟随系统：只要未显式调用 setLocale / setSystemLocale(true)，任何表格（含未配置语言包的表）都保持中文。需要跟随或切换时再手动控制。语言码 en-US/en、zh-CN/zh 均可，词典按短码命中。

import { setLocale, setSystemLocale, lang, getMessages } from 'table-grid-plugin'

setLocale({ lang: 'en-US' })            // 手动切换为英文（默认不跟随系统，见下）
setSystemLocale(false)                   // 关闭系统语言自动跟随（默认即为关闭，可完全手动控制）
setSystemLocale(true)                    // 显式开启自动跟随（无配置时仍会随系统语言切换）
setLocale({ lang: 'zh-CN', autoSystem: false }) // 回中文且不跟随系统

表格级 locale prop 做 key 型实例覆盖，粒度最优先：

<XDataGrid :columns="columns" :data="rows" row-key="id"
  :locale="{ empty: '暂无数据', total: '共 {n} 条' }" />

7.3 语言包结构（内置 zh-CN / en-US 完整覆盖）

文本使用 {n} 占位符插值。全部消息键：

语言包是按扁平 key 全量收录的完整对象；传入 Partial<LocaleMessages> 即可增量覆盖，未覆盖项回退内置语言包默认文案（props.locale > 全局 setLocale > 内置语言包）。

8. 浏览器兼容性

• 使用 Set、CSS 变量、sticky 定位、ResizeObserver、IndexedDB。
• 支持所有现代浏览器（Chrome / Edge / Firefox / Safari，含移动端）。
• 不做 IE 兼容。

9. 常见问题 FAQ

Q1：为什么表格空白 / 总高度为 0？

虚拟滚动依赖容器高度。请为 <XDataGrid> 或外层设置确定高度，例如 style="height: 400px"。

Q2：rowKey 不传会怎样？

选择、树形、展开、合并、宽高追踪都依赖稳定的行键。若省略可能导致跨页选择错乱。必须提供。

Q3：cellRender 返回的 HTML 字符串没有渲染成富文本？

返回值为 VNode/文本，非 innerHTML。如需富文本请返回 h() 创建的 VNode，或使用插槽 + v-html。

Q4：表格列宽与容器不一致？

width 为固定占位；未设 width 的列按 minWidth 在剩余空间内自适应分配。可调用实例方法 recalcWidths() 在容器变化后重算。

Q5：数据量非常大时还卡顿吗？

Body 只渲染可视区间（约 视图高度/行高 + 2×overscan 行）。滚动只更新偏移量，不做重计算，十万级数据首屏与滚动均保持在毫秒级。

Q6：展开行怎么触发？

两种方式：配置 type:'expand' 列（行内按钮），或 :expandable="true" 且不配置 expand 列（首个数据列自动挂展开箭头）。内容经 #expand-row 插槽渲染。同一时刻仅一行可展开，展开行高度自适应插槽内容；@expand-change="(row, expanded)" 回调可在展开时动态加载接口数据更新插槽。

Q7：列设置如何持久化？

配置 id 属性后，用户调整的列顺序 / 显隐自动写入 IndexedDB，刷新页面保留；columns 配置结构变化或点击「重置」时自动失效。

License

MIT