点击要素、查询与高亮
🎯 引言
学完本文,你能知道用户点击了地图上的哪个对象、读取它的属性,并通过颜色和大小变化显示悬浮与选中状态。
这套交互常用于“点击地图上的点,在旁边显示详情”。Point 表示一个位置,Feature 是携带位置和业务属性的地图对象,Layer 负责把这些对象绘制成圆点。
🖱 点击圆点后取得对象信息
作用:确定用户点中了谁,并取得详情需要的数据。
例如,地图上有三个位置。用户点击“位置 B”后,页面需要拿到它的 ID、名称和状态,才能打开对应详情。给指定 Layer 绑定点击事件即可完成这个动作:
function handlePlaceClick(event: mapboxgl.MapLayerMouseEvent) {
const feature = event.features?.[0]
if (!feature) return
selectedId.value = feature.id
selectedProperties.value = feature.properties
}
map.on('click', 'places', handlePlaceClick)
'places' 是可点击的 Layer ID,所以点击底图或其他 Layer 不会执行 handlePlaceClick。event.features[0] 是当前点击位置命中的第一个对象:
feature.id用来区分不同对象。feature.properties保存名称、状态等业务字段。
可点击对象还应该给出鼠标提示。鼠标进入圆点时显示手型,离开后恢复:
map.on('mouseenter', 'places', () => {
map.getCanvas().style.cursor = 'pointer'
})
map.on('mouseleave', 'places', () => {
map.getCanvas().style.cursor = ''
})
下面的组件对应以上代码。点击任意蓝色圆点,上方会显示该对象的 ID、名称和状态;鼠标进入圆点时也会变成手型。
🔎 判断点击位置有没有对象
作用:让代码主动检查某个屏幕位置上画了哪些对象。
Layer 点击事件只在点中圆点时执行。如果还要识别“用户点了地图空白位置”,可以使用 queryRenderedFeatures()。它会从当前画面中查询指定像素位置命中的 Feature:
map.on('click', (event) => {
const features = map.queryRenderedFeatures(event.point, {
layers: ['places'],
})
if (features.length === 0) {
selectedId.value = undefined
return
}
selectedId.value = features[0].id
})
event.point 是鼠标在地图容器中的屏幕位置,layers 限定只查询需要交互的 Layer。结果为空,说明这里没有目标对象,因此可以关闭详情或清除选择。
下面分别点击紫色圆点和地图空白位置,观察查询数量为什么分别是 1 和 0。
✨ 让悬浮和选中状态看得见
作用:用颜色和大小告诉用户当前指向了谁、已经选择了谁。
feature-state 是 Mapbox 为单个 Feature 保存的临时显示状态。它适合保存 hover 和 selected,但不会修改原始 GeoJSON。
首先让 Layer 根据状态决定圆点样式:
map.addLayer({
id: 'places',
type: 'circle',
source: 'places-source',
paint: {
'circle-radius': [
'case',
['boolean', ['feature-state', 'selected'], false], 13,
['boolean', ['feature-state', 'hover'], false], 10,
6,
],
'circle-color': [
'case',
['boolean', ['feature-state', 'selected'], false], '#dc2626',
['boolean', ['feature-state', 'hover'], false], '#f59e0b',
'#2563eb',
],
},
})
这段表达式的结果很直接:普通圆点是蓝色,鼠标悬浮时变成较大的橙色圆点,选中后变成更大的红色圆点。
然后在鼠标移动时更新 hover。设置新对象前,必须先清除上一个对象的状态:
let hoveredId: string | number | undefined
function setHovered(nextId: string | number | undefined) {
if (hoveredId !== undefined) {
map.setFeatureState(
{ source: 'places-source', id: hoveredId },
{ hover: false },
)
}
hoveredId = nextId
if (nextId !== undefined) {
map.setFeatureState(
{ source: 'places-source', id: nextId },
{ hover: true },
)
}
}
选中状态使用同样的处理方式。Vue 中只保存一个 selectedId,地图点击、列表点击和详情面板都使用它,避免三个位置各自保存不同的选中结果:
watch(selectedId, (nextId, previousId) => {
if (previousId !== undefined) {
map.setFeatureState(
{ source: 'places-source', id: previousId },
{ selected: false },
)
}
if (nextId !== undefined) {
map.setFeatureState(
{ source: 'places-source', id: nextId },
{ selected: true },
)
}
})
setFeatureState() 需要稳定的 Feature ID。可以直接在 GeoJSON Feature 上设置 id;如果 ID 已经保存在 properties.businessId,则在 Source 中配置 promoteId: 'businessId'。
下面把鼠标移到圆点上,再点击圆点。你会依次看到橙色悬浮状态和红色选中状态;点击地图空白位置会清除选择。
⚠️ 查询到的是当前画面,不是完整数据
queryRenderedFeatures() 查询的是当前已经绘制到画面上的对象。对象不在视口内、被 filter 排除、因缩放级别而隐藏,或者尚未完成渲染时,都不会出现在结果中。
如果要在鼠标附近扩大点击范围,可以传入一个屏幕矩形:
const padding = 5
const box = [
[event.point.x - padding, event.point.y - padding],
[event.point.x + padding, event.point.y + padding],
]
const features = map.queryRenderedFeatures(box, {
layers: ['place-circles'],
})
这适合让细线或小点更容易点中,但不能代替完整数据查询。需要搜索视口外对象、分页或取得完整几何时,应查询业务接口或原始数据,再让地图负责显示结果。
🧾 小节总结
- Layer 点击事件用来取得用户点中的 Feature。
- Feature ID 用来确定对象身份,
properties用来显示业务信息。 queryRenderedFeatures()可以判断点击位置是否命中目标对象。- 查询结果受当前视口、筛选条件和缩放级别影响。
feature-state保存临时显示状态,不会修改原始 GeoJSON。- 切换悬浮或选中对象时,要先清除上一个对象的状态。
- Vue 中使用一个
selectedId统一地图、列表和详情面板。
❓ 知识问答
Q1:为什么点击圆点后读不到 ID?
该 GeoJSON Feature 没有 id,并且 Source 也没有通过 promoteId 指定业务 ID。
Q2:为什么鼠标经过的所有圆点都保持高亮?
设置新对象的 hover: true 前,没有把上一个对象改回 hover: false。
Q3:为什么点击空白位置无法关闭详情?
Layer 点击事件不会在空白处触发。需要监听地图点击,再用 queryRenderedFeatures() 判断结果是否为空。
🧪 小练习
- 点击圆点后,在页面上显示它的
name和status。 - 点击地图空白位置时,清除
selectedId和详情内容。
// 请在这里编写代码
🎉 恭喜你已经掌握点击查询与要素高亮啦!
