Pekon 在线表格

基于 React、TypeScript 和 Handsontable 6.2.2 构建的强大协作表格组件

功能特性 • 快速开始 • 使用方法 • 配置说明 • 开发指南

Pekon 在线表格是一个功能丰富的协作表格组件，专为企业应用程序设计。基于 Handsontable 6.2.2 构建，提供实时协作、动态高度管理和丰富的格式化功能，同时保持出色的性能表现。

功能特性

核心功能

• 实时协作编辑 - 多用户同时编辑，实时更新并显示可视化指示器
• 动态表格高度 - 根据内容自动调整高度，最大高度为 60dvh，优化用户体验
• 高级单元格类型 - 支持文本、数字、日期、下拉选择、公式和自定义单元格类型
• 丰富文本格式 - 字体样式、颜色、对齐方式、单元格合并和自定义格式选项
• 公式支持 - 内置公式计算引擎，由 HyperFormula 提供支持
• 多工作表 - 基于标签页的工作表管理，支持添加/删除功能

用户体验

• 右键菜单 - 全面的右键操作，提升工作效率
• 键盘快捷键 - 标准表格导航和编辑快捷键
• 附件支持 - 直接将文件和附件链接到单元格
• 消息系统 - 单元格内消息传递和协作功能
• 移动端适配 - 优化触摸设备和移动端屏幕显示

性能与可靠性

• 虚拟滚动 - 大型数据集的高效渲染，无性能下降
• 行标题持久化 - 滚动时行号始终可见，不受表格高度影响
• 内存管理 - 适当的清理和资源管理，防止内存泄漏
• 优化重新渲染 - 智能更新，最小化协作过程中的性能影响

[!NOTE] 此组件专为企业使用场景优化，支持数千个单元格和并发用户。

快速开始

环境要求

• Node.js（版本 14 或更高）
• npm 或 yarn 包管理器

快速启动

1. 克隆仓库

   git clone <repository-url>
   cd pekon-online-table

2. 安装依赖

   npm install

3. 启动开发服务器

   npm run demo

4. 打开浏览器，导航到开发服务器地址

生产环境构建

npm run build:pages

构建后的组件将在 dist 文件夹中提供。

使用方法

基础实现

import OnlineTable from './src/v1/pages/online-table';

const MySpreadsheet = () => {
  const tableProps = {
    excelOid: "your-excel-id",
    excelName: "文档名称", 
    sourceId: "source-identifier",
    isEditing: true,
    isLocal: true,
    sheetList: [/* 你的工作表数据 */],
  
    // 事件回调
    onSheetOption: (type, saveData) => {
      console.log('工作表操作:', type, saveData);
    },
    onSaveSheetStyle: (sheetStyle, sheetMergeInfo) => {
      console.log('样式已保存:', sheetStyle);
    },
    onSaveSheetContent: (sheetInfo) => {
      console.log('内容已保存:', sheetInfo);
    },
  };

  return <OnlineTable {...tableProps} />;
};

高级配置

const advancedProps = {
  // UI 控制
  isShowSheetTabs: false,      // 显示多表格标签
  isShowToolbar: false,       // 启用/禁用格式化工具栏
  
  // 格式化能力
  canSetFontSize: true,        // 字体大小设置
  canSetFontColor: true,       // 字体颜色设置
  canFormatBold: true,         // 粗体格式
  canFormatItalic: true,       // 斜体格式
  canFormatUnderline: true,    // 下划线格式
  canMergeCells: true,         // 单元格合并
  canUnmergeCells: true,       // 取消合并
  
  // 表格操作
  canInsertCol: true,          // 插入列
  canDeleteCol: true,          // 删除列
  canInsertRow: true,          // 插入行
  canDeleteRow: true,          // 删除行
  canClearFormats: true,       // 清除格式
};

配置说明

动态高度系统

表格根据内容自动调整高度：

• 最大高度：60dvh（视口高度的 60%）
• 动态调整：内容小于 60dvh 时，使用计算的内容高度
• 行标题持久化：滚动时行号始终可见
• 平滑过渡：高度变化无动画效果，提供更好的用户体验

功能开关

| 属性 | 类型 | 默认值 | 描述 | | ------------------- | ------- | ------ | ---------------- | | isEditing | boolean | false | 禁用所有编辑功能 | | isLocal | boolean | true | 是否本地化 | | isShowSheetTabs | boolean | false | 显示多Sheet标签 | | isShowToolbar | boolean | false | 禁用格式化工具栏 |

单元格类型配置

const cellTypes = {
  text: { /* 文本单元格配置 */ },
  number: { /* 数字单元格配置 */ },
  date: { /* 日期单元格配置 */ },
  dropdown: { 
    selectEnum: [
      { label: "选项 1", value: "opt1" },
      { label: "选项 2", value: "opt2" }
    ]
  },
  formula: { /* 公式单元格配置 */ }
};

