@agile-team/mach-table-react

MachTable 0.36.0 的官方 React 18+ 适配包。一个依赖即可获得 Core、泛型 <MachTable>、应用/路由配置、按需工作流、StrictMode 安全清理和最新闭包事件处理。

小型本地明细设置 domLayout="autoHeight" 并让宿主保持自然高度即可随内容收起；空态、加载态和错误态保留必要空间，恢复数据后释放。大数据表仍应使用明确高度的虚拟视口，分页继续使用内置分页条。

pnpm add @agile-team/mach-table-react

应用入口只引入一次样式：

import "@agile-team/mach-table-react/styles.css";

基础接入

import { useMemo } from "react";
import { MachTable, indexColumn, useMachTable, type ColDef } from "@agile-team/mach-table-react";

interface Row { id: string; name: string }

export function Customers({ rows }: { rows: Row[] }) {
  const table = useMachTable<Row>();
  const columns = useMemo<ColDef<Row>[]>(
    () => [indexColumn({ headerName: "序号" }), { field: "name", flex: 1, editable: true }],
    []
  );

  return (
    <div style={{ height: 520 }}>
      <MachTable<Row>
        apiRef={table.apiRef}
        rowData={rows}
        columnDefs={columns}
        rowKey="id"
        enableColumnResize
        persistence={{ key: "customers:list", sections: ["columns"] }}
      />
    </div>
  );
}

对象型列和配置建议用 useMemo 保持引用稳定。useMachTable() 同时提供 apiRef、响应式 api 与 ready。

应用配置

// src/config/mach-table.config.ts
import { defineMachTableConfig, defineMachTablePreset } from "@agile-team/mach-table-react";

export default defineMachTableConfig({
  defaults: {
    size: "compact",
    columnLayout: "fit",
    enableColumnResize: true,
    defaultColDef: { sortable: true, filter: true, resizable: true }
  },
  defaultPreset: "list",
  presets: {
    list: defineMachTablePreset({ stripedRows: true }),
    crud: defineMachTablePreset({ rowSelection: "multiple", editType: "fullRow" })
  }
});

<MachTableProvider config={machTableConfig}>
  <App />
</MachTableProvider>

Provider 可按路由/布局嵌套，最近一层覆盖外层，表格 props 优先级最高。

编辑、粘贴、清空和填充复用已有列与整行校验。useMachTableEditing() 隔离重挂载或数据替换前的保存结果、错误和冲突；查询工作流在 StrictMode 下保留 immediate: false，重复设置相同搜索值不会重新请求。

按需加载

React 不模拟全局组件注册。路由本身懒加载时普通 import 已自然拆包；需要独立边界时：

const MachTable = lazy(() => import("@agile-team/mach-table-react"));

可选能力使用子入口：

import { useMachTableQuery, useMachTableEditing } from "@agile-team/mach-table-react/workflows";
import { MachTableToolbar } from "@agile-team/mach-table-react/ui";
import { reactCellRenderer } from "@agile-team/mach-table-react/adapters";
import { createWorkerDataProcessor } from "@agile-team/mach-table-react/worker";

• /workflows：请求取消、防过期覆盖、服务端分页、跨页选择、脏数据和冲突保存；reset() 清空全部表格过滤且只请求一次。
• /ui：可选标准工具栏。
• /adapters：自定义 React cell/detail renderer 桥接。
• /worker：大型本地过滤/排序的独立 Worker 能力。

const query = useMachTableQuery({
  query: filters,
  queryKey: filters,
  rowKey: "id",
  request: orderApi.page,
  mode: "manual"
});

<MachTable<Row> apiRef={table.apiRef} columnDefs={columns} {...query.bindings} />;

该包自动依赖 @agile-team/mach-table 并重导出 Core 类型；宿主只需提供 react 和 react-dom >= 18。

行拖拽与条件整行颜色

import { dragColumn, type GridOptions } from "@agile-team/mach-table-react";

interface Plan { id: string; name: string; status: string }
const options: GridOptions<Plan> = {
  rowKey: "id",
  columnDefs: [dragColumn(), { field: "name" }, { field: "status" }],
  rowStyleRules: [
    { when: ({ data }) => data.status === "pending", tone: "warning" },
    { when: ({ data }) => data.status === "failed", tone: "danger" },
    { when: ({ data }) => data.status === "done", tone: "success" }
  ]
};

状态码由应用定义，包内不识别业务状态。颜色规则取第一条命中结果，未命中时沿用默认样式；支持自定义背景/文字颜色、固定列、明暗主题、选择和虚拟行复用。拖拽提供主题手柄、落点线、位置浮层、边缘滚动、Esc 取消和 Alt + ↑/↓ 移动。扁平外部数据设置 applyRowDrag: false，由 onRowDragEnd 处理持久化；自动模式先完成移动再发出事件，使用 targetIndex 读取最终下标。树、分组及排序等自动模式限制见完整配方。

文档：React 指南 · 企业接入 · SSR

按需高级入口（0.34）

仍从本包导入，无需另装高级功能包。普通根入口不加载这些实现或附加 CSS。

| 子路径 | 功能 | | --- | --- | | /workbench | 高级过滤草稿与应用、修改差异/部分保存/冲突审阅、手动诊断 | | /preferences | 复合身份隔离、CAS、有序写入、历史版本及列 ID/类型迁移报告 | | /ordering | 多行/树移动、防环与业务约束、失败回滚、持久化撤销/重做 | | /server-side | 服务端分组/聚合、route 分页、缓存/刷新/事务及层级选择 | | /multi-range | Ctrl/Cmd 追加范围、格式化复制、校验清空及撤销 | | /import | 有界数据预览、共享同步/异步校验、结构化错误与过期保护 | | /business | 显式字典显示/解析/输出策略、范围与币种/单位分组的本地语义合计 | | /analysis | Pivot、安全公式、柱/折线图和数据表回退 |

