更新记录

2.0.0（2026-11-01）

核心引擎

• 纯 Canvas 2D 渲染，零 DOM 表格；行 + 主区列双虚拟化，2 万行流畅滚动。
• 固定列（左 / 右）与边缘阴影、冻结行、多级表头、汇总页脚。
• 排序（多列）、筛选、树形（含懒加载）、逻辑分页。
• rowKey 受控选择、合并单元格、变高行、自定义渲染器。
• 惯性滚动 + 边界回弹；浅色 / 暗色主题 + 自定义色板。
• 高倍屏（dpr 2/3）按运行环境区分「位图已缩放 / 需自行缩放」，移动端不再只画出表格一角。

渲染与交互修正（首版发布前修复）

• H5 首屏不再「只渲染左上角一块」：uni-app 的 H5 canvas 上下文带 __hidpi__（平台已把坐标乘过 dpr），旧实现又额外 setTransform(dpr)，缩放叠加成 dpr²。现由 contextScaled 标记区分，原生端仍按 dpr。
• 固定列里的高亮不再消失：激活框 / 框选 / 查找命中改为按「左固定 / 主区 / 右固定」三条竖带逐段裁剪，既不越界也不画不出来。
• 被固定列盖住的主区列不再露出手柄：列宽手柄与拖拽指示线的绘制、命中共用同一份「本带内是否可见」判据。
• 冻结行上的行高拖拽命中正确的行（旧实现按屏幕坐标反查，改的是屏幕外那行）。
• 右侧固定列阴影只在右边还有内容时出现，无横向余量时不再常驻。
• 键盘方向键会把激活格横向滚入视口（此前只滚纵向），与查找的「滚入视口」收敛为一份实现。
• 单层绘制异常不再让整表被裁成一条：裁剪统一走 paint.withClip()，异常路径也保证 restore。
• 窗口尺寸变化后文字不再上移：canvas.width = 会静默重置 2D 上下文（字体 / 基线 / 对齐回默认），而 Paint.bind() 因 ctx 引用未变而早退；现在位图尺寸变更后强制 paint.resetCtx() 重发状态。
• resize 不再闪一帧空白：canvas 尺寸只在 render 帧首修改，避免「清空画布 → 下一帧才重绘」的中间透明白帧。

主题

• 可覆盖字段 37 个，全部生效；theme 传 null = 撤掉全部覆盖，切 dark 同理。
• 暗色滚动条按主题灰阶重做：轨道取表头色半透明（贴合任意行色，不再出现比行更黑的竖条），滑块 #5d6875、拖拽态 #93a2b3，与正文形成四级递进。
• 暗色 tooltip 浮层提亮至 rgba(53,60,71,.96)，不再与背景融成一片。

数据筛选

• 受控 prop filters（{ 列的 key 或 field: 值 }，多条件 AND），filterMethod 提供表级自定义匹配，列级优先。
• 内置匹配按值类型分派：字符串 = 包含、数组 = IN、数字 / 布尔 = 等价比较；'' / [] / null 视为不筛。
• 事件 filter-change 只在 setFilters / clearFilters 后回抛，改 prop 不抛（避免受控侧死循环）。
• 与分页 / 树 / 分组叠加，顺序为「先筛选 → 再分页 / 建树 / 分组」。
• 组件不画筛选 UI：入口由业务自建，改 filters 即生效。

交互能力

• 列宽 / 行高拖拽：常驻手柄，移动端按输入源自动取长按阈值，按下即反馈。
• 行拖拽排序（rowReorder）、列拖拽重排（columnReorder），落位回抛新顺序。
• 列显隐 / 列选择器；条件格式（cellStyle → conditional → 主题）。
• 行选择：行级勾选与单元格选区两套独立 API。

行内编辑

• editable 一处开关，串起编辑 → 校验 → 历史。
• 双击 / Enter / F2 三入口；列级 editType（text / number / textarea）；只读、序号、手柄、分组行自动拒编。
• 事件 edit-commit / edit-cancel，携带 rowKey / field / oldValue / newValue / valid / message。
• 键盘导航、TSV 复制粘贴、校验（required / number / integer / email / regex / min / max / custom）、撤销重做。

