extagird/README.md

一个面向 Vue 的类 Excel 网格组件（Web 技术组件），支持单元格编辑、校验、渲染、筛选、排序、合并单元格、撤销重做、导出等常见表格能力，适用于数据密集型场景。

## Ex-ta-gird

一个面向 Vue 的类 Excel 网格组件（Web 技术组件），支持单元格编辑、校验、渲染、筛选、排序、合并单元格、撤销重做、导出等常见表格能力，适用于数据密集型场景。

> 说明：仓库内包含核心表格引擎与 Vue 包装组件（`lib/tableLib` 与 `lib/wrapper`）。包名为 `extagird`，使用 Vite 构建，提供类型定义与多格式产物。


## 特性

- **Excel 级交互**：单元格编辑、复制粘贴、填充柄、自动列宽/行高、冻结列行等
- **丰富单元格类型**：文本、数字、选择、下拉、日期、时间、密码、自动完成、自定义类型等
- **渲染与校验分离**：渲染器、编辑器、校验器可插拔，按需扩展
- **强大的扩展系统**：排序、筛选、合并单元格、上下文菜单、拖拽、持久化等
- **国际化与格式化**：内置 i18n、数字/日期格式化
- **高性能大数据量**：虚拟滚动与按需渲染（由内部 walkontable 驱动）
- **主题与样式**：提供默认样式及可选主题，支持自定义覆盖
- **类型完善**：内置 `d.ts` 类型声明，良好 IDE 体验


## 安装

```bash
# 通过 npm
npm install extagird

# 或 pnpm
pnpm add extagird

# 或 yarn
yarn add extagird
```


## 快速上手（Vue 3）

### 安装样式

最少需要引入基础样式与主题样式（任选其一主题）。

```ts
// main.ts
import 'extagird/dist/styles/pipetable.css';
// 或最小化版本
// import 'extagird/dist/styles/pipetable.min.css';

// 可选主题（示例：Horizon）
import 'extagird/dist/styles/ht-theme-horizon.css';
// import 'extagird/dist/styles/ht-theme-horizon.min.css';
```

> 如果你使用的是源码方式集成，可从仓库的 `lib/tableLib/styles` 路径下按需选择。

### 基础用法

```vue
<script setup lang="ts">
import { ref } from 'vue';
// Vue 包装组件
import PipeTable from 'extagird/dist/wrapper/PipeTable.vue';
// 类型（可选）
// import type { PipeTableOptions, PipeColumn } from 'extagird';

const columns = ref([
  { data: 'id', title: 'ID', type: 'numeric', readOnly: true },
  { data: 'name', title: '名称', type: 'text' },
  { data: 'type', title: '类型', type: 'dropdown', source: ['A', 'B', 'C'] },
  { data: 'date', title: '日期', type: 'date', dateFormat: 'YYYY-MM-DD' }
]);

const rows = ref([
  { id: 1, name: '示例 1', type: 'A', date: '2025-01-01' },
  { id: 2, name: '示例 2', type: 'B', date: '2025-02-02' }
]);

const options = ref({
  rowHeaders: true,
  colHeaders: true,
  height: 360,
  licenseKey: 'non-commercial-and-evaluation',
});
</script>

<template>
  <PipeTable :data="rows" :columns="columns" :options="options" />
</template>
```

> 以上属性命名与结构与常见的 Handsontable/类表格库相似；根据你的实际导出 API 略有差异，见下文 API 概览。


## API 概览

> 以下为常用能力速览，完整能力可参考源码目录：`lib/tableLib/*` 与 `lib/wrapper/*`。

### 组件与入口

- **Vue 组件**：`dist/wrapper/PipeTable.vue`、`dist/wrapper/PipeColumn.vue`
- **Types**：`dist/wrapper/types.d.ts` 或 `dist/settings.d.ts`
- **核心入口**：`dist/index.js` / `dist/index.umd.cjs`

### 组件 Props（示例）

- **data**: `Record<string, any>[]` 数据源（行）
- **columns**: `ColumnMeta[]` 列定义（字段、标题、类型、校验、渲染等）
- **options**: `PipeTableOptions` 全局配置（表头可见、选择、滚动、扩展开关等）

### 常见列类型（`type`）

- **text**、**numeric**、**checkbox**、**select**、**dropdown**、**date**、**time**、**password**、**autocomplete**、自定义类型

对应实现可在：
- 渲染器：`lib/tableLib/drawers/*`
- 编辑器：`lib/tableLib/compilers/*`
- 校验器：`lib/tableLib/checkers/*`

### 常用扩展（部分）

- 排序：`extensions/columnSorting`、多列排序：`extensions/multiColumnSorting`
- 筛选：`extensions/filters`
- 合并单元格：`extensions/mergeCells`
- 上下文菜单：`extensions/contextMenu`
- 复制粘贴：`extensions/copyPaste`
- 撤销重做：`extensions/undoRedo`
- 隐藏行列：`extensions/hiddenRows`、`extensions/hiddenColumns`
- 手动移动/调整大小/冻结：`manual*` 系列、`manualColumnFreeze`


## 事件与回调（示例）

```vue
<PipeTable
  :data="rows"
  :columns="columns"
  :options="options"
  @afterChange="onAfterChange"
  @afterSelection="onAfterSelection"
  @beforeRemoveRow="onBeforeRemoveRow"
/>
```

- **afterChange**: (changes, source) => void
- **afterSelection**: (row, col, row2, col2) => void
- **beforeRemoveRow**: (index, amount) => boolean | void（返回 false 可阻止）

> 事件名与参数以实际导出为准，通常与 `lib/tableLib/eventsManager.js`、`features/localHooks.js` 等相对应。


## 自定义渲染器/编辑器/校验器

- 渲染器注册：`lib/tableLib/drawers/registry.js`
- 编辑器注册：`lib/tableLib/compilers/registry.js`
- 校验器注册：`lib/tableLib/checkers/registry.js`

你可以参考现有类型目录（如 `textEditor`、`numericRenderer`、`dateValidator`）新建实现并注册为自定义 `type`，然后在列定义中使用。


## 样式与主题

- 基础样式：`dist/styles/pipetable.css`（或 `.min.css`）
- 主题样式：`dist/styles/ht-theme-main.css`、`dist/styles/ht-theme-horizon.css` 等
- SCSS 源码：`lib/tableLib/styles/*`（包含 `styles/base`、`styles/components`、`styles/themes`）

可通过自定义 CSS 变量或覆写类名进行品牌化定制。建议在自己项目的样式文件中按需覆盖。


## 类型定义

- 主类型入口：`dist/DProject.d.ts`、`dist/wrapper/types.d.ts`
- 你也可以在 TS 项目中获得完整的智能提示（需正确安装本库）


## 构建与本地开发

```bash
# 启动示例/开发环境
pnpm dev

# 类型检查
pnpm check

# 打包构建
pnpm build
```

产物：
- **ESM**：`dist/index.js`
- **UMD**：`dist/index.umd.cjs`
- **类型**：`dist/*.d.ts`
- **样式**：`dist/styles/*.css`


## 常见问题（FAQ）

- **组件不显示/样式错乱？** 确保按顺序引入了基础样式与至少一个主题样式。
- **性能问题（大数据量）？** 启用虚拟滚动（默认开启），尽量使用轻量渲染器，减少过多自定义 DOM。
- **日期/时间格式不生效？** 检查 `moment` 或格式化配置是否与列 `type` 匹配，数据值需规范化。
- **自定义类型不生效？** 确认已在对应 `registry` 完成注册，并在列定义中设置正确的 `type` 名称。


## 贡献指南

欢迎通过 Issue/PR 参与共建：
- 修复问题、补充文档、完善类型
- 新增单元格类型、渲染器/编辑器/校验器
- 新增扩展能力（如更多导出格式、快捷键等）

本地开发请遵循现有代码风格，避免不相关的格式化改动。


## 许可

默认采用与仓库一致的开源许可（如未在根目录声明，请补充 `LICENSE`）。


## 版本记录

- 0.2.1：初始公开说明，完善 README，整理样式与示例用法