更新记录

1.0.10（2026-05-09）

Bug 修复

UniLegacyRenderer 不支持 #RRGGBBAA 颜色格式导致 App 端背景色渲染为黑色

• renderer/UniLegacyRenderer.ts：新增私有方法 _normalizeColor(color)——检测到 9 位 #RRGGBBAA 格式时自动转换为 rgba(r,g,b,a) 字符串，其余格式透传；旧版 canvas API（uni.createCanvasContext）不支持 CSS4 的 #RRGGBBAA 写法，遇到时会退为黑色；setFillStyle / setStrokeStyle 调用前均经过此归一化，上层代码无需感知平台差异

1.0.9（2026-05-07）

性能优化

LayerDrawHelper 消除每帧 O(N) 分配

• types.ts：TableLayout 新增 layerCols: IColumnGroup[]、layerColOffsets: number[]、layerColKeyMap: Map<string, number> 三个字段——按 fixed 分组后的合并叶列数组、列宽前缀和及 key→索引 Map，列变化时重建一次，帧内直接复用
• hooks/useTableLayout.ts：computeTableLayout 在列分组计算完成后一次性构建 layerCols/layerColOffsets/layerColKeyMap 并嵌入返回对象
• layers/LayerDrawHelper.ts：构造函数改为直接引用 layout.layerCols/layout.layerColOffsets/layout.layerColKeyMap，移除 buildColOffsets import；消除每帧 2× O(列数) 的数组分配与 Map 构建开销（Overlay body + fixedTop 两路各触发一次）

drawText / drawSmoothLine / drawPolyline / drawArea 行列双向自动裁剪

• layers/LayerDrawHelper.ts：drawText 改为复用 _isInVisibleRange 做行列双向可见性检测——以 text.length × fontSize 作为文字宽度的严格保守上界（CJK ≈ 1× fontSize/char，ASCII ≈ 0.55×，取 1× 保证无漏判），消除旧版仅有 Y 轴检测的遗漏；canvas clip 保障像素级正确性，_isInVisibleRange 仅对完全位于主区可见列窗口外的文字跳过，固定列区域恒允许；至此 LayerDrawHelper 全部 draw* 方法均实现行列双向裁剪
• layers/LayerDrawHelper.ts：新增私有方法 _trimPoints(points, buffer)——检测点集主方向：Y 单调递增时按可见行像素窗口（_visY1/_visY2）裁剪；X 单调递增且整体在主区内时按可见主区列像素窗口（_visMainX1/_visMainX2）裁剪；两端各保留 buffer 个边界点供 Catmull-Rom 切线计算；跨固定列或双向非单调时不裁剪，保证正确性
• layers/LayerDrawHelper.ts：drawSmoothLine、drawPolyline、drawArea 在发送 Canvas 命令前调用 _trimPoints(points, 1)，将 JSBridge 命令量从 O(总行/列数) 降至 O(可见行/列数)；500 行趋势线场景约减少 94% 的 bezierCurveTo/lineTo 调用，App 平台滑动帧率显著提升

1.0.8（2026-05-06）

性能优化

OverlayLayer 自定义绘制全局可见性裁剪

• layers/LayerDrawHelper.ts：新增完整的行列双向可见性裁剪系统——构造时从 ILayerDrawContext.virtual 预算可见行范围（_visRowStart/_visRowEnd）、主区可见列范围（_visColStart/_visColEnd）、可见区像素边界（_visY1/_visY2、_visMainX1/_visMainX2）以及主区全范围像素边界（_mainAreaX1/_mainAreaX2），帧内常量，零额外计算
• layers/LayerDrawHelper.ts：drawCell* 系列（drawCellBg/drawCellCircle/drawCellText/drawCellBadge）和 drawColBg/drawRowBg 均加入行列索引级早退检测，不在可见窗口内的单元格直接跳过，避免无效 Canvas API 调用
• layers/LayerDrawHelper.ts：drawCircle/drawRect/drawRoundRect/drawHLine/drawVLine/drawLine 加入像素级包围盒检测（_isInVisibleRange），包围盒完全在可见区域外则跳过
• layers/LayerDrawHelper.ts：_isInVisibleRange 使用预算的 _mainAreaX1/_mainAreaX2 常量，热路径消除每次调用时的 fixedLeftPx/fixedRightPx 数组查找和算术计算