分组 / 聚合

• groupBy + 列级 aggregate；组头为行投影伪行，虚拟滚动 / 导出全自动，与页脚口径独立。

导出

• exportImage() 导出当前帧位图（返回值随运行环境而定，可能是 data URL 或临时文件路径），只生成不落盘。
• getExportData() 返回 { columns, rows }；exportCsv() 返回纯字符串 CSV。

插件化

• registerCellRenderer / registerCellEditor 支持自定义类型而不改引擎。
• table.use() 全局插件注册表；TooltipPlugin 拆为独立产物（core-tooltip.esm.min.js，2.2kb）按需启用。

文档与类型

• 44 个 prop 的说明在四处（props.ts / TableProps / l-table-x.uvue / l-table-x.vue）逐字一致，字段顺序统一，说明只保留一句话作用，并由 unit_props_alignment 守卫。
• props.ts 去掉 as PropType<...> 断言：类型契约统一由 TableProps 承载，运行时对象只留 type / default。
• 对外类型注释精简，去掉版本注记与长篇取舍叙述。
• readme 顶部补插件元信息（name / description / tags / componentTag / plugin / category / dependencies），与「插件标签说明」表及真实依赖保持一致。
• 插件文档收敛为 readme.md 单文件：68 个实例方法、37 个主题字段（含浅色 / 暗色默认值）、ColumnDefine 等类型定义全部内联，不再引用 docs/ 目录，包内 docs/ 与 build:docs 一并移除。

示例

• 示例画廊六个分类：基础 / 选择 / 树形 / 表头渲染 / 分组聚合 / 编辑导出。
• 移动端一屏可见：控制区压到最小，说明文字下移，表格高度按视口自适应；390×844 下六个分类均无溢出。

平台兼容性

uni-app(5.31)

uni-app x(5.31)

其他

name: lime-table-x 高性能表格组件 description: 高性能表格组件，纯 Canvas 2D 绘制，行与主区列双向虚拟化，支持固定列、冻结行、多级表头、排序、筛选、树形、分组聚合、行内编辑与导出，2 万行流畅滚动，适用于数据列表、报表、后台管理等场景。 tags:

• table
• 表格
• canvas
• 虚拟滚动
• 高性能
• 数据展示 componentTag: l-table-x plugin: lime-table-x category: 展示组件 dependencies:

• lime-shared

lime-table-x 高性能 Canvas 表格

一款纯 Canvas 2D 绘制的 uni-app / uni-app x 表格组件：零 DOM 表格结构，行 + 主区列双向虚拟化，2 万行流畅滚动。支持固定列 / 冻结行 / 多级表头 / 排序 / 筛选 / 树形 / 分组聚合 / 行内编辑 / 导出。

插件依赖：lime-shared

安装方法

1. 在 uni-app 插件市场中搜索并导入 lime-table-x
2. 确保依赖 lime-shared 已安装（首次导入后可能需要重新编译项目）
3. 在页面中使用 <l-table-x> 组件

代码演示

基础用法

通过 :data 与 :columns 传入数据与列定义即可。

<l-table-x
    ref="tableRef"
    :data="data"
    :columns="columns"
    row-key="id"
    width="100%"
    :height="430"
    @cell-click="onCellClick" />

import { ref } from 'vue'

const tableRef = ref(null)
const data = ref([
    { id: 1, name: '用户1', email: 'user1@example.com' },
    { id: 2, name: '用户2', email: 'user2@example.com' }
])
const columns = ref([
    { field: 'id', title: 'ID', width: 80 },
    { field: 'name', title: '姓名', width: 120 },
    { field: 'email', title: '邮箱', width: 160 }
])
const onCellClick = (info) => {
    console.log('点击单元格:', info.rowIndex, info.field, info.value)
}

固定列 / 排序 / 汇总页脚

fixed 固定左 / 右列，sortable 开启排序，列级 footer 声明全表汇总口径。

const columns = [
    { field: 'id', title: 'ID', width: 72, fixed: 'left', sortable: true },
    { field: 'name', title: '姓名', width: 110, fixed: 'left' },
    { field: 'salary', title: '薪资', width: 120, align: 'right', sortable: true, footer: { type: 'sum' } }
]

