@flow97/handsontable

基于 Handsontable 的 React 封装组件库，提供增强的表格功能和差异对比能力。

特性

• 📊 增强的表格组件：基于 Handsontable 的 React 封装，支持搜索、复制等功能
• 🔍 内置搜索功能：支持表格内容搜索和高亮显示
• 📋 智能复制：支持复制为 HTML 和纯文本格式，可粘贴到 Google Sheets、飞书等工具
• 🔄 差异对比表格：DiffTable 组件支持显示数据差异，自动高亮新增、删除和编辑的内容
• 🌐 国际化支持：内置中文语言包
• 🎨 类型安全：完整的 TypeScript 类型定义
• 🔌 原生 API 导出：可直接使用 Handsontable 的所有原生 API

安装

pnpm add @flow97/handsontable

对等依赖

• react: ^19.2.0
• antd: ^6.0.0

快速开始

基础表格

import '@flow97/handsontable/style.css'
import { Table } from '@flow97/handsontable'

const App = () => {
  const data = [
    ['姓名', '年龄', '城市'],
    ['张三', '25', '北京'],
    ['李四', '30', '上海'],
  ]

  return <Table data={data} colHeaders rowHeaders />
}

差异对比表格

import '@flow97/handsontable/style.css'
import { DiffTable } from '@flow97/handsontable'

const App = () => {
  const header = [['姓名', '年龄', '城市']]
  const body = [
    ['张三', '25', '北京'],
    ['李四', '30', '上海'],
  ]

  return <DiffTable header={header} body={body} colHeaders rowHeaders />
}

API 文档

组件

Table

基础表格组件，基于 Handsontable 封装。

Props:

interface TableProps extends Omit<HotTableProps, 'width'> {
  /** 是否显示加载状态 */
  loading?: boolean
  /** 自定义 HTML 生成函数，用于复制到剪贴板 */
  toHTML?: (instance: Handsontable) => string
  /** 自定义文本生成函数，用于复制到剪贴板 */
  toText?: (instance: Handsontable) => string
}

特性：

• 内置搜索功能（顶部搜索框）
• 一键复制功能（支持 HTML 和文本格式）
• 自动计算行高和表格高度
• 支持所有 Handsontable 原生配置

示例：

import { Table, type TableRef } from '@flow97/handsontable'
import { useRef } from 'react'

const App = () => {
  const tableRef = useRef<TableRef>(null)
  const data = [
    ['A1', 'B1'],
    ['A2', 'B2'],
  ]

  return (
    <Table
      ref={tableRef}
      data={data}
      colHeaders
      rowHeaders
      loading={false}
      onAfterChange={changes => {
        console.log('数据变化:', changes)
      }}
    />
  )
}

DiffTable

差异对比表格组件，用于显示数据的前后对比。

Props:

interface DiffTableProps extends Omit<TableProps, 'data' | 'cells' | 'fixedRowsTop' | 'fixedColumnsLeft' | 'toHTML'> {
  /** 表头数据 */
  header?: string[][]
  /** 表格主体数据 */
  body?: string[][]
}

Diff 标记说明：

• +++：新增的行或列（绿色背景）
• ---：删除的行或列（红色背景）
• ->：编辑标记（旧值->新值，显示为红底+绿底）

示例：

import { DiffTable } from '@flow97/handsontable'

const App = () => {
  // 表头
  const header = [['姓名', '年龄', '城市']]

  // 主体数据，第一列包含 diff 标记
  const body = [
    ['+++', '新用户', '20', '深圳'], // 新增行
    ['---', '旧用户', '30', '北京'], // 删除行
    ['->', '修改用户', '25->26', '上海'], // 编辑行
  ]

  return <DiffTable header={header} body={body} colHeaders rowHeaders />
}

Hooks

useHeight

计算表格高度的 Hook。

const height = useHeight(data, autoCalculate, fixedRowsTop)

Handsontable 原生 API

包中重新导出了 Handsontable 的所有原生 API，可以直接使用：

