React中Mapbox GL标记与标签重叠问题的解决方法

DevOps 小满

2026-7-18

在React中使用Mapbox GL避免标记与标签重叠的方案

问题背景

需要在React开发的Mapbox GL应用中解决标签位置接近时，所有缩放场景下的标记与标签重叠问题，已知text-allow-overlap、icon-allow-overlap等属性可用于处理重叠，但不清楚添加位置。

用户当前实现代码：

import React, {
    createRef,
    useMemo
} from "react";

import ReactMapboxGl, {
    Marker,
    ZoomControl
} from "!react-mapbox-gl";
import mapbox from './mapbox.png';
import './mapbox.css';
import mapboxgl from '!mapbox-gl';
import "mapbox-gl/dist/mapbox-gl.css";

const Map = ReactMapboxGl({
    accessToken: "some token",
});


function Mapbox(props) {

    const markers = props.locationData;
    const zoomValue = useMemo(() => markers.map(() => createRef()), []);
    const getZoomValue = (e) => {
        for (let i = 0; i < markers.length; i++) {
            if (zoomValue[i] !== null && zoomValue[i].current !== (undefined || null)) {
                if (e.getZoom() === 12) {
                    zoomValue[i].current.style.fontSize = "20px";
                    zoomValue[i].current.style.color = "yellow";
                } else if (e.getZoom() > 12 && e.getZoom() <= 15) {
                    zoomValue[i].current.style.fontSize = "15px";
                    zoomValue[i].current.style.color = "yellow";
                } else if (e.getZoom() > 15 && e.getZoom() <= 17) {
                    zoomValue[i].current.style.fontSize = "10px";
                    zoomValue[i].current.style.color = "yellow";
                } else if (e.getZoom() > 17) {
                    zoomValue[i].current.style.fontSize = "5px";
                    zoomValue[i].current.style.color = "yellow";
                }
            }
        }
    }

    return (
        <Map className="map-main"
            viewport={{
                latitude: 1.74328,
                longitude: 106.34792,
                zoom: 12,
            }}
            containerStyle={{
                width: "100vw",
            }}
            style=''
            center={[106.989441, 1.45678]}
            zoom={[12]}
            scrollZoom={true}
            boxZoom={true}
            onZoom={(e) => {
                getZoomValue(e)
            }}
            maxBounds={[
                [106.2006, 1.3890],
                [108.0700, 1.5680], {
                    padding: 200
                }
            ]}
            bearing={[217.3]} >
            <div>
                {markers.map((mark, index) => {
                    return (
                        <Marker key={index}
                            coordinates={[mark.eastLong, mark.northLat]}
                            anchor="bottom">
                            <div className="marker-text">
                                <img style={{
                                    width: '8px',
                                    height: '8px'
                                }}
                                    src={mapbox}
                                    alt="mark"></img>
                                <div ref={zoomValue[index]}
                                    className="marker-text">{mark?.location}</div>
                            </div>
                        </Marker>)
                })}
            </div>
            <ZoomControl position="top-left" />
        </Map>
    )
}

export default Mapbox;

解决方案

方法一：使用Mapbox原生符号层（推荐）

Mapbox原生的符号层（Symbol Layer）内置了标签避让逻辑，只需配置对应的layout属性即可自动处理重叠问题，这也是最简便的方案。

实现步骤：

引入Source和Layer组件（react-mapbox-gl库提供）
将标记数据转换为GeoJSON格式作为数据源
配置符号层的layout属性，设置text-allow-overlap: false和icon-allow-overlap: false，让Mapbox自动隐藏重叠的标签和图标

修改后的代码示例：

import React, { useMemo } from "react";
import ReactMapboxGl, { Source, Layer, ZoomControl } from "!react-mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";

const Map = ReactMapboxGl({
    accessToken: "some token",
});

function Mapbox(props) {
    const markers = props.locationData;

    // 将标记数据转换为GeoJSON格式
    const geoJsonData = useMemo(() => ({
        type: "FeatureCollection",
        features: markers.map(mark => ({
            type: "Feature",
            properties: {
                location: mark.location
            },
            geometry: {
                type: "Point",
                coordinates: [mark.eastLong, mark.northLat]
            }
        }))
    }), [markers]);

    // 图标样式（对应原代码中的自定义图标）
    const iconLayer = {
        id: "markers-icon",
        type: "symbol",
        layout: {
            "icon-image": "custom-marker",
            "icon-size": 0.1, // 匹配原代码中8px的图标大小比例
            "icon-allow-overlap": false, // 禁止图标重叠
            "icon-ignore-placement": false
        }
    };

    // 标签样式，通过stops配置不同缩放级别下的字体大小
    const textLayer = {
        id: "markers-text",
        type: "symbol",
        layout: {
            "text-field": ["get", "location"],
            "text-font": ["Open Sans Bold", "Arial Unicode MS Bold"],
            "text-size": {
                stops: [
                    [12, 20],
                    [15, 15],
                    [17, 10],
                    [18, 5]
                ]
            },
            "text-color": "yellow",
            "text-allow-overlap": false, // 禁止标签重叠
            "text-ignore-placement": false,
            "text-offset": [0, -1.5], // 标签位于图标上方
            "text-anchor": "top"
        }
    };

    return (
        <Map className="map-main"
            viewport={{
                latitude: 1.74328,
                longitude: 106.34792,
                zoom: 12,
            }}
            containerStyle={{
                width: "100vw",
            }}
            style=''
            center={[106.989441, 1.45678]}
            zoom={[12]}
            scrollZoom={true}
            boxZoom={true}
            maxBounds={[
                [106.2006, 1.3890],
                [108.0700, 1.5680], {
                    padding: 200
                }
            ]}
            bearing={[217.3]} >
            {/* 加载自定义图标到Mapbox */}
            <Map.Context.Consumer>
                {map => {
                    map.loadImage('/mapbox.png', (error, image) => {
                        if (error) throw error;
                        if (!map.hasImage('custom-marker')) {
                            map.addImage('custom-marker', image);
                        }
                    });
                    return null;
                }}
            </Map.Context.Consumer>

            {/* 标记数据源 */}
            <Source id="markers-source" type="geojson" data={geoJsonData} />

            {/* 图标层 */}
            <Layer {...iconLayer} source="markers-source" />

            {/* 标签层 */}
            <Layer {...textLayer} source="markers-source" />

            <ZoomControl position="top-left" />
        </Map>
    )
}

export default Mapbox;

属性说明：

text-allow-overlap: false：禁止标签重叠，当空间不足时Mapbox会自动隐藏部分标签
icon-allow-overlap: false：禁止图标重叠
text-size使用stops配置，替代原代码中通过zoom事件动态修改样式的逻辑，更符合Mapbox原生规范

方法二：自定义DOM Marker的重叠检测（仅特殊场景使用）

如果必须使用自定义DOM元素作为Marker，需要自行实现重叠检测逻辑：

监听地图的zoom和move事件，获取每个Marker的屏幕坐标
计算每个标签的DOM元素边界，检测是否与其他标签重叠
隐藏重叠的标签或调整其位置

这种方案需要编写较多计算逻辑，性能不如原生符号层，仅推荐在特殊需求场景下使用。

内容的提问来源于stack exchange，提问作者Inspond

React中Mapbox GL标记与标签重叠问题的解决方法

问题背景 #

解决方案 #

方法一：使用Mapbox原生符号层（推荐） #