<l-table-x :data="data" :columns="columns" :footer-height="40" @sort-change="onSort" />

footer 与 aggregate 支持 sum / avg / count / min / max / custom（fn）/ text（固定文案）。

多级表头与合并单元格

列上写 children 即多级表头；span 返回 { rowspan, colspan } 声明合并（两者都必填）。

const columns = [
    {
        title: '基本信息',
        children: [
            { field: 'id', title: 'ID', width: 80 },
            { field: 'name', title: '姓名', width: 120 }
        ]
    },
    { field: 'dept', title: '部门', width: 120, span: (row) => ({ rowspan: 2, colspan: 1 }) }
]

树形（含懒加载）

tree 配置开启树形，childrenKey 指定子节点字段，lazy + load 实现异步懒加载。

// 预置子节点
const tree = { childrenKey: 'children', defaultExpandAll: false }

// 懒加载（点开才拉取子节点）
const treeLazy = {
    childrenKey: 'children',
    lazy: true,
    load: (row) => fetchChildren(row)   // 返回 Promise<any[]>
}

<l-table-x :data="data" :columns="columns" :tree="tree" :indent="20" @row-expand="onExpand" />

分组 / 聚合

groupBy 按字段分组，组头行跟随虚拟滚动；列级 aggregate 声明组内口径。

const groupBy = { field: 'dept', defaultExpanded: true }
const columns = [
    { field: 'dept', title: '部门', width: 120 },
    { field: 'salary', title: '薪资', width: 120, aggregate: { type: 'avg' } }
]

<l-table-x :data="data" :columns="columns" :group-by="groupBy" @group-toggle="onGroupToggle" />

受控展开态：:group-expanded-keys + @update:group-expanded-keys。

数据筛选（受控）

filters 是受控筛选值 { 列的 key 或 field: 值 }，多条件取 AND；组件不画筛选 UI，入口自己画（表头菜单 / 搜索框 / 外部表单），改值即生效。

内置匹配够用就不必写 filterMethod：字符串 = 包含（忽略大小写）、数组 = IN、数字与布尔 = 等价比较；'' / [] / null 视为不筛。

<l-table-x :data="data" :columns="columns" :filters="filters" @filter-change="" />

const filters = ref({ name: '张', dept: ['研发部', '财务部'] })   // 姓名含「张」且部门属于两者之一

const  = ({ filters: f, count }) => {
    console.log('筛选后行数', count)   // 只在调 setFilters / clearFilters 时回抛，改 props 不抛
}

// 内置表达不了的（日期 / 数值区间）：值可以是任意对象，交给 filterMethod 解释
const filterMethod = (v, row) => row.salary >= v[0] && row.salary <= v[1]
// filters: { salary: [3000, 8000] }

行内编辑与校验

editable 一处开关开启编辑；列上 editType: 'text' | 'number' | 'textarea'，editable: false 置灰。双击 / Enter / F2 进入编辑，Enter 提交、Esc 取消。

const columns = [
    { field: 'name', title: '姓名', width: 120, editType: 'text' },
    {
        field: 'salary', title: '薪资', width: 120, editType: 'number',
        validators: [{ type: 'required' }, { type: 'min', value: 0 }]
    },
    { field: 'id', title: 'ID', width: 80, editable: false }
]

<l-table-x :data="data" :columns="columns" editable @edit-commit="onCommit" />

配套实例方法：beginEditCell / commitEdit / cancelEdit / undoEdit / redoEdit / pasteText。

自定义单元格

render(params) 函数式绘制，注入 drawText / drawRoundRect / drawCircle / drawPolyline / drawSmoothLine / drawArea / registerClickArea（禁止返回 VNode；后三个为点集原语，画 sparkline / 趋势图）。

const columns = [
    {
        field: 'op', title: '操作', width: 150,
        render: (p) => {
            p.drawRoundRect(p.rect.x + 10, p.rect.y + 10, 60, 24, 5, '#2f7ef7', null)
            p.drawText('查看', p.rect.x + 10, p.rect.y + p.rect.height / 2, 60, '#ffffff', 'center')
            p.registerClickArea(
                { x: p.rect.x + 10, y: p.rect.y + 10, width: 60, height: 24 },
                () => console.log('点击查看', p.row)
            )
        }
    }
]