StickyHeaderLayer 表头列虚拟化

• layers/StickyHeaderLayer.ts：min 区单元格绘制和边框循环均增加列虚拟化过滤——基于 virtual.colStart/colEnd 转换为全局叶列索引范围，跳过完全在可见区域外的单元格，含 colSpan>1 的分组表头仅在任意部分可见时才绘制；100 列只有 10 列可见时每帧 Canvas API 调用量降低约 90%
• layers/StickyHeaderLayer.ts：查询 layout.leafColOffsets 直接复用全量叶列前缀和，替代每帧重新分配和填充 colOffsets 数组

TableLayout 增加共享字段

• types.ts：TableLayout 新增 leafColOffsets: number[]——全量叶列宽度前缀和（fixedLeft → main → fixedRight），长度 = leafColumns.length + 1，供 StickyHeaderLayer 等直接复用
• types.ts：TableLayout 新增 hasSpan: boolean——布局计算时一次性检测主区是否存在 span 函数，避免 BodyLayer 每帧调用 Array.some
• hooks/useTableLayout.ts：computeTableLayout 在已算好 mainColOffsets 后延伸计算 leafColOffsets 和 hasSpan，一并嵌入返回对象

BodyLayer 消除每帧高频遍历

• layers/BodyLayer.ts：mainContentW 由每帧 Array.reduce 改为直接取 layout.mainColOffsets[mainCols.length]（O(N) → O(1)）
• layers/BodyLayer.ts：hover 列索引查找由每帧 Array.findIndex 改为 Map.get()（O(N) → O(1)），Map 仅在 mainCols 引用变化时重建
• layers/BodyLayer.ts：hasSpans 由每帧 Array.some 改为读取 layout.hasSpan 布尔缓存

hitTest 列命中改二分查找

• hooks/useHitTest.ts：hitTestLeafColIndex 和 hitTestColKey 的主区列命中由 O(N) 线性扫描改为利用 mainColOffsets 的二分查找（O(N) → O(log N)），优化高频 mousemove 场景下的列定位性能

BodySpanMask 跨帧缓存

• layers/BodyLayer.ts：引入 _spanMaskCache 字段缓存上一帧的 BodySpanMask；当 data 与 mainCols 引用不变且当前 rowStart/rowEnd 完全在上次扫描范围内时直接复用，已避免每帧 O(可见行 × 所有列)的 span() 函数重复调用

Bug 修复

OverlayLayer payload 遗漏新增属性导致崩溃

• layers/OverlayLayer.ts：手动构建的 payload 对象补充转发 visibleRowRange/visibleColRange（getter）、isRowVisible/isColVisible，修复因属性未转发导致 payload.visibleRowRange.start 抛出 TypeError: Cannot read property 'start' of undefined 的崩溃

drawCellBadge 测量宽度前未设置字号

• layers/LayerDrawHelper.ts：drawCellBadge 在调用 measureText 前加入 this._r.setFontSize(fontSize)，修复沿用上次渲染调用遗留字号状态导致 badge 宽度错误的问题

API 新增

ILayerDrawHelper 新增可见范围查询字段

• types.ts：ILayerDrawHelper 新增 visibleRowRange: Readonly<{ start: number; end: number }>——当前可见行范围，可用于跳过不可见行的 JS 侧自定义计算
• types.ts：ILayerDrawHelper 新增 visibleColRange: Readonly<{ start: number; end: number }>——当前可见主区列范围（绝对索引），fixedLeft/Right 列不受此约束
• types.ts：ILayerDrawHelper 新增 isRowVisible(rowIndex: number): boolean——判断行是否在可见窗口内，draw* 系列已内置此判断，通常无需手动调用
• types.ts：ILayerDrawHelper 新增 isColVisible(colIndex: number): boolean——判断列是否在可见窗口内，fixedLeft/Right 列恒返回 true

文档

• readme.md：ILayerDrawHelper 接口代码块同步新增 4 个字段；坐标查询 API 说明表补充对应条目；单元格便捷系列说明表上方新增内置可见性保护说明

平台兼容性

uni-app(3.7.7)

其他

> [!CAUTION]

⚠️ 购买前请务必阅读

