前端UI组件【免费下载链接】react-dndDrag and Drop for React项目地址https://gitcode.com/gh_mirrors/re/react-dnd点击查看免费下载React DnD 的示例集中提供了一组回归示例regression examples用于验证历史 bug 已被修复。其中chained-connectors链式连接器示例演示了如何将useDrag返回的多个连接器与useDrop返回的连接器嵌套链式调用在同一个元素上实现既是拖拽源、又是放置目标还能指定拖拽手柄的组合场景。本文以该示例为核心逐行解读其源码实现并深入wrapConnectorHooks与SourceConnector的底层机制说明连接器为什么可以被链式嵌套、被包裹元素的内部 ref 如何共存。一、示例背景链式连接器与回归测试示例文档 chained-connectors.md 指出该示例是PR #1465 的回归示例用于验证连接器函数可以链式组合这一能力在后续版本迭代中没有回归。回归示例regression example在 React DnD 项目中承担着双重职责功能演示向开发者展示一种真实、常见的组合用法回归防护通过 packages/examples/src/07-regression/ 下的集成测试防止历史修复被再次破坏。与之同目录的还有drag-source-rerender拖拽源重渲染、previews-memory-leak预览内存泄漏、remount-with-correct-props重挂载携带正确 props等回归示例共同覆盖了 React DnD 历史上容易出现问题的几个角落。二、示例整体结构chained-connectors示例位于 packages/examples/src/07-regression/chained-connectors/共 4 个文件文件职责ItemTypes.ts定义拖拽类型常量BOX: boxBoxWithHandle.tsx核心组件同时注册拖拽源与放置目标并链式组合三个连接器Container.tsx外层容器渲染BoxWithHandleindex.ts将Container作为默认导出供示例路由加载ItemTypes.ts十分简单定义了唯一一个类型常量export const ItemTypes { BOX: box, }Container.tsx只负责以 400px 宽度的容器包裹BoxWithHandle本身不包含任何拖拽逻辑export const Container: FC () { return ( div style{style} BoxWithHandle / /div ) }三、核心示例逐行解析BoxWithHandleBoxWithHandle是链式连接器的典型实现完整源码如下BoxWithHandle.tsximport type { CSSProperties, FC } from react import { useDrag, useDrop } from react-dnd import { ItemTypes } from ./ItemTypes.js const style: CSSProperties { border: 1px dashed gray, padding: 0.5rem 1rem, marginBottom: .5rem, backgroundColor: white, width: 20rem, } const handleStyle: CSSProperties { backgroundColor: green, width: 1rem, height: 1rem, display: inline-block, marginRight: 0.75rem, cursor: move, } export const BoxWithHandle: FC () { const [, drop] useDrop(() ({ accept: ItemTypes.BOX, })) const [{ isDragging }, drag, preview] useDrag(() ({ type: ItemTypes.BOX, collect: (monitor) ({ isDragging: monitor.isDragging(), }), })) const opacity isDragging ? 0.4 : 1 return drop( preview( div style{{ ...style, opacity }} {drag(div style{handleStyle} /)} Drag me by the handle, the whole box should drag /div, ), ) }3.1 同时注册放置目标与拖拽源组件顶部同时调用了两个 hooksconst [, drop] useDrop(() ({ accept: ItemTypes.BOX, })) const [{ isDragging }, drag, preview] useDrag(() ({ type: ItemTypes.BOX, collect: (monitor) ({ isDragging: monitor.isDragging(), }), }))useDrop声明该组件接受类型为BOX的放置返回的drop是放置目标连接器useDrag声明该组件是BOX类型的拖拽源返回三元组collect收集的状态isDragging、拖拽源连接器drag、拖拽预览连接器preview。注意useDrop的返回值中第一个元素被跳过[, drop]因为本例不需要读取放置状态。useDrag的collect通过monitor.isDragging()获取实时拖拽状态并据此在渲染时把盒子整体透明度降为0.4给用户明确的正在拖拽反馈const opacity isDragging ? 0.4 : 13.2 三连接器链式嵌套drop(preview(div))示例最核心的一行是渲染部分的链式调用return drop( preview( div style{{ ...style, opacity }} {drag(div style{handleStyle} /)} Drag me by the handle, the whole box should drag /div, ), )这里同时出现了三种不同的连接器用法drag(div style{handleStyle} /)drag连接器接收一个React 元素将它克隆并注入 ref让绿色的 1rem 小方块成为实际的拖拽手柄handlepreview(div)preview连接器接收外层盒子元素将其挂接为拖拽预览拖拽时跟随鼠标的半透明图层drop(preview(...))drop连接器再包裹最外层把整个盒子注册为放置目标。三个连接器从内到外依次作用于不同粒度手柄负责发起拖拽、盒子负责预览、最外层负责接收放置。整条调用链形成了drop(preview(drag-box))的嵌套结构这正是链式连接器名称的由来。3.3 界面效果与用户提示盒子的border: 1px dashed gray表明它同时是一个可接收拖拽的放置区域绿色手柄的cursor: move提示用户可拖拽文案 Drag me by the handle, the whole box should drag 直接点明了本示例的行为契约只有拖动手柄整个盒子而非手柄本身跟随拖拽。四、连接器为什么能被链式调用wrapConnectorHooks 源码解析要理解链式调用的可行性需要看连接器函数从哪来。在 packages/react-dnd/src/hooks/useDrag/connectors.ts 中drag与preview连接器分别来自SourceConnector的 hooksexport function useConnectDragSource(connector: SourceConnector) { return useMemo(() connector.hooks.dragSource(), [connector]) } export function useConnectDragPreview(connector: SourceConnector) { return useMemo(() connector.hooks.dragPreview(), [connector]) }而connector.hooks中的这些函数统一由 packages/react-dnd/src/internals/wrapConnectorHooks.ts 的wrapConnectorHooks加工生成export function wrapConnectorHooks(hooks: any) { const wrappedHooks: any {} Object.keys(hooks).forEach((key) { const hook hooks[key] // ref objects should be passed straight through without wrapping if (key.endsWith(Ref)) { wrappedHooks[key] hooks[key] } else { const wrappedHook wrapHookToRecognizeElement(hook) wrappedHooks[key] () wrappedHook } }) return wrappedHooks }每个非Ref结尾的连接器钩子都经过wrapHookToRecognizeElement包装该函数定义了连接器的两种入参形态function wrapHookToRecognizeElement(hook: (node: any, options: any) void) { return (elementOrNode null, options null) { // When passed a node, call the hook straight away. if (!isValidElement(elementOrNode)) { const node elementOrNode hook(node, options) // return the node so it can be chained (e.g. when within callback refs // div ref{node connectDragSource(connectDropTarget(node))}/ return node } // If passed a ReactElement, clone it and attach this function as a ref. const element: ReactElement | null elementOrNode throwIfCompositeComponentElement(element as any) const ref options ? (node: Element) hook(node, options) : hook return cloneWithRef(element, ref) } }两种形态分别对应链式组合的两种经典写法形态一传入 DOM 节点ref 回调内链式当传入的不是 React 元素而是真实 DOM 节点时连接器立即执行挂接并返回该节点。正因为返回值是节点本身才支持在 ref 回调里写这种形式div ref{(node) connectDragSource(connectDropTarget(node))} /源码注释中明确给出了这一用例return node就是为链式而设计的。形态二传入 React 元素克隆并注入 ref当传入 React 元素时连接器会调用throwIfCompositeComponentElement校验只允许原生 DOM 元素如div、span被直接连接自定义组件必须先用div包裹或自身成为拖拽源/放置目标详见下文第五节通过cloneWithRef克隆该元素并把连接器函数作为新 ref 注入。cloneWithRef的关键逻辑是ref 合并wrapConnectorHooks.tsfunction cloneWithRef(element: any, newRef: any): ReactElementany { const previousRef element.ref invariant( typeof previousRef ! string, Cannot connect React DnD to an element with an existing string ref. ..., ) if (!previousRef) { // When there is no ref on the element, use the new ref directly return cloneElement(element, { ref: newRef, }) } else { return cloneElement(element, { ref: (node: any) { setRef(previousRef, node) setRef(newRef, node) }, }) } }若元素原本没有 ref直接把连接器作为 ref 注入若元素已有 ref则生成一个组合 ref在节点挂载时同时调用原 ref 与新 ref从而不覆盖使用方已有的 ref。这是链式 用户自定义 ref 共存的底层保证例如preview(div)中的div若自带 ref克隆后两个 ref 都会执行。组合 ref 与链式的完整图景综合来看示例中的链式调用在底层发生了这些事drag(div style{handleStyle} /)克隆手柄元素并注入拖拽源 refDragSourceConnector通过receiveHandlerId等注册——即useDrag的dragSource钩子preview(div)克隆盒子元素并注入拖拽预览 refdragPreview钩子指定拖拽预览层drop(...)克隆经preview处理后的元素并注入放置目标 ref。最终 React 渲染时三个 ref 依次被调用同一棵 DOM 树的不同节点分别被注册为拖拽源、拖拽预览与放置目标。五、一个关键的边界为什么只能连接原生 DOM 元素wrapHookToRecognizeElement在克隆元素前会先调用校验函数function throwIfCompositeComponentElement(element: ReactElementany) { if (typeof element.type string) { return } const displayName (element.type as any).displayName || element.type.name || the component throw new Error( Only native element nodes can now be passed to React DnD connectors.You can either wrap ${displayName} into a div, or turn it into a drag source or a drop target itself., ) }源码注释解释了原因React DnD 2.0 起不再依赖react-dom的findDOMNode()因此无法在自定义组件上直接注入 DOM ref。如果向连接器传入自定义组件element.type不是字符串会直接抛出错误并给出两条迁移建议用div等原生元素把它包裹起来再连接让该组件自己成为拖拽源或放置目标。这解释了为什么所有 React DnD 示例都只对div、span等原生元素调用连接器——BoxWithHandle中drag、preview、drop三个连接器接收的都是原生div元素。这也是连接器 API 从旧版依赖findDOMNode演进到新版后的重要行为约束。六、链式连接器的其他应用场景对比chained-connectors并非唯一使用连接器组合的示例。在 packages/examples/src/05-customize/handles-and-previews/BoxWithHandle.tsx 中useDrag的返回结构同样是[{ isDragging }, drag, preview]也采用手柄元素交给drag、盒子交给preview的写法。区别在于handles-and-previews属于功能定制类示例重点演示手柄handle与预览preview的定制chained-connectors属于回归类示例重点验证drag/preview/drop三者叠加在同一组件上时连接器仍能正确工作——特别是drop连接器接收另一个连接器返回的 React 元素这一嵌套形态。换句话说chained-connectors验证的是连接器 API 的可组合性契约连接器既可以接收 DOM 节点返回节点便于 ref 内链式也可以接收 React 元素克隆并注入 ref返回值仍可继续传给外层连接器。这种对称设计让drop(preview(div/))这样的表达式得以成立。七、如何运行与验证本示例位于 monorepo 的packages/examples包内可通过 docsite 的示例页面直接预览文档 frontmatter 中的path: /examples/regression/chained-connectors即其路由。相关验证手段包括手动验证渲染BoxWithHandle仅拖动绿色手柄观察整个盒子含文字区域是否跟随移动且拖拽时盒子透明度变为 0.4将盒子拖到自身区域时由于它也是BOX类型的放置目标放置行为应正常注册。集成测试React DnD 仓库的packages/examples下为多类示例提供了集成测试如 packages/examples/src/01-dustbin/single-target/tests/single-target-integration.spec.tsx 等通过react-dnd/testing-library与测试后端packages/backend-test/src/TestBackend.ts模拟拖拽事件回归类示例同样可在此基础上扩展断言防止连接器链式行为回归。八、总结chained-connectors回归示例用 40 余行代码浓缩了 React DnD 连接器机制的三个核心知识点连接器的双重形态传入 DOM 节点则立即挂接并返回节点便于 ref 回调内链式传入原生 React 元素则克隆注入 ref链式组合的成立条件drop(preview(drag-box))之所以可行是因为连接器处理元素后返回的是新元素可继续作为外层连接器的输入ref 合并与原生元素约束cloneWithRef保证既有 ref 不被覆盖throwIfCompositeComponentElement强制连接器只能用于原生 DOM 元素。对使用 React DnD 的开发者而言本文的示例代码可作为同时拖拽 放置 手柄 预览组合场景的最小参考实现而wrapConnectorHooks.ts的源码则是理解连接器一切组合能力的底层钥匙。赞分享前端UI组件【免费下载链接】react-dndDrag and Drop for React项目地址https://gitcode.com/gh_mirrors/re/react-dnd点击查看免费下载相关推荐揭秘二进制补丁技术深度解析RevokeMsgPatcher防撤回实战揭秘二进制补丁技术深度解析RevokeMsgPatcher防撤回实战 在即时通讯日益普及的今天对方已撤回一条消息的提示已成为信息留存的最大挑战。Revo数据目录数据血缘数据治理后端MCP 服务React DnD连接器系统深入理解Source和Target连接器React DnD连接器系统深入理解Source和Target连接器 React DnD是现代React应用中实现拖放功能的强大库其核心连接器系统是构建复杂前端UI组件Pathway SharePoint 连接器连通性测试示例sharepoint-test 的运行、配置与底层原理Pathway SharePoint 连接器连通性测试示例sharepoint test 的运行、配置与底层原理 导读 sharepoint test 是 P后端流处理实时分析数据工程人工智能RAG上一篇copyparty线程池工作线程池与任务调度下一篇Video2X终极指南免费开源视频超分辨率与帧插值完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