条件格式

列上 cellStyle（函数式）或 conditional（声明式规则数组），优先级：cellStyle → conditional → 主题。

const columns = [
    {
        field: 'salary', title: '薪资', width: 120,
        conditional: [
            { when: (row) => row.salary > 20000, style: { backgroundColor: '#fff1f0' } },
            { when: (row) => row.salary < 5000, style: { backgroundColor: '#f0f9ff' } }
        ]
    }
]

列宽 / 行高拖拽

colResizable 默认开（按列 resizable: false 可单独关闭），rowResizable 默认关（会占用数据区的纵向拖拽手势）。showResizeHandle 控制是否常驻显示手柄短线。

<l-table-x :data="data" :columns="columns" row-resizable show-resize-handle
           @column-width-change="onColWidth" @row-height-change="onRowHeight" />

移动端与桌面共用一份实现：鼠标按下即拖，手指需长按（阈值由 resizePressDelay 控制，-1 = 按输入源自适应）。

导出

exportImage() 无参导出当前渲染画面位图（只生成不落盘）；getExportData() 返回结构化行列，可接任意 xlsx 库自建 Excel 导出；exportCsv() 返回纯字符串 CSV。

const img = await tableRef.value?.exportImage()   // 返回值随运行环境而定：data URL 或临时文件路径
const { columns, rows } = tableRef.value?.getExportData()
const csv = tableRef.value?.exportCsv()

可选插件（tooltip 浮层）

浮层提示（文本溢出 / 校验错误文案）默认不打包，需要时从独立产物启用一次即可——全局启用：

import { table } from '@/uni_modules/lime-table-x'
import { TooltipPlugin } from '@/uni_modules/lime-table-x/plugins/tooltip'

// use() 不做去重，重复注册会重复挂图层（浮层画两遍）；在可能多次调用的地方先判一下
if (table.plugins().indexOf(TooltipPlugin) < 0) table.use(TooltipPlugin)

只让某一张表启用：tableRef.value.usePlugin(TooltipPlugin)。

自定义插件

插件是一个普通对象 / 类，install(engine) 里挂图层或订阅信号即可（usePlugin 传类或实例都行，引擎未就绪时自动缓冲）：

import type { TablePlugin } from '@/uni_modules/lime-table-x'

const MyPlugin: TablePlugin = {
    name: 'my-plugin',
    install(engine) { /* 注册时调用一次：engine.addLayer(...) / 订阅信号 */ },
    onBeforeRender(state) { /* 每帧在重绘前调用：把状态写进 RenderState，必须纯函数 */ },
    dispose() { /* 引擎销毁时清理，需幂等 */ }
}

tableRef.value?.usePlugin(MyPlugin)

API 文档

Props 分类

🎯 基础配置（最常用）

🎨 主题与外观

✅ 选择 / 编辑 / 拖拽

🌲 树形与分组

🔍 数据筛选

📄 分页与文案

⚡ 性能与滚动

Events

实例方法（通过 ref）

实例上共 68 个公开方法，按用途分组（方法名与 TableInstance 类型逐项一致）。

布局与滚动（7）

排序与筛选（6）

行选择（4）

单元格选区与剪贴板（8）

查找（5）

行内编辑（9）

列显隐（5）

分组（6）

数据与行序（3）

导出（3）

渲染器与插件（6）

性能与调试（6）

常用写法：

const t = tableRef.value

t?.resize()                       // 容器尺寸变了
t?.scrollToIndex(200)             // 滚到第 200 行
t?.setFilters({ dept: '研发部' })  // 设筛选（null / {} = 清空）
t?.beginEditCell(0, 1)            // 进入编辑（行下标, 列下标）
t?.exportCsv()                    // 导出 CSV 字符串

TypeScript 下建议给 ref 标上实例类型（省得手写一长串签名）：

import type { TableInstance } from '@/uni_modules/lime-table-x'
const tableRef = ref<TableInstance | null>(null)