• 试用版 和 普通授权版 均 不建议购买，试用版及导入示例项目后无法直接运行，普通授权版也不保证后续持续同步更新。
• 强烈建议购买 源码授权版，可获得完整源码并保障后续版本同步更新。
• 源码授权版定价合理，pro-table 基于单 canvas 分层渲染架构，功能完整、性能出色，物有所值。

pro-table 是一个基于单 canvas 分层渲染的高性能表格组件，面向 uni-app + Vue 3 场景，兼容 H5 / APP / 小程序端。

它不是 DOM 表格，而是把表头、表体、固定列、固定行、阴影、选区、tooltip、拖拽指示线等内容拆成多个 layer 绘制到同一张 canvas 上，因此更适合大数据量、固定列、虚拟滚动、复杂自定义绘制等场景。

特性

• 单 canvas 分层渲染
• H5 / 小程序双端适配
• 固定表头、固定列、固定行
• 行虚拟滚动、主区列虚拟滚动
• 单元格选区
• 行选择 checkbox / radio
• 列宽拖拽、行高拖拽
• 树形数据展开 / 折叠 / 懒加载
• 客户端排序
• 分页数据切片
• 悬浮提示 tooltip
• 自定义单元格绘制、覆盖层绘制、操作按钮
• 单元格横向 / 纵向合并

在线体验

扫描下方二维码，即可体验 pro-table 示例：

赞赏路径

扫描下方二维码，即可赞赏此项目：

快速开始

<template>
  <view class="table-wrap">
    <pro-table
      ref="tableRef"
      :columns="columns"
      :data="data"
      :options="options"
      @cell-click="onCellClick"
    />
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import ProTable from '@/uni_modules/pro-table/components/pro-table/pro-table.vue'
import type {
  ColumnNode,
  ProTableOptions,
  RowData,
} from '@/uni_modules/pro-table'

interface UserRow extends RowData {
  id: number
  name: string
  dept: string
  salary: number
}

const tableRef = ref<any>(null)

const columns: ColumnNode[] = [
  { key: 'id', title: 'ID', width: 80, cellAlign: 'center', headerAlign: 'center' },
  { key: 'name', title: '姓名', width: 120 },
  { key: 'dept', title: '部门', width: 140 },
  { key: 'salary', title: '薪资', width: 120, cellAlign: 'right', sortable: true },
]

const data = ref<UserRow[]>([
  { id: 1, name: '张三', dept: '研发', salary: 12000 },
  { id: 2, name: '李四', dept: '产品', salary: 15000 },
])

const options: ProTableOptions = {
  fontSize: 13,
  padding: [8, 10],
  stripedBgColor: '#fafafa',
}

function onCellClick(payload: any) {
  console.log('cell-click', payload)
}
</script>

<style scoped>
.table-wrap {
  height: 600px;
}
</style>

组件参数

Props

Props 详细说明

columns

• 作用：描述整张表的列结构，是最核心的输入参数
• 影响范围：表头结构、列宽、固定列、排序、tooltip、自定义单元格绘制、单元格合并都由它决定
• 使用建议：key 必须稳定且唯一，避免在运行时频繁修改列对象结构

data

• 作用：表格主体行数据
• 数据要求：每一项都是一个对象，字段名通常与列 key 对应
• 额外能力：除业务字段外，还可以内联 __resizable__、__minHeight__、__maxHeight__ 等控制字段
• 更新建议：优先替换数组引用，而不是原地深改对象

options

• 作用：统一控制视觉样式和部分交互细节
• 典型用途：边框颜色、背景色、hover 色、字体大小、内边距、选区颜色、拖拽手柄显示
• 适用场景：想整体换风格时优先改这里，而不是在每列里单独覆盖

fixedRows

• 作用：定义固定在表头下方或底部的特殊行
• 典型用途：汇总行、合计行、说明行、固定提示行
• 数据结构：每一项都要显式声明 position: 'top' | 'bottom'
• 能力范围：支持按列覆写渲染，也支持固定行内部单元格合并

enableStriped

• 作用：开启后按奇偶行绘制斑马纹背景
• 注意：只是视觉层面的辅助识别，不影响数据和事件

enableHover

• 作用：是否高亮当前悬浮行
• 平台差异：H5 主要响应鼠标悬浮，小程序依赖触摸交互流程

