地图事件与基础控件

监听地图加载、鼠标和视角事件,并添加导航、比例尺、定位与弹窗能力。

🎯 引言

学完本文,你能在正确时机操作地图,从鼠标事件读取经纬度,并添加项目中常用的地图控件和 Popup。


🧱 加载事件决定何时操作资源

map.on('load', () => {
    // Style 首次加载完成,可以添加业务 Source 和 Layer
})

map.on('idle', () => {
    // 当前视口所需资源加载完成,地图暂时没有过渡动画
})

load 适合首次添加 Source 和 Layer。idle 可能触发多次,适合等待当前画面稳定,不适合把一次性初始化逻辑直接放进去。


🖱 鼠标与视角事件

function handleMapClick(event: mapboxgl.MapMouseEvent) {
    console.log(event.lngLat.lng, event.lngLat.lat)
}

map.on('click', handleMapClick)
map.on('dblclick', event => console.log(event.lngLat))
map.on('mousemove', event => console.log(event.point))

map.on('move', () => console.log(map.getCenter()))
map.on('moveend', () => console.log('视角移动结束'))
map.on('zoom', () => console.log(map.getZoom()))
map.on('zoomend', () => console.log('缩放结束'))

event.lngLat 是鼠标位置对应的经纬度,event.point 是相对地图容器左上角的像素坐标。需要实时反馈时使用 move、zoom,需要请求数据或保存状态时优先使用 moveend、zoomend,避免高频调用接口。

下面的地图把事件结果直接显示在地图上方。移动鼠标可以看到 lngLat,拖动或缩放结束后可以看到新的中心点和 zoom:

把鼠标移入地图,查看当前位置拖动或缩放地图,查看 moveend 结果

🧰 添加常用控件

map.addControl(new mapboxgl.NavigationControl(), 'top-right')
map.addControl(new mapboxgl.ScaleControl({ unit: 'metric' }), 'bottom-left')
map.addControl(new mapboxgl.GeolocateControl({
    positionOptions: { enableHighAccuracy: true },
    trackUserLocation: true,
}), 'top-right')
  • NavigationControl 提供缩放与恢复北向功能。
  • ScaleControl 显示当前比例尺,metric 使用米和千米。
  • GeolocateControl 调用浏览器定位能力,需要 HTTPS 或本地开发环境,并由用户授权。

定位结果来自设备和浏览器,精度会受环境影响,不能假设它始终可用或足够准确。

下面是三个控件的真实显示效果:右上角依次显示缩放、旋转和定位按钮,左下角显示比例尺。点击定位按钮时,浏览器会请求位置权限;拒绝授权不会影响其他控件。


💬 最基础的 Popup

const popup = new mapboxgl.Popup({ offset: 12 })
    .setLngLat([116.397, 39.909])
    .setText('当前位置')
    .addTo(map)

popup.setText('内容已更新')
popup.remove()

显示普通文本时优先使用 setText。setHTML 会把字符串解析为 HTML,内容来自接口或用户输入时必须先做安全处理。

下面可以直接观察 Popup 的打开、关闭和文字更新。Popup 会固定在指定经纬度,并在拖动地图时继续跟随该位置。


🧹 取消监听避免重复绑定

off 需要传入与 on 相同的事件名和函数引用:

function handleMoveEnd() {
    console.log(map.getBounds())
}

map.on('moveend', handleMoveEnd)

function destroyMap() {
    map.off('moveend', handleMoveEnd)
    map.remove()
}

页面或组件销毁时调用 destroyMap()。如果 on 和 off 分别写两个匿名函数,它们不是同一个函数,监听不会被移除。重复进入页面或重复执行初始化时,这类问题会表现为一次操作触发多次回调。


🧾 小节总结

  • load 适合首次添加地图资源,idle 表示当前画面暂时稳定。
  • 鼠标事件通过 lngLat 取得经纬度,通过 point 取得像素位置。
  • 接口请求优先放在 moveend、zoomend 等结束事件中。
  • Navigation、Scale、Geolocate 是常用基础控件。
  • 取消监听时必须保留原函数引用。

❓ 知识问答

Q1:为什么 idle 中的代码执行了很多次?

地图每次资源加载和动画结束后都可能再次进入空闲状态,idle 不是只执行一次的生命周期钩子。

Q2:浏览器定位为什么没有反应?

检查页面是否使用 HTTPS、用户是否授权定位,以及设备是否能提供位置。

Q3:move 和 moveend 怎么选?

实时更新界面用 move;发请求、保存范围等较重操作用 moveend。


🧪 小练习

  1. 点击地图时用 Popup 显示取整后的经纬度。
  2. 监听 moveend,输出当前中心点与缩放级别,并在卸载时取消监听。
// 请在这里编写代码

🎉 恭喜你已经掌握地图事件与基础控件啦!