@canvas-components/core

@canvas-components/core 是整个项目的纯原生 Canvas 表格核心包，不依赖 React，可直接在 DOM 容器中创建高性能表格实例，也可作为适配层的底层引擎使用。

功能作用

• 原生 Canvas 表格渲染
• 大数据量虚拟滚动
• 多级表头、固定列、汇总行
• 排序、过滤、自动合并单元格
• 行选择、展开树表、右键菜单
• 单元格编辑、校验、tooltip、图片预览
• 列宽调整、列拖拽、行拖拽、轮播滚动
• 内建二维码、条形码、进度、图表、评分、按钮等单元格内容

安装方法

pnpm add @canvas-components/core

最低环境要求：

• Node.js >= 18.12.0
• pnpm >= 9.0.0

使用方法

import { CanvasTable } from "@canvas-components/core";

const container = document.querySelector("#table") as HTMLElement;

const table = new CanvasTable(container, {
  type: "list",
  width: "100%",
  height: 480,
  rowKey: "id",
  columns: [
    { key: "name", title: "姓名", dataIndex: "name", width: 180 },
    { key: "age", title: "年龄", dataIndex: "age", width: 120, align: "right" },
  ],
  dataSource: [
    { id: 1, name: "张三", age: 28 },
    { id: 2, name: "李四", age: 31 },
  ],
});

table.mount();

属性说明

实例配置 CanvasTableOptions

| 属性 | 类型 | 说明 | | --- | --- | --- | | type | "list" | 表格类型，当前稳定支持列表表格 | | rowKey | string \| number \| Array<string \| number> \| ((record, index) => string \| number) | 行主键解析规则 | | columns | CanvasTableColumn[] | 列配置集合 | | width | number \| string | 表格宽度 | | height | number \| string | 表格高度 | | dataSource | RecordType[] | 表格数据源 | | emptyText | string | 空状态文案 | | theme | Partial<CanvasTableTheme> | 主题覆盖 | | striped | boolean | 是否开启斑马纹 | | highlightMode | "cell" \| "row" \| "column" \| "cross" | 点击高亮模式 | | contextMenu | false \| CanvasTableContextMenuOptions | 右键菜单配置 | | rowHeight | number \| "auto" | 行高 | | headerRowHeight | number | 表头单行高度 | | summaryRowHeight | number | 汇总行高度 | | overscanRowCount | number | 虚拟滚动预渲染行数 | | query | CanvasTableQueryOptions | 排序、过滤、合并单元格配置 | | rowSelection | CanvasTableRowSelectionOptions | 行选择配置 | | expandable | CanvasTableExpandableOptions | 树表 / 展开行配置 | | pagination | false \| CanvasTablePaginationOptions | 分页或滚动加载配置 | | scrollbar | CanvasTableScrollbarOptions | 滚动条配置 | | carouselScroll | CanvasTableCarouselScrollOptions | 自动轮播滚动配置 | | stretchColumns | boolean | 列总宽不足时是否拉伸补齐 | | resizable | boolean | 是否开启列宽拖拽 | | storageKey | string | 持久化键 | | draggable | boolean | 是否开启列拖拽排序 | | tableId | string | 表格唯一标识 | | rowDrag | CanvasTableRowDragOptions | 行拖拽配置 | | debug | CanvasTableDebugOptions | 调试配置 |

列配置 CanvasTableColumn

| 属性 | 类型 | 说明 | | --- | --- | --- | | key | string | 列唯一标识 | | title | string | 列标题 | | dataIndex | string \| number \| Array<string \| number> | 取值路径 | | children | CanvasTableColumn[] | 子列，用于多级表头 | | width | number | 列宽 | | minWidth / maxWidth | number | 允许调整的最小 / 最大列宽 | | align | "left" \| "center" \| "right" | 内容对齐 | | fixed | "left" \| "right" | 固定列 | | hidden | boolean | 是否隐藏 | | ellipsis | boolean | 超出是否省略 | | editable | boolean \| (text, record, index) => boolean | 是否允许编辑 | | formItemProps | CanvasTableFormItemPropsConfig | 编辑器配置 | | resizable | boolean | 单列是否允许调整宽度 | | draggable | boolean | 单列是否允许拖拽 | | allowSort | boolean | 是否开启排序 | | allowFilter | boolean | 是否开启过滤 | | filterOptions | CanvasTableFilterOption[] | 精确过滤选项 | | cellType | CanvasTableCellContent["type"] | 内建单元格类型 | | render | (value, record, rowIndex, column) => ... | 自定义渲染 | | onCell | (value, record, rowIndex, column) => { rowSpan?: number; colSpan?: number } | 单元格跨度控制 | | summary | boolean \| CanvasTableSummaryConfig | 汇总配置 | | summaryTitle | string | 汇总标题文本 |

常见嵌套能力

| 配置 | 说明 | | --- | --- | | query | 排序、筛选、远程查询、自动合并单元格 | | rowSelection | checkbox / radio 行选择 | | expandable | 树形数据、详情展开、展开列 | | pagination | 按钮分页或滚动加载 | | rowDrag | 行拖拽、跨表拖拽、拖放回调 | | contextMenu | 复制、导出、冻结、列显示、密度、缩放等菜单能力 |

方法说明

| 方法 | 签名 | 说明 | | --- | --- | --- | | constructor | new CanvasTable(container, options) | 创建实例 | | mount | () => void | 挂载表格 | | updateOptions | (options) => void | 更新配置并刷新 | | getDebugSnapshot | () => CanvasTableDebugSnapshot \| null | 获取调试快照 | | validate | () => Promise<RecordType[]> | 手动触发校验，失败时抛出 CanvasTableValidationFailure | | exportXlsx | () => void | 异步导出全部原始数据为 XLSX | | scrollTo | (options: CanvasTableScrollToOptions) => void | 滚动到指定行 | | destroy | () => void | 销毁实例 |

内建单元格内容

render 支持直接返回结构化内容，内建类型包括：

• text
• image
• qrcode
• barcode
• progress
• chart
• rate
• button
• tag
• color
• icon
• checkbox
• radio
• switch
• link

推荐搭配

• 原生 DOM 场景：直接使用 CanvasTable
• React 场景：优先使用 @canvas-components/react-table
• 二维码 / 条形码 / 图表单元格：配合 @canvas-components/qrcode、@canvas-components/barcode、@canvas-components/chart