MapBox NavigationMapView中如何让导航路线显示在瓦片覆盖层上方？

API 探路者

2026-6-20

解决Mapbox导航路线被瓦片覆盖层遮挡的问题

问题分析

你在使用NavigationViewController实现逐向导航时，添加瓦片覆盖层后，起点/终点标记能正常显示在覆盖层上方，但导航路线却无法显示。核心原因是瓦片覆盖层被错误地添加到了导航路线层的上方，导致路线被完全遮挡，且当前代码中定位导航层的逻辑不准确，无法确保瓦片层处于正确层级。

解决方案

Mapbox Navigation的路线有固定的核心层ID：route-layer（路线主体）和route-casing-layer（路线轮廓）。我们需要确保瓦片覆盖层被添加到这些路线层的下方，让路线正常显示在覆盖层之上。

修改层级定位逻辑

替换原有的getLayerPositionBelowNavigation函数，直接定位到导航路线的专属层ID：

func getLayerPositionBelowNavigation(for mapView: NavigationMapView) -> LayerPosition {
    // Mapbox Navigation 默认的路线层ID集合
    let routeLayerIds = ["route-casing-layer", "route-layer"]
    
    // 优先将瓦片层添加到路线轮廓层下方，确保完整路线都在上方
    for layerId in routeLayerIds {
        if mapView.mapView.mapboxMap.style.layerExists(withId: layerId) {
            return .below(layerId)
        }
    }
    
    //  fallback 位置：确保瓦片层在基础地图之上，路线层之下
    return .above("water")
}

确保添加时机正确

需要在NavigationMapView的样式加载完成后再添加瓦片覆盖层，避免路线层尚未创建导致层级设置失效。可以在视图控制器的viewDidAppear或者地图样式加载回调中调用addRasterSource：

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    addRasterSource(for: navigationMapView)
}

// 或者通过地图加载回调监听
func mapView(_ mapView: MapView, didFinishLoading style: Style) {
    addRasterSource(for: navigationMapView)
}