React-Grid-Layout v2：Hooks、Compactor 與 legacy 迁移路径

相對 Packery/Gridster 的 React 原生網格

README 定位 React-Grid-Layout（RGL）為类似 Packery、Gridster 的網格係统，但专為 React 設计：响應式、支持 breakpoints、可用户提供或自動生成 breakpoint layout，且不需要 jQuery。演示站 react-grid-layout.github.io 含 Showcase、Basic、No Dragging 等示例；README 称 BitMEX.com 生產環境使用過（附 GIF 说明）。

MIT 許可證，star 22400、openIssues 62 相對可控。homepage 指向 examples/00-showcase.html，npm 包 react-grid-layout 是主要分發渠道，最近 release v2.2.4（2026-07-29）與 v1 線 1.5.4 并行维護。RGL is React-only 一句说明它不绑定 DOM 操作庫，集成成本主要在 layout state 管理。

react-grid-layout v2.2.4 的 RFC 0001 列出 onDragStart 3px 阈值與 data-grid 仅 legacy 可用；在 CodeSandbox demo 里拖動 grid item 少于 3px 時不應触發 onDragStart。若项目仍用 WidthProvider，改 import 為 react-grid-layout/legacy 後跑現有 e2e，确認 layout 數组未被 mutable callback 污染。

演示站含 Showcase、Basic、No Dragging；README 称 BitMEX 生產用過。MIT；star 22400、openIssues 62。npm react-grid-layout，release v2.2.4（2026-07-29）與 1.5.4 并行。

v1 迁移表建议 existing v1 codebase 用 legacy import；new project 用 v2 API。LayoutItem 必填 i 键作 React key；w h 单位為 grid cell。resizeConfig.handles 控制拖拽手柄方向；dragConfig.cancel 排除按钮点击触發 drag。Performance 章建议 memo 子 widget 减少 drag 時全树 render。react-grid-layout/core 可在非 React 環境单元测試 compact 算法；生產 BitMEX 引用说明 API 稳定性经长期驗證但 v2 仍有大版本 breaking。

补充核對：對照 react/grid/layout/react/grid/layout 與 release tag 记錄命令输出、配置文件路径與版本号，在隔离環境重跑最小示例後再决定是否纳入生產依赖链。 RGL 文檔 rfcs 目錄记錄 v2 設计决策，升級前應浏览。 BitMEX 案例證明拖拽網格可用于金融终端級 UI。 选型前讀 Performance 章。 注意 bundle 體积。 测試通過即可。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落1专用核對项。）

react-grid-layout 的佈局資料不是單純的 CSS 片段，x、y、w、h 與 i 會共同決定每個 GridItem 的位置和尺寸。測試時固定容器寬度、cols、rowHeight 與 margin，再比較 onLayoutChange 回傳的陣列；只拖動一次而不保存資料，無法驗證重新載入後是否仍一致。

Responsive 元件會依 breakpoints 和 cols 產生多組 layouts。若只提供一個 breakpoint，切換視窗寬度時可能沒有預期配置。應在同一個 React 頁面記錄 lg、md、sm 的 layout，觀察拖曳、縮放、碰撞與 static 項目的行為，並把序列化結果寫回測試資料。

v2 TypeScript 重寫與模块化入口

v2 完整 TypeScript 重寫，亮点包括：一等类型（无需 @types/react-grid-layout）、Hooks（useContainerWidth、useGridLayout、useResponsiveLayout）、组合式配置（gridConfig、dragConfig、resizeConfig、positionStrategy、compactor）。模块化 import：react-grid-layout（v2 组件與 hooks）、react-grid-layout/core（纯布局算法）、react-grid-layout/legacy（v1 扁平 props API）、react-grid-layout/extras（GridBackground 等）。

Tree-shakeable ESM/CJS，bundle 更小。Breaking changes 详见 rfcs/0001-v2-typescript-rewrite.md。UMD bundle 已移除，必须用 Vite/webpack/esbuild 等 bundler，這對老 CRA 项目可能是迁移摩擦点。

v2 模块化：core 纯算法、legacy v1 API、extras 含 GridBackground。rfcs/0001-v2-typescript-rewrite.md 列 breaking changes；UMD 移除，需 Vite/webpack。

