尧图网站建设 
Gutenberg useDropZone Hook 完全指南用 wordpress/compose 构建可复用的拖放区域【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读useDropZone是 WordPress Gutenberg 项目在wordpress/compose包中提供的一个实验性 React Hook用于在指定区域内统一处理 HTML5 拖放Drag and Drop事件。它是块编辑器拖拽即插即用交互体验的基础设施——从wordpress/components的DropZone组件到block-editor的useBlockDropZone都构建在它之上。读完本文你将掌握useDropZone的全部参数、两种绑定方式默认 ref 与自定义dropZoneElement、底层事件处理机制并能直接照搬到自己的组件中实现文件拖放、区块拖放等能力。useDropZone 是什么useDropZone是一个用于在指定拖放区域drop zone内组织拖放处理的 Hook。它默认把返回值——一个 ref 回调——绑定到的 DOM 节点作为拖放区域也可以通过dropZoneElement参数显式指定一个更外层的元素作为拖放区域此时返回的 ref 应挂载到dropZoneElement的后代节点上。需要特别强调的是该 Hook 目前是实验性 API在wordpress/compose的公开导出中它以__experimentalUseDropZone的名字对外暴露见 packages/compose/src/index.js#L52引入方式为import { __experimentalUseDropZone } from wordpress/compose;因此它可能在未来版本中发生破坏性变更生产使用前请关注版本变更说明。基本用法两种绑定方式useDropZone接受一个配置对象作为唯一参数返回一个RefCallbackHTMLElement。根据是否传入dropZoneElement有两种使用形态。形态一自定义dropZoneElement覆盖更大拖放区域当拖放区域需要比 ref 节点更大时把外层容器作为dropZoneElement传入而 ref 挂载在其后代上import { useState } from react; import { useDropZone } from wordpress/compose; const WithWrapperDropZoneElement () { const [ dropZoneElement, setDropZoneElement ] useState( null ); const dropZoneRef useDropZone( { dropZoneElement, onDrop() { console.log( Dropped within the drop zone. ); }, onDragEnter() { console.log( Dragging within the drop zone ); } } ) return ( div classNameouter-wrapper ref{ setDropZoneElement } div ref{ dropZoneRef } pDrop Zone/p /div /div ); };形态二仅使用返回的 ref默认区域不传dropZoneElement时返回的 ref 本身即拖放区域import { useDropZone } from wordpress/compose; const WithoutWrapperDropZoneElement () { const dropZoneRef useDropZone( { onDrop() { console.log( Dropped within the drop zone. ); }, onDragEnter() { console.log( Dragging within the drop zone ); } } ) return ( div ref{ dropZoneRef } pDrop Zone/p /div ); };关键约束dropZoneElement必须存于 state使用dropZoneElement时原文档明确指出传入的元素应保存在 state 中而非普通 ref以确保元素变化时 Hook 能响应式更新。这从源码可以得到印证——use-drop-zone/index.ts#L197 中useRefEffect的依赖数组是[ isDisabled, dropZoneElement ]当dropZoneElement变化时整个事件绑定都会被重建而它正是通过useState的 setter 直接作为 ref 回调来收集 DOM 节点如上面示例的ref{ setDropZoneElement }。若用普通useRef节点变化不会触发重新绑定。参数详解根据 use-drop-zone/types.ts 的类型定义与 README 的参数说明useDropZone接受以下命名参数全部可选参数类型说明dropZoneElementHTMLElement \| null可选用作拖放区域的元素默认使用返回 ref 所挂载的节点isDisabledboolean是否禁用拖放区域onDragStart( e: DragEvent ) void拖放开始拖拽发起时调用onDragEnter( e: DragEvent ) void进入区域时调用onDragOver( e: DragEvent ) void在区域内移动时调用onDragLeave( e: DragEvent ) void离开区域时调用onDragEnd( e: MouseEvent ) void拖拽结束时调用注意其事件类型是MouseEventonDrop( e: DragEvent ) void在区域内松开放置时调用返回值RefCallbackHTMLElement即需要传递给拖放区域元素的 ref 回调。注意onDragStart的语义与直觉略有不同它不是在被拖拽元素上触发的dragstart而是当拖拽进入当前文档并落向拖放区域时标记一次拖拽开始详见下文事件机制。事件机制与源码级原理useDropZone的实现use-drop-zone/index.ts本质上是把浏览器原生拖放事件做了一层收窄与封装让开发者拿到的回调只在真正符合语义的时刻触发。它由useRefEffect与useEvent两个更底层的 Hook 组合而成。事件绑定与清理useRefEffectuse-ref-effect/index.ts的作用是把一段带清理函数的副作用与 DOM 节点生命周期绑定节点挂载时执行副作用节点卸载或依赖变化时执行清理。useDropZone在其内部为拖放元素统一绑定drop、dragenter、dragover、dragleave四个原生事件并在 document 上挂载dragenter监听同时在清理函数中逐一移除避免内存泄漏element.setAttribute( data-is-drop-zone, true ); element.addEventListener( drop, onDrop ); element.addEventListener( dragenter, onDragEnter ); element.addEventListener( dragover, onDragOver ); element.addEventListener( dragleave, onDragLeave ); // The dragstart event doesnt fire if the drag started outside the document. ownerDocument.addEventListener( dragenter, maybeDragStart );useEventuse-event/index.ts则负责把onDrop等回调包装成始终稳定、但永远拿到最新 props的函数内部用 ref 持有最新回调返回一个空依赖的useCallback。这正是useRefEffect依赖数组里不需要包含各回调的原因——它们永远引用最新实现从而避免因回调变化导致频繁重新绑定事件。data-is-drop-zone标记与嵌套区域的判定绑定同时会给拖放元素打上data-is-drop-zonetrue属性。这个属性有两个作用测试可验证性测试用例正是通过断言该属性来判断事件是否成功挂载见下文测试章节嵌套判定内部函数isElementInZone在判定目标是否属于本区域时会沿祖先链向上查找带有data-is-drop-zone标记的节点一旦找到只有它与当前element是同一个节点才判定在区域内从而让嵌套的多个拖放区域互不干扰let elementToCheck: HTMLElement | null targetToCheck; do { if ( elementToCheck.dataset.isDropZone ) { return elementToCheck element; } } while ( ( elementToCheck elementToCheck.parentElement ) );dragenter/dragleave的区域边界过滤浏览器原生dragenter在进入任意子元素时也会触发这会导致一个区域内连续触发多次。源码通过检查relatedTarget是否仍在该元素内部来过滤onDragEnter仅当relatedTarget刚离开的元素不在区域内时才视为真正进入区域并回调onDragLeave仅当relatedTarget不属于本区域isElementInZone返回 false时才回调。源码注释特别提示dragleave的这一判定在 Safari 上并不完全可靠存在一个 WebKit 缺陷bugs.webkit.org 编号 66547。拖拽状态机与跨窗口拖入maybeDragStart/maybeDragEnd构成一个简单的拖拽状态机maybeDragStart由 document 级别的dragenter触发用于捕获从浏览器外部发起的拖拽如从桌面拖入文件触发后置isDragging true并挂载dragend与mousemove两个兜底监听maybeDragEnd在两个条件满足之一时结束状态并调用onDragEnd。之所以需要mousemove兜底是因为对于从浏览器窗口外部发起的文件拖放或 HTML 拖放dragend事件并不总是可靠触发Firefox 在源节点被移除时也可能不触发。onDrop的默认行为处理与 Safari 兼容onDrop内部首先检查event.defaultPrevented——若内层拖放区域已经处理过本次 drop则直接返回保证嵌套区域只响应一次。随后preventDefault()阻止浏览器默认行为如直接用浏览器打开拖入的文件同时向父级拖放区域发出已处理信号。源码中还保留了一行看似无用的表达式event.dataTransfer event.dataTransfer.files.length注释说明这行代码能解决 Safari 从 Dock 直接拖出文件时文件不被识别的问题。测试与验证useDropZone配有基于 Vitest 与 Testing Library 的测试test/index.jsdom.test.jsx覆盖两种绑定形态will attach dropzone to outer wrapper传入dropZoneElement时断言外层 wrapper 获得data-is-drop-zone属性will attach dropzone to element with dropZoneRef attached未传dropZoneElement时断言返回 ref 所挂载的节点获得data-is-drop-zone属性。测试中通过一次rerender确保useEffect实际为useRefEffect的 effect 逻辑已经执行。这两条用例同时验证了属性标记即事件绑定的实现约定可作为你接入后自行验证的最小模板。在仓库中的真实使用案例useDropZone在 Gutenberg 中有两处典型消费场景可直接作为最佳实践参考。案例一DropZone组件文件拖放wordpress/components中的DropZoneComponentpackages/components/src/drop-zone/index.tsx#L48直接用useDropZone实现可视化拖放层在onDrop中通过dataTransfer提取文件与 HTML注意从 Windows Chrome 96 起dataTransfer可能同时返回文件与 HTML需先判断text/html再判断文件在onDragStart中根据dataTransfer.types判定拖入内容是 HTML、文件还是其他从而决定高亮态与可用回调。案例二块列表拖放区块拖拽排序block-editor的useBlockDropZonepackages/block-editor/src/components/use-block-drop-zone/index.js以__experimentalUseDropZone as useDropZone的方式引入并把onDragOver中的高频事件交给useThrottle200ms 节流处理以计算插入位置与方向onDragLeave/onDragEnd中隐藏插入点并停止拖拽状态。它还展示了嵌套区域的进阶用法通过isInsertionPoint判断relatedTarget是否落在插入点组件上若是则不触发onDragLeave因为插入点概念上仍属于拖放区域。注意事项与边界行为实验性 API公开导出名为__experimentalUseDropZoneAPI 可能变更dropZoneElement必须放 state否则依赖数组不更新事件绑定不会随目标变化而重建回调都是可选的只关心 drop 可以只传onDrop其余不传即可onDragEnd的事件类型是MouseEvent因为它在mousemove兜底路径下也会被调用类型定义与其余回调不同嵌套区域按层级响应内层区域preventDefault()后外层区域的onDrop不会重复触发dragenter/dragleave已做relatedTarget边界过滤无需自行处理子元素进出跨窗口拖入文件依赖 document 级dragenter感知拖拽开始并以mousemove作为dragend不可靠时的兜底结束条件Safari 限制dragleave边界判定与 Dock 文件拖放存在已知兼容性问题源码中已有针对性规避见onDrop中的无意义表达式与isElementInZone的instanceof defaultView.HTMLElement跨窗口类型检查。小结useDropZone用约 200 行源码把 HTML5 拖放事件的脏活收敛为一个声明式 Hook你只需要提供 ref 与一组回调它替你处理嵌套区域、跨窗口拖入、子元素进出过滤、dragend不可靠等边界问题。理解它的参数语义与事件机制无论你是要在自定义组件中实现文件拖放还是要像块编辑器那样实现复杂的区块拖拽排序都能在此基础上快速、可靠地落地。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gutenberg useDropZone Hook 完全指南：用 @wordpress/compose 构建可复用的拖放区域
Gutenberg useDropZone Hook 完全指南用 wordpress/compose 构建可复用的拖放区域【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读useDropZone是 WordPress Gutenberg 项目在wordpress/compose包中提供的一个实验性 React Hook用于在指定区域内统一处理 HTML5 拖放Drag and Drop事件。它是块编辑器拖拽即插即用交互体验的基础设施——从wordpress/components的DropZone组件到block-editor的useBlockDropZone都构建在它之上。读完本文你将掌握useDropZone的全部参数、两种绑定方式默认 ref 与自定义dropZoneElement、底层事件处理机制并能直接照搬到自己的组件中实现文件拖放、区块拖放等能力。useDropZone 是什么useDropZone是一个用于在指定拖放区域drop zone内组织拖放处理的 Hook。它默认把返回值——一个 ref 回调——绑定到的 DOM 节点作为拖放区域也可以通过dropZoneElement参数显式指定一个更外层的元素作为拖放区域此时返回的 ref 应挂载到dropZoneElement的后代节点上。需要特别强调的是该 Hook 目前是实验性 API在wordpress/compose的公开导出中它以__experimentalUseDropZone的名字对外暴露见 packages/compose/src/index.js#L52引入方式为import { __experimentalUseDropZone } from wordpress/compose;因此它可能在未来版本中发生破坏性变更生产使用前请关注版本变更说明。基本用法两种绑定方式useDropZone接受一个配置对象作为唯一参数返回一个RefCallbackHTMLElement。根据是否传入dropZoneElement有两种使用形态。形态一自定义dropZoneElement覆盖更大拖放区域当拖放区域需要比 ref 节点更大时把外层容器作为dropZoneElement传入而 ref 挂载在其后代上import { useState } from react; import { useDropZone } from wordpress/compose; const WithWrapperDropZoneElement () { const [ dropZoneElement, setDropZoneElement ] useState( null ); const dropZoneRef useDropZone( { dropZoneElement, onDrop() { console.log( Dropped within the drop zone. ); }, onDragEnter() { console.log( Dragging within the drop zone ); } } ) return ( div classNameouter-wrapper ref{ setDropZoneElement } div ref{ dropZoneRef } pDrop Zone/p /div /div ); };形态二仅使用返回的 ref默认区域不传dropZoneElement时返回的 ref 本身即拖放区域import { useDropZone } from wordpress/compose; const WithoutWrapperDropZoneElement () { const dropZoneRef useDropZone( { onDrop() { console.log( Dropped within the drop zone. ); }, onDragEnter() { console.log( Dragging within the drop zone ); } } ) return ( div ref{ dropZoneRef } pDrop Zone/p /div ); };关键约束dropZoneElement必须存于 state使用dropZoneElement时原文档明确指出传入的元素应保存在 state 中而非普通 ref以确保元素变化时 Hook 能响应式更新。这从源码可以得到印证——use-drop-zone/index.ts#L197 中useRefEffect的依赖数组是[ isDisabled, dropZoneElement ]当dropZoneElement变化时整个事件绑定都会被重建而它正是通过useState的 setter 直接作为 ref 回调来收集 DOM 节点如上面示例的ref{ setDropZoneElement }。若用普通useRef节点变化不会触发重新绑定。参数详解根据 use-drop-zone/types.ts 的类型定义与 README 的参数说明useDropZone接受以下命名参数全部可选参数类型说明dropZoneElementHTMLElement \| null可选用作拖放区域的元素默认使用返回 ref 所挂载的节点isDisabledboolean是否禁用拖放区域onDragStart( e: DragEvent ) void拖放开始拖拽发起时调用onDragEnter( e: DragEvent ) void进入区域时调用onDragOver( e: DragEvent ) void在区域内移动时调用onDragLeave( e: DragEvent ) void离开区域时调用onDragEnd( e: MouseEvent ) void拖拽结束时调用注意其事件类型是MouseEventonDrop( e: DragEvent ) void在区域内松开放置时调用返回值RefCallbackHTMLElement即需要传递给拖放区域元素的 ref 回调。注意onDragStart的语义与直觉略有不同它不是在被拖拽元素上触发的dragstart而是当拖拽进入当前文档并落向拖放区域时标记一次拖拽开始详见下文事件机制。事件机制与源码级原理useDropZone的实现use-drop-zone/index.ts本质上是把浏览器原生拖放事件做了一层收窄与封装让开发者拿到的回调只在真正符合语义的时刻触发。它由useRefEffect与useEvent两个更底层的 Hook 组合而成。事件绑定与清理useRefEffectuse-ref-effect/index.ts的作用是把一段带清理函数的副作用与 DOM 节点生命周期绑定节点挂载时执行副作用节点卸载或依赖变化时执行清理。useDropZone在其内部为拖放元素统一绑定drop、dragenter、dragover、dragleave四个原生事件并在 document 上挂载dragenter监听同时在清理函数中逐一移除避免内存泄漏element.setAttribute( data-is-drop-zone, true ); element.addEventListener( drop, onDrop ); element.addEventListener( dragenter, onDragEnter ); element.addEventListener( dragover, onDragOver ); element.addEventListener( dragleave, onDragLeave ); // The dragstart event doesnt fire if the drag started outside the document. ownerDocument.addEventListener( dragenter, maybeDragStart );useEventuse-event/index.ts则负责把onDrop等回调包装成始终稳定、但永远拿到最新 props的函数内部用 ref 持有最新回调返回一个空依赖的useCallback。这正是useRefEffect依赖数组里不需要包含各回调的原因——它们永远引用最新实现从而避免因回调变化导致频繁重新绑定事件。data-is-drop-zone标记与嵌套区域的判定绑定同时会给拖放元素打上data-is-drop-zonetrue属性。这个属性有两个作用测试可验证性测试用例正是通过断言该属性来判断事件是否成功挂载见下文测试章节嵌套判定内部函数isElementInZone在判定目标是否属于本区域时会沿祖先链向上查找带有data-is-drop-zone标记的节点一旦找到只有它与当前element是同一个节点才判定在区域内从而让嵌套的多个拖放区域互不干扰let elementToCheck: HTMLElement | null targetToCheck; do { if ( elementToCheck.dataset.isDropZone ) { return elementToCheck element; } } while ( ( elementToCheck elementToCheck.parentElement ) );dragenter/dragleave的区域边界过滤浏览器原生dragenter在进入任意子元素时也会触发这会导致一个区域内连续触发多次。源码通过检查relatedTarget是否仍在该元素内部来过滤onDragEnter仅当relatedTarget刚离开的元素不在区域内时才视为真正进入区域并回调onDragLeave仅当relatedTarget不属于本区域isElementInZone返回 false时才回调。源码注释特别提示dragleave的这一判定在 Safari 上并不完全可靠存在一个 WebKit 缺陷bugs.webkit.org 编号 66547。拖拽状态机与跨窗口拖入maybeDragStart/maybeDragEnd构成一个简单的拖拽状态机maybeDragStart由 document 级别的dragenter触发用于捕获从浏览器外部发起的拖拽如从桌面拖入文件触发后置isDragging true并挂载dragend与mousemove两个兜底监听maybeDragEnd在两个条件满足之一时结束状态并调用onDragEnd。之所以需要mousemove兜底是因为对于从浏览器窗口外部发起的文件拖放或 HTML 拖放dragend事件并不总是可靠触发Firefox 在源节点被移除时也可能不触发。onDrop的默认行为处理与 Safari 兼容onDrop内部首先检查event.defaultPrevented——若内层拖放区域已经处理过本次 drop则直接返回保证嵌套区域只响应一次。随后preventDefault()阻止浏览器默认行为如直接用浏览器打开拖入的文件同时向父级拖放区域发出已处理信号。源码中还保留了一行看似无用的表达式event.dataTransfer event.dataTransfer.files.length注释说明这行代码能解决 Safari 从 Dock 直接拖出文件时文件不被识别的问题。测试与验证useDropZone配有基于 Vitest 与 Testing Library 的测试test/index.jsdom.test.jsx覆盖两种绑定形态will attach dropzone to outer wrapper传入dropZoneElement时断言外层 wrapper 获得data-is-drop-zone属性will attach dropzone to element with dropZoneRef attached未传dropZoneElement时断言返回 ref 所挂载的节点获得data-is-drop-zone属性。测试中通过一次rerender确保useEffect实际为useRefEffect的 effect 逻辑已经执行。这两条用例同时验证了属性标记即事件绑定的实现约定可作为你接入后自行验证的最小模板。在仓库中的真实使用案例useDropZone在 Gutenberg 中有两处典型消费场景可直接作为最佳实践参考。案例一DropZone组件文件拖放wordpress/components中的DropZoneComponentpackages/components/src/drop-zone/index.tsx#L48直接用useDropZone实现可视化拖放层在onDrop中通过dataTransfer提取文件与 HTML注意从 Windows Chrome 96 起dataTransfer可能同时返回文件与 HTML需先判断text/html再判断文件在onDragStart中根据dataTransfer.types判定拖入内容是 HTML、文件还是其他从而决定高亮态与可用回调。案例二块列表拖放区块拖拽排序block-editor的useBlockDropZonepackages/block-editor/src/components/use-block-drop-zone/index.js以__experimentalUseDropZone as useDropZone的方式引入并把onDragOver中的高频事件交给useThrottle200ms 节流处理以计算插入位置与方向onDragLeave/onDragEnd中隐藏插入点并停止拖拽状态。它还展示了嵌套区域的进阶用法通过isInsertionPoint判断relatedTarget是否落在插入点组件上若是则不触发onDragLeave因为插入点概念上仍属于拖放区域。注意事项与边界行为实验性 API公开导出名为__experimentalUseDropZoneAPI 可能变更dropZoneElement必须放 state否则依赖数组不更新事件绑定不会随目标变化而重建回调都是可选的只关心 drop 可以只传onDrop其余不传即可onDragEnd的事件类型是MouseEvent因为它在mousemove兜底路径下也会被调用类型定义与其余回调不同嵌套区域按层级响应内层区域preventDefault()后外层区域的onDrop不会重复触发dragenter/dragleave已做relatedTarget边界过滤无需自行处理子元素进出跨窗口拖入文件依赖 document 级dragenter感知拖拽开始并以mousemove作为dragend不可靠时的兜底结束条件Safari 限制dragleave边界判定与 Dock 文件拖放存在已知兼容性问题源码中已有针对性规避见onDrop中的无意义表达式与isElementInZone的instanceof defaultView.HTMLElement跨窗口类型检查。小结useDropZone用约 200 行源码把 HTML5 拖放事件的脏活收敛为一个声明式 Hook你只需要提供 ref 与一组回调它替你处理嵌套区域、跨窗口拖入、子元素进出过滤、dragend不可靠等边界问题。理解它的参数语义与事件机制无论你是要在自定义组件中实现文件拖放还是要像块编辑器那样实现复杂的区块拖拽排序都能在此基础上快速、可靠地落地。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考