地图事件与基础控件
🎯 引言
学完本文,你能在正确时机操作地图,从鼠标事件读取经纬度,并添加项目中常用的地图控件和 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:
🧰 添加常用控件
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。
🧪 小练习
- 点击地图时用 Popup 显示取整后的经纬度。
- 监听
moveend,输出当前中心点与缩放级别,并在卸载时取消监听。
// 请在这里编写代码
🎉 恭喜你已经掌握地图事件与基础控件啦!
