概述

Map.BoxZoom是Map类的一个扩展方法，用于实现地图框选缩放功能，属于Leaflet 内部的事件处理器之一。

源码分析

源码实现

Map.BoxZoom源码实现如下：

Map.mergeOPtions({
  boxZoom: true, //合并配置，默认启用框选缩放功能。
});

// 继承于`Handler`类，用于处理地图事件。

export var BoxZoom = Handler.extend({
  initialize: function (map) {
    this._map = map; // 关联地图实例
    this._container = map._container; // 地图容器元素
    this._pane = map._panes.overlayPane; // 覆盖层面板
    this._resetStateTimeout = 0; // 重置状态的计时器
    map.on("unload", this._destroy, this); // 地图卸载时触发清理方法
  },
  addHooks: function () {
    DomEvent.on(this._container, "mousedown", this._onMouseDown, this);
  },
  removeHooks: function () {
    DomEvent.off(this._container, "mousedown", this._onMouseDown, this);
  },
  moved: function () {
    return this._moved;
  },
  _destroy: function () {
    DomUtil.remove(this._pane); //地图卸载时清理覆盖层
    delete this._pane;
  },
  _resetState: function () {
    this._resetStateTimeout = 0;
    this._moved = false;
  },
  _clearDeferredResetState: function () {
    if (this._resetStateTimeout !== 0) {
      clearTimeout(this._resetStateTimeout);
      this._resetStateTimeout = 0;
    }
  },
  _onMouseDown: function (e) {
    if (!e.shiftKey || (e.which !== 1 && e.button !== 1)) { // 判断是否按下了Shift键和鼠标左键
      return false;
    }
    //重置状态
    this._clearDeferredResetState();
    this._resetState();

    DomUtil.disableTextSelection(); // 禁用文本选择
    DomUtil.disableImageDrag(); // 禁用图片拖拽

    this._startPoint = this._map.mouseEventToContainerPoint(e); // 记录起始位置

    // 绑定全局鼠标移动、抬起、按键事件
    DomEvent.on(
      document,
      {
        contextmenu: DomEvent.stop,
        mousemove: this._onMouseMove,
        mouseup: this._onMouseUp,
        keydown: this._onKeyDown,
      },
      this
    );
  },
  _onMouseMove: function (e) {
    if (!this._moved) {
      this._moved = true;

      this._box = DomUtil.create("div", "leaflet-zoom-box", this._container); // 创建框选矩形
      DomUtil.addClass(this._container, "leaflet-crosshair"); //添加十字光标样式

      this._map.fire("boxzoomstart"); // 触发框选开始事件
    }

    // 更新框选矩形的位置和大小
    this._point = this._map.mouseEventToContainerPoint(e);

    var bounds = new Bounds(this._point, this._startPoint),
      size = bounds.getSize();

    DomUtil.setPosition(this._box, bounds.min);

    this._box.style.width = size.x + "px";
    this._box.style.height = size.y + "px";
  },
  _finish: function () {
    if (this._moved) {
      DomUtil.remove(this._box);
      DomUtil.removeClass(this._container, "leaflet-crosshair");
    }

    DomUtil.enableTextSelection();
    DomUtil.enableImageDrag();

    DomEvent.off(
      document,
      {
        contextmenu: DomEvent.stop,
        mousemove: this._onMouseMove,
        mouseup: this._onMouseUp,
        keydown: this._onKeyDown,
      },
      this
    );
  },
  _onMouseUp: function (e) {
    if (e.which !== 1 && e.button !== 1) {
      return;
    }
    
    // 清理DOM和事件
    this._finish();

    if (!this._moved) {
      return;
    }
    this._clearDeferredResetState();
    this._resetStateTimeout = setTimeout(Util.bind(this._resetState, this), 0);

    var bounds = new LatLngBounds(
      this._map.containerPointToLatLng(this._startPoint),
      this._map.containerPointToLatLng(this._point)
    );
    
    // 缩放地图，触发boxzoomend事件
    this._map.fitBounds(bounds).fire("boxzoomend", { boxZoomBounds: bounds });
  },
  _onKeyDown: function (e) {
    if (e.keyCode === 27) { // ESC键
      this._finish();
      this._clearDeferredResetState();
      this._resetState();
    }
  },
});

Map.addInitHook("addHandler", "boxZoom", BoxZoom);

源码详细分析

BoxZoom类

1. 初始化initialize

initialize方法用于初始化BoxZoom类的实例，接受一个map参数，该参数是Map类的实例，表示要绑定事件的地图对象。在initialize方法中，首先将map对象赋值给this._map属性，然后获取地图容器元素和覆盖层元素，并将其赋值给this._container和this._pane属性。接着，将unload事件绑定到_destroy方法上，用于在地图卸载时销毁BoxZoom类的实例。

2. 钩子函数addHooks/removeHooks

