react-beautiful-dnd innerRef 完全指南让 Draggable 与 Droppable 正确拿到 HTMLElement【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dndinnerRef是 react-beautiful-dnd 中Draggable /与Droppable /暴露给使用者的关键回调属性它负责把组件的真实 DOM 节点交给库引擎。本文以官方指南为主线结合仓库源码与测试用例系统讲解innerRef的用法、常见误区、自定义组件透传方案以及底层校验机制读完即可在自己的项目中正确接入拖拽能力并规避“应用爆炸”式的 ref 陷阱。为什么Draggable和Droppable需要innerRefreact-beautiful-dnd 是一个基于 DOM 测量的拖拽库在拖拽开始前它需要通过getBoundingClientRect()读取被拖拽项与可放置容器的位置、尺寸并据此计算位移与排序。因此Draggable /与Droppable /都必须拿到一个真实的HTMLElement而这个节点正是通过DraggableProvided和DroppableProvided对象上的innerRef属性提供的。如果你还不熟悉 React 的 ref 机制建议先阅读 React 官方文档中的 Refs and the DOM 章节理解 ref 回调的触发时机与节点生命周期后再继续。基本用法将innerRef挂到你的 DOM 节点上最简单、最标准的用法是把provided.innerRef直接作为ref传给渲染函数返回的 JSX 元素ReactElementDraggable draggableIddraggable-1 index{0} {(provided, snapshot) ( div ref{provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps} h4My draggable/h4 /div )} /Draggable;Droppable droppableIddroppable-1 {(provided, snapshot) ( div ref{provided.innerRef} {...provided.droppableProps} h2I am a droppable!/h2 {provided.placeholder} /div )} /Droppable;从源码可以看到innerRef实际就是组件内部维护的一个 ref 写入函数。在 src/view/draggable/draggable.jsx 中Draggable通过useRef保存节点并用useCallback定义了setRef随后在provided对象里暴露innerRef: setRef见 draggable.jsx。Droppable同样以setDroppableRef作为provided.innerRef见 src/view/droppable/droppable.jsx 与 droppable.jsx。当 ref 被正确写入后getRef返回的节点会通过useDraggablePublisher注册进 registry并在每次拖拽开始时用于计算尺寸见 src/view/use-draggable-publisher/use-draggable-publisher.js 与 src/view/use-draggable-publisher/get-dimension.js——尺寸计算依赖getBoundingClientRect()、getComputedStyle()等标准 DOM API这也就解释了为什么节点必须是HTMLElement而不是任意对象。并不是所有的 ref 都“生而平等”很多困惑源于 React 中ref回调在不同目标上的返回值差异当 ref 挂在组件Component上如Person ref{...} /回调收到的是Person组件的实例当 ref 挂在ReactElement上如div ref{...} /回调收到的是该元素对应的HTMLElement。下面的示例直观展示了这两种差异class Person extends React.Component { state { sayHello: false, }; sayHello() { this.setState({ sayHello: true, }); } render() { if (this.state.sayHello) { return div {...this.props}Hello/div; } return div {...this.props}I am a person, I think../div; } } class App extends React.Component { setPersonRef (ref) { this.personRef ref; // 当 ref 变化时它首先会被置为 null if (this.personRef) { // personRef 是 Person 类的实例 this.personRef.sayHello(); } }; setDivRef (ref) { this.divRef ref; if (this.divRef) { // div ref 是 HTMLElement this.divRef.style.backgroundColor lightgreen; } }; render() { return ( React.Fragment Person ref{this.setPersonRef} / div ref{this.setDivRef}hi there/div /React.Fragment ); } }Person实例上没有style、getBoundingClientRect等 DOM 能力而div的回调则能直接操作样式。理解这一点是正确使用innerRef的前提。一个常见的错误把组件实例传给innerRef请看下面这段“看起来没问题”的代码Draggable draggableIddraggable-1 index{0} {(provided, snapshot) ( Person ref{provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps} / )} /Draggable它会让你的应用直接崩溃 原因正如上文所述react-beautiful-dnd期望provided.innerRef收到的是组件的DOM 节点而不是类组件的实例。这里我们传入的是Person的实例底层在调用节点方法、读取节点几何信息时会立即失败。仓库在开发模式下提供了明确的校验来拦截这类错误。看 src/view/check-is-valid-inner-ref.js它断言innerRef收到的必须是一个HTMLElementinvariant( el isHtmlElement(el), provided.innerRef has not been provided with a HTMLElement. ... , );isHtmlElement的实现见 src/view/is-type-of-element/is-html-element.js是对目标元素所在 window 的HTMLElement做instanceof判断export default function isHtmlElement(el: Object): boolean %checks { return el instanceof getWindowFromEl(el).HTMLElement; }Draggable与Droppable会在挂载及更新时通过各自的useValidation见 src/view/draggable/use-validation.js 与 src/view/droppable/use-validation.js调用该校验。对应的测试用例也验证了这一点test/unit/view/droppable/inner-ref-validation.spec.js 确认“未提供 ref”时开发者会收到警告inner-ref-validation.spec.js 确认把SVGElement传给innerRef时会抛出错误。正确姿势为自定义组件暴露一个 DOM ref如果你把拖拽内容封装成了自定义组件一个简单可靠的做法是给组件自定义一个innerRefprop由它在渲染时把这个 prop 挂到组件内部真实的 DOM 元素上class Person extends React.Component { render() { return ( div {...this.props} ref{this.props.innerRef} I am a person, I think.. /div ); } }注意innerRef只是一个约定俗成的名字。你也可以命名为domRef之类的其他名字只要语义清晰即可。然后在Draggable /中把provided.innerRef通过自定义 prop 传入而不是通过refDraggable draggableIddraggable-1 index{0} {(provided, snapshot) ( Person - ref{provided.innerRef} innerRef{provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps} h4My draggable/h4 /Person )} /Draggable关于 styled-components v4 与 emotion v10如果你使用styled-components v4其innerRefprop 已被ref取代——v4 基于 React 16 的forwardRefAPI通过ref回调直接把 DOM 节点透传出来而不是组件实例。emotion v10同样弃用了innerRef推荐使用带forwardRef透传的ref。消除 React 警告避免把全部 props 铺到 DOM 节点上上面“透传innerRefprop”的方案虽然简单但会触发一个React 警告我们通过{...this.props}把组件所有 props 都展开到了 DOM 节点上其中包含innerRef这个自定义 prop——React 不允许你把这种非 DOM 属性添加到元素上。正确的做法是把需要下发的 props 显式解构出来只把真正的 DOM 相关 props 铺到元素上class Person extends React.Component { render() { - return ( - div {...this.props} ref{this.props.innerRef} - I am a person, I think.. - /div - ); } } class Person extends React.Component { render() { const { provided, innerRef } this.props; return ( div {...provided.draggableProps} {...provided.dragHandleProps} ref{innerRef} I am a person, I think.. /div ); } } Draggable draggableIddraggable-1 index{0} {(provided, snapshot) ( Person innerRef{provided.innerRef} - {...provided.draggableProps} - {...provided.dragHandleProps} provided{provided} / )} /Draggable注意这里把provided整体作为 prop 传入由Person自行决定把draggableProps、dragHandleProps铺在哪个节点上。这样既避免了 React 警告又保持了自定义组件对 DOM 结构的完全控制。进阶组件内部也需要 DOM 节点时怎么办如果自定义组件自身也需要使用那个 DOM 节点比如读取自身尺寸、注册事件可以编写一个更强大的 ref 设置函数同时完成两件事把节点保存为自己的实例属性并把它转发给react-beautiful-dndclass Person extends React.Component { setRef (ref) { // 把 dom ref 保存为实例属性 this.ref ref; // 把 dom ref 交给 react-beautiful-dnd this.props.innerRef(ref); }; render() { const { provided, innerRef } this.props; return ( div {...provided.draggableProps} {...provided.dragHandleProps} ref{this.setRef} I am a person, I think.. /div ); } }这样this.ref与库内部的innerRef指向同一个节点组件内外的测量结果保持一致。这也是对库内部setRef模式先写入ref.current、再由getRef读取的一种用户侧复刻。关于 SVG 的重要提示react-beautiful-dnd不支持直接拖拽svg元素SVGElement并不实现HTMLElement且在各浏览器上的焦点管理行为不一致、甚至缺失如 IE11 上调用svgElement.focus()会抛异常这与库“漂亮且无障碍的拖拽”核心价值相悖。如果你需要拖拽 SVG 图形请把svg包进一个HTMLElement如span或div以获得良好的无障碍支持与跨浏览器兼容性// ✅ 支持用 span 包裹 svg并把 innerRef 挂在 span 上 Draggable draggableIdsupported index{0} {(provided) ( span {...provided.draggableProps} {...provided.dragHandleProps} ref{provided.innerRef} svg {/* SVG 内容 */} / /span )} /Draggable更多替代方案img标签、background-image等请参阅仓库中的 dragging SVGs 指南。小结一条铁律回顾整篇指南核心只有一条规则provided.innerRef必须收到一个真实的HTMLElement绝不能是组件实例、SVGElement 或其他任何对象。直接渲染 JSX 元素时把ref{provided.innerRef}挂在元素上即可使用自定义组件时通过自定义 prop如innerRef把 DOM 节点透传出来避免{...this.props}引发的 React 警告若使用 styled-components v4 或 emotion v10优先使用基于forwardRef的ref透传拖拽 SVG 时务必用HTMLElement包裹并参照 dragging SVGs 指南 的推荐方案。仓库在开发模式下内置的checkIsValidInnerRef校验src/view/check-is-valid-inner-ref.js与相关测试test/unit/view/droppable/inner-ref-validation.spec.js会第一时间帮你发现传错 ref 的问题。只要遵循上述模式你就能把任意自定义组件安全地接入 react-beautiful-dnd 的拖拽体系。【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
react-beautiful-dnd innerRef 完全指南：让 Draggable 与 Droppable 正确拿到 HTMLElement
react-beautiful-dnd innerRef 完全指南让 Draggable 与 Droppable 正确拿到 HTMLElement【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dndinnerRef是 react-beautiful-dnd 中Draggable /与Droppable /暴露给使用者的关键回调属性它负责把组件的真实 DOM 节点交给库引擎。本文以官方指南为主线结合仓库源码与测试用例系统讲解innerRef的用法、常见误区、自定义组件透传方案以及底层校验机制读完即可在自己的项目中正确接入拖拽能力并规避“应用爆炸”式的 ref 陷阱。为什么Draggable和Droppable需要innerRefreact-beautiful-dnd 是一个基于 DOM 测量的拖拽库在拖拽开始前它需要通过getBoundingClientRect()读取被拖拽项与可放置容器的位置、尺寸并据此计算位移与排序。因此Draggable /与Droppable /都必须拿到一个真实的HTMLElement而这个节点正是通过DraggableProvided和DroppableProvided对象上的innerRef属性提供的。如果你还不熟悉 React 的 ref 机制建议先阅读 React 官方文档中的 Refs and the DOM 章节理解 ref 回调的触发时机与节点生命周期后再继续。基本用法将innerRef挂到你的 DOM 节点上最简单、最标准的用法是把provided.innerRef直接作为ref传给渲染函数返回的 JSX 元素ReactElementDraggable draggableIddraggable-1 index{0} {(provided, snapshot) ( div ref{provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps} h4My draggable/h4 /div )} /Draggable;Droppable droppableIddroppable-1 {(provided, snapshot) ( div ref{provided.innerRef} {...provided.droppableProps} h2I am a droppable!/h2 {provided.placeholder} /div )} /Droppable;从源码可以看到innerRef实际就是组件内部维护的一个 ref 写入函数。在 src/view/draggable/draggable.jsx 中Draggable通过useRef保存节点并用useCallback定义了setRef随后在provided对象里暴露innerRef: setRef见 draggable.jsx。Droppable同样以setDroppableRef作为provided.innerRef见 src/view/droppable/droppable.jsx 与 droppable.jsx。当 ref 被正确写入后getRef返回的节点会通过useDraggablePublisher注册进 registry并在每次拖拽开始时用于计算尺寸见 src/view/use-draggable-publisher/use-draggable-publisher.js 与 src/view/use-draggable-publisher/get-dimension.js——尺寸计算依赖getBoundingClientRect()、getComputedStyle()等标准 DOM API这也就解释了为什么节点必须是HTMLElement而不是任意对象。并不是所有的 ref 都“生而平等”很多困惑源于 React 中ref回调在不同目标上的返回值差异当 ref 挂在组件Component上如Person ref{...} /回调收到的是Person组件的实例当 ref 挂在ReactElement上如div ref{...} /回调收到的是该元素对应的HTMLElement。下面的示例直观展示了这两种差异class Person extends React.Component { state { sayHello: false, }; sayHello() { this.setState({ sayHello: true, }); } render() { if (this.state.sayHello) { return div {...this.props}Hello/div; } return div {...this.props}I am a person, I think../div; } } class App extends React.Component { setPersonRef (ref) { this.personRef ref; // 当 ref 变化时它首先会被置为 null if (this.personRef) { // personRef 是 Person 类的实例 this.personRef.sayHello(); } }; setDivRef (ref) { this.divRef ref; if (this.divRef) { // div ref 是 HTMLElement this.divRef.style.backgroundColor lightgreen; } }; render() { return ( React.Fragment Person ref{this.setPersonRef} / div ref{this.setDivRef}hi there/div /React.Fragment ); } }Person实例上没有style、getBoundingClientRect等 DOM 能力而div的回调则能直接操作样式。理解这一点是正确使用innerRef的前提。一个常见的错误把组件实例传给innerRef请看下面这段“看起来没问题”的代码Draggable draggableIddraggable-1 index{0} {(provided, snapshot) ( Person ref{provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps} / )} /Draggable它会让你的应用直接崩溃 原因正如上文所述react-beautiful-dnd期望provided.innerRef收到的是组件的DOM 节点而不是类组件的实例。这里我们传入的是Person的实例底层在调用节点方法、读取节点几何信息时会立即失败。仓库在开发模式下提供了明确的校验来拦截这类错误。看 src/view/check-is-valid-inner-ref.js它断言innerRef收到的必须是一个HTMLElementinvariant( el isHtmlElement(el), provided.innerRef has not been provided with a HTMLElement. ... , );isHtmlElement的实现见 src/view/is-type-of-element/is-html-element.js是对目标元素所在 window 的HTMLElement做instanceof判断export default function isHtmlElement(el: Object): boolean %checks { return el instanceof getWindowFromEl(el).HTMLElement; }Draggable与Droppable会在挂载及更新时通过各自的useValidation见 src/view/draggable/use-validation.js 与 src/view/droppable/use-validation.js调用该校验。对应的测试用例也验证了这一点test/unit/view/droppable/inner-ref-validation.spec.js 确认“未提供 ref”时开发者会收到警告inner-ref-validation.spec.js 确认把SVGElement传给innerRef时会抛出错误。正确姿势为自定义组件暴露一个 DOM ref如果你把拖拽内容封装成了自定义组件一个简单可靠的做法是给组件自定义一个innerRefprop由它在渲染时把这个 prop 挂到组件内部真实的 DOM 元素上class Person extends React.Component { render() { return ( div {...this.props} ref{this.props.innerRef} I am a person, I think.. /div ); } }注意innerRef只是一个约定俗成的名字。你也可以命名为domRef之类的其他名字只要语义清晰即可。然后在Draggable /中把provided.innerRef通过自定义 prop 传入而不是通过refDraggable draggableIddraggable-1 index{0} {(provided, snapshot) ( Person - ref{provided.innerRef} innerRef{provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps} h4My draggable/h4 /Person )} /Draggable关于 styled-components v4 与 emotion v10如果你使用styled-components v4其innerRefprop 已被ref取代——v4 基于 React 16 的forwardRefAPI通过ref回调直接把 DOM 节点透传出来而不是组件实例。emotion v10同样弃用了innerRef推荐使用带forwardRef透传的ref。消除 React 警告避免把全部 props 铺到 DOM 节点上上面“透传innerRefprop”的方案虽然简单但会触发一个React 警告我们通过{...this.props}把组件所有 props 都展开到了 DOM 节点上其中包含innerRef这个自定义 prop——React 不允许你把这种非 DOM 属性添加到元素上。正确的做法是把需要下发的 props 显式解构出来只把真正的 DOM 相关 props 铺到元素上class Person extends React.Component { render() { - return ( - div {...this.props} ref{this.props.innerRef} - I am a person, I think.. - /div - ); } } class Person extends React.Component { render() { const { provided, innerRef } this.props; return ( div {...provided.draggableProps} {...provided.dragHandleProps} ref{innerRef} I am a person, I think.. /div ); } } Draggable draggableIddraggable-1 index{0} {(provided, snapshot) ( Person innerRef{provided.innerRef} - {...provided.draggableProps} - {...provided.dragHandleProps} provided{provided} / )} /Draggable注意这里把provided整体作为 prop 传入由Person自行决定把draggableProps、dragHandleProps铺在哪个节点上。这样既避免了 React 警告又保持了自定义组件对 DOM 结构的完全控制。进阶组件内部也需要 DOM 节点时怎么办如果自定义组件自身也需要使用那个 DOM 节点比如读取自身尺寸、注册事件可以编写一个更强大的 ref 设置函数同时完成两件事把节点保存为自己的实例属性并把它转发给react-beautiful-dndclass Person extends React.Component { setRef (ref) { // 把 dom ref 保存为实例属性 this.ref ref; // 把 dom ref 交给 react-beautiful-dnd this.props.innerRef(ref); }; render() { const { provided, innerRef } this.props; return ( div {...provided.draggableProps} {...provided.dragHandleProps} ref{this.setRef} I am a person, I think.. /div ); } }这样this.ref与库内部的innerRef指向同一个节点组件内外的测量结果保持一致。这也是对库内部setRef模式先写入ref.current、再由getRef读取的一种用户侧复刻。关于 SVG 的重要提示react-beautiful-dnd不支持直接拖拽svg元素SVGElement并不实现HTMLElement且在各浏览器上的焦点管理行为不一致、甚至缺失如 IE11 上调用svgElement.focus()会抛异常这与库“漂亮且无障碍的拖拽”核心价值相悖。如果你需要拖拽 SVG 图形请把svg包进一个HTMLElement如span或div以获得良好的无障碍支持与跨浏览器兼容性// ✅ 支持用 span 包裹 svg并把 innerRef 挂在 span 上 Draggable draggableIdsupported index{0} {(provided) ( span {...provided.draggableProps} {...provided.dragHandleProps} ref{provided.innerRef} svg {/* SVG 内容 */} / /span )} /Draggable更多替代方案img标签、background-image等请参阅仓库中的 dragging SVGs 指南。小结一条铁律回顾整篇指南核心只有一条规则provided.innerRef必须收到一个真实的HTMLElement绝不能是组件实例、SVGElement 或其他任何对象。直接渲染 JSX 元素时把ref{provided.innerRef}挂在元素上即可使用自定义组件时通过自定义 prop如innerRef把 DOM 节点透传出来避免{...this.props}引发的 React 警告若使用 styled-components v4 或 emotion v10优先使用基于forwardRef的ref透传拖拽 SVG 时务必用HTMLElement包裹并参照 dragging SVGs 指南 的推荐方案。仓库在开发模式下内置的checkIsValidInnerRef校验src/view/check-is-valid-inner-ref.js与相关测试test/unit/view/droppable/inner-ref-validation.spec.js会第一时间帮你发现传错 ref 的问题。只要遵循上述模式你就能把任意自定义组件安全地接入 react-beautiful-dnd 的拖拽体系。【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
