用户交互

本文档涵盖 Leaflet 的用户交互系统，该系统处理来自用户的鼠标、触摸、键盘和指针事件输入，并将其转换为地图行为，如平移、缩放和元素选择。这包括 DOM 事件处理管道、可拖拽元素系统以及提供拖曳平移和滚动缩放等行为的地图交互处理器。

关于 UI 控件（如缩放按钮和图层切换器）的信息，请参阅 控件。关于 DOM 工具和低级别事件处理的详细信息，请参阅 DOM 工具与事件处理。关于地图交互行为的具体信息，请参阅 地图交互处理器。

交互管道概览

Leaflet 的用户交互系统通过多层处理原始 DOM 事件，将基本输入转换为有意义的地图交互。该系统设计用于处理现代 Web 输入方法，包括触摸、指针事件以及传统的鼠标/键盘输入。

100%

核心交互组件

交互系统围绕几个关键组件构建，它们协同工作以在不同设备和输入方法上提供流畅的用户体验。

DOM 事件基础

DomEvent 模块通过规范化浏览器差异并提供一致的事件处理接口，为所有用户交互提供基础。它处理指针事件检测、触摸事件处理和跨浏览器兼容性。

组件	用途	关键函数
DomEvent.on()	事件监听器注册	支持多种事件类型和上下文
DomEvent.getPointerPosition()	坐标提取	规范化相对于容器的客户端坐标
DomEvent.getWheelDelta()	滚轮处理	处理不同的滚轮事件格式
DomEvent.stopPropagation()	事件控制	防止不必要的事件冒泡

可拖拽元素系统

Draggable 类为 Leaflet 中用于地图平移、标记拖拽和其他拖拽交互的核心拖拽功能提供支持。它实现指针捕获、容差检查和拖拽状态管理。

100%

浏览器能力检测

Browser 模块检测设备浏览器能力，以优化不同环境的交互处理。这会影响触摸事件、指针事件和设备特定行为的处理方式。

属性	检测目标	对交互的影响
Browser.touch	触摸能力	启用触摸手势处理
Browser.pointer	Pointer Events API	使用现代指针事件处理
Browser.mobile	移动设备	调整交互容差
Browser.retina	高 DPI 显示屏	影响像素计算

事件流架构

用户交互通过定义良好的管道流动，将原始 DOM 事件转换为结构化的地图行为。系统使用事件委托和规范化来确保跨平台的一致行为。

100%

输入设备支持

Leaflet 的交互系统同时支持多种输入方法，自动检测并为每种设备类型提供适当的处理。

指针事件处理

现代浏览器支持 Pointer Events API，它统一了鼠标、触摸和笔输入。Leaflet 检测此能力并在可用时使用它，对于旧版浏览器则回退到单独的鼠标和触摸事件处理。

触摸手势处理

触摸交互包括以下特殊处理：

• 单点触摸：转换为指针事件以进行一致的处理
• 多点触摸：检测和处理缩放手势
• 触摸容差：为基于手指的交互提供更大的容差值
• 指针捕获：防止同时触摸之间的冲突

鼠标和键盘集成

传统的鼠标和键盘交互保持完整功能：

• 鼠标滚轮：可配置灵敏度和去抖动的缩放
• 键盘修饰键：Shift+拖拽用于框选缩放，修饰键用于缩放方向
• 上下文菜单：与浏览器上下文菜单正确集成
• 焦点管理：在适当时支持键盘导航

处理器系统集成

交互系统与 Leaflet 的 Handler 架构集成，以提供模块化、可配置的地图行为。每种交互类型都实现为一个 Handler，可以独立启用或禁用。

处理器生命周期

100%

核心地图处理器

处理器	事件触发	交互结果
Map.Drag	地图容器上的 pointerdown	带可选惯性的平移
ScrollWheelZoom	wheel 事件	向光标位置缩放
BoxZoom	pointerdown + shiftKey	缩放到选中的矩形
DoubleClickZoom	dblclick 事件	在点击点缩放

每个处理器管理自己的事件监听器和交互状态，确保关注点的清晰分离和自定义每种交互类型行为的能力。