@canvas-components/list-table 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 canvas-components contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @canvas-components/list-table
+
+`@canvas-components/list-table` 是整个项目的纯原生 Canvas 表格核心包，不依赖 React，可直接在 DOM 容器中创建高性能表格实例，也可作为适配层的底层引擎使用。
+
+## 功能作用
+
+- 原生 Canvas 表格渲染
+- 大数据量虚拟滚动
+- 多级表头、固定列、汇总行
+- 排序、过滤、自动合并单元格
+- 行选择、展开树表、右键菜单
+- 单元格编辑、校验、tooltip、图片预览
+- 列宽调整、列拖拽、行拖拽、轮播滚动
+- 内建二维码、条形码、进度、图表、评分、按钮等单元格内容
+
+## 安装方法
+
+```bash
+pnpm add @canvas-components/list-table
+```
+
+最低环境要求：
+
+- `Node.js >= 18.12.0`
+- `pnpm >= 9.0.0`
+
+## 使用方法
+
+```ts
+import { ListTable } from "@canvas-components/list-table";
+
+const container = document.querySelector("#table") as HTMLElement;
+
+const table = new ListTable(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();
+```
+
+## 属性说明
+
+### 实例配置 `ListTableOptions`
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `type` | `"list"` | 表格类型，当前稳定支持列表表格 |
+| `rowKey` | `string \| number \| Array<string \| number> \| ((record, index) => string \| number)` | 行主键解析规则 |
+| `columns` | `ListTableColumn[]` | 列配置集合 |
+| `width` | `number \| string` | 表格宽度 |
+| `height` | `number \| string` | 表格高度 |
+| `dataSource` | `RecordType[]` | 表格数据源 |
+| `emptyText` | `string` | 空状态文案 |
+| `theme` | `Partial<ListTableTheme>` | 主题覆盖 |
+| `striped` | `boolean` | 是否开启斑马纹 |
+| `highlightMode` | `"cell" \| "row" \| "column" \| "cross"` | 点击高亮模式 |
+| `contextMenu` | `false \| ListTableContextMenuOptions` | 右键菜单配置 |
+| `rowHeight` | `number \| "auto"` | 行高 |
+| `headerRowHeight` | `number` | 表头单行高度 |
+| `summaryRowHeight` | `number` | 汇总行高度 |
+| `overscanRowCount` | `number` | 虚拟滚动预渲染行数 |
+| `query` | `ListTableQueryOptions` | 排序、过滤、合并单元格配置 |
+| `rowSelection` | `ListTableRowSelectionOptions` | 行选择配置 |
+| `expandable` | `ListTableExpandableOptions` | 树表 / 展开行配置 |
+| `pagination` | `false \| ListTablePaginationOptions` | 分页或滚动加载配置 |
+| `scrollbar` | `ListTableScrollbarOptions` | 滚动条配置 |
+| `carouselScroll` | `ListTableCarouselScrollOptions` | 自动轮播滚动配置 |
+| `stretchColumns` | `boolean` | 列总宽不足时是否拉伸补齐 |
+| `resizable` | `boolean` | 是否开启列宽拖拽 |
+| `storageKey` | `string` | 持久化键 |
+| `draggable` | `boolean` | 是否开启列拖拽排序 |
+| `tableId` | `string` | 表格唯一标识 |
+| `rowDrag` | `ListTableRowDragOptions` | 行拖拽配置 |
+| `debug` | `ListTableDebugOptions` | 调试配置 |
+
+### 列配置 `ListTableColumn`
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `key` | `string` | 列唯一标识 |
+| `title` | `string` | 列标题 |
+| `dataIndex` | `string \| number \| Array<string \| number>` | 取值路径 |
+| `children` | `ListTableColumn[]` | 子列，用于多级表头 |
+| `width` | `number` | 列宽 |
+| `minWidth` / `maxWidth` | `number` | 允许调整的最小 / 最大列宽 |
+| `align` | `"left" \| "center" \| "right"` | 内容对齐 |
+| `fixed` | `"left" \| "right"` | 固定列 |
+| `hidden` | `boolean` | 是否隐藏 |
+| `ellipsis` | `boolean` | 超出是否省略 |
+| `editable` | `boolean \| (text, record, index) => boolean` | 是否允许编辑 |
+| `formItemProps` | `ListTableFormItemPropsConfig` | 编辑器配置 |
+| `resizable` | `boolean` | 单列是否允许调整宽度 |
+| `draggable` | `boolean` | 单列是否允许拖拽 |
+| `allowSort` | `boolean` | 是否开启排序 |
+| `allowFilter` | `boolean` | 是否开启过滤 |
+| `filterOptions` | `ListTableFilterOption[]` | 精确过滤选项 |
+| `cellType` | `ListTableCellContent["type"]` | 内建单元格类型 |
+| `moneyFormat` | `ListTableMoneyFormatOptions` | 金额格式配置，仅在 `cellType: "money"` 时生效 |
+| `render` | `(value, record, rowIndex, column) => ...` | 自定义渲染 |
+| `onCell` | `(value, record, rowIndex, column) => { rowSpan?: number; colSpan?: number }` | 单元格跨度控制 |
+| `summary` | `boolean \| ListTableSummaryConfig` | 汇总配置 |
+| `summaryTitle` | `string` | 汇总标题文本 |
+
+### 常见嵌套能力
+
+| 配置 | 说明 |
+| --- | --- |
+| `query` | 排序、筛选、远程查询、自动合并单元格 |
+| `rowSelection` | checkbox / radio 行选择 |
+| `expandable` | 树形数据、详情展开、展开列 |
+| `pagination` | 按钮分页或滚动加载 |
+| `rowDrag` | 行拖拽、跨表拖拽、拖放回调 |
+| `contextMenu` | 复制、导出、冻结、列显示、密度、缩放等菜单能力 |
+
+## 方法说明
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `constructor` | `new ListTable(container, options)` | 创建实例 |
+| `mount` | `() => void` | 挂载表格 |
+| `updateOptions` | `(options) => void` | 更新配置并刷新 |
+| `getDebugSnapshot` | `() => ListTableDebugSnapshot \| null` | 获取调试快照 |
+| `validate` | `() => Promise<RecordType[]>` | 手动触发校验，失败时抛出 `ListTableValidationFailure` |
+| `exportXlsx` | `() => void` | 异步导出全部原始数据为 XLSX |
+| `scrollTo` | `(options: ListTableScrollToOptions) => void` | 滚动到指定行 |
+| `destroy` | `() => void` | 销毁实例 |
+
+## 内建单元格内容
+
+`render` 支持直接返回结构化内容，内建类型包括：
+
+- `text`
+- `money`
+- `image`
+- `qrcode`
+- `barcode`
+- `progress`
+- `chart`
+- `rate`
+- `button`
+- `tag`
+- `color`
+- `icon`
+- `checkbox`
+- `radio`
+- `switch`
+- `link`
+
+### 金额单元格示例
+
+```ts
+const columns = [
+  {
+    title: "金额",
+    dataIndex: "amount",
+    width: 140,
+    align: "right",
+    cellType: "money",
+    moneyFormat: {
+      symbol: "¥",
+      thousandsSeparator: true,
+      decimalPlaces: 2,
+    },
+  },
+  {
+    title: "结算金额",
+    dataIndex: "settlementAmount",
+    width: 160,
+    align: "right",
+    render(value) {
+      return {
+        type: "money",
+        value: value as number,
+        symbol: "$",
+        thousandsSeparator: ",",
+        decimalPlaces: 1,
+      };
+    },
+  },
+];
+```
+
+## 推荐搭配
+
+- 原生 DOM 场景：直接使用 `ListTable`
+- React 场景：优先使用 `@canvas-components/react-list-table`
+- 二维码 / 条形码 / 图表单元格：配合 `@canvas-components/qrcode`、`@canvas-components/barcode`、`@canvas-components/chart`