enableColHover

• 作用：是否高亮当前悬浮列
• 适用场景：强调列阅读对齐，例如财务表、对比表

enableSelection

• 作用：开启后可拖拽选择单元格区域
• 注意：这是“单元格框选”，和 rowSelection 的“行勾选”是两套独立能力

rowSelection

• 作用：开启行级单选或多选能力
• 具体行为：组件会自动在最左侧插入一列选择列
• 注意：当前实现返回的是“当前页索引”，不是业务主键

selectedRowKeys

• 作用：行选择的受控值
• 实际含义：这里的数组成员不是 rowKey，而是当前分页结果中的行下标
• 适用场景：父组件完全接管行选择状态时使用

bodyOverlayDraw / fixedTopOverlayDraw / fixedBottomOverlayDraw

• 作用：在既有表格绘制完成后，再追加一层自定义图形
• 适用场景：趋势线、热点标记、角标、辅助线、状态点、业务注释
• 区别：三个回调分别作用于表体、顶部固定行、底部固定行区域

loading

• 作用：显示加载层，并阻止常规交互
• 适用场景：接口请求中、局部数据切换中、懒加载等待中

treeProps

• 作用：开启树形表格能力
• 适用场景：目录树、组织架构、层级账目、主从明细
• 能力范围：支持默认展开、指定展开、懒加载、缩进列配置

pagination

• 作用：开启组件内部的数据切片逻辑
• 注意：它不渲染分页器，只保存分页状态并对当前数据做 slice
• 适用场景：你自己在页面外部渲染分页栏，再通过 ref 方法或响应式配置联动

Events

事件参数详细说明

cell-click

{
  row: T | null
  rowIndex: number
  colKey: string
  value: any
  isHeader: boolean
  fixedRow?: 'top' | 'bottom'
  localX?: number
  localY?: number
}

适用场景：

• 统一处理普通单元格点击
• 区分表头点击和表体点击
• 在自定义 render 中根据 localX/localY 做更细粒度交互

selection-change / selection-end

{
  range: SelectionRange | null
}

区别：

• selection-change 在拖拽过程中持续触发，适合实时展示状态
• selection-end 只在拖拽完成后触发，适合做最终提交或复制逻辑

row-select-change

{
  indices: number[]
  rows: T[]
}

注意：这里不是全量数据索引，也不是业务 id。

col-resize

{
  key: string
  width: number
}

row-resize

{
  rowIndex: number
  height: number
}

sort-change

排序回调返回 SortState：

• key：当前参与排序的列 key
• order：当前排序方向，可能是 'asc'、'desc' 或 null

page-change

{
  page: number
  pageSize: number
}

Ref 方法

组件通过 defineExpose 暴露了一组实例方法，推荐配合模板 ref 调用。

interface ProTableInstance {
  scheduleRender(): void
  recalcLayout(): void
  scrollToRow(rowIndex: number): void
  scrollToColumn(colKey: string): void
  scrollTo(x?: number, y?: number): void

  selectRows(indices: number[]): void
  deselectRows(indices: number[]): void
  selectAll(): void
  deselectAll(): void
  getSelectedRowIndices(): number[]

  getSelection(): SelectionRange | null
  clearSelection(): void

  getSortState(): SortState
  setSortState(state: SortState): void

  getScrollLeft(): number
  getScrollTop(): number

  toggleExpand(rowKey: string | number): void
  expandAll(): void
  collapseAll(): void
  getExpandedKeys(): Array<string | number>

  goTo(page: number): void
  prevPage(): void
  nextPage(): void
  setPageSize(size: number): void
  getCurrentPage(): number
  getPageCount(): number
  getTotal(): number
}

方法说明

方法参数与行为说明

scheduleRender()

• 含义：请求组件在下一帧重新绘制
• 什么时候用：外部数据没有变，但你知道自定义覆盖层或内部显示状态需要刷新时
• 注意：它只负责重绘，不负责重新计算布局

recalcLayout()

• 含义：重新计算列宽、行高、总宽高、固定区宽度等布局信息
• 什么时候用：容器尺寸变化、列定义变化、你手动修改了需要影响布局的数据时
• 补充：内部会顺带把滚动位置限制到合法范围，避免空白区域

scrollToRow(rowIndex)

