react-beautiful-dnd 事件系统全解DOM 事件捕获、preventDefault 策略与自定义事件处理实战【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dnd本文基于 react-beautiful-dnd 官方指南 docs/guides/how-we-use-dom-events.md 展开系统梳理该库在拖拽交互中如何消费mousedown、mousemove、touchstart、keydown等 DOM 输入事件何时调用event.preventDefault()、何时保持克制以及你如何在自有的 window 级或拖拽手柄drag handle级事件处理器之上安全地叠加业务逻辑。读完本文你将掌握event.defaultPrevented的正确检查姿势、三类传感器鼠标 / 触摸 / 键盘在每个拖拽阶段的事件消费细则并能结合源码理解其实现原理。什么时候你需要阅读这份指南react-beautiful-dnd的大多数使用者并不需要了解其内部事件机制——拖拽、排序、动画都由库自身完成。但当出现以下场景时这份知识就变得至关重要你在window上自己绑定了click、keydown等监听器却发现拖拽结束后业务点击逻辑被吞掉了你在拖拽手柄DragHandle上绑定了自己的事件处理器想要区分这次点击是普通点击还是拖拽的一部分你希望拦截或复用在拖拽过程中产生的键盘输入例如阻止表单提交、Tab 切换。在进入细节前先记住一条关键结论判断某个事件是否已被拖拽系统消费唯一可靠的信号是event.defaultPrevented属性。注意由于 webkit 的一个已知 bug对应 issue 见 react-beautiful-dnd#413部分事件如mousemove在调用event.preventDefault()后event.defaultPrevented可能不会正确变为true这一点在 Safari 等 WebKit 内核浏览器上需要额外留意。最安全的事件绑定方式先看结论如果你不想深究全部细节可以直接使用下面两个事件作为安全港——它们可以绑定在拖拽手柄上、组件树中更高的任意节点上或直接绑定在window上事件行为click若该次点击属于拖拽交互的一部分event.defaultPrevented会被置为true。即使拖拽并未以mouseup/touchend等点击前动作收尾例如拖拽被取消该标记依然成立。详见 docs/sensors/mouse.md 中的 Sloppy clicks and click prevention 一节keydown若该按键被用作拖拽的一部分event.defaultPrevented会被置为true也就是说只要你的业务处理器遵循先检查defaultPrevented再决定是否执行的模式就能与拖拽系统和平共处。通用规则preventDefault 而非 stopPropagationreact-beautiful-dnd对事件消费有一套明确且一致的哲学使用event.preventDefault()当某个输入事件被用作拖拽交互的一部分时库会调用preventDefault()来退出浏览器对该事件的默认行为如滚动、聚焦、表单提交绝不使用event.stopPropagation()被消费的事件依然会正常冒泡propagate到你的处理器。这意味着即使mousemove正被用于拖拽移动你仍然能收到该事件——只是需要检查它是否已被消费。window.addEventListener(click, (event: MouseEvent) { // 该事件已被用于拖拽直接返回 if (event.defaultPrevented) { return; } doMyCoolThing(); });捕获阶段capture phase绑定库将所有事件处理器都绑定在window上且使用捕获阶段capture: true。只要你的事件处理器使用默认的冒泡阶段capture: false即addEventListener的默认值绑定事件到达你的处理器时行为就与本文描述一致——你先收到事件再通过defaultPrevented判断它是否已被消费。从源码看这一约定由 src/view/event-bindings/bind-events.js 与 src/view/event-bindings/event-types.js 支撑。bindEvents接受EventBinding[]和可共享的EventOptionspassive、capture、once为每个绑定执行addEventListener并返回一个统一的解绑函数// src/view/event-bindings/bind-events.js简化示意 export default function bindEvents(el, bindings, sharedOptions) { const unbindings bindings.map((binding) { const options { ...sharedOptions, ...binding.options }; el.addEventListener(binding.eventName, binding.fn, options); return () el.removeEventListener(binding.eventName, binding.fn, options); }); return () unbindings.forEach((unbind) unbind()); }例如鼠标传感器在开始捕获时传入{ passive: false, capture: true }见 src/view/use-sensor-marshal/sensors/use-mouse-sensor.js 中listenForCapture这正是捕获阶段 允许 preventDefault的落地实现。直接操作与间接操作react-beautiful-dnd将影响拖拽的事件分为两类直接操作direct actions事件直接驱动拖拽例如鼠标拖拽中的mousemove、键盘拖拽中的方向键↑↓←→keydown。这类事件会调用preventDefault()以阻止其浏览器默认行为。间接操作indirect actions事件间接影响拖拽典型是取消拖拽类事件如resize、orientationchange。这类事件不会被调用preventDefault()。判断依据很简单只有当事件被直接用于拖拽时库才会消费它的默认行为间接取消拖拽的事件保持原样以最大限度保留浏览器原生行为。鼠标拖拽Mouse dragging的事件消费细则鼠标拖拽的完整状态机IDLE → PENDING → DRAGGING可以在 src/view/use-sensor-marshal/sensors/use-mouse-sensor.js 中看到组件挂载时只在window捕获阶段绑定mousedown和webkitmouseforcewillbegin一旦mousedown命中拖拽手柄并成功获得锁tryGetLock便解绑这两个监听器转而在window上绑定mousemove、mouseup、mousedown、keydown、resize、scroll等一整套捕获监听器。各阶段的preventDefault行为如下。初始 mousedownmousedown上会调用preventDefault()这是全库规则中已知的唯一例外。为什么当用户首次在拖拽手柄上按下鼠标时库并不知道用户是想点击还是想拖拽——理想情况下不应调用preventDefault()。但拖拽手柄带有tabIndex如果不阻止默认行为元素会在按下瞬间获得焦点。为了不让聚焦打断潜在的拖拽库只能在此处牺牲这个事件。源码中对应逻辑位于 use-mouse-sensor.js 的startCaptureBinding在确认事件未被消费、按下的主鼠标键button 0、无修饰键Ctrl/Meta/Shift/Alt、找到最近的 draggable 且成功tryGetLock之后执行event.preventDefault()。尚未确认拖拽是否开始mousemove上不调用preventDefault()。用户必须移动超过一定阈值库才会认定这是拖拽而非手滑点击sloppy click。在等待阈值达成的 PENDING 阶段任何mousemove都不会被消费。源码中定义了sloppyClickThreshold 5use-mouse-sensor.js 第 26 行只有当Math.abs(current.x - original.x) 5或Math.abs(current.y - original.y) 5时才会触发fluidLift正式起拖并在此刻对触发阈值的那次mousemove调用preventDefault()。用户表明不进行鼠标拖拽导致 pending 拖拽结束的事件如mouseup、keydown不调用preventDefault()pending 期间的任何keydown都被视为间接取消若随后产生了click事件不调用preventDefault()。这保证了按下去没拖动的交互退化为一次普通点击锚点、按钮等交互元素可以自然工作参见 docs/sensors/mouse.md 中 Sloppy clicks 一节的说明。拖拽进行中mousemove调用preventDefault()用于阻止文本选择等默认行为并标记事件已消费部分keydown调用preventDefault()阻止标准浏览器行为见下文keyup不调用preventDefault()即使对应的keydown被阻止过。keydown的具体消费逻辑在 src/view/use-sensor-marshal/sensors/util/prevent-standard-key-events.js 中拖拽期间会阻止Enter提交表单和Tab切换焦点避免拖拽过程中的误操作。鼠标拖拽中的键盘快捷键仅有escapeesc取消拖拽见 docs/sensors/mouse.md 的 Keyboard shortcuts 一节。拖拽结束若mouseup结束了拖拽调用preventDefault()若escapeesckeydown结束了拖拽直接取消调用preventDefault()紧随其后的click事件无论拖拽以何种方式结束都会被调用preventDefault()见下文click 阻断说明间接结束拖拽的事件如resize不调用preventDefault()keyup即使导致拖拽结束也不调用preventDefault()。源码佐证mouseup在 DRAGGING 阶段会执行event.preventDefault()并调用actions.drop({ shouldBlockNextClick: true })use-mouse-sensor.js 第 115–130 行。shouldBlockNextClick的落实则在 src/view/use-sensor-marshal/use-sensor-marshal.js 的finish函数中它会在window上以capture: true, passive: false, once: true绑定一个click处理器对下一次 click 调用preventDefault()并用setTimeout兜底解绑防止被吞掉的 click 事件导致监听器泄漏。触摸拖拽Touch dragging的事件消费细则触摸拖拽与鼠标拖拽机制类似同样有 PENDING 阶段但等待的是长按计时器而非移动阈值实现见 src/view/use-sensor-marshal/sensors/use-touch-sensor.js。其中两个关键常量值得注意timeForLongPress 120长按起拖延迟单位为毫秒从 150 下调以规避 iOS force press 相关问题与forcePressThreshold 0.15判定强制按压的力度阈值。初始 touchstarttouchstart不调用preventDefault()。当用户手指或其他触控输入按在Draggable /上时库无法确定用户意图是轻点、强制按压、滚动容器还是拖拽。因此它选择完全放手保留尽可能多的原生交互——例如保留锚点的导航行为。源码 use-touch-sensor.js 的startCaptureBinding注释明确写道We need to NOT callevent.preventDefault()so as to maintain as much standard browser interactions as possible.用户表明不进行触摸拖拽任何事件都不调用preventDefault()。用户可以通过手指按住元素一小段时间长按来起拖若在此期间发生touchmove库也不调用preventDefault()。orientationchange、touchcancel等事件可以取消触摸拖拽同样不调用preventDefault()。拖拽进行中touchmove调用preventDefault()阻止原生滚动并标记事件已消费。注意touchmove绑定在window上且为非 passiveoptions: { capture: false }注释提到这是为了规避一个 Firefox bug因为只有非 passive 才能让preventDefault()生效以阻止滚动。另外use-touch-sensor.js 底部还有一个针对 Safari 的webkitHack额外绑定一个非捕获、非 passive 的空touchmove监听器强制让动态添加的touchmove处理器中的preventDefault()真正生效。拖拽结束touchend调用preventDefault()正常放下touchcancel调用preventDefault()若拖拽已在进行属于直接结束escapeesckeydown调用preventDefault()直接取消其他keydown不调用视为间接取消间接取消事件如orientationchange不调用preventDefault()。此外触摸拖拽期间contextmenu事件会被一律preventDefault()以阻止长按弹出的上下文菜单干扰拖拽。强制按压Force press强制按压force touch的行为取决于Draggable /的shouldRespectForcePress属性详见 docs/api/draggable.md。Draggable shouldRespectForcePress{false} /默认值默认选择退出 force press 事件以获得更一致的拖拽体验。在touchstart触发且 pending 长按计时器启动后所有touchforcechange事件都会调用preventDefault()。Draggable shouldRespectForcePress /尊重标准的 force touch 交互。拖拽尚未开始时touchforcechange不调用preventDefault()拖拽已开始但尚无任何移动时touchforcechange不调用preventDefault()——此时 force press 会取消拖拽属于间接取消拖拽已开始且已经发生过touchmove后后续的touchforcechange会调用preventDefault()。这是防御性措施正常情况下 force press 不应在touchmove之后发生例如防止拖拽中途弹出链接预览等奇怪行为。源码中这一分支逻辑位于 use-touch-sensor.js 的touchforcechange处理器当touch.force forcePressThreshold且shouldRespect为真时若已hasMoved则preventDefault()并返回否则cancel()若shouldRespect为假则一律preventDefault()。键盘拖拽Keyboard dragging的事件消费细则键盘拖拽只使用keydown事件因此keyup永远不会被调用preventDefault()。实现见 src/view/use-sensor-marshal/sensors/use-keyboard-sensor.js。拖拽开始keydown调用preventDefault()。与鼠标拖拽不同键盘拖拽在用户按下空格键space的瞬间即开始没有 pending 等待期。这个初始按键会调用event.preventDefault()源码中preDrag.snapLift()前执行event.preventDefault()随后解绑捕获监听器绑定拖拽期间的keydown、mousedown、mouseup、click、touchstart、resize、wheel等监听器。拖拽进行中被用作拖拽的keydown方向键↑↓←→调用preventDefault()需要阻止标准浏览器行为的keydown如Enter⏎提交、Tabtab切换焦点以及 PageUp/PageDown/Home/End 等滚动跳键调用preventDefault()未用于拖拽的keydown不调用preventDefault()。按键码定义集中在 src/view/key-codes.js而拖拽期间禁止的标准按键Enter 与 Tab由 prevent-standard-key-events.js 统一处理。键盘拖拽期间任何鼠标动作mousedown、mouseup、click、touchstart、resize或wheel都会取消拖拽——其中wheel使用 passive 监听因为只需收到事件即取消无需阻止默认滚动。拖拽结束空格键spacekeydown调用preventDefault()放下/提交当前拖拽escapeesckeydown调用preventDefault()显式取消拖拽间接取消的事件如resize、mousedown不调用preventDefault()。错误事件Error events的特殊处理除了输入事件库对window上的error事件也有自己的消费策略。相关背景见 docs/guides/setup-problem-detection-and-error-recovery.md。如果抛出一个rbd错误并被库的windowerror监听器捕获库会调用event.preventDefault()将该事件标记为已消费同时中止当前拖拽并在开发模式下输出警告日志。实现位于 src/view/drag-drop-context/error-boundary.jsxonWindowError处理器中当err instanceof RbdInvariant时执行event.preventDefault()从而抑制控制台中的 uncaught error 警告若拖拽正在进行还会通过callbacks.tryAbort()中止拖拽并打印开发警告。在自己的代码中叠加事件处理的完整示例综合以上规则一个同时监听click与keydown且与拖拽系统兼容的示例大致如下// 在 window 上以默认冒泡阶段绑定 window.addEventListener(click, (event) { // 事件已被用于拖拽无论是成功放下还是取消 if (event.defaultPrevented) { return; } // 仅处理真正的普通点击 handleNormalClick(event); }); window.addEventListener(keydown, (event) { // 事件已被用于拖拽起拖、移动、放下或取消 if (event.defaultPrevented) { return; } handleNormalKeyDown(event); });如果你的业务事件绑定在拖拽手柄或组件树内层节点上且同样使用冒泡阶段上述检查依然成立——因为库的事件都绑定在window捕获阶段你的处理器总能先于库的消费逻辑观察到事件也总能在之后读到准确的defaultPrevented状态。若你确实需要绝对不被拖拽系统干扰的事件则应优先选用本文开头列出的click与keydown这两个安全事件。总结react-beautiful-dnd的 DOM 事件策略可以浓缩为三条原则只用preventDefault()不用stopPropagation()——事件始终可达你的处理器用event.defaultPrevented判断是否已被消费全部绑定在window捕获阶段——你的冒泡阶段处理器天然与之兼容直接操作消费事件间接操作取消类事件不消费——最大化保留浏览器原生行为仅在确有必要时如mousedown防止聚焦、touchmove阻止滚动才干预默认行为。无论你是在集成分析埋点、处理业务点击还是构建自定义传感器把这份事件消费地图鼠标、触摸、键盘三个阶段 错误事件放在手边都能帮你快速定位事件被吞或未被吞的根因。想进一步探索传感器 API 与自定义传感器的构建方式可以继续阅读 docs/sensors/sensor-api.md完整文档目录见 README.md。【免费下载链接】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 事件系统全解：DOM 事件捕获、preventDefault 策略与自定义事件处理实战
react-beautiful-dnd 事件系统全解DOM 事件捕获、preventDefault 策略与自定义事件处理实战【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dnd本文基于 react-beautiful-dnd 官方指南 docs/guides/how-we-use-dom-events.md 展开系统梳理该库在拖拽交互中如何消费mousedown、mousemove、touchstart、keydown等 DOM 输入事件何时调用event.preventDefault()、何时保持克制以及你如何在自有的 window 级或拖拽手柄drag handle级事件处理器之上安全地叠加业务逻辑。读完本文你将掌握event.defaultPrevented的正确检查姿势、三类传感器鼠标 / 触摸 / 键盘在每个拖拽阶段的事件消费细则并能结合源码理解其实现原理。什么时候你需要阅读这份指南react-beautiful-dnd的大多数使用者并不需要了解其内部事件机制——拖拽、排序、动画都由库自身完成。但当出现以下场景时这份知识就变得至关重要你在window上自己绑定了click、keydown等监听器却发现拖拽结束后业务点击逻辑被吞掉了你在拖拽手柄DragHandle上绑定了自己的事件处理器想要区分这次点击是普通点击还是拖拽的一部分你希望拦截或复用在拖拽过程中产生的键盘输入例如阻止表单提交、Tab 切换。在进入细节前先记住一条关键结论判断某个事件是否已被拖拽系统消费唯一可靠的信号是event.defaultPrevented属性。注意由于 webkit 的一个已知 bug对应 issue 见 react-beautiful-dnd#413部分事件如mousemove在调用event.preventDefault()后event.defaultPrevented可能不会正确变为true这一点在 Safari 等 WebKit 内核浏览器上需要额外留意。最安全的事件绑定方式先看结论如果你不想深究全部细节可以直接使用下面两个事件作为安全港——它们可以绑定在拖拽手柄上、组件树中更高的任意节点上或直接绑定在window上事件行为click若该次点击属于拖拽交互的一部分event.defaultPrevented会被置为true。即使拖拽并未以mouseup/touchend等点击前动作收尾例如拖拽被取消该标记依然成立。详见 docs/sensors/mouse.md 中的 Sloppy clicks and click prevention 一节keydown若该按键被用作拖拽的一部分event.defaultPrevented会被置为true也就是说只要你的业务处理器遵循先检查defaultPrevented再决定是否执行的模式就能与拖拽系统和平共处。通用规则preventDefault 而非 stopPropagationreact-beautiful-dnd对事件消费有一套明确且一致的哲学使用event.preventDefault()当某个输入事件被用作拖拽交互的一部分时库会调用preventDefault()来退出浏览器对该事件的默认行为如滚动、聚焦、表单提交绝不使用event.stopPropagation()被消费的事件依然会正常冒泡propagate到你的处理器。这意味着即使mousemove正被用于拖拽移动你仍然能收到该事件——只是需要检查它是否已被消费。window.addEventListener(click, (event: MouseEvent) { // 该事件已被用于拖拽直接返回 if (event.defaultPrevented) { return; } doMyCoolThing(); });捕获阶段capture phase绑定库将所有事件处理器都绑定在window上且使用捕获阶段capture: true。只要你的事件处理器使用默认的冒泡阶段capture: false即addEventListener的默认值绑定事件到达你的处理器时行为就与本文描述一致——你先收到事件再通过defaultPrevented判断它是否已被消费。从源码看这一约定由 src/view/event-bindings/bind-events.js 与 src/view/event-bindings/event-types.js 支撑。bindEvents接受EventBinding[]和可共享的EventOptionspassive、capture、once为每个绑定执行addEventListener并返回一个统一的解绑函数// src/view/event-bindings/bind-events.js简化示意 export default function bindEvents(el, bindings, sharedOptions) { const unbindings bindings.map((binding) { const options { ...sharedOptions, ...binding.options }; el.addEventListener(binding.eventName, binding.fn, options); return () el.removeEventListener(binding.eventName, binding.fn, options); }); return () unbindings.forEach((unbind) unbind()); }例如鼠标传感器在开始捕获时传入{ passive: false, capture: true }见 src/view/use-sensor-marshal/sensors/use-mouse-sensor.js 中listenForCapture这正是捕获阶段 允许 preventDefault的落地实现。直接操作与间接操作react-beautiful-dnd将影响拖拽的事件分为两类直接操作direct actions事件直接驱动拖拽例如鼠标拖拽中的mousemove、键盘拖拽中的方向键↑↓←→keydown。这类事件会调用preventDefault()以阻止其浏览器默认行为。间接操作indirect actions事件间接影响拖拽典型是取消拖拽类事件如resize、orientationchange。这类事件不会被调用preventDefault()。判断依据很简单只有当事件被直接用于拖拽时库才会消费它的默认行为间接取消拖拽的事件保持原样以最大限度保留浏览器原生行为。鼠标拖拽Mouse dragging的事件消费细则鼠标拖拽的完整状态机IDLE → PENDING → DRAGGING可以在 src/view/use-sensor-marshal/sensors/use-mouse-sensor.js 中看到组件挂载时只在window捕获阶段绑定mousedown和webkitmouseforcewillbegin一旦mousedown命中拖拽手柄并成功获得锁tryGetLock便解绑这两个监听器转而在window上绑定mousemove、mouseup、mousedown、keydown、resize、scroll等一整套捕获监听器。各阶段的preventDefault行为如下。初始 mousedownmousedown上会调用preventDefault()这是全库规则中已知的唯一例外。为什么当用户首次在拖拽手柄上按下鼠标时库并不知道用户是想点击还是想拖拽——理想情况下不应调用preventDefault()。但拖拽手柄带有tabIndex如果不阻止默认行为元素会在按下瞬间获得焦点。为了不让聚焦打断潜在的拖拽库只能在此处牺牲这个事件。源码中对应逻辑位于 use-mouse-sensor.js 的startCaptureBinding在确认事件未被消费、按下的主鼠标键button 0、无修饰键Ctrl/Meta/Shift/Alt、找到最近的 draggable 且成功tryGetLock之后执行event.preventDefault()。尚未确认拖拽是否开始mousemove上不调用preventDefault()。用户必须移动超过一定阈值库才会认定这是拖拽而非手滑点击sloppy click。在等待阈值达成的 PENDING 阶段任何mousemove都不会被消费。源码中定义了sloppyClickThreshold 5use-mouse-sensor.js 第 26 行只有当Math.abs(current.x - original.x) 5或Math.abs(current.y - original.y) 5时才会触发fluidLift正式起拖并在此刻对触发阈值的那次mousemove调用preventDefault()。用户表明不进行鼠标拖拽导致 pending 拖拽结束的事件如mouseup、keydown不调用preventDefault()pending 期间的任何keydown都被视为间接取消若随后产生了click事件不调用preventDefault()。这保证了按下去没拖动的交互退化为一次普通点击锚点、按钮等交互元素可以自然工作参见 docs/sensors/mouse.md 中 Sloppy clicks 一节的说明。拖拽进行中mousemove调用preventDefault()用于阻止文本选择等默认行为并标记事件已消费部分keydown调用preventDefault()阻止标准浏览器行为见下文keyup不调用preventDefault()即使对应的keydown被阻止过。keydown的具体消费逻辑在 src/view/use-sensor-marshal/sensors/util/prevent-standard-key-events.js 中拖拽期间会阻止Enter提交表单和Tab切换焦点避免拖拽过程中的误操作。鼠标拖拽中的键盘快捷键仅有escapeesc取消拖拽见 docs/sensors/mouse.md 的 Keyboard shortcuts 一节。拖拽结束若mouseup结束了拖拽调用preventDefault()若escapeesckeydown结束了拖拽直接取消调用preventDefault()紧随其后的click事件无论拖拽以何种方式结束都会被调用preventDefault()见下文click 阻断说明间接结束拖拽的事件如resize不调用preventDefault()keyup即使导致拖拽结束也不调用preventDefault()。源码佐证mouseup在 DRAGGING 阶段会执行event.preventDefault()并调用actions.drop({ shouldBlockNextClick: true })use-mouse-sensor.js 第 115–130 行。shouldBlockNextClick的落实则在 src/view/use-sensor-marshal/use-sensor-marshal.js 的finish函数中它会在window上以capture: true, passive: false, once: true绑定一个click处理器对下一次 click 调用preventDefault()并用setTimeout兜底解绑防止被吞掉的 click 事件导致监听器泄漏。触摸拖拽Touch dragging的事件消费细则触摸拖拽与鼠标拖拽机制类似同样有 PENDING 阶段但等待的是长按计时器而非移动阈值实现见 src/view/use-sensor-marshal/sensors/use-touch-sensor.js。其中两个关键常量值得注意timeForLongPress 120长按起拖延迟单位为毫秒从 150 下调以规避 iOS force press 相关问题与forcePressThreshold 0.15判定强制按压的力度阈值。初始 touchstarttouchstart不调用preventDefault()。当用户手指或其他触控输入按在Draggable /上时库无法确定用户意图是轻点、强制按压、滚动容器还是拖拽。因此它选择完全放手保留尽可能多的原生交互——例如保留锚点的导航行为。源码 use-touch-sensor.js 的startCaptureBinding注释明确写道We need to NOT callevent.preventDefault()so as to maintain as much standard browser interactions as possible.用户表明不进行触摸拖拽任何事件都不调用preventDefault()。用户可以通过手指按住元素一小段时间长按来起拖若在此期间发生touchmove库也不调用preventDefault()。orientationchange、touchcancel等事件可以取消触摸拖拽同样不调用preventDefault()。拖拽进行中touchmove调用preventDefault()阻止原生滚动并标记事件已消费。注意touchmove绑定在window上且为非 passiveoptions: { capture: false }注释提到这是为了规避一个 Firefox bug因为只有非 passive 才能让preventDefault()生效以阻止滚动。另外use-touch-sensor.js 底部还有一个针对 Safari 的webkitHack额外绑定一个非捕获、非 passive 的空touchmove监听器强制让动态添加的touchmove处理器中的preventDefault()真正生效。拖拽结束touchend调用preventDefault()正常放下touchcancel调用preventDefault()若拖拽已在进行属于直接结束escapeesckeydown调用preventDefault()直接取消其他keydown不调用视为间接取消间接取消事件如orientationchange不调用preventDefault()。此外触摸拖拽期间contextmenu事件会被一律preventDefault()以阻止长按弹出的上下文菜单干扰拖拽。强制按压Force press强制按压force touch的行为取决于Draggable /的shouldRespectForcePress属性详见 docs/api/draggable.md。Draggable shouldRespectForcePress{false} /默认值默认选择退出 force press 事件以获得更一致的拖拽体验。在touchstart触发且 pending 长按计时器启动后所有touchforcechange事件都会调用preventDefault()。Draggable shouldRespectForcePress /尊重标准的 force touch 交互。拖拽尚未开始时touchforcechange不调用preventDefault()拖拽已开始但尚无任何移动时touchforcechange不调用preventDefault()——此时 force press 会取消拖拽属于间接取消拖拽已开始且已经发生过touchmove后后续的touchforcechange会调用preventDefault()。这是防御性措施正常情况下 force press 不应在touchmove之后发生例如防止拖拽中途弹出链接预览等奇怪行为。源码中这一分支逻辑位于 use-touch-sensor.js 的touchforcechange处理器当touch.force forcePressThreshold且shouldRespect为真时若已hasMoved则preventDefault()并返回否则cancel()若shouldRespect为假则一律preventDefault()。键盘拖拽Keyboard dragging的事件消费细则键盘拖拽只使用keydown事件因此keyup永远不会被调用preventDefault()。实现见 src/view/use-sensor-marshal/sensors/use-keyboard-sensor.js。拖拽开始keydown调用preventDefault()。与鼠标拖拽不同键盘拖拽在用户按下空格键space的瞬间即开始没有 pending 等待期。这个初始按键会调用event.preventDefault()源码中preDrag.snapLift()前执行event.preventDefault()随后解绑捕获监听器绑定拖拽期间的keydown、mousedown、mouseup、click、touchstart、resize、wheel等监听器。拖拽进行中被用作拖拽的keydown方向键↑↓←→调用preventDefault()需要阻止标准浏览器行为的keydown如Enter⏎提交、Tabtab切换焦点以及 PageUp/PageDown/Home/End 等滚动跳键调用preventDefault()未用于拖拽的keydown不调用preventDefault()。按键码定义集中在 src/view/key-codes.js而拖拽期间禁止的标准按键Enter 与 Tab由 prevent-standard-key-events.js 统一处理。键盘拖拽期间任何鼠标动作mousedown、mouseup、click、touchstart、resize或wheel都会取消拖拽——其中wheel使用 passive 监听因为只需收到事件即取消无需阻止默认滚动。拖拽结束空格键spacekeydown调用preventDefault()放下/提交当前拖拽escapeesckeydown调用preventDefault()显式取消拖拽间接取消的事件如resize、mousedown不调用preventDefault()。错误事件Error events的特殊处理除了输入事件库对window上的error事件也有自己的消费策略。相关背景见 docs/guides/setup-problem-detection-and-error-recovery.md。如果抛出一个rbd错误并被库的windowerror监听器捕获库会调用event.preventDefault()将该事件标记为已消费同时中止当前拖拽并在开发模式下输出警告日志。实现位于 src/view/drag-drop-context/error-boundary.jsxonWindowError处理器中当err instanceof RbdInvariant时执行event.preventDefault()从而抑制控制台中的 uncaught error 警告若拖拽正在进行还会通过callbacks.tryAbort()中止拖拽并打印开发警告。在自己的代码中叠加事件处理的完整示例综合以上规则一个同时监听click与keydown且与拖拽系统兼容的示例大致如下// 在 window 上以默认冒泡阶段绑定 window.addEventListener(click, (event) { // 事件已被用于拖拽无论是成功放下还是取消 if (event.defaultPrevented) { return; } // 仅处理真正的普通点击 handleNormalClick(event); }); window.addEventListener(keydown, (event) { // 事件已被用于拖拽起拖、移动、放下或取消 if (event.defaultPrevented) { return; } handleNormalKeyDown(event); });如果你的业务事件绑定在拖拽手柄或组件树内层节点上且同样使用冒泡阶段上述检查依然成立——因为库的事件都绑定在window捕获阶段你的处理器总能先于库的消费逻辑观察到事件也总能在之后读到准确的defaultPrevented状态。若你确实需要绝对不被拖拽系统干扰的事件则应优先选用本文开头列出的click与keydown这两个安全事件。总结react-beautiful-dnd的 DOM 事件策略可以浓缩为三条原则只用preventDefault()不用stopPropagation()——事件始终可达你的处理器用event.defaultPrevented判断是否已被消费全部绑定在window捕获阶段——你的冒泡阶段处理器天然与之兼容直接操作消费事件间接操作取消类事件不消费——最大化保留浏览器原生行为仅在确有必要时如mousedown防止聚焦、touchmove阻止滚动才干预默认行为。无论你是在集成分析埋点、处理业务点击还是构建自定义传感器把这份事件消费地图鼠标、触摸、键盘三个阶段 错误事件放在手边都能帮你快速定位事件被吞或未被吞的根因。想进一步探索传感器 API 与自定义传感器的构建方式可以继续阅读 docs/sensors/sensor-api.md完整文档目录见 README.md。【免费下载链接】react-beautiful-dndBeautiful and accessible drag and drop for lists with React项目地址: https://gitcode.com/gh_mirrors/re/react-beautiful-dnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考