v1 迁移表建议 existing v1 codebase 用 legacy import；new project 用 v2 API。LayoutItem 必填 i 键作 React key；w h 单位為 grid cell。resizeConfig.handles 控制拖拽手柄方向；dragConfig.cancel 排除按钮点击触發 drag。Performance 章建议 m

补充核對：對照 react/grid/layout/react/grid/layout 與 release tag 记錄命令输出、配置文件路径與版本号，在隔离環境重跑最小示例後再决定是否纳入生產依赖链。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落2专用核對项。）

width 必填與 useContainerWidth

v2 要求提供 width：推荐 useContainerWidth hook 自動测量容器。README 示例：const { width, containerRef, mounted } = useContainerWidth(); 在 div ref={containerRef} 內 mounted 為 true 後再渲染 ReactGridLayout，传入 width、layout、gridConfig={{ cols: 12, rowHeight: 30 }} 等。

未 mounted 前不渲染 Grid 是為避免 width=0 時的 layout 抖動。SSR 用例 README 建议 v2 且 measureBeforeMount: true。v1 的 WidthProvider HOC 在 v2 中被 hook 模式取代；忘记传 width 是最常见 runtime 报錯來源之一。

useContainerWidth 返回 width、containerRef、mounted；mounted 前不渲染避免 width=0。SSR 用 measureBeforeMount: true；v1 WidthProvider 改為 hook。

react-grid-layout 1.5.4 與 2.2.4 同日 release 说明 v1 仍维護；legacy 路径长期可用。width prop required 是 v2 最常见迁移坑；useContainerWidth mounted gate 避免 SSR flash。compactor horizontal 與 vertical 影响 widget Reflow 方向；custom Compactor 接口见 rfcs。npm org react-grid-layout 為官方包名。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落3专用核對项。）

onDragStart 3px 阈值與 immutable callbacks

Breaking change：onDragStart 在移動 3px 後才触發，不再 mousedown 即触發；需要即時响應改用 onMouseDown。回調參數只讀，不能再 mutate layout item，應通過 onLayoutChange 或 constraints 更新状态。

data-grid 属性仅在 legacy wrapper 可用；v2 必须显式传 layout prop。verticalCompact 移除，改用 compactType={null} 或 compactor={noCompactor}。compaction 算法可插拔 Compactor interface，extras 提供 O(n log n) fast compactor；自定义 compaction 适合仪表盘 widget 密度策略與產品交互规范不一致的场景。

onDragStart 需移動 3px；即時响應用 onMouseDown。回調參數 immutable；data-grid 仅 legacy。verticalCompact 改為 compactType null 或 noCompactor；Compactor 可插拔。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落4专用核對项。）

legacy 导入與 TypeScript 类型 rename

快速迁移只需改 import：從 react-grid-layout 改為 react-grid-layout/legacy。README 称 legacy 提供 100% v1 runtime API 兼容。TypeScript 类型 rename：RGL.Layout 变為 LayoutItem，RGL.Layout[] 变為 Layout，RGL.Layouts 变為 ResponsiveLayouts，需從 react-grid-layout/legacy 导入新名。

选型表：現有 v1 代码用 legacy；新项目用 v2 hooks；自定义 compaction 用 v2 custom Compactor；SSR 用 v2 measureBeforeMount。CodeSandbox editable demo 链接在 README 顶部，适合在改生產代码前驗證 drag/resize 行為。

import from react-grid-layout/legacy 保 v1 兼容；类型 RGL.Layout 改 LayoutItem。新项目用 v2 hooks；CodeSandbox editable demo 在 README 链接。

npm ls react-grid-layout 确認 2.2.4；legacy 包路径 react-grid-layout/legacy 與主包同版本。drag 時 onLayoutChange 收到新 layout 數组應 immutable 更新 state。responsive breakpoints 默認 lg md sm 可在 gridConfig 覆盖；GridBackground extras 绘制網格線辅助設计态。CHANGELOG v2.2.4 列 bugfix 應讀。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落5专用核對项。）

Responsive、Hooks API 與 Performance

Responsive Usage、Providing Grid Width、Hooks API、API Reference 等章节在 README 目錄列出。v2 把 cols/rowHeight/margin/padding 收進 gridConfig，drag/resize 各自 config，positionStrategy 可选 transform vs absolute positioning。