类型定义

ColumnDefine（列定义）

columns 数组的每一项，也是 children 递归的类型。

TreeConfig（树形配置）

GroupConfig（分组配置）

FooterDef（汇总 / 聚合口径）

footer 与 aggregate 共用这一结构。

SpanDef

合并单元格的描述对象。

ConditionalRule

声明式条件格式的一条规则。

ValidatorRule

行内编辑的校验规则。

CellInfo

点击类事件回传的单元格信息。

CellRenderParams

render(params) 收到的上下文与绘制原语。

主题定制

组件通过 props 定制主题，无需额外 CSS 变量。

方式一：暗色主题（推荐）

<l-table-x :data="data" :columns="columns" :dark="true" />

方式二：自定义色板

<l-table-x :data="data" :columns="columns" :theme="myTheme" />

// 覆盖部分色板字段（只写要改的，未写的取当前 dark 模式的默认值）
const myTheme = { textColor: '#333', borderColor: '#e5e6eb', selectedColor: '#e8f0fe' }

⚠️ 选中底色是 selectedColor（不是 selectedBgColor），选中文字色是 selectedTextColor。 mergeTheme() 只认同名字段，拼错等于没写，且不会有任何提示。可覆盖字段共 37 个，下表的后两列是内置浅色 / 暗色默认值（暗色下只写要改的字段，其余取暗色默认）。

⚠️ 重要提示

关于组件使用

• 对外只有一个业务组件 <l-table-x>。components/lime-table-x/（含 lime-table-x.uvue）是示例演示页面，内置写死的演示数据与画廊，业务代码请勿使用。
• 尺寸请用 width / height 控制：支持数字（px）或百分比字符串（如 '100%'）。不要依赖外部 class / style 去改变内部 Canvas 的绘制尺寸。
• exportImage() 只生成不落盘：返回值格式随运行环境而定，是否存相册 / 上传 / 预览由调用方按实际返回值自行处理。
• 行内编辑需两端齐备：组件上传 editable，且目标列未被 editable: false 置灰。
• 包里只有壳层 + 压缩产物：引擎（core/*.ts）属于源码，不随包发布，包内是 core.esm.min.js 与自包含的 core.esm.min.d.ts。

快速预览

导入插件后，可以直接使用以下标签查看完整功能演示（含基础性能、树形、分组、编辑、导出等分类画廊）：

<!-- 代码位于 uni_modules/lime-table-x/components/lime-table-x -->
<lime-table-x />

插件标签说明

注意事项

1. 组件初始化时需要获取 Canvas 的真实尺寸，请确保容器已具备有效宽高后再渲染。
2. rowKey 默认 'id'，若业务主键字段不同请显式设置，否则选择 / 编辑 / 展开态会错乱。
3. 自定义单元格 render 为函数式绘制，禁止返回 VNode / 组件，只能调用注入的绘制 API。
4. 浅色 / 暗色通过 dark 切换，theme 仅做色板覆盖，二者独立。
5. 树形 / 分组 tree 与 groupBy 同时给时 树形优先。

常见问题

在弹窗（Popup / Dialog）中使用时组件无法正常显示？

组件初始化时需要获取 Canvas 的真实尺寸，如果弹窗尚未展开就渲染组件，Canvas 可能获取到 0 尺寸导致绘制异常。请确保弹窗展开后再渲染组件：

<l-popup v-model="show">
    <l-table-x v-if="show" :data="data" :columns="columns" />
</l-popup>

也可以使用 nextTick 延迟渲染：

const mounted = ref(false)
watch(() => show, (v) => {
    if (v) nextTick(() => { mounted.value = true })
    else mounted.value = false
})

改了 prop 没反应？

• 组件按引用比较 data / columns：原地修改数组（data.value.push(...)）不会被识别，请整体替换，或调 updateData() / updateColumns()。
• 引擎是预打包产物，升级插件后请重新编译，H5 端可能是缓存没刷。

容器宽度变了但表格没跟着变？

组件只在自身尺寸变化时自动重排。外层布局变化但组件本身尺寸未变（如侧栏收起导致父容器重新分配）时，请手动调 tableRef.value?.resize()。

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助