首页 / MapLibre / API 文档

MapTouchEvent

先看结论

触摸事件对象，一次手势可能包含多根手指，所以坐标有成对的数组与代表中心的单值两种形式。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-28 · 引用本文

map.on('touchstart', function (e) { e.lngLats; e.points; })

事件类型

事件名	触发时机
`touchstart`	手指按下，多指时每加一指触发一次
`touchmove`	手指移动，频率随设备而定
`touchend`	手指抬起
`touchcancel`	手势被系统或控件打断

字段

字段	类型	说明
`type`	string	上述四个事件名之一
`target`	Map	触发事件的地图实例
`originalEvent`	TouchEvent	浏览器原始事件，可取 `touches`、`changedTouches`
`point`	Point	触点中心相对地图容器的像素坐标
`lngLat`	LngLat	触点中心对应的经纬度
`points`	Array<Point>	每根手指的像素坐标
`lngLats`	Array<LngLat>	每根手指的经纬度
`preventDefault()`	方法	阻止地图对该手势的默认处理

示例

map.on('touchstart', function (e) {
  /* 两指同时按下，数组长度就是手指数 */
  e.lngLats.forEach(function (ll) {
    new maplibregl.Marker({ color: '#e8590c' })
      .setLngLat(ll)
      .addTo(map);
  });

  document.getElementById('finger').textContent = e.points.length;
});

map.on('touchmove', function (e) {
  /* 只记录中心点，避免每次移动都刷一大串数字 */
  document.getElementById('center').textContent =
    e.lngLat.lng.toFixed(4) + ', ' + e.lngLat.lat.toFixed(4);
});

/* 单指手势自己接管时，取消地图的拖动 */
map.on('touchstart', function (e) {
  if (e.points.length === 1) e.preventDefault();
});

注意事项

preventDefault() 只影响地图自身的处理逻辑，不会阻止页面滚动。要阻止页面跟着手指滚，需要给地图容器设置 touch-action: none，或在 originalEvent 上调用原生方法。

桌面浏览器不派发触摸事件，用鼠标模拟设备在 DevTools 里打开的触摸模拟才会触发。想同时支持鼠标与触摸，分别监听 MapMouseEvent 与 MapTouchEvent，或在业务层做手势抽象。

触摸点在地图外也会进来。手指从画布拖出边界时， touchmove 仍会触发，lngLat 可能落到负像素区。需要限制在可视范围内时，先判断 point.x、 point.y 是否在画布尺寸内。

引用本文

经纬志（2026）。《MapTouchEvent》。https://www.jingweizhi.com/maplibre/api/map-touch-event.html（访问日期 2026-11-03）。