Mapbox iOS 集成模式

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

使用此技能的场景：

• - 安装和配置适用于 iOS 的 Mapbox Maps SDK
• 在地图上添加标记和注释
• 显示用户位置并通过相机进行跟踪
• 向地图添加自定义数据（GeoJSON）
• 处理地图样式、相机或用户交互
• 处理要素交互和点击

官方资源：

• - iOS 地图指南
• API 参考
• 示例应用

安装与设置

系统要求

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

第 1 步：配置访问令牌

将您的公共令牌添加到 Info.plist：

xml
MBXAccessToken
pk.yourmapboxtoken_here

获取令牌： 登录 mapbox.com

第 2 步：添加 Swift 包依赖

1. 1. 文件 → 添加包依赖
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+）

基础地图：

swift
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)
}
}

带装饰组件：

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

UIKit 模式

swift
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)
}
}

添加标记（点注释）

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

SwiftUI：

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

UIKit：

swift
// 创建注释管理器（一次创建，重复使用进行更新）
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]

多个标记：

swift
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 中添加位置权限：

xml
NSLocationWhenInUseUsageDescription
在地图上显示您的位置

第 2 步：请求权限并显示位置：

swift
import CoreLocation

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

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

性能最佳实践

复用注释管理器

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

// ✅ 一次创建，重复使用
let pointAnnotationManager: PointAnnotationManager

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

func updateMarkers() {
pointAnnotationManager.annotations = markers
}

批量更新注释

swift
// ✅ 一次性全部更新
pointAnnotationManager.annotations = newAnnotations

// ❌ 不要逐个更新
for annotation in newAnnotations {
pointAnnotationManager.annotations.append(annotation)
}

内存管理

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

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

使用标准样式

swift
// ✅ 标准样式经过优化，推荐使用
.mapStyle(.standard)

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

故障排除

地图未显示

检查：

1. 1. ✅ Info.plist 中的 MBXAccessToken
2. ✅ 令牌有效（在 mapbox.com 测试）
3. ✅ 已导入 MapboxMaps 框架
4. ✅ MapView 已添加到视图层级
5. ✅ 已设置正确的 frame/约束

样式未加载

swift
mapView.mapboxMap.onStyleLoaded.observe { [weak self] _ in
print(样式加载成功)
// 在此处添加图层和数据源
}.store(in: &cancelables)

性能问题

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

参考文件

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

• - references/annotations.md — 圆形、折线、多边形注释
• references/location-tracking.md — 相机跟随用户 + 获取当前位置
• references/custom-data.md — GeoJSON：线、多边形、点、更新/删除
• references/camera-styles.md — 相机控制 + 地图样式
• references/interactions.md — 要素集交互、自定义图层点击、长按、手势

其他资源

• - iOS 地图指南
• API 参考
• 交互指南
• SwiftUI 用户指南
• 示例应用
• 迁移指南（v10 → v11）