点击要素、查询与高亮

点击和查询地图要素,读取业务属性,并用 feature-state 实现悬浮与选中高亮。

🎯 引言

学完本文,你能知道用户点击了地图上的哪个对象、读取它的属性,并通过颜色和大小变化显示悬浮与选中状态。

这套交互常用于“点击地图上的点,在旁边显示详情”。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、名称和状态;鼠标进入圆点时也会变成手型。

点击任意圆点,查看它的 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。结果为空,说明这里没有目标对象,因此可以关闭详情或清除选择。

它查询的是当前屏幕中已经画出来的对象,不是 Source 中的全部数据。被隐藏、被过滤或位于屏幕外的对象不会返回。

下面分别点击紫色圆点和地图空白位置,观察查询数量为什么分别是 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() 判断结果是否为空。


🧪 小练习

  1. 点击圆点后,在页面上显示它的 name 和 status。
  2. 点击地图空白位置时,清除 selectedId 和详情内容。
// 请在这里编写代码

🎉 恭喜你已经掌握点击查询与要素高亮啦!