• 参数含义：rowIndex 是 body 区数据索引，从 0 开始
• 行为：若目标行已在可视区内，不会多余滚动；若越界则直接忽略
• 注意：这里不支持传固定行索引，也不是业务主键

scrollToColumn(colKey)

• 参数含义：colKey 是你在 columns 中定义的列 key
• 行为：只会滚动主区列；如果目标列本身是固定列，不会产生横向滚动效果
• 适用场景：表单校验后快速跳到某一列、联动定位某列

scrollTo(x, y)

• 参数含义：x 是横向滚动值，y 是纵向滚动值，单位都是像素
• 行为：任一参数传 undefined 表示该方向保持不变
• 补充：内部会自动夹紧到合法滚动范围

selectRows(indices)

• 参数含义：indices 是当前页内需要追加选中的行索引数组
• 行为：是“追加选中”，不会先清空已有选择

deselectRows(indices)

• 参数含义：indices 是当前页内需要取消选择的行索引数组
• 行为：只移除指定项，不影响其它已选行

selectAll()

• 含义：选中当前分页切片中的全部行
• 注意：不是全量数据全选

deselectAll()

• 含义：清空当前组件维护的行选中状态

getSelectedRowIndices()

• 返回值含义：返回当前页中已选行索引，结果会按从小到大排序

getSelection()

• 返回值含义：返回当前单元格框选范围
• 结果解释：若返回 null，表示当前没有有效选区

clearSelection()

• 含义：清空当前单元格选区，不影响行选择状态

getSortState() / setSortState(state)

• getSortState()：获取当前排序列和排序方向
• setSortState(state)：直接改排序状态并重绘
• state.key：排序列 key
• state.order：'asc'、'desc' 或 null
• 注意：这里是直接设置内部排序状态，适合做外部排序同步

getScrollLeft() / getScrollTop()

• 返回值含义：当前实际滚动位置，单位是像素

toggleExpand(rowKey)

• 参数含义：rowKey 是树节点业务主键，对应 treeProps.rowKey 指定的字段值
• 行为：已展开则折叠，未展开则展开
• 懒加载场景：首次展开时可能触发 loadChildren

expandAll() / collapseAll()

• 含义：一次性展开或折叠全部树节点
• 注意：只对树形模式有效

getExpandedKeys()

• 返回值含义：返回当前所有已展开节点的 rowKey 数组

goTo(page)

• 参数含义：目标页码，从 1 开始
• 行为：内部会自动限制在合法页码范围内

prevPage() / nextPage()

• 含义：翻到上一页或下一页
• 行为：到达边界时不会继续超出

setPageSize(size)

• 参数含义：新的每页条数
• 行为：更新后会把当前页重置到第 1 页

getCurrentPage() / getPageCount() / getTotal()

• getCurrentPage()：当前页码
• getPageCount()：按 total / pageSize 计算出的总页数
• getTotal()：当前总条数，优先取 pagination.total

核心类型说明

类型定义位于 components/pro-table/types.ts。

RowMeta / RowData

interface RowMeta {
  __checkable__?: boolean
  __resizable__?: boolean
  __minHeight__?: number
  __maxHeight__?: number
  __level__?: number
  __expanded__?: boolean
  __hasChildren__?: boolean
  __isLeaf__?: boolean
  __loading__?: boolean
}

type RowData = RowMeta & Record<string, any>

CellSpan

interface CellSpan {
  colspan?: number
  rowspan?: number
}

用于描述单元格合并：

• colspan 表示向右合并几列
• rowspan 表示向下合并几行
• 列合并不能跨固定区，fixedLeft、主区、fixedRight 各自独立

ColumnNode

interface ColumnNode {
  key: string
  title: string
  width?: number
  minWidth?: number
  maxWidth?: number
  resizable?: boolean
  headerAlign?: 'left' | 'center' | 'right'
  cellAlign?: 'left' | 'center' | 'right'
  fixed?: 'left' | 'right'
  cellBgColor?: string
  render?: (params: CellRenderParams) => void
  renderHeader?: (params: HeaderCellRenderParams) => void
  children?: ColumnNode[]
  sortable?: boolean
  sorter?: (a: RowData, b: RowData) => number
  defaultSortOrder?: 'asc' | 'desc' | null
  cellOverflow?: 'clip' | 'ellipsis' | 'wrap'
  maxLines?: number
  tooltip?: boolean
  span?: (row: RowData, rowIndex: number) => CellSpan | null | undefined
}

