一个功能强大的 Excel 风格可编辑表格组件，基于 React + TypeScript + Vite 构建，支持表达式计算、自动完成、排序、搜索等丰富功能。

• 多种列类型支持：文本、数字、标签、自动完成、下拉选择、公式文本、引用计算
• Excel 风格编辑：双击或直接输入进入编辑模式，支持 Tab/Enter 快速跳转
• 键盘导航：方向键（↑ ↓ ← →）在单元格间自由导航
• 自动新增行：在最后一行末尾按 Enter 或 ↓ 自动添加新行
• 禁用行：支持设置某些行不可编辑，导航时自动跳过

• 智能搜索：支持全局搜索、指定列搜索、自定义搜索逻辑
• 列排序：点击表头排序图标，支持升序/降序/取消排序
• 自动完成：异步搜索、防抖、自由输入或选择建议项
• 级联填充：选择某列后自动填充关联列（如选择城市自动填充省份和区号）
• 表达式计算：支持引用其他列进行计算（如 price*count）
• 公式文本：输入纯数字表达式（如 1+2*2+3），可被其他列引用计算

• 行操作：删除、复制行，支持自定义操作按钮
• 多选操作：批量选择、复制到剪贴板、从剪贴板导入
• 自定义渲染：支持自定义搜索框、操作列、多选操作栏的渲染
• 回调钩子：提供丰富的前置/后置回调函数，方便扩展业务逻辑

npm install

npm run dev

npm run build

npm run preview

• 框架: React 19.2.0
• 语言: TypeScript 5.9.3
• 构建工具: Vite 7.2.2
• UI 组件: Radix UI + shadcn/ui
• 样式: Tailwind CSS 3.4.17
• 图标: Lucide React

import { useRef, useState } from 'react'
import EditableTable from '@/components/EditableTable'
import { ColumnConfig, ColumnType, TableRow, TableRef } from '@/types/table'

function App() {
  const tableRef = useRef<TableRef>(null)
  const [data, setData] = useState<TableRow[]>([
    { id: '1', name: 'iPhone 15', price: 5999, count: 2 }
  ])

  const columns: ColumnConfig[] = [
    { key: 'name', title: '商品名称', type: ColumnType.TEXT, editable: true },
    { key: 'price', title: '单价', type: ColumnType.NUMBER, editable: true },
    { key: 'count', title: '数量', type: ColumnType.NUMBER, editable: true },
  ]

  return (
    <EditableTable
      ref={tableRef}
      columns={columns}
      data={data}
      onChange={setData}
      enableAutoAddRow={true}
    />
  )
}

const columns: ColumnConfig[] = [
  { key: 'price', title: '单价', type: ColumnType.NUMBER, editable: true },
  { key: 'count', title: '数量', type: ColumnType.NUMBER, editable: true },
  { 
    key: 'total', 
    title: '总价', 
    type: ColumnType.REFERENCE,
    expression: 'price*count', // 自动计算
    editable: false 
  },
]

const searchCities = async (searchValue: string) => {
  const results = await fetch(`/api/cities?q=${searchValue}`)
  return results.json()
}

const columns: ColumnConfig[] = [
  {
    key: 'city',
    title: '城市',
    type: ColumnType.AUTOCOMPLETE,
    editable: true,
    autoComplete: {
      request: searchCities,
      debounceDelay: 300,
      placeholder: '请输入城市名称...',
      onSelect: (option, rowIndex) => {
        // 级联填充其他列
        tableRef.current?.batchUpdateCells(rowIndex, {
          province: option.extra.province,
          areaCode: option.extra.areaCode,
        })
      },
    },
  },
]

<EditableTable
  columns={columns}
  data={data}
  search={{
    enabled: true,
    placeholder: '搜索商品...',
    searchableColumns: ['name', 'price'], // 只搜索这些列
  }}
/>

const columns: ColumnConfig[] = [
  { 
    key: 'price', 
    title: '单价', 
    type: ColumnType.NUMBER, 
    sortable: true // 启用排序
  },
]

<EditableTable
  columns={columns}
  data={data}
  actionColumn={{
    enabled: true,
    showDelete: true,
    showCopy: true,
    onBeforeDelete: (row) => {
      return window.confirm(`确定要删除 ${row.name} 吗？`)
    },
    onAfterCopy: (originalRow, newRow) => {
      console.log('已复制行:', newRow)
    },
  }}
/>

