前端开发工具【免费下载链接】beautiful-react-hooks A collection of beautiful and (hopefully) useful React hooks to speed-up your components and hooks development 项目地址https://gitcode.com/gh_mirrors/be/beautiful-react-hooks点击查看免费下载在 React 项目中实现可拖拽元素往往要手写draggable属性、dragstart/dragend监听器、组件卸载时的清理逻辑以及DataTransfer的数据序列化细节。beautiful-react-hooks提供的useDrag将这一整套流程收敛为一次 Hook 调用传入一个 DOM ref即可让元素获得原生拖拽能力并拿到一个表示是否正在被拖拽的布尔状态再通过dragImage、transfer等选项可自定义拖拽时显示的图像与传递给放置目标的数据。读完本文你将掌握useDrag的全部选项参数、三类典型用法基础拖拽、自定义拖拽图像、数据传递并能从源码层面理解其事件注册、draggable属性自动设置与监听器自动清理的完整实现机制。简介一行 Hook 启用元素拖拽useDrag接收一个指向 HTML 元素的引用通常来自 React 的useRef并让该元素变为可拖拽。Hook 返回一个布尔值表示元素当前是否正在被拖拽。官方文档docs/useDrag.md给出的三点价值主张负责将拖拽相关的事件监听器挂载到指定的目标元素上负责在组件卸载时移除这些监听器让你可以轻松实现可拖拽的业务逻辑。按需引入方式与包名对应关系可在 package.json 的exports字段中确认./useDrag同时提供 ESMdist/esm/useDrag.js、CJSdist/useDrag.js与类型声明dist/useDrag.d.ts三种产物因此支持beautiful-react-hooks/useDrag这种按子路径的引入方式也便于打包器做 tree-shaking。包的peerDependencies要求react 18.2.0 20.0.0使用时需保证项目 React 版本在该区间内。基础用法让元素可拖拽并跟踪拖拽状态第一个参数传入一个 DOM ref返回值即拖拽状态import { useRef } from react; import useDrag from beautiful-react-hooks/useDrag; const MyComponent () { const ref useRef(); const isDragged useDrag(ref); return ( DisplayDemo titleuseDrag div ref{ref} style{{ padding: 20px 0, background: isDragged ? #BE496E : #1D6C8B }} Draggable item... {isDragged spanis being dragged/span} /div /DisplayDemo ); }; MyComponent /示例中的DisplayDemo是官方文档演示用的容器组件实际项目中可替换为任意容器或直接去掉。这里有两个值得注意的机制均能由源码证实无需手动设置draggable属性。useDrag内部固定以isDraggable true调用useDragEvents见 src/useDrag.ts而useDragEvents在挂载时的useEffect中检查目标元素若其没有draggable属性则自动调用setAttribute(draggable, true)见 src/useDragEvents.ts。因此示例代码没有写draggable属性也能拖同时已自带该属性的元素不会被覆盖。isDragged只在dragstart与dragend两个时刻翻转。源码中onDragStart回调执行setIsDragging(true)onDragEnd回调执行setIsDragging(false)见 src/useDrag.ts它只回答是否处于拖拽进行中不提供拖拽坐标等更细粒度的信息——这一点在注意事项中会进一步展开。自定义拖拽图像dragImage 与偏移量默认情况下浏览器拖拽时显示的是元素自身的截图。如果希望拖拽时跟随鼠标的是一个自定义图片例如项目 Logo 或缩略图可以传入dragImage及其在光标处的偏移量import { useRef } from react; import useDrag from beautiful-react-hooks/useDrag; const MyComponent () { const ref useRef(); const isDragged useDrag(ref, { dragImage: https://beautifulinteractions.com/img/logo-colorful.svg, dragImageXOffset: 5, dragImageYOffset: 5, }); return ( DisplayDemo titleuseDrag div ref{ref} style{{ padding: 20px 0, background: isDragged ? #BE496E : #1D6C8B }} Draggable item... {isDragged spanis being dragged/span} /div /DisplayDemo ); }; MyComponent /从源码看src/useDrag.ts这段配置的落地逻辑是if (opts.dragImage event.dataTransfer) { const img new Image() img.src opts.dragImage event.dataTransfer.setDragImage(img, opts.dragImageXOffset ?? 0, opts.dragImageYOffset ?? 0) }即在dragstart事件中动态构造一个Image对象并交给dataTransfer.setDragImage()渲染。两个偏移量的默认值均为0由defaultOptions提供见 src/useDrag.ts其语义是图像左上角相对光标的像素偏移示例中的5, 5让图像中心大致对准光标位置避免图像左上角与光标重叠导致的贴边观感。拖拽数据传递transfer 与 transferFormatHTML5 拖放模型中可拖拽源负责往DataTransfer里写数据放置目标在drop事件中读取。useDrag通过transfer与transferFormat两个选项封装了这个过程import { useRef } from react; import useDrag from beautiful-react-hooks/useDrag; const MyComponent () { const ref useRef(); const isDragged useDrag(ref, { transfer: { id: item-id, foo: bar }, transferFormat: text/plain, }); return ( DisplayDemo titleuseDrag div ref{ref} style{{ padding: 20px 0, background: isDragged ? #BE496E : #1D6C8B }} Draggable item... {isDragged spanis being dragged/span} /div /DisplayDemo ); }; MyComponent /源码中的序列化与写入逻辑src/useDrag.ts为if (opts.transfer event.dataTransfer) { const data typeof opts.transfer object ? JSON.stringify(opts.transfer) : ${opts.transfer} event.dataTransfer.setData(opts.transferFormat ?? text, data) }由此可以明确transfer的类型与行为对应关系传入对象如{ id: item-id, foo: bar }时会被JSON.stringify序列化为 JSON 字符串后写入传入字符串或数字时直接以模板字符串转成文本写入transferFormat指定写入DataTransfer的 MIME 类型源码兜底值为textdefaultOptions.transferFormat见 src/useDrag.ts官方示例中显式使用了标准的text/plain。对应的放置目标侧可以用同库的 useDropZone 或在放置区的onDrop中通过event.dataTransfer.getData(text/plain)取回该字符串并JSON.parse还原。由于写入的始终是字符串对象 → JSON 字符串 → 放置端解析这一约定需要两端自行保持一致这是 HTML5 原生拖放模型本身的限制并非 Hook 缺陷。参数参考Types完整选项接口与函数签名如下继承自 docs/useDrag.md 的 Types 部分与 src/useDrag.ts 的源码定义一致import { type RefObject } from react; export interface UseDragOptions { dragImage?: string; dragImageXOffset?: number; dragImageYOffset?: number; transfer?: string | number | Recordstring, any; transferFormat?: string; } declare const useDrag: TElement extends HTMLElement(targetRef: RefObjectTElement, options?: UseDragOptions) boolean; export default useDrag;结合源码defaultOptions与setData的兜底逻辑各参数的默认值与语义整理如下参数类型默认值说明dragImagestring无不设置则使用元素自身截图拖拽时显示的自定义图像 URLdragImageXOffsetnumber0自定义图像相对光标的水平偏移像素dragImageYOffsetnumber0自定义图像相对光标的垂直偏移像素transferstring \| number \| Recordstring, any无不写数据拖拽时写入DataTransfer的数据对象会被 JSON 序列化transferFormatstringtext写入数据所用的 MIME 格式建议显式使用text/plain等标准类型另外从源码结构看src/useDrag.ts选项的合并方式是{ ...defaultOptions, ...(options || {}) }即未显式传入的字段会自动补齐默认值每个渲染都会重新注册捕获最新opts的回调因此后续渲染中更新选项对象对之后的下一次拖拽会生效。源码走读useDrag 底层是如何工作的useDrag的实现不到 50 行其核心是三层委托结构理解这条调用链能解释它的行为边界。第一层useDragsrc/useDrag.ts负责业务语义——状态翻转、dragImage设置、DataTransfer写入全部集中在onDragStart/onDragEnd两个回调里。第二层useDragEventssrc/useDragEvents.ts负责事件抽象。它基于useEvent批量构造了onDrag、onDrop、onDragEnter、onDragEnd、onDragExit、onDragLeave、onDragOver、onDragStart共 8 个回调设置器并以Object.freeze返回只读对象见 src/useDragEvents.ts。它还包含一道防御性校验若传入的 ref 不是标准的 React ref缺少current属性会直接抛出Unable to assign any drag event to the given ref错误src/useDragEvents.ts把传错 ref的问题暴露在渲染期而非事件期。第三层useEventsrc/useEvent.ts负责真正的事件绑定。它在useEffect中执行addEventListener并在 cleanup 函数中执行removeEventListener见 src/useEvent.ts——这正是文档中组件卸载时自动移除监听器承诺的实现来源。事件触发时原生事件会被转发到一个 ref 中缓存的最新回调而这个缓存机制由工厂函数 createHandlerSetter 提供。这里有一个对使用者很关键的设计约束createHandlerSetter的注释明确说明它返回的 setter 只是更新回调 ref设置回调 ref 不会强制组件重新渲染。因此回调必须在函数组件体内同步调用onDragStart(fn)、onDragEnd(fn)写在 render 过程中而不能放在setTimeout、Promise.then等异步上下文中——异步调用发生在事件监听建立流程之外回调无法被正确挂载。这也是同库useDragEvents文档反复强调的不要异步调用回调设置器的原因。从源码结构看这种渲染期注册 事件期读取 ref的模式同时避免了为每次拖拽重新绑定原生监听器是这套 Hooks 控制性能的手段之一。仓库内的测试用例 test/useDrag.spec.js 验证了基本契约以{ current: document.createElement(div) }作为 ref 渲染 Hook 后返回值必须是布尔值it(should return an object the state of the current dragging element, () { const targetRef { current: document.createElement(div) } const { result } renderHook(() useDrag(targetRef)) expect(result.current).to.be.an(boolean) })注意事项与能力边界它封装的是 HTML5 原生拖放而非基于 Pointer 事件的自定义拖拽。useDrag依赖dragstart/dragend事件与draggable属性因此受浏览器原生拖放模型的约束例如移动端浏览器对 HTML5 拖放的支持并不完整。它适合把元素拖到另一个放置区这类场景不适合实现需要逐帧跟手坐标的拖动交互。isDragged只表达状态不表达位置。Hook 不暴露clientX/clientY或偏移量如果业务需要元素跟着鼠标走的效果需要自行在drag事件基础上扩展或直接使用同库的 useDragEvents其文档中还给出了带放置区onDragOver/onDrop的完整示例。放置端需要配对 Hook。transfer写入的数据必须有一个读取方仓库中对应的放置端 Hook 是 useDropZone若只使用useDrag拖拽行为本身不受影响只是drop时读不到数据。不建议用底层事件 Hook 替代标准 propsuseDragEvents官方文档特别指出若组件已有onDragStart{handler}这类标准 React 拖拽 props 的用法应继续沿用标准 props 方案因为绕过 React SyntheticEvent 会损失相应性能见 docs/useDragEvents.md 的 What not to do 部分。何时选用 useDrag官方文档给出的使用判据很简洁当你需要基础的拖拽相关业务逻辑时。结合源码与同库 Hook 的分工可以把选型边界再具体化一些需求推荐 Hook让元素可拖拽 跟踪拖拽中状态 可选自定义图像/传数据useDrag需要drop、dragOver、dragEnter/Leave等完整事件集合来抽象自定义拖放逻辑useDragEvents需要一个放置区来接收拖放数据useDropZoneuseDrag本质上是useDragEvents的上层封装仅消费其中的onDragStart/onDragEnd因此当需求超出状态翻转 图像 传数据时向下切换到底层 Hook 是仓库内自然的升级路径而不必换用第三方拖拽库。赞分享前端开发工具【免费下载链接】beautiful-react-hooks A collection of beautiful and (hopefully) useful React hooks to speed-up your components and hooks development 项目地址https://gitcode.com/gh_mirrors/be/beautiful-react-hooks点击查看免费下载相关推荐Clypra基础操作指南10分钟学会视频剪辑的核心技巧Clypra基础操作指南10分钟学会视频剪辑的核心技巧 Clypra是一款基于Tauri、React和TypeScript构建的现代视频编辑器专注于提供免费音视频视频视频处理桌面应用React Beautiful DND 拖拽元素的自定义形状非矩形拖拽区域实现React Beautiful DND 拖拽元素的自定义形状非矩形拖拽区域实现 在使用React Beautiful DND构建拖放界面时默认的矩形拖拽区域自定义拖拽图层实战用 react-dnd 的 DragLayer 打造零闪烁的拖拽反馈自定义拖拽图层实战用 react dnd 的 DragLayer 打造零闪烁的拖拽反馈 react dnd 的浏览器后端依赖 HTML5 原生拖放 API而前端UI组件上一篇Prompt2Model高级配置教程自定义组件、API集成与多平台部署下一篇【亲测免费】 强大的动态壁纸工具SwayFX创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考