CellRenderBase

CellRenderParams 和 HeaderCellRenderParams 共同继承的公共基础接口，包含坐标、样式和绘制相关的公共字段。

interface CellRenderBase {
  ctx: IRenderer
  x: number
  y: number
  width: number
  height: number
  align: TextAlign
  fontSize: number
  paddingX: number
  textColor: string
  drawText(text: string | number, color?: string): void
  drawCircle(cx: number, cy: number, r: number, color: string, opts?: CircleOptions): void
}

CellRenderParams

自定义列 render 和固定行 cellRender 会收到以下参数（继承 CellRenderBase）：

interface CellRenderParams extends CellRenderBase {
  row: RowData
  value: any
  rowIndex: number
  isHovered: boolean
  hoveredLocalX: number
  hoveredLocalY: number
  pressedAreaKey: string | null
  drawButtons(buttons: ActionButtonConfig[]): void
  registerClickArea(
    key: string,
    x: number,
    y: number,
    w: number,
    h: number,
    onClick: (row: RowData, rowIndex: number) => void,
  ): void
}

几个常用能力：

• drawText：按列对齐和内边距绘制文本，遵循 cellOverflow 配置
• drawCircle(cx, cy, r, color, opts?)：在指定坐标绘制圆形；cx/cy 为画布绝对坐标，居中绘制时可用 x + width/2、y + height/2
• drawButtons：绘制操作按钮并自动接管点击态
• registerClickArea：注册当前单元格内部的局部点击区域

字段含义补充：

HeaderCellRenderParams

自定义表头 renderHeader 会收到以下参数（继承 CellRenderBase）：

interface HeaderCellRenderParams extends CellRenderBase {
  title: string
  column: ColumnNode
  isLeaf: boolean
  drawSortArrow(): void
  fillBackground(color: string, alpha?: number): void
  drawRect(x: number, y: number, w: number, h: number, color: string, alpha?: number): void
  drawRoundRect(x: number, y: number, w: number, h: number, radius: number, fillColor: string, strokeColor?: string, lineWidth?: number): void
}

所有绘制方法底层复用组件内部绘制原语，自动抹平 H5 / 小程序差异，无需直接操作 ctx。

ActionButtonConfig

interface ActionButtonConfig {
  key: string
  label: string
  type?: 'button' | 'link'
  color?: string
  textColor?: string
  hoverColor?: string
  onClick?: (row: RowData, rowIndex: number) => void
}

FixedRowDef

interface FixedRowDef {
  position: 'top' | 'bottom'
  data: RowData
  cellRender?: Record<string, (params: CellRenderParams) => void>
  spans?: Record<string, CellSpan>
}

ProTableOptions

interface ProTableOptions {
  borderColor?: string
  headerBgColor?: string
  bodyBgColor?: string
  hoverRowBgColor?: string
  hoverColBgColor?: string
  stripedBgColor?: string
  textColor?: string
  fontSize?: number
  padding?: number | [number, number]
  rowBgColor?: (row: RowData, rowIndex: number) => string | undefined
  cellBgColor?: (row: RowData, rowIndex: number, colKey: string) => string | undefined
  selectionFillColor?: string
  selectionBorderColor?: string
  resizeHandleVisible?: boolean
}

实际默认值如下：

{
  borderColor: '#e8e8e8',
  headerBgColor: '#fafafa',
  bodyBgColor: '#ffffff',
  hoverRowBgColor: '#f5f5f5',
  hoverColBgColor: '#f0f7ff',
  stripedBgColor: '#fafafa',
  textColor: '#333333',
  fontSize: 13,
  padding: [8, 8],
  selectionFillColor: 'rgba(24,144,255,0.12)',
  selectionBorderColor: '#1890ff',
  resizeHandleVisible: false,
}

说明：

• padding 支持 number 或 [paddingY, paddingX]
• 行高会按 ceil(fontSize * 1.2) + paddingY * 2 自动推导
• rowBgColor 是行级背景色回调
• cellBgColor 优先级高于 rowBgColor 和列级 cellBgColor
• resizeHandleVisible 当前实际默认值是 false

