前端UI组件【免费下载链接】react-dndDrag and Drop for React项目地址https://gitcode.com/gh_mirrors/re/react-dnd点击查看免费下载DragPreviewImage 是 react-dnd 提供的一个轻量级辅助组件用于将一张 HTMLimg图片渲染为浏览器拖拽过程中的游离式disconnected拖拽预览替代默认的源节点截图。本文将以 packages/docsite/markdown/docs/01 Common Components/DragPreviewImage.md 为骨架结合 组件源码、连接器类型定义、预览选项类型 与 组件测试 及仓库内置示例帮助你彻底掌握该组件的用法、原理与最佳实践。组件是什么为什么需要游离式拖拽预览默认情况下浏览器在拖拽时会自动对源 DOM 节点进行截图作为拖拽预览drag preview。但默认截图存在两个明显问题视觉失真截图发生在拖拽开始后的一帧内若此时源节点正处于半透明、缩小等拖拽中样式预览会带着这些样式一起被拍进去无法自定义浏览器原生 API 在拖拽开始后无法再更换预览内容你无法自由指定拖拽时应该显示哪张图。DragPreviewImage 正是为第二个问题而生的解决方案它会在组件内部创建一个独立的HTMLImageElement等图片资源加载完成后把该图片实例通过connectdrag preview 连接器交给 react-dnd使拖拽预览与源 DOM 节点完全解耦。原文档对它的描述是A Component to render an HTML Image element as a disconnected drag preview.即渲染一个 HTML Image 元素作为游离的拖拽预览。基本用法经典写法DragSource高阶组件 DragPreviewImage原文档给出了最典型的组合用法通过DragSource的collect拿到connectDragPreview再把DragPreviewImage放进渲染树中与之相连import { DragSource, DragPreviewImage } from react-dnd function DraggableHouse({ connectDragSource, connectDragPreview }) { return ( DragPreviewImage srchouse_dragged.png connect{connectDragPreview} / div ref{connectDragSource}/div / ) } export default DragSource( /* ... */ (connect, monitor) ({ connectDragSource: connect.dragSource(), connectDragPreview: connect.dragPreview() }) )要点拆解connectDragSource绑到实际可拖拽的 DOM 节点上connectDragPreview不绑任何 DOM 节点而是传给DragPreviewImage的connectpropDragPreviewImage自身不渲染任何可见 DOM源码中它始终return null它只是一个图片加载 连接的调度器它必须与可拖拽组件同时渲染通常放在同一个 fragment 中这样才能在拖拽发生时把预览连接好。Hooks 写法useDrag现代 react-dnd 推荐使用 Hooks。仓库内置示例 packages/examples/src/05-customize/handles-and-previews/BoxWithImage.tsx 展示了完整的 Hooks 用法import type { CSSProperties, FC } from react import { DragPreviewImage, useDrag } from react-dnd import { boxImage } from ./boxImage.js import { ItemTypes } from ./ItemTypes.js const style: CSSProperties { border: 1px dashed gray, padding: 0.5rem 1rem, marginBottom: .5rem, backgroundColor: white, cursor: move, width: 20rem, } export const BoxWithImage: FC () { const [{ opacity }, drag, preview] useDrag(() ({ type: ItemTypes.BOX, collect: (monitor) ({ opacity: monitor.isDragging() ? 0.4 : 1, }), })) return ( DragPreviewImage connect{preview} src{boxImage} / div ref{drag} style{{ ...style, opacity }} Drag me to see an image /div / ) }useDrag返回数组的第三个元素preview就是 drag preview 连接器直接传给DragPreviewImage即可。国际象棋示例 packages/examples/src/00-chessboard/Knight.tsx 也是同样的模式该示例将马头图片knightImage用作拖拽预览。回归测试示例 packages/examples/src/07-regression/previews-memory-leak/BoxWithImage.tsx 亦复如此说明该模式在仓库中是被反复使用、经过回归验证的推荐范式。Props原文档列出的 Props 只有两个全部为必填Prop类型是否必填说明connectConnectDragPreview必填drag preview 连接器函数来源于connect.dragPreview()经典写法或useDrag返回的第三个元素Hooks 写法srcstring必填预览图片的 URL支持相对路径、绝对路径以及 data URI其中ConnectDragPreview在 packages/react-dnd/src/types/connectors.ts 中的定义是export type ConnectDragPreview DragElementWrapperDragPreviewOptions即它接受一个可选参数对象DragPreviewOptions详见下文预览选项一节并在内部返回ReactElement | null。这也解释了为什么preview连接器可以直接传给connectpropDragPreviewImage 只是把整个连接器原样转交。源码原理一张图片如何变成拖拽预览组件源码位于 packages/react-dnd/src/core/DragPreviewImage.ts全部逻辑只有约 30 行核心机制如下export const DragPreviewImage: FCDragPreviewImageProps memo( function DragPreviewImage({ connect, src }) { useEffect(() { if (typeof Image undefined) return let connected false const img new Image() img.src src img.onload () { connect(img) connected true } return () { if (connected) { connect(null) } } }) return null }, )逐段解读memo包裹组件用React.memo缓存只有在connect或src引用变化时才重新渲染避免无谓的重渲染开销。SSR 安全if (typeof Image undefined) return——在服务端渲染SSR环境没有Image构造器时直接跳过保证组件不会在服务端崩溃该组件渲染结果恒为null本就无 DOM 可输出。动态创建图片每次 effect 执行时新建new Image()并设置src注意这里没有设置img.width/img.height或alt——因为它不参与页面布局只是作为一个已加载的图片对象交给浏览器后端绘制。加载完成后再连接img.onload中才调用connect(img)确保 react-dnd 拿到的是一张已加载完毕的图片。这是因为浏览器拖拽预览需要直接读取图片位图数据未加载完成的图片会被视为无效。这也是原文档与示例中反复强调等它加载后的原因docsite 示例文档 handles-and-previews.md 同样提到一旦加载完成你可以使用程序化创建的 Image 实例。connected标志用一个局部布尔变量标记是否已经连接成功。清理函数当组件卸载或src/connect变化导致 effect 重新执行时若此前已连接成功则调用connect(null)撤销连接把预览恢复为空。这保证了内存与预览状态的正确回收——仓库中 07-regression/previews-memory-leak 这一回归示例正是围绕预览/连接器的内存泄漏问题建立的。没有依赖数组effect 未指定依赖数组因此每次渲染后都会执行清理与重连。这是有意为之的简单策略——组件本身就应保持跟随每次渲染重新同步连接的行为。测试文件 packages/react-dnd/src/core/tests/DragPreviewImage.spec.tsx 使用TestBackend与useDrag验证了组件在DndProvider内能够正常渲染并把预览连接器接入测试中通过包装preview连接器connectPreview记录调用并注释指出验证图片确实被创建在当前测试框架下难以断言从侧面印证了该组件本质上是图片加载的异步副作用其正确性更多由onload时序与连接器协议保证。预览选项DragPreviewOptions控制预览的位置与截图时机虽然DragPreviewImage自身只有connect和src两个 prop但通过connect传入的连接器在调用时可以携带DragPreviewOptions。完整定义见 packages/react-dnd/src/types/options.ts选项类型默认值作用captureDraggingStatebooleanfalse为true时拖拽开始当帧就立即让组件感知到正在拖拽截图会带上monitor.isDragging()为真的样式如半透明。默认false更稳妥因为大多数情况下不希望截图里带着拖拽中的样式。仅少数场景需要开启例如在 IE 下想让自定义 DragLayer 生效且不得不用空预览时anchorXnumber0~10.5当预览尺寸与源节点尺寸不一致时水平方向的对齐方式0靠左、0.5线性插值、1靠右anchorYnumber0~10.5同上垂直方向0靠上、0.5居中插值、1靠下offsetXnumber \| nullnull预览相对光标的水平偏移像素值一旦设置anchorX失效offsetYnumber \| nullnull预览相对光标的垂直偏移像素值一旦设置anchorY失效典型的自定义预览锚点调用形如connectDragPreview(null, { offsetX: -8, offsetY: -8 }) // 或 connectDragPreview(null, { anchorX: 0, anchorY: 0 })在DragPreviewImage场景中这些选项通常不直接传给组件组件内部调用connect(img)时不带选项但如果你希望图片预览在光标右下/左下等位置出现可以像上面的写法一样自行包装连接器。相关实践空预览与自定义 DragLayer理解 DragPreviewImage 后还应了解它的两个近亲1. 空图片预览getEmptyImage有时我们不想要任何预览图片而是配合自定义DragLayer完全手绘拖拽反馈例如实现吸附网格、边界检查等复杂交互。此时可以使用 packages/backend-html5/src/getEmptyImage.ts 提供的getEmptyImage()——它返回一个 1×1 透明 GIF 的HTMLImageElement通过preview(getEmptyImage(), { captureDraggingState: true })方式隐藏默认预览。这比DragPreviewImage更进一步前者是用我的图片当预览后者是不用预览、完全自定义。docsite 的 custom-drag-layer.md 详细说明了该思路的取舍换来极大的自定义灵活度和零闪烁代价是失去默认的拖出容器后回弹动画。2. 默认浏览器截图naive 方式如果不设置任何预览浏览器会使用源节点截图作为预览。naive.md 指出这种方式在简单场景可用但放下时会明显闪烁。DragPreviewImage 正是规避这种闪烁、同时保留真实图片预览能力的最轻量手段。常见坑与注意事项务必在可拖拽组件内渲染DragPreviewImage必须在产生preview/connectDragPreview连接器的组件渲染树中且与之同时挂载否则拖拽开始时连接器尚未就绪。图片要能被加载src指向的资源必须可访问且能正确解码如示例中的boxImage、knightImage均为 base64 data URI 导入见 packages/examples/src/05-customize/handles-and-previews/boxImage.ts 与 packages/examples/src/00-chessboard/knightImage.ts加载失败时onload不会触发预览也就不会建立。非 SSR 环境依赖组件源码在Image不存在时静默返回null服务端渲染下它不会报错但也自然不会产生任何连接行为。卸载/换图时自动断开effect 清理逻辑会调用connect(null)因此无需手动管理连接器的释放这也正是 07-regression/previews-memory-leak 回归用例要守护的行为。小结DragPreviewImage 用约 30 行代码解决了自定义拖拽预览图片这一高频需求以memouseEffect管理图片的异步加载与连接器生命周期以connect(img)完成图片到 react-dnd 拖拽系统的接入并在卸载时以connect(null)干净地回收。配合useDrag的preview返回值或DragSource的connect.dragPreview()你可以在几行代码内把默认的节点截图替换为任意定制图片为拖拽体验提供更专业的视觉反馈。延伸阅读组件实现packages/react-dnd/src/core/DragPreviewImage.ts连接器类型packages/react-dnd/src/types/connectors.ts 与预览选项 packages/react-dnd/src/types/options.ts组件测试packages/react-dnd/src/core/tests/DragPreviewImage.spec.tsx完整示例Handles and PreviewsBoxWithImage.tsx、ChessboardKnight.tsx、Previews Memory LeakBoxWithImage.tsx相关文档自定义拖拽层 custom-drag-layer.md、native 拖拽 naive.md、空预览实现 getEmptyImage.ts赞分享前端UI组件【免费下载链接】react-dndDrag and Drop for React项目地址https://gitcode.com/gh_mirrors/re/react-dnd点击查看免费下载相关推荐React DnD拖拽层终极指南如何创建自定义拖拽预览组件React DnD拖拽层终极指南如何创建自定义拖拽预览组件 想要让你的React应用拥有专业级的拖拽体验吗自定义拖拽预览组件是实现这一目标的关键技术本文将前端UI组件用 react-dnd 构建国际象棋棋盘教程从零实现拖拽棋子与自定义拖拽预览用 react dnd 构建国际象棋棋盘教程从零实现拖拽棋子与自定义拖拽预览 本篇技术指南围绕 react dnd 官方教程中的“孤独骑士Lonely Kn前端UI组件一劳永逸uBlock Origin 安装配置全攻略10分钟拦截广告与跟踪器网页提速看得见一劳永逸uBlock Origin 安装配置全攻略10分钟拦截广告与跟踪器网页提速看得见 深夜刷剧正到关键时刻突然跳出全屏广告打开新闻网站页面来回跳网络安全应用安全上一篇终极指南daedalOS中的Web Workers错误处理策略确保多线程稳定性下一篇Fay数字人框架部署教程本地与云端方案对比创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
react-dnd 之 DragPreviewImage：用 HTML Image 实现自定义拖拽预览
前端UI组件【免费下载链接】react-dndDrag and Drop for React项目地址https://gitcode.com/gh_mirrors/re/react-dnd点击查看免费下载DragPreviewImage 是 react-dnd 提供的一个轻量级辅助组件用于将一张 HTMLimg图片渲染为浏览器拖拽过程中的游离式disconnected拖拽预览替代默认的源节点截图。本文将以 packages/docsite/markdown/docs/01 Common Components/DragPreviewImage.md 为骨架结合 组件源码、连接器类型定义、预览选项类型 与 组件测试 及仓库内置示例帮助你彻底掌握该组件的用法、原理与最佳实践。组件是什么为什么需要游离式拖拽预览默认情况下浏览器在拖拽时会自动对源 DOM 节点进行截图作为拖拽预览drag preview。但默认截图存在两个明显问题视觉失真截图发生在拖拽开始后的一帧内若此时源节点正处于半透明、缩小等拖拽中样式预览会带着这些样式一起被拍进去无法自定义浏览器原生 API 在拖拽开始后无法再更换预览内容你无法自由指定拖拽时应该显示哪张图。DragPreviewImage 正是为第二个问题而生的解决方案它会在组件内部创建一个独立的HTMLImageElement等图片资源加载完成后把该图片实例通过connectdrag preview 连接器交给 react-dnd使拖拽预览与源 DOM 节点完全解耦。原文档对它的描述是A Component to render an HTML Image element as a disconnected drag preview.即渲染一个 HTML Image 元素作为游离的拖拽预览。基本用法经典写法DragSource高阶组件 DragPreviewImage原文档给出了最典型的组合用法通过DragSource的collect拿到connectDragPreview再把DragPreviewImage放进渲染树中与之相连import { DragSource, DragPreviewImage } from react-dnd function DraggableHouse({ connectDragSource, connectDragPreview }) { return ( DragPreviewImage srchouse_dragged.png connect{connectDragPreview} / div ref{connectDragSource}/div / ) } export default DragSource( /* ... */ (connect, monitor) ({ connectDragSource: connect.dragSource(), connectDragPreview: connect.dragPreview() }) )要点拆解connectDragSource绑到实际可拖拽的 DOM 节点上connectDragPreview不绑任何 DOM 节点而是传给DragPreviewImage的connectpropDragPreviewImage自身不渲染任何可见 DOM源码中它始终return null它只是一个图片加载 连接的调度器它必须与可拖拽组件同时渲染通常放在同一个 fragment 中这样才能在拖拽发生时把预览连接好。Hooks 写法useDrag现代 react-dnd 推荐使用 Hooks。仓库内置示例 packages/examples/src/05-customize/handles-and-previews/BoxWithImage.tsx 展示了完整的 Hooks 用法import type { CSSProperties, FC } from react import { DragPreviewImage, useDrag } from react-dnd import { boxImage } from ./boxImage.js import { ItemTypes } from ./ItemTypes.js const style: CSSProperties { border: 1px dashed gray, padding: 0.5rem 1rem, marginBottom: .5rem, backgroundColor: white, cursor: move, width: 20rem, } export const BoxWithImage: FC () { const [{ opacity }, drag, preview] useDrag(() ({ type: ItemTypes.BOX, collect: (monitor) ({ opacity: monitor.isDragging() ? 0.4 : 1, }), })) return ( DragPreviewImage connect{preview} src{boxImage} / div ref{drag} style{{ ...style, opacity }} Drag me to see an image /div / ) }useDrag返回数组的第三个元素preview就是 drag preview 连接器直接传给DragPreviewImage即可。国际象棋示例 packages/examples/src/00-chessboard/Knight.tsx 也是同样的模式该示例将马头图片knightImage用作拖拽预览。回归测试示例 packages/examples/src/07-regression/previews-memory-leak/BoxWithImage.tsx 亦复如此说明该模式在仓库中是被反复使用、经过回归验证的推荐范式。Props原文档列出的 Props 只有两个全部为必填Prop类型是否必填说明connectConnectDragPreview必填drag preview 连接器函数来源于connect.dragPreview()经典写法或useDrag返回的第三个元素Hooks 写法srcstring必填预览图片的 URL支持相对路径、绝对路径以及 data URI其中ConnectDragPreview在 packages/react-dnd/src/types/connectors.ts 中的定义是export type ConnectDragPreview DragElementWrapperDragPreviewOptions即它接受一个可选参数对象DragPreviewOptions详见下文预览选项一节并在内部返回ReactElement | null。这也解释了为什么preview连接器可以直接传给connectpropDragPreviewImage 只是把整个连接器原样转交。源码原理一张图片如何变成拖拽预览组件源码位于 packages/react-dnd/src/core/DragPreviewImage.ts全部逻辑只有约 30 行核心机制如下export const DragPreviewImage: FCDragPreviewImageProps memo( function DragPreviewImage({ connect, src }) { useEffect(() { if (typeof Image undefined) return let connected false const img new Image() img.src src img.onload () { connect(img) connected true } return () { if (connected) { connect(null) } } }) return null }, )逐段解读memo包裹组件用React.memo缓存只有在connect或src引用变化时才重新渲染避免无谓的重渲染开销。SSR 安全if (typeof Image undefined) return——在服务端渲染SSR环境没有Image构造器时直接跳过保证组件不会在服务端崩溃该组件渲染结果恒为null本就无 DOM 可输出。动态创建图片每次 effect 执行时新建new Image()并设置src注意这里没有设置img.width/img.height或alt——因为它不参与页面布局只是作为一个已加载的图片对象交给浏览器后端绘制。加载完成后再连接img.onload中才调用connect(img)确保 react-dnd 拿到的是一张已加载完毕的图片。这是因为浏览器拖拽预览需要直接读取图片位图数据未加载完成的图片会被视为无效。这也是原文档与示例中反复强调等它加载后的原因docsite 示例文档 handles-and-previews.md 同样提到一旦加载完成你可以使用程序化创建的 Image 实例。connected标志用一个局部布尔变量标记是否已经连接成功。清理函数当组件卸载或src/connect变化导致 effect 重新执行时若此前已连接成功则调用connect(null)撤销连接把预览恢复为空。这保证了内存与预览状态的正确回收——仓库中 07-regression/previews-memory-leak 这一回归示例正是围绕预览/连接器的内存泄漏问题建立的。没有依赖数组effect 未指定依赖数组因此每次渲染后都会执行清理与重连。这是有意为之的简单策略——组件本身就应保持跟随每次渲染重新同步连接的行为。测试文件 packages/react-dnd/src/core/tests/DragPreviewImage.spec.tsx 使用TestBackend与useDrag验证了组件在DndProvider内能够正常渲染并把预览连接器接入测试中通过包装preview连接器connectPreview记录调用并注释指出验证图片确实被创建在当前测试框架下难以断言从侧面印证了该组件本质上是图片加载的异步副作用其正确性更多由onload时序与连接器协议保证。预览选项DragPreviewOptions控制预览的位置与截图时机虽然DragPreviewImage自身只有connect和src两个 prop但通过connect传入的连接器在调用时可以携带DragPreviewOptions。完整定义见 packages/react-dnd/src/types/options.ts选项类型默认值作用captureDraggingStatebooleanfalse为true时拖拽开始当帧就立即让组件感知到正在拖拽截图会带上monitor.isDragging()为真的样式如半透明。默认false更稳妥因为大多数情况下不希望截图里带着拖拽中的样式。仅少数场景需要开启例如在 IE 下想让自定义 DragLayer 生效且不得不用空预览时anchorXnumber0~10.5当预览尺寸与源节点尺寸不一致时水平方向的对齐方式0靠左、0.5线性插值、1靠右anchorYnumber0~10.5同上垂直方向0靠上、0.5居中插值、1靠下offsetXnumber \| nullnull预览相对光标的水平偏移像素值一旦设置anchorX失效offsetYnumber \| nullnull预览相对光标的垂直偏移像素值一旦设置anchorY失效典型的自定义预览锚点调用形如connectDragPreview(null, { offsetX: -8, offsetY: -8 }) // 或 connectDragPreview(null, { anchorX: 0, anchorY: 0 })在DragPreviewImage场景中这些选项通常不直接传给组件组件内部调用connect(img)时不带选项但如果你希望图片预览在光标右下/左下等位置出现可以像上面的写法一样自行包装连接器。相关实践空预览与自定义 DragLayer理解 DragPreviewImage 后还应了解它的两个近亲1. 空图片预览getEmptyImage有时我们不想要任何预览图片而是配合自定义DragLayer完全手绘拖拽反馈例如实现吸附网格、边界检查等复杂交互。此时可以使用 packages/backend-html5/src/getEmptyImage.ts 提供的getEmptyImage()——它返回一个 1×1 透明 GIF 的HTMLImageElement通过preview(getEmptyImage(), { captureDraggingState: true })方式隐藏默认预览。这比DragPreviewImage更进一步前者是用我的图片当预览后者是不用预览、完全自定义。docsite 的 custom-drag-layer.md 详细说明了该思路的取舍换来极大的自定义灵活度和零闪烁代价是失去默认的拖出容器后回弹动画。2. 默认浏览器截图naive 方式如果不设置任何预览浏览器会使用源节点截图作为预览。naive.md 指出这种方式在简单场景可用但放下时会明显闪烁。DragPreviewImage 正是规避这种闪烁、同时保留真实图片预览能力的最轻量手段。常见坑与注意事项务必在可拖拽组件内渲染DragPreviewImage必须在产生preview/connectDragPreview连接器的组件渲染树中且与之同时挂载否则拖拽开始时连接器尚未就绪。图片要能被加载src指向的资源必须可访问且能正确解码如示例中的boxImage、knightImage均为 base64 data URI 导入见 packages/examples/src/05-customize/handles-and-previews/boxImage.ts 与 packages/examples/src/00-chessboard/knightImage.ts加载失败时onload不会触发预览也就不会建立。非 SSR 环境依赖组件源码在Image不存在时静默返回null服务端渲染下它不会报错但也自然不会产生任何连接行为。卸载/换图时自动断开effect 清理逻辑会调用connect(null)因此无需手动管理连接器的释放这也正是 07-regression/previews-memory-leak 回归用例要守护的行为。小结DragPreviewImage 用约 30 行代码解决了自定义拖拽预览图片这一高频需求以memouseEffect管理图片的异步加载与连接器生命周期以connect(img)完成图片到 react-dnd 拖拽系统的接入并在卸载时以connect(null)干净地回收。配合useDrag的preview返回值或DragSource的connect.dragPreview()你可以在几行代码内把默认的节点截图替换为任意定制图片为拖拽体验提供更专业的视觉反馈。延伸阅读组件实现packages/react-dnd/src/core/DragPreviewImage.ts连接器类型packages/react-dnd/src/types/connectors.ts 与预览选项 packages/react-dnd/src/types/options.ts组件测试packages/react-dnd/src/core/tests/DragPreviewImage.spec.tsx完整示例Handles and PreviewsBoxWithImage.tsx、ChessboardKnight.tsx、Previews Memory LeakBoxWithImage.tsx相关文档自定义拖拽层 custom-drag-layer.md、native 拖拽 naive.md、空预览实现 getEmptyImage.ts赞分享前端UI组件【免费下载链接】react-dndDrag and Drop for React项目地址https://gitcode.com/gh_mirrors/re/react-dnd点击查看免费下载相关推荐React DnD拖拽层终极指南如何创建自定义拖拽预览组件React DnD拖拽层终极指南如何创建自定义拖拽预览组件 想要让你的React应用拥有专业级的拖拽体验吗自定义拖拽预览组件是实现这一目标的关键技术本文将前端UI组件用 react-dnd 构建国际象棋棋盘教程从零实现拖拽棋子与自定义拖拽预览用 react dnd 构建国际象棋棋盘教程从零实现拖拽棋子与自定义拖拽预览 本篇技术指南围绕 react dnd 官方教程中的“孤独骑士Lonely Kn前端UI组件一劳永逸uBlock Origin 安装配置全攻略10分钟拦截广告与跟踪器网页提速看得见一劳永逸uBlock Origin 安装配置全攻略10分钟拦截广告与跟踪器网页提速看得见 深夜刷剧正到关键时刻突然跳出全屏广告打开新闻网站页面来回跳网络安全应用安全上一篇终极指南daedalOS中的Web Workers错误处理策略确保多线程稳定性下一篇Fay数字人框架部署教程本地与云端方案对比创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
