Mapbox中随缩放级别调整地图俯仰角的实现崩溃问题

希望实现用户放大地图时，地图俯仰角随缩放级别逐渐增大的效果，但怀疑由于.cameraChanged事件频繁触发，导致应用在地图初始加载时崩溃。

问题代码 #

override public func viewDidLoad() {
    let myResourceOptions = ResourceOptions(accessToken: "pk.ey###################")
    let myCameraOptions = CameraOptions(center: appState.myLocation.coordinate, zoom: 12)
    let myMapInitOptions = MapInitOptions(resourceOptions: myResourceOptions, cameraOptions: myCameraOptions, styleURI: StyleURI(url: URL(string: "mapbox://styles/myaccount/myMap")!)!)
    let myCameraBoundsOptions = CameraBoundsOptions(maxZoom: 18.5, minZoom: 11, maxPitch: 60, minPitch: 0)

    do {
        try mapView.mapboxMap.setCameraBounds(with: myCameraBoundsOptions)
        mapView.mapboxMap.onNext(event: .mapLoaded) { _ in
            // add sources, layers, etc
        }

        mapView.mapboxMap.onEvery(event: .cameraChanged, handler: { [weak self] _ in
            guard let self = self else { return }
            let pitch = ((self.mapView.mapboxMap.cameraState.zoom - self.mapView.mapboxMap.cameraBounds.minZoom)/(self.mapView.mapboxMap.cameraBounds.maxZoom - self.mapView.mapboxMap.cameraBounds.minZoom)) * 60
            let options = CameraOptions(pitch: pitch)
            self.mapView.mapboxMap.setCamera(to: options)
        })
    }
}

核心问题分析 #

在.cameraChanged事件回调中直接调用setCamera(to:)会再次触发.cameraChanged事件，形成无限递归循环，导致主线程阻塞甚至应用崩溃。同时，初始加载时地图资源未完全就绪，提前监听事件可能引发异常计算。

可行解决方法 #

1. 避免递归触发+防抖更新

添加状态标记防止递归调用，同时设置阈值过滤微小变化，配合短动画平滑过渡：

// 添加类属性
private var isUpdatingCamera = false
private let pitchUpdateThreshold: CGFloat = 0.5

override public func viewDidLoad() {
    let myResourceOptions = ResourceOptions(accessToken: "pk.ey###################")
    let myCameraOptions = CameraOptions(center: appState.myLocation.coordinate, zoom: 12)
    let myMapInitOptions = MapInitOptions(resourceOptions: myResourceOptions, cameraOptions: myCameraOptions, styleURI: StyleURI(url: URL(string: "mapbox://styles/myaccount/myMap")!)!)
    let myCameraBoundsOptions = CameraBoundsOptions(maxZoom: 18.5, minZoom: 11, maxPitch: 60, minPitch: 0)

    do {
        try mapView.mapboxMap.setCameraBounds(with: myCameraBoundsOptions)
        mapView.mapboxMap.onNext(event: .mapLoaded) { [weak self] _ in
            guard let self = self else { return }
            // 地图加载完成后再监听相机变化，避免初始状态异常
            self.setupCameraChangeListener()
            // add sources, layers, etc
        }
    }
}

private func setupCameraChangeListener() {
    mapView.mapboxMap.onEvery(event: .cameraChanged, handler: { [weak self] _ in
        guard let self = self else { return }
        // 正在更新相机时跳过当前回调，避免递归
        guard !self.isUpdatingCamera else { return }
        
        let cameraState = self.mapView.mapboxMap.cameraState
        let cameraBounds = self.mapView.mapboxMap.cameraBounds
        
        // 计算归一化缩放比例（限制在0-1区间，避免越界）
        let normalizedZoom = max(0, min(1, (cameraState.zoom - cameraBounds.minZoom)/(cameraBounds.maxZoom - cameraBounds.minZoom)))
        let targetPitch = normalizedZoom * 60
        
        // 只有当目标俯仰角与当前值差异超过阈值时才更新
        guard abs(targetPitch - cameraState.pitch) > self.pitchUpdateThreshold else { return }
        
        self.isUpdatingCamera = true
        let options = CameraOptions(pitch: targetPitch)
        // 用短动画平滑过渡，动画结束后重置状态标记
        self.mapView.mapboxMap.setCamera(to: options, animationDuration: 0.1) { _ in
            self.isUpdatingCamera = false
        }
    })
}

2. 改用相机过渡事件监听（非实时更新）

如果不需要实时跟随缩放变化，可以在缩放结束后一次性更新俯仰角，彻底避免频繁触发：

override public func viewDidLoad() {
    // ... 初始化代码不变 ...
    
    do {
        try mapView.mapboxMap.setCameraBounds(with: myCameraBoundsOptions)
        mapView.mapboxMap.onNext(event: .mapLoaded) { [weak self] _ in
            guard let self = self else { return }
            // 监听缩放结束事件
            self.mapView.mapboxMap.onEvery(event: .cameraTransitionEnded, handler: { [weak self] _ in
                guard let self = self else { return }
                let cameraState = self.mapView.mapboxMap.cameraState
                let cameraBounds = self.mapView.mapboxMap.cameraBounds
                let normalizedZoom = max(0, min(1, (cameraState.zoom - cameraBounds.minZoom)/(cameraBounds.maxZoom - cameraBounds.minZoom)))
                let targetPitch = normalizedZoom * 60
                let options = CameraOptions(pitch: targetPitch)
                self.mapView.mapboxMap.setCamera(to: options)
            })
            // add sources, layers, etc
        }
    }
}

关键优化点 #

• 延迟相机事件监听：等待mapLoaded事件触发后再设置监听器，确保地图资源和相机边界已正确初始化。
• 防止递归循环：通过isUpdatingCamera标记避免在相机更新过程中再次响应.cameraChanged事件。
• 阈值过滤：忽略微小的俯仰角变化，减少不必要的相机更新操作。
• 平滑动画：使用短时长动画过渡，提升用户体验的同时避免频繁触发事件。

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