import { mountAdvancedFilterBuilder } from "@agile-team/mach-table-react/workbench";
import "@agile-team/mach-table-react/styles/workbench.css";

const filters = mountAdvancedFilterBuilder(host, { api });
// 宿主卸载时调用；表格销毁也会释放工作台。
filters.destroy();

服务端分组控件使用 /styles/server-side.css，分析与多范围使用 /styles/workbench.css。排序、偏好和纯分析计算无需附加 CSS。服务端 Store 按 route 分页，不提供全树任意显示 offset；分析只处理当前已加载数据并显示范围。排序 undo/redo 的 transport 必须一次 CAS 保存 context.operations 的完整批次或 context.plan.after，只保存首参数无法完整恢复非连续/跨父级位置。

完整示例与限制：工作台 · 排序 · 企业偏好 · 服务端 Store · 多范围 · 分析。

Source-available © ChenyCHENYU (Agile Team). 任何使用均须事先取得书面授权。详见 LICENSE 与授权流程。

0.34 字典列策略与语义合计

import { createDictionaryColumn, summarizeRows } from "@agile-team/mach-table-react/business";

const options = [{ value: "ready", label: "已就绪" }];
const labels = new Map(options.map(entry => [entry.value, entry.label]));
const statusColumn = {
  field: "status",
  ...createDictionaryColumn({ get: key => labels.get(key) }, {
    options,
    display: "label",
    output: { clipboard: "label", csv: "code-label" }
  })
};

/business 无 UI、请求或缓存，连接已有 Provider；异步标签先预热，动态选项用新数组替换快照。原始数字/文本编码保留类型，重复标签拒绝歧义；未配置的输出通道保留原码，旧 renderer 的导出行为不变。

summarizeRows(rows, { scope, metrics, groupBy?, numeric? }) 只计算传入记录，支持 sum/count/ratio/none；ratio 先分别汇总分子分母。业务按币种、单位分组，scope 仅声明 page/selected/query，不自动获取全量。默认有限 number 仍遵循浮点语义，精确金额使用已有同步 numeric 策略；结果接入原 summaryMethod 或固定行。详见业务列与字典。

根入口的 createCachedDictionary() 现在复用同 key 在途请求，失效隔离旧响应并结束旧等待，缺失项受同一 TTL/LRU 约束。失败可重试，销毁拒绝未完成请求，错误观察回调不会阻塞清理。具体升级边界见升级指南。

列值与运行边界（自 0.33）

ColDef.valueParser 统一编辑、粘贴和导入的规范值；valueSerializer 按 clipboard/csv/xlsx 定义输出，沿用已有 columnTypes 优先级。排序/过滤读取规范值，可信事务与撤销不重复解析。api.io.importMatrix() / exportMatrix() 直传类型，完整导入预览从当前包的 /import 导入 createImportPlan()，不加载到默认入口。

sum / avg / min / max 只聚合有限数，空数值集合返回 null，sum/avg 溢出返回 null；count 计全部记录，空集合为 0。自定义聚合保留原始输入。分组 ID 区分数字/文本/空值，旧展开路径仅在唯一时迁移，歧义报告错误。超大远程滚动使用有界物理坐标，API、滚轮和交互共用逻辑偏移；应用默认配置的 dataProcessor 使用每表工厂。完整边界与升级说明见升级指南。

内容列宽与状态颜色（0.35）

未声明 width 的列默认按表头和已加载数据的显示文本测宽：每列均匀抽样最多 100 行，默认 80–360px，minWidth/maxWidth 可覆盖。长内容在单元格内省略，表格保留内部横向滚动；不为测宽请求远程数据或执行自定义渲染器。格式化、字典及状态标签文字都参与测量。图形/操作等特殊列请指定宽度。

const columns = [
  { field: "customer", headerName: "客户", maxWidth: 280 },
  { field: "status", headerName: "状态", status: true },
  { field: "planStatus", headerName: "计划状态", status: {
    S1B: { label: "待复核", color: "danger" },
    S1C: { label: "已完成", color: "success" },
    special: { label: "特殊处理", color: "#8b5cf6" }
  } }
];

status 复用主题标签，支持 success/warning/danger/info/neutral 及 CSS 颜色；未知代码保持中性，0/false 保留。字典/formatter 的文字可参与默认语义匹配；显式 renderer 优先。状态配置只控制展示，导出继续遵循原有列值政策。

普通布局尊重显式 width 和拖动后的宽度；autoWidth: false 保留原默认 150px。显式选择 columnLayout: "fit" 时仍按首选宽度比例铺满，360px 限制的是内容首选宽度，实际铺满仍遵循显式 minWidth/maxWidth；配置 flex 则主动允许本列吸收余量。手动调宽、列状态恢复及主动 columns.fit() 不受自动默认上限限制。更新数据或刷新单元格会重新测量，普通布局刷新复用结果。

表头默认完整展示，不省略。初始布局、fit、列宽恢复、API、鼠标和 Alt+方向键统一以完整标题及排序/筛选/列工具控件为最小宽度；显式 width/minWidth/maxWidth 不能把标题压窄，空间不足时表格内部横向滚动。360px 上限仅作用于数据内容的首选宽度，不截断表头。复杂自定义表头请显式提供 minWidth。

原生单元格按钮、链接、输入控件及 contenteditable 保留自身键盘和剪贴板行为；Enter/空格可直接激活详情等操作，Ctrl/Cmd 快捷键不会误触发表格编辑或修改表格数据。