Mapbox iOS 集成模式

在 iOS 平台上使用 Swift、SwiftUI 和 UIKit 集成 Mapbox Maps SDK v11 的官方推荐模式。

适用场景：

• 安装与配置 Mapbox Maps SDK for iOS
• 向地图添加标记（Markers）和注释（Annotations）
• 显示用户位置并结合相机（Camera）实现位置追踪
• 向地图添加自定义数据（GeoJSON）
• 操作地图样式（Map Styles）、相机（Camera）或用户交互行为
• 处理要素（Feature）交互与点击事件

官方资源：

• iOS Maps 指南
• API 参考文档
• 示例应用

安装与配置

系统要求

• iOS 12+
• Xcode 15+
• Swift 5.9+
• 免费的 Mapbox 账户

步骤 1：配置访问令牌（Access Token）

将您的公开令牌（public token）添加至 Info.plist：

MBXAccessToken
pk.your_mapbox_token_here

获取您的令牌：请登录 mapbox.com

步骤 2：添加 Swift Package 依赖

1. File → Add Package Dependencies
2. 输入 URL：https://github.com/mapbox/mapbox-maps-ios.git
3. 版本选择：从 11.0.0 开始选择 “Up to Next Major”
4. 确认以下四个依赖项已正确引入：MapboxCommon、MapboxCoreMaps、MapboxMaps、Turf

替代方案：CocoaPods 或直接下载（详见安装指南）

地图初始化

SwiftUI 模式（iOS 13+）

基础地图：

import SwiftUI
import MapboxMaps

struct ContentView: View {
    @State private var viewport: Viewport = .camera(
        center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
        zoom: 12
    )

    var body: some View {
        Map(viewport: $viewport)
            .mapStyle(.standard)
    }
}

启用控件装饰（Ornaments）：

Map(viewport: $viewport)
    .mapStyle(.standard)
    .ornamentOptions(OrnamentOptions(
        scaleBar: .init(visibility: .visible),
        compass: .init(visibility: .adaptive),
        logo: .init(position: .bottomLeading)
    ))

UIKit 模式

import UIKit
import MapboxMaps

class MapViewController: UIViewController {
    private var mapView: MapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let options = MapInitOptions(
            cameraOptions: CameraOptions(
                center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
                zoom: 12
            )
        )

        mapView = MapView(frame: view.bounds, mapInitOptions: options)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)

        mapView.mapboxMap.loadStyle(.standard)
    }
}

添加标记（点注释，Point Annotations）

点注释是地图上标注位置最常用的方式。

SwiftUI：

Map(viewport: $viewport) {
    PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
        .iconImage("custom-marker")
}

UIKit：

// 创建注释管理器（仅需一次，后续复用）
var pointAnnotationManager = mapView.annotations.makePointAnnotationManager()

// 创建标记
var annotation = PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))
annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
annotation.iconAnchor = .bottom

// 添加至地图
pointAnnotationManager.annotations = [annotation]

多个标记：

let locations = [
    CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
    CLLocationCoordinate2D(latitude: 37.7849, longitude: -122.4094),
    CLLocationCoordinate2D(latitude: 37.7649, longitude: -122.4294)
]

let annotations = locations.map { coordinate in
    var annotation = PointAnnotation(coordinate: coordinate)
    annotation.image = .init(image: UIImage(named: "marker")!, name: "marker")
    return annotation
}

pointAnnotationManager.annotations = annotations

显示用户位置

步骤 1：在 Info.plist 中添加定位权限声明：

NSLocationWhenInUseUsageDescription
在地图上显示您的位置

步骤 2：请求权限并启用用户位置指示器（Puck）：

import CoreLocation

// 请求权限
let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()

// 显示用户位置指示器（2D puck）
mapView.location.options.puckType = .puck2D()
mapView.location.options.puckBearingEnabled = true

性能最佳实践

复用注释管理器（Annotation Managers）

// ❌ 避免重复创建新管理器
func updateMarkers() {
    let manager = mapView.annotations.makePointAnnotationManager()
    manager.annotations = markers
}

// ✅ 创建一次，长期复用
let pointAnnotationManager: PointAnnotationManager

init() {
    pointAnnotationManager = mapView.annotations.makePointAnnotationManager()
}

func updateMarkers() {
    pointAnnotationManager.annotations = markers
}

批量更新注释

// ✅ 一次性批量更新
pointAnnotationManager.annotations = newAnnotations

// ❌ 避免逐个追加
for annotation in newAnnotations {
    pointAnnotationManager.annotations.append(annotation)
}

内存管理

// 在闭包中使用 weak self
mapView.gestures.onMapTap.observe { [weak self] context in
    self?.handleTap(context.coordinate)
}.store(in: &cancelables)

// 在 deinit 中清理资源
deinit {
    cancelables.forEach { $0.cancel() }
}

优先使用标准样式（Standard Style）

// ✅ 标准样式已针对性能优化，为官方推荐
.mapStyle(.standard)

// 其他样式仅在特定需求下使用
.mapStyle(.standardSatellite) // 卫星影像

问题排查

地图未显示

请检查：

1. ✅ MBXAccessToken 是否已正确配置于 Info.plist
2. ✅ 访问令牌是否有效（可在 mapbox.com 测试）
3. ✅ 是否已导入 MapboxMaps 框架
4. ✅ MapView 是否已加入视图层级（view hierarchy）
5. ✅ 是否设置了正确的 frame 或 Auto Layout 约束

地图样式未加载

mapView.mapboxMap.onStyleLoaded.observe { [weak self] _ in
    print("样式加载成功")
    // 此处添加图层（layers）与数据源（sources）
}.store(in: &cancelables)

性能问题

• 优先使用 .standard 样式（推荐且已优化）
• 限制视口（viewport）内可见的注释数量
• 复用注释管理器
• 避免频繁重载样式
• 采用批量方式更新注释

参考文件

当任务需要更深入的实现模式时，请加载以下参考文档：

• references/annotations.md — 圆形（Circle）、折线（Polyline）、多边形（Polygon）注释
• references/location-tracking.md — 相机跟随用户 + 获取当前位置
• references/custom-data.md — GeoJSON：线、面、点数据的加载、更新与移除
• references/camera-styles.md — 相机控制（Camera Control）与地图样式（Map Styles）
• references/interactions.md — 要素集（Featureset）交互、自定义图层点击、长按、手势等

附加资源

• iOS Maps 指南
• API 参考文档
• 交互指南（Interactions Guide）
• SwiftUI 用户指南（SwiftUI User Guide）
• 示例应用（Example Apps）
• 迁移指南（v10 → v11）