react-grid-layout v2 重写：从 jQuery 时代到 TypeScript 钩子，迁移前先看这几点
用于 React 的可拖动且可调整大小的网格布局，带有响应断点。
秒懂
- 它是什么？
- react-grid-layout 是 React 生态里历史悠久的拖拽网格库，v2 用 TypeScript 重写并引入 Hooks 与可插拔压缩算法。本文基于 README 与 RFC 材料，梳理它的核心机制、迁移成本与适用边界。
- 适合谁用？
- 新项目且团队已用 TypeScript 的，值得直接上 v2 API，它能拿到树摇优化和 Hooks 的简洁写法。存量 v1 代码库，别急着全面迁移，先用 react-grid-layout/legacy 保持运行，再逐个页面切换，因为 v2 的 width prop 必填和回调不可变是破坏性变更，涉及拖动逻辑的地方要重新验证。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 15 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题，谁该用
react-grid-layout 解决的是 React 应用里「网格拖拽与缩放」这个具体问题。它不像 CSS Grid 那样只负责静态排版，而是让你用鼠标把卡片拖到任意位置，拖拽后自动压缩空白，还支持响应式断点。目标用户是仪表盘、后台管理面板、可视化编辑器这类需要用户自定义布局的产品。它明确不依赖 jQuery，这点对现代 React 项目很关键。如果你只是要一个静态响应式网格，CSS Grid 就够，这个库反而重。
v2 重写的核心变化：从扁平 props 到组合配置
v2 是完整的 TypeScript 重写，API 从 v1 的扁平 props 改为组合式配置。原来所有选项堆在组件上，现在分组为 gridConfig、dragConfig、resizeConfig、compactor 等接口。例如 gridConfig 管 cols、rowHeight、margin、padding，dragConfig 管 enable、handle、cancel。这种设计让配置意图更清晰，也方便按需导入。但代价是迁移时你得重新组织所有 props，不是简单改个名字。README 里给了 legacy 包装器，import 从 'react-grid-layout' 换成 'react-grid-layout/legacy' 就能获得 100% 的 v1 运行时兼容，这算是给存量项目的安全通道。
数据流与布局机制：width 是硬前提
v2 里 width prop 变成必填，这是最大的破坏性变更。它不像 v1 有 WidthProvider 自动测量，现在你得自己用 useContainerWidth 钩子拿容器宽度，或者自己量。useContainerWidth 返回 width、containerRef、mounted 三个值，典型用法是挂 ref 到容器 div，mounted 为 true 时才渲染网格。这个设计把测量责任推给用户，换来了更可控的渲染时机，但如果你忘了处理 mounted，首屏会空白。布局数据本身是 LayoutItem 数组，每个项有 i、x、y、w、h，v2 要求显式传 layout prop，v1 的 data-grid 属性只在 legacy 包装器里可用。这意味着 v2 的布局必须由父组件管理，不能靠子组件自描述。
Hooks API 与性能考量
v2 引入了三个 Hooks：useContainerWidth、useGridLayout、useResponsiveLayout。useContainerWidth 解决测量，useResponsiveLayout 处理断点映射，useGridLayout 封装核心布局计算。配合可选的 positionStrategy（transform 或 absolute），你能选择用 transform 定位来减少重排，还是用 absolute 兼容老浏览器。性能方面，README 提到可选的 O(n log n) 快速压缩算法在 /extras 里，默认的垂直压缩是 O(n^2) 级别。如果你的网格有几十上百个卡片，默认算法可能卡顿，换成 fast 算法是具体优化手段。但注意，快速算法是额外导入的，不是默认行为，你得自己评估布局规模再决定。
可插拔压缩器：自定义布局策略的入口
v2 把压缩逻辑抽象成 Compactor 接口，你可以传 verticalCompactor、horizontalCompactor，或者自己写。v1 的 verticalCompact 布尔值被删了，想关掉压缩得用 compactType={null} 或 compactor={noCompactor}。这个设计让布局规则不再是黑盒，比如你可以实现一个「保持原始间距」的压缩器，或者按优先级排序的算法。但代价是，如果你需要自定义，你得理解布局算法的输入输出，README 没给详细接口签名，得去 RFC 或源码里查。对于大多数用户，默认垂直压缩够用，自定义是少数高级场景。
迁移路径：legacy 包装器与类型变化
迁移有两条路。快速路线是换 import 到 legacy，运行时行为不变，但类型要手动改：RGL.Layout 变 LayoutItem，RGL.Layouts 变 ResponsiveLayouts。完整路线是重写为 v2 API，能拿到树摇和 Hooks，但工作量更大。README 明确建议：存量 v1 代码用 legacy，新项目用 v2。这个建议很务实，因为 v2 的破坏性变更不止 width，还有 onDragStart 现在要移动 3px 才触发，不再响应 mousedown。如果你的界面依赖点击即触发拖拽逻辑，这个变化会直接破坏交互。另外回调参数变成只读，你不能在回调里改 layout，得用 onLayoutChange 或约束。这些细节在 RFC 里有例子，迁移前必须逐条过。
局限与适用边界：什么时候别用它
这个库不是万能的。首先，它只处理网格布局，不包含虚拟滚动，卡片数量上千时，DOM 节点数会拖垮性能，即使有快速压缩算法也救不了渲染开销。其次，v2 移除了 UMD 包，意味着你不能在无打包器的环境里用 script 标签引入，这对老项目是硬门槛。再者，拖拽体验依赖鼠标事件，触屏设备支持没有在 README 里明确承诺，如果你要纯移动端优先，得自己验证。最后，响应式断点布局需要你提供每个断点的 layout，或者让库自动生成，但自动生成的结果可能不符合你的设计意图，最好手动配置。如果你的需求是「固定行列的简单拖拽」，这个库的复杂度是过度的。
替代方案与维护成本
同类库有 Packery 和 Gridster，但 react-grid-layout 明确区分了自己：它们不响应式，不支持断点。更现代的替代是 react-mosaic 或 dnd-kit 配合自定义布局，但那些需要你实现拖拽后的位置计算。react-grid-layout 的价值在于把拖拽、缩放、压缩、响应式打包成一套 API。维护方面，项目在 2026 年 7 月还有 v2.2.4 发布，说明活跃。MIT 许可意味着你可以自由商用，但注意 v2 的模块化架构下，你引入的子路径（如 /core、/extras）在升级时可能变动，因为它们是新结构，还没经过长时间稳定。升级成本主要在 v1 到 v2，一旦上了 v2，后续小版本应该平滑。
编辑结论
新项目且团队已用 TypeScript 的，值得直接上 v2 API，它能拿到树摇优化和 Hooks 的简洁写法。存量 v1 代码库，别急着全面迁移，先用 react-grid-layout/legacy 保持运行，再逐个页面切换，因为 v2 的 width prop 必填和回调不可变是破坏性变更，涉及拖动逻辑的地方要重新验证。需要自定义压缩策略的，v2 的 Compactor 接口是唯一出路，但你要接受自己写算法和测试。SSR 场景必须用 measureBeforeMount: true，否则首屏会闪。最后，UMD 没了，如果你的构建流程还依赖 script 标签直接引入，先换打包器再说。验证顺序：先跑一遍官方 CodeSandbox demo，再在你的真实布局数据上测拖拽和断点切换，最后检查所有 onDragStart 回调是否依赖旧的 mousedown 触发时机。
社区笔记