<EditableTable
  columns={columns}
  data={data}
  batchOperation={{
    enabled: true,
    showCopyToClipboard: true,
    showImportFromClipboard: true,
    onAfterCopy: (selectedRows) => {
      alert(`已复制 ${selectedRows.length} 行数据`)
    },
  }}
/>

属性	类型	默认值	说明
columns	ColumnConfig[]	必填	列配置数组
data	TableRow[]	必填	表格数据
enableAutoAddRow	boolean	true	是否启用自动新增行
onSubmit	(data: TableRow[]) => void	-	提交数据回调
onCellChange	(rowId, columnKey, value) => void	-	单元格变更回调
onChange	(data: TableRow[]) => void	-	数据变更回调（受控模式）
onCreateRow	() => TableRow	-	自定义创建新行方法
search	SearchConfig	-	搜索配置
actionColumn	ActionColumnConfig	-	操作列配置
batchOperation	BatchOperationConfig	-	多选操作配置

属性	类型	说明
key	string	列的唯一标识
title	string	列标题
type	ColumnType	列类型
width	number	列宽度
editable	boolean	是否可编辑
sortable	boolean	是否可排序
expression	string	引用列表达式（如 price*count）
autoComplete	AutoCompleteConfig	自动完成配置
select	SelectConfig	下拉选择配置
tags	TagConfig[]	标签配置
render	(value, row) => ReactNode	自定义渲染
customSort	(a, b, direction) => number	自定义排序函数

• TEXT: 文本类型
• NUMBER: 数字类型
• TAG: 标签类型
• AUTOCOMPLETE: 自动完成类型
• SELECT: 下拉选择类型
• FORMULA_TEXT: 公式文本类型
• REFERENCE: 引用计算类型

const tableRef = useRef<TableRef>(null)

// 添加行
tableRef.current?.addRow(customRow)

// 更新单元格
tableRef.current?.updateCell(rowIndex, columnKey, value)

// 批量更新多个单元格
tableRef.current?.batchUpdateCells(rowIndex, { 
  province: '北京', 
  areaCode: '010' 
})

普通文本输入，支持任意字符。

只允许输入数字，自动过滤非数字字符。

预定义的标签选项，输入匹配值后显示对应标签样式。

• 支持异步搜索
• 防抖延迟
• 可自由输入或选择建议项
• 支持级联填充其他列

• 从预定义选项中选择
• 不支持自由输入
• 支持自定义渲染选项

• 输入纯数字表达式（如 1+2*2+3）
• 显示和保存原始字符串
• 可被其他引用列引用并计算

• 引用其他列进行计算
• 支持复杂表达式（如 price*count*discount）
• 自动响应依赖列的变化

项目提供了完整的表达式计算工具（src/utils/expression.ts）：

• evaluateExpression(expression): 计算纯数字表达式
• evaluateExpressionWithColumnNames(expression, row): 计算包含列名的表达式
• isValidFormulaText(text): 验证是否是有效的公式文本

提供了防抖函数（src/utils/debounce.ts），用于优化自动完成等场景。

• ✅ 商品管理系统
• ✅ 订单录入系统
• ✅ 数据采集表单
• ✅ 预算编制工具
• ✅ 库存管理系统
• ✅ 报价单生成器

react-table-plus/
├── src/
│   ├── components/
│   │   ├── EditableTable/
│   │   │   ├── index.tsx           # 主表格组件
│   │   │   ├── EditableCell.tsx    # 可编辑单元格
│   │   │   ├── AutoCompleteInput.tsx # 自动完成输入
│   │   │   └── SelectInput.tsx      # 下拉选择输入
│   │   └── ui/                     # UI 组件（shadcn/ui）
│   ├── types/
│   │   └── table.ts                # 类型定义
│   ├── utils/
│   │   ├── expression.ts           # 表达式计算工具
│   │   └── debounce.ts             # 防抖工具
│   ├── App.tsx                     # 示例应用
│   └── main.tsx                    # 入口文件
├── package.json
├── vite.config.ts
├── tailwind.config.js
└── tsconfig.json

• 使用 TypeScript 严格模式
• 遵循 React Hooks 最佳实践
• 使用 ESLint 进行代码检查
• 组件采用函数式组件 + Hooks 编写

• 使用 useMemo 缓存计算结果
• 使用 useCallback 避免不必要的重渲染
• 防抖优化搜索和自动完成
• 虚拟滚动（TODO）

欢迎提交 Issue 和 Pull Request！

MIT License

• React
• Vite
• Tailwind CSS
• shadcn/ui
• Radix UI
• Lucide Icons

---

Made with ❤️ by React Table Plus Team