字段含义补充：

RowSelectionConfig

interface RowSelectionConfig {
  type?: 'checkbox' | 'radio'
  columnTitle?: string
  columnWidth?: number | string
  fixed?: boolean
  hideSelectAll?: boolean
}

注意事项：

• selectedRowKeys 与 row-select-change.indices 使用的是当前分页切片内的索引，不是业务主键
• selectAll() 也只作用于当前页数据

SelectionRange

interface SelectionRange {
  startRow: number
  endRow: number
  startColIndex: number
  endColIndex: number
}

SelectionRange 中的行索引是统一虚拟行索引：

• 负值：固定顶部行
• 0 ~ data.length - 1：body 行
• 大于等于 data.length：固定底部行

列索引对应 layout.leafColumns 顺序，也就是“固定左列 -> 主区列 -> 固定右列”。

字段含义补充：

说明：起止值不要求一定是左上到右下，消费时建议自己做一次 min/max 归一化。

SortState

type SortOrder = 'asc' | 'desc' | null

interface SortState {
  key: string
  order: SortOrder
}

TreeConfig

interface TreeConfig {
  childrenKey?: string
  indent?: number
  defaultExpandAll?: boolean
  defaultExpandedKeys?: Array<string | number>
  rowKey?: string
  treeColumnKey?: string
  lazy?: boolean
  loadChildren?: (row: RowData) => Promise<RowData[]>
  hasChildrenField?: string
  onLoadError?: (error: unknown, row: RowData) => void
}

行为说明：

• 懒加载模式下，首次展开某个节点时会调用 loadChildren
• 加载过程中会给该行注入 __loading__ = true
• toggleExpand(rowKey) 传的是 rowKey 值，不是行索引

PaginationConfig

interface PaginationConfig {
  current: number
  pageSize: number
  total: number
  pageSizeOptions?: number[]
}

行为说明：

• 不传 pagination 时，组件直接使用全量数据
• 传入 pagination 时，组件对当前数据执行切片
• 组件提供分页方法和 page-change 事件，但不提供内置分页栏 UI

OverlayDrawPayload

bodyOverlayDraw、fixedTopOverlayDraw、fixedBottomOverlayDraw 会收到以下 payload，继承 ILayerDrawHelper 全部方法并额外提供底层渲染器：

interface OverlayDrawPayload extends ILayerDrawHelper {
  renderer: IRenderer
}

interface ILayerDrawHelper {
  // ─── 坐标查询 ────────────────────────────────────────────
  getColIndexByKey(key: string): number
  getCellRect(colIndex: number, rowIndex: number): { x: number; y: number; w: number; h: number }
  getCellCenter(colIndex: number, rowIndex: number): { x: number; y: number }
  getCellRadius(colIndex: number): number
  getRowHeight(rowIndex: number): number
  getRowCount(): number
  getColCount(): number
  getColBounds(colIndex: number): { x: number; w: number }
  getRowBounds(rowIndex: number): { y: number; h: number }
  visibleRowRange: Readonly<{ start: number; end: number }>
  visibleColRange: Readonly<{ start: number; end: number }>
  isRowVisible(rowIndex: number): boolean
  isColVisible(colIndex: number): boolean

  // ─── 基础几何 ────────────────────────────────────────────
  drawCircle(x: number, y: number, r: number, color: string, opts?: CircleOptions): void
  drawRoundRect(x: number, y: number, w: number, h: number, radius: number, fillColor: string, strokeColor?: string, lineWidth?: number): void
  drawPolyline(points: Array<{ x: number; y: number }>, color: string, lineWidth?: number): void
  drawSmoothLine(points: Array<{ x: number; y: number }>, color: string, lineWidth?: number): void
  drawArea(points: Array<{ x: number; y: number }>, baseY: number, fillColor: string, alpha?: number): void
  drawRect(x: number, y: number, w: number, h: number, color: string, alpha?: number): void

  // ─── 辅助线 ──────────────────────────────────────────────
  drawHLine(x1: number, x2: number, y: number, color: string, lineWidth?: number, dash?: number[]): void
  drawVLine(x: number, y1: number, y2: number, color: string, lineWidth?: number, dash?: number[]): void
  drawLine(x1: number, y1: number, x2: number, y2: number, color: string, lineWidth?: number): void

