React 按值自动合并

列上配 mergeKey，相邻同键的行自动纵向合并。这是对静态 merges 的补充，不是替代：静态 merges 表达任意几何但禁用排序，mergeKey 只做纵向成段但由管线自动维护、排序后重新分段。

使用的 API

type Column = {
  key: string;  // 列标识(必填)
  title: string;  // 列标题(必填)
  width: number;  // 列宽(必填)
  /**
   * true                → 用 row[key] 作为比较键
   * (row, i) => unknown → 自定义键；返回 undefined 表示该行不参与合并
   */
  mergeKey?: boolean | ((row: T, rowIndex: number) => unknown);
  mergeMaxSpan?: number;  // 单段最大跨度，超出则断开（不传则不限）
}

type Options = {
  list: T[];  // 数据列表
  itemKey: string;  // 行唯一标识字段名
  estimatedSize: number;  // 行预估高度(px)
  fixedSize: boolean;  // 固定行高（合并场景推荐）
  border: boolean;  // 是否显示边框
  stripe: boolean;  // 斑马纹（合并格不带斑马纹）
}

const columns: ReactTableColumn<Row>[] = [
  // 按单字段合并
  { key: 'dept', title: '部门', width: 150, mergeKey: true, sortable: true },
  // 拼键：只有「大区 + 状态」都相同才合并
  { key: 'region', title: '大区', width: 150, mergeKey: (r) => `${r.region}/${r.status}` },
];

完整语义（长段重锚、结构边界断开、固定列限制、buildMergesFromSpan 迁移）见 Vanilla · 按值自动合并。

示例

微应用尚未挂载。

源码

点击查看源码

import React from 'react';
import { VirtTableReact, type ReactTableColumn } from '@virt-table/react';

/**
 * 按值自动合并（列 `mergeKey`）。
 *
 * 10 万行，三种段长同时在场：
 *   - 部门：8 行一段（常规）
 *   - 状态：约 3.3 万行一段（长段，用来看「重锚」与虚拟滚动是否还成立）
 *   - 大区：跨两个字段拼键（`mergeKey` 返回自定义键）
 * 排序照常可用 —— 分段在管线末端重算，这是它与静态 `merges` 的关键差别。
 */
const ROW_COUNT = 100_000;
const REGIONS = ['华东', '华北', '华南'];
const STATUSES = ['待处理', '进行中', '已完成'];

interface Row extends Record<string, unknown> {
  id: number;
  region: string;
  dept: string;
  status: string;
  owner: string;
  amount: number;
}

// 懒生成：App 会静态 import 全部示例模块，10 万行放在模块顶层会拖慢整个 demo 站首屏
let _db: Row[] | null = null;
const getList = (): Row[] =>
  (_db ??= Array.from({ length: ROW_COUNT }, (_, i) => ({
    id: i,
    region: REGIONS[(i / 25_000) | 0] ?? '华南',
    dept: 'D' + ((i / 8) | 0),
    status: STATUSES[(i / 33_333) | 0] ?? '已完成',
    owner: '员工 ' + i,
    amount: ((i * 37) % 900) + 100,
  })));

const columns: ReactTableColumn<Row>[] = [
  // 拼键：只有「大区 + 状态」都相同才合并
  {
    key: 'region',
    title: '大区（拼键合并）',
    width: 150,
    mergeKey: (row) => `${row.region}/${row.status}`,
    align: 'center',
    vAlign: 'middle',
  },
  {
    key: 'status',
    title: '状态（长段 + 重锚）',
    width: 160,
    mergeKey: true,
    align: 'center',
    vAlign: 'middle',
    sortable: true,
  },
  {
    key: 'dept',
    title: '部门（8 行一段）',
    width: 150,
    mergeKey: true,
    align: 'center',
    vAlign: 'middle',
    sortable: true,
  },
  { key: 'owner', title: '负责人', width: 160 },
  { key: 'amount', title: '金额', width: 120, align: 'right', sortable: true },
];

export default function AutoMergeTable() {
  const list = React.useMemo(getList, []);
  return (
    <div className="demo-wrapper">
      <h3 className="demo-title">React 按值自动合并</h3>
      <div className="status-text">
        {ROW_COUNT.toLocaleString()} 行 · 滚到长段中间时合并格会重锚到可视区顶部（虚拟滚动下的必然）·{' '}
        <code>mergeKey</code> 不禁用排序，点表头试试
      </div>
      <div style={{ width: '100%', height: 600 }} className="demo-container">
        <VirtTableReact
          columns={columns}
          options={{
            list,
            itemKey: 'id',
            estimatedSize: 40,
            buffer: 4,
            // 合并 + 动态行高是既有的敏感组合，自动合并建议配固定行高
            fixedSize: true,
            border: true,
            stripe: true,
          }}
        />
      </div>
    </div>
  );
}