注册所有模块

import { registerAllModules } from '@flow97/handsontable'

// 在应用启动时注册所有 Handsontable 模块
registerAllModules()

注册插件

import { registerPlugin, AutoColumnSize, Search } from '@flow97/handsontable'

// 注册单个插件
registerPlugin(AutoColumnSize)
registerPlugin(Search)

注册语言包

import { registerLanguageDictionary, zhCN } from '@flow97/handsontable'

// 注册中文语言包
registerLanguageDictionary(zhCN)

使用 Renderers、Validators、Editors

import {
  textRenderer,
  numericRenderer,
  numericValidator,
  textEditor
} from '@flow97/handsontable'

// 在表格配置中使用
<Table
  data={data}
  cells={() => ({
    renderer: textRenderer,
    validator: numericValidator,
    editor: textEditor,
  })}
/>

使用命名空间 API

Handsontable 的命名空间 API 也可以通过主类访问：

import { Handsontable } from '@flow97/handsontable'

// 访问命名空间
Handsontable.plugins.AutoColumnSize
Handsontable.languages.registerLanguageDictionary(zhCN)
Handsontable.cellTypes.text
Handsontable.editors.TextEditor
Handsontable.renderers.TextRenderer
Handsontable.validators.NumericValidator

类型定义

import type { HandsontableType } from '@flow97/handsontable'
import { Handsontable } from '@flow97/handsontable'

// 使用类型
const instance: HandsontableType = new Handsontable(container, options)

完整示例

带搜索和复制的表格

import '@flow97/handsontable/style.css'
import { Table, type TableRef } from '@flow97/handsontable'
import { useRef } from 'react'

const App = () => {
  const tableRef = useRef<TableRef>(null)
  const data = [
    ['产品', '价格', '库存'],
    ['iPhone', '5999', '100'],
    ['iPad', '3299', '50'],
    ['MacBook', '9999', '30'],
  ]

  return (
    <Table
      ref={tableRef}
      data={data}
      colHeaders
      rowHeaders
      onAfterChange={changes => {
        console.log('数据已修改:', changes)
      }}
    />
  )
}

差异对比表格

import '@flow97/handsontable/style.css'
import { DiffTable } from '@flow97/handsontable'

const App = () => {
  const header = [['ID', '名称', '价格', '状态']]
  const body = [
    ['+++', 'P001', '新产品', '100', 'active'], // 新增
    ['---', 'P002', '旧产品', '200', 'inactive'], // 删除
    ['->', 'P003', '更新产品', '150->180', 'active'], // 编辑
  ]

  return <DiffTable header={header} body={body} colHeaders rowHeaders readOnly />
}

使用原生 API 注册模块

import { registerAllModules } from '@flow97/handsontable'
import { useEffect } from 'react'

const App = () => {
  useEffect(() => {
    // 注册所有 Handsontable 模块
    registerAllModules()
  }, [])

  return <YourTableComponent />
}

自定义 Renderer

import { Table, textRenderer } from '@flow97/handsontable'

const App = () => {
  const data = [
    ['A1', 'B1'],
    ['A2', 'B2'],
  ]

  return (
    <Table
      data={data}
      cells={() => ({
        renderer: textRenderer,
      })}
    />
  )
}

样式导入

使用组件前，需要导入样式文件：

import '@flow97/handsontable/style.css'

类型定义

所有组件和 API 都提供了完整的 TypeScript 类型定义：

import type { TableProps, TableRef, DiffTableProps, HandsontableType } from '@flow97/handsontable'

注意事项

1. 样式导入：使用组件前必须导入样式文件 @flow97/handsontable/style.css
2. 数据格式：Table 组件接受二维数组 string[][] 作为数据
3. Diff 标记：DiffTable 使用特殊标记（+++、---、->）来标识差异
4. 原生 API：所有 Handsontable 的原生 API 都可以通过 @flow97/handsontable 访问，无需额外安装 handsontable 包

License

ISC