  // ─── 文字 ────────────────────────────────────────────────
  drawText(text: string, x: number, y: number, opts?: DrawTextOptions): void
  measureText(text: string, fontSize?: number): number

  // ─── 单元格便捷系列 ───────────────────────────────────────
  drawCellBg(colIndex: number, rowIndex: number, color: string): void
  drawCellCircle(colIndex: number, rowIndex: number, color: string, opts?: CircleOptions): void
  drawCellText(colIndex: number, rowIndex: number, text: string, opts?: DrawTextOptions): void
  drawCellBadge(colIndex: number, rowIndex: number, text: string, bgColor: string, textColor?: string): void
  drawColBg(colIndex: number, color: string, alpha?: number): void
  drawRowBg(rowIndex: number, color: string, alpha?: number): void
}

这个 payload 适合做趋势线、角标、额外装饰、热力区块等高阶绘制。

坐标查询：

绘制原语：

单元格便捷系列：

以下方法内置行列可见性判断，不在虚拟化可见窗口内的单元格会自动跳过 Canvas API 调用，无需外部过滤。

常见用法

1. 行选择

<pro-table
  v-model:selectedRowKeys="selectedRowKeys"
  :columns="columns"
  :data="data"
  :row-selection="{ type: 'checkbox', columnWidth: 48 }"
  @row-select-change="onRowSelectChange"
/>

const selectedRowKeys = ref<number[]>([])

function onRowSelectChange(payload: { indices: number[]; rows: RowData[] }) {
  console.log(payload.indices, payload.rows)
}

2. 树形表格

<pro-table
  :columns="columns"
  :data="treeData"
  :tree-props="{
    rowKey: 'id',
    childrenKey: 'children',
    treeColumnKey: 'name',
    indent: 12,
    defaultExpandAll: true,
  }"
/>

3. 固定行

const fixedRows: FixedRowDef[] = [
  {
    position: 'top',
    data: { name: '顶部汇总', salary: 300000 },
  },
  {
    position: 'bottom',
    data: { name: '底部合计', salary: 280000 },
    spans: {
      name: { colspan: 2 },
    },
  },
]

4. 自定义单元格绘制

const columns: ColumnNode[] = [
  {
    key: 'progress',
    title: '进度',
    width: 120,
    render: ({ ctx, x, y, width, height, value, drawText }) => {
      const percent = Number(value) || 0
      ctx.setFillStyle('#f0f0f0')
      ctx.fillRect(x + 8, y + height / 2 - 4, width - 16, 8)

      ctx.setFillStyle('#1890ff')
      ctx.fillRect(x + 8, y + height / 2 - 4, ((width - 16) * percent) / 100, 8)

      drawText(`${percent}%`)
    },
  },
]

使用注意事项

1. data 变更建议替换引用

组件对 data 使用的是引用级 watch，而不是深度 watch。这样做是为了避免大数组深遍历的性能开销。

推荐：

data.value = [...data.value, newRow]

不推荐依赖深层属性原地修改后自动触发布局重算。

2. 行选择索引是“当前页索引”

无论是 selectedRowKeys、row-select-change.indices、getSelectedRowIndices()，当前实现返回的都是分页切片内索引，而不是业务主键。

如果你的业务需要稳定主键选择，建议在外层把索引映射成真实 id 存储。

3. 分页是逻辑分页，不是完整分页组件

pagination 只负责：

• 当前页切片
• 页码状态
• 对外暴露翻页方法
• 触发 page-change

它不负责渲染页码器、页大小切换器、总数展示。

4. resizeHandleVisible 当前默认是 false

源码合并默认值时，resizeHandleVisible 的实际默认行为是 false。如果你希望显示列宽 / 行高拖拽手柄，需要显式设置：

const options: ProTableOptions = {
  resizeHandleVisible: true,
}

建议的类型导入方式

import type {
  RowData,
  ColumnNode,
  ProTableOptions,
  FixedRowDef,
  RowSelectionConfig,
  SelectionRange,
  SortState,
  TreeConfig,
  PaginationConfig,
  CellRenderBase,
  CellRenderParams,
  HeaderCellRenderParams,
  ActionButtonConfig,
  OverlayDrawPayload,
} from '@/uni_modules/pro-table'