Performance 與 Architecture maps 章节指向內部設计，大规模 dashboard（數十 widget）應讀 Performance 建议，避免每次 drag 全量 re-render。Extras 含 GridBackground 等可选组件，按需從 react-grid-layout/extras 导入以保持 bundle 小。

gridConfig 含 cols rowHeight margin；positionStrategy 选 transform 或 absolute。Performance 章建议大 dashboard 减 re-render；extras 按需导入。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落6专用核對项。）

CodeSandbox 或本地驗證 v2.2.4 與 legacy

打開 README 链接 CodeSandbox editable demo，或 npm install react-grid-layout@2.2.4 新建 React 项目。v2 路径：復制 useContainerWidth 示例，确認 drag 3px 後才触發 onDragStart；改 layout state 只能通過 onLayoutChange。

若現有项目使用 data-grid 子属性，把 import 改到 react-grid-layout/legacy 跑回归测試。對照 CHANGELOG.md 與 v2.2.4 release，檢查是否影响 Responsive breakpoints 默認值。生產部署前在目標浏览器测 touch drag（若啟用），并固定 package-lock 中 2.x 版本避免 silent major 升級。

react-grid-layout/react-grid-layout 的 v2.2.4 在 npm 與 GitHub release 同步；安装後 import { useContainerWidth } from react-grid-layout 驗證类型导出。legacy 路径下 Responsive 與 WidthProvider 行為與 v1 文檔一致。生產仪表盘應持久化 layout JSON 并在 onLayoutChange 寫回後端。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落7专用核對项。）

Responsive breakpoints 與 layout 序列化

Responsive Usage 章节说明可為 lg/md/sm 提供 ResponsiveLayouts map；v2 类型 ResponsiveLayouts 取代旧 RGL.Layouts。持久化 layout 時應 JSON.stringify layout 數组并校驗每個 LayoutItem 含 i,x,y,w,h；服務端渲染頁面需在 measureBeforeMount 或客户端 mount 後再显示 grid，避免 hydration mismatch。CHANGELOG 與 v2.2.4 release 可能修正 drag handle selector；若用 dragConfig.handle 限定 .handle 类，确保子组件根元素带该类。生產環境 BitMEX 案例说明 RGL 可承载交易 UI 級交互，但仍需自行做 undo/redo 與 layout 版本迁移策略。

Hooks API 中 useGridLayout 與 useResponsiveLayout 可分离 layout state 逻辑；gridConfig.rowHeight 與 margin 影响 compact 算法竖向堆叠。extras 包 fast compactor 為 O(n log n)，默認 verticalCompactor 行為與 v1 verticalCompact 类似。迁移時對照 rfcs/0001 表格：onLayoutChange 是更新 layout 的唯一推荐路径；mutation 会导致 React 18 strict mode 下双重渲染异常。codesandbox demo 链接在 README 顶部 bracket 內。

試装時在 package.json 钉死 react-grid-layout@2.2.4，跑 vite dev 打開含 Grid 的頁面，拖動 item 超過 3px 應触發 onDragStart；layout 數组经 onLayoutChange 寫 console 可见 i,x,y,w,h 更新。

RGL v2 要求 width；legacy 包兼容 data-grid 属性。 （段落8专用核對项。）

在 react-grid-layout 的回歸測試中，還要把 resizeHandles、draggableHandle、isBounded 和 compactType 分別切換。固定同一組 GridItem 後，記錄碰撞前後的 x、y、w、h；若載入 localStorage 的 layout，則比較 JSON 解析前後的 i 值。這些資料才能說明問題來自拖曳規則、容器尺寸或保存格式。

同時核對 width、height 與 containerPadding，避免只檢查座標。

記錄每個 breakpoint 的實際寬度與排序。

確認載入與儲存結果一致。

保留版本記錄。

編輯結論

适合需要仪表盘式可拖拽布局的 React 應用；v1 代码庫可先用 `react-grid-layout/legacy` 零改動导入。驗證時用 CodeSandbox editable demo 或 `npm install react-grid-layout@2.2.4`，确認 useContainerWidth 测得 width 後再 mount GridLayout；若依赖 data-grid 属性，必须走 legacy 包。SSR 场景查 measureBeforeMount 與 v2.2.4 release note。

官方來源

1. Official documentation
2. Official README
3. Project repository
4. Release notes