addHooks方法用于添加事件钩子，将mousedown事件绑定到_onMouseDown方法上。

removeHooks方法用于移除事件钩子，将mousedown事件从_onMouseDown方法上解绑。

3. 鼠标状态moved方法

moved方法用于判断是否发生了移动操作，返回一个布尔值，表示是否发生了移动操作。

4. 销毁方法_destroy

_destroy方法用于销毁BoxZoom类的实例，移除覆盖层元素和禁用文本选择和图像拖动。

6. 重置状态_resetState

_resetState方法用于重置状态，将this._resetStateTimeout属性设置为0，将this._moved属性设置为false。

7. 清除延迟重置状态_clearDeferredResetState

_clearDeferredResetState方法用于清除延迟重置状态，将this._resetStateTimeout属性设置为0。

8. 鼠标按下事件_onMouseDown _onMouseDown方法用于处理鼠标按下事件，接受一个e参数，该参数是鼠标事件对象。 在_onMouseDown方法中，首先判断是否按下了Shift键和鼠标左键或右键，如果不满足条件，则返回false。 然后，调用_clearDeferredResetState方法清除延迟重置状态，调用_resetState方法重置状态。 接着，禁用文本选择和图像拖动，将鼠标按下的容器点赋值给this._startPoint属性。 最后，将contextmenu事件绑定到DomEvent.stop方法上，将mousemove事件绑定到_onMouseMove方法上，将mouseup事件绑定到_onMouseUp方法上，将keydown事件绑定到_onKeyDown方法上。

9. 鼠标移动事件_onMouseMove _onMouseMove方法用于处理鼠标移动事件，接受一个e参数，该参数是鼠标事件对象。 在_onMouseMove方法中，首先判断是否发生了移动操作，如果没有发生，则将this._moved属性设置为true。 然后，创建一个div元素，设置其类名为leaflet-zoom-box，并将其添加到this._container元素中。 接着，将leaflet-crosshair类添加到this._container元素中。 最后，调用this._map.fire("boxzoomstart")方法触发boxzoomstart事件。

10. 完成处理_finish

框选结束鼠标抬起时会触发_finish方法，用于进行完成操作，如移除div元素、禁用文本选择和图像拖动以及移除全局绑定的监听事件。

11. 鼠标抬起事件_onMouseUp _onMouseUp方法用于处理鼠标抬起事件，接受一个e参数，该参数是鼠标事件对象。

在_onMouseUp方法中，首先判断是否抬起了鼠标左键或右键，如果不满足条件，则返回。然后，调用_finish方法完成操作，调用_clearDeferredResetState方法清除延迟重置状态，调用_resetStateTimeout方法设置延迟重置状态。最后，将鼠标抬起的容器点赋值给this._point属性，计算出矩形框的左上角和右下角的经纬度坐标，创建一个LatLngBounds对象，将其赋值给bounds变量。然后，调用this._map.fitBounds(bounds).fire("boxzoomend", { boxZoomBounds: bounds })方法将地图缩放到矩形框的范围内，并触发boxzoomend事件，将矩形框的边界传递给事件处理函数。

1. _onKeyDown键盘按下事件 _onKeyDown方法用于处理键盘按下事件，接受一个e参数，该参数是键盘事件对象。 在_onKeyDown方法中，首先判断是否按下了Esc键，如果按下了，则调用_finish方法完成操作，调用_clearDeferredResetState方法清除延迟重置状态，调用_resetState方法重置状态。

Map类

Map.addInitHook方法是将BoxZoom注册为Leaflet的默认处理器，使得地图初始化时会自动加载。

而Map.addInitHook方法的第一个参数addHandler就是用于添加处理器，它接受三个参数，分别是name、handler和context。而在上述中，name和handler对应的就是boxZoom字符串和BoxZoom类，首先判断是否存在this._handlers属性，如果不存在，则创建一个空对象。然后，将handler对象赋值给this._handlers[name]属性，即this._handlers.boxZoom= new BoxZoom(this)。在最开始合并选项时默认boxZoom为true，所以会执行this._handlers.boxZoom.enable()即启用处理器。enable()方法是在Handler基类中实现的，enable方法内部会调用this.addHooks()方法，即添加钩子函数，监听mousedown事件。

总结

Map.BoxZoom是通过继承 Handler 类，实现了框选缩放的核心交互逻辑：

1. ​​事件监听​​：通过钩子函数绑定/解绑鼠标和键盘事件。
2. ​​DOM 操作​​：动态创建/更新框选矩形，并管理相关样式。
3. 地理计算​​：将屏幕坐标转换为地理边界，触发地图缩放。
4. 状态管理​​：处理中途取消（ESC 键）、资源清理等边界条件。

它是 Leaflet 高可扩展性的典型示例，通过自定义 Handler 可灵活添加或修改交互行为。