开发指南

项目结构

pekon-online-table/
├── packages/
│   └── app/
│       ├── src/
│       │   └── v1/
│       │       ├── components/        # 可复用组件
│       │       │   ├── online-table/  # 核心表格钩子
│       │       │   ├── sheet-toolbar/ # 格式化控件
│       │       │   └── sheet-tabs/    # 多工作表导航
│       │       ├── pages/             # 主要页面组件
│       │       │   └── online-table/  # 主表格组件
│       │       ├── demo/              # 演示和示例
│       │       │   └── samples/       # 示例实现
│       │       └── utils/             # 工具函数
│       ├── webpack_demo.config.js     # 开发构建配置
│       └── webpack_dist.config.js     # 生产构建配置
├── package.json
└── README.md

核心架构

主要组件

• OnlineTable - 主要编排组件，处理数据、协作和事件
• useTable - 核心表格状态和配置管理钩子
• useTableOperations - CRUD 操作和单元格编辑逻辑
• useStyleOperations - 格式化和样式操作
• useContextMenu - 右键菜单功能
• useHyperFormula - 公式计算集成

核心技术

• React 16.3.2 - 使用钩子和现代模式的 UI 框架
• TypeScript 3.3.3 - 类型安全和增强的开发体验
• Handsontable 6.2.2 - 核心表格功能
• HyperFormula 1.3.1 - 公式计算引擎
• Ant Design 3.18.0 - UI 组件库
• WebSocket - 实时协作通信

演示环境

运行包含示例数据的综合演示：

npm run demo

这将启动一个开发服务器，所有功能都已启用并加载了示例数据。

测试

# 运行单元测试
npm test

# 运行集成测试  
npm run test:integration

# 运行覆盖率测试
npm run test:coverage

浏览器支持

• Chrome（推荐，性能最佳）
• Firefox
• Safari
• Edge

[!IMPORTANT] 为了获得最佳性能和功能兼容性，请使用支持 ES6+ 的现代浏览器。某些高级功能可能需要较新的浏览器 API。

性能优化

优化功能

• 虚拟滚动支持数千行数据集
• React 优化模式的高效重新渲染
• 内存泄漏预防机制
• 实时协作的优化事件处理
• 频繁访问数据的智能缓存

最佳实践

• 限制初始数据大小以加快加载速度（推荐：初始 <1000 行）
• 对超大数据集使用分页或懒加载
• 监控长时间运行会话中的内存使用情况
• 定期清理事件监听器和订阅
• 优化复杂内容的单元格渲染器

故障排除

表格高度未正确更新

• 确保容器具有正确的 CSS 设置
• 验证已启用动态高度计算
• 检查浏览器是否支持视口高度单位（dvh）

滚动时行标题消失

• 这由动态高度系统自动处理
• 确保自定义样式未覆盖 .ht_clone_left 的 CSS 类

大数据集性能问题

• 在表格设置中启用虚拟滚动
• 考虑实现数据分页
• 优化自定义单元格渲染器以避免繁重计算

协作功能无法工作

• 验证 WebSocket 连接已建立
• 确保正确的身份验证和权限

依赖项

核心库

| 包名 | 版本 | 用途 | | ------------------- | ------- | ---------- | | React | ^16.3.2 | UI 框架 | | Handsontable | ^6.2.2 | 表格功能 | | @handsontable/react | ^2.1.0 | React 集成 | | TypeScript | ^3.3.3 | 类型安全 | | Ant Design | ^3.18.0 | UI 组件 |

专业功能

| 包名 | 版本 | 用途 | | ------------ | -------- | -------- | | HyperFormula | ^1.3.1 | 公式计算 | | Lodash | ^4.17.10 | 工具函数 | | Moment.js | ^2.22.1 | 日期处理 | | CryptoJS | ^3.3.0 | 数据加密 |

相关资源

• Handsontable 文档
• React Hooks 指南
• TypeScript 手册
• HyperFormula 文档
• Ant Design 组件

常见问题

此组件为 React 16.3.2+ 构建，支持钩子。虽然可能与更新版本兼容，但建议彻底测试，因为 Handsontable 集成可能有兼容性要求。

对于大型数据集（>10,000 行），启用虚拟滚动，实现服务器端分页，并考虑增量加载数据。组件开箱即支持这些模式。

可以！组件支持自定义 CSS 样式、主题覆盖和 Ant Design 主题自定义。请参考演示中的样式指南获取示例。

组件提供协作框架，但安全实现（身份验证、授权、数据加密）应由您的后端服务处理。