axiom-mapkit-ref

MapKit API 参考

iOS 开发的完整 MapKit API 参考。涵盖 SwiftUI Map（iOS 17+）和 MKMapView（UIKit）。

相关技能

• axiom-mapkit — 决策树、反模式、压力场景
• axiom-mapkit-diag — 基于症状的故障排查

---

第 1 部分：现代 API 概览

功能	SwiftUI Map（iOS 17+）	MKMapView
声明	Map(position:) { content }	MKMapView()
摄像头控制	MapCameraPosition 绑定	setRegion(_:animated:)
标注	内容中的 Marker、Annotation	addAnnotation(_:) + 代理
覆盖层	MapCircle、MapPolyline、MapPolygon	addOverlay(_:) + 渲染器代理
用户位置	UserAnnotation()	showsUserLocation = true
选择	.mapSelection($selection)	代理 didSelect
控件	.mapControls { }	showsCompass、showsScale
交互模式	.mapInteractionModes([])	代理方法
聚类	通过 .mapItemClusteringIdentifier 内置支持	MKClusterAnnotation

---

第 2 部分：SwiftUI Map API

基本地图

@State private var cameraPosition: MapCameraPosition = .automatic

Map(position: $cameraPosition) {
    Marker("Home", coordinate: homeCoord)
    Annotation("Custom", coordinate: coord) {
        Image(systemName: "star.fill")
            .foregroundStyle(.yellow)
            .padding(4)
            .background(.blue, in: Circle())
    }
    UserAnnotation()
    MapCircle(center: coord, radius: 500)
        .foregroundStyle(.blue.opacity(0.3))
    MapPolyline(coordinates: routeCoords)
        .stroke(.blue, lineWidth: 3)
}
.mapStyle(.standard(elevation: .realistic))
.mapControls {
    MapUserLocationButton()
    MapCompass()
    MapScaleView()
}

MapCameraPosition

控制摄像头的位置：

// System manages camera to show all content
.automatic

// Specific region
.region(MKCoordinateRegion(
    center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
    span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
))

// Specific camera with pitch and heading
.camera(MapCamera(
    centerCoordinate: coordinate,
    distance: 1000,    // meters from center
    heading: 90,       // degrees from north
    pitch: 60          // degrees from vertical (0 = top-down)
))

// Follow user location
.userLocation(followsHeading: true, fallback: .automatic)

// Show specific item
.item(mapItem)

// Show specific rect
.rect(MKMapRect(...))

以编程方式更改摄像头

// Animate to new position
withAnimation {
    cameraPosition = .region(newRegion)
}

// Keyframe animation (iOS 17+)
Map(position: $cameraPosition)
    .mapCameraKeyframeAnimator(trigger: flyToTrigger) { initialCamera in
        KeyframeTrack(\.centerCoordinate) {
            LinearKeyframe(destination, duration: 2.0)
        }
        KeyframeTrack(\.distance) {
            CubicKeyframe(5000, duration: 1.0)
            CubicKeyframe(1000, duration: 1.0)
        }
    }

地图选择

@State private var selectedItem: MKMapItem?

Map(position: $cameraPosition, selection: $selectedItem) {
    ForEach(mapItems, id: \.self) { item in
        Marker(item: item)
    }
}
.onChange(of: selectedItem) { _, newItem in
    if let newItem {
        // Handle selection
    }
}

摄像头变化回调

Map(position: $cameraPosition) { ... }
    .onMapCameraChange { context in
        // context.region — visible MKCoordinateRegion
        // context.camera — current MapCamera
        // context.rect — visible MKMapRect
        fetchAnnotations(in: context.region)
    }
    .onMapCameraChange(frequency: .continuous) { context in
        // Called during gesture (not just at end)
    }

地图样式

.mapStyle(.standard)                              // Default
.mapStyle(.standard(elevation: .realistic))        // 3D buildings
.mapStyle(.standard(emphasis: .muted))             // Muted colors
.mapStyle(.standard(pointsOfInterest: .including([.restaurant, .cafe])))
.mapStyle(.imagery)                                // Satellite
.mapStyle(.imagery(elevation: .realistic))         // 3D satellite
.mapStyle(.hybrid)                                 // Satellite + labels
.mapStyle(.hybrid(elevation: .realistic))          // 3D hybrid

交互模式

// Allow all interactions (default)
.mapInteractionModes(.all)

// Read-only map (no interaction)
.mapInteractionModes([])

// Pan only, no zoom
.mapInteractionModes([.pan])

// Pan and zoom, no rotate/pitch
.mapInteractionModes([.pan, .zoom])

---

第 3 部分：地图内容

Marker

带有标注气泡的系统样式地图标记：

// Basic marker
Marker("Coffee Shop", coordinate: coord)

// With system image
Marker("Coffee Shop", systemImage: "cup.and.saucer.fill", coordinate: coord)

// With monogram (2 characters max)
Marker("Coffee Shop", monogram: Text("CS"), coordinate: coord)

// Color
Marker("Coffee Shop", coordinate: coord)
    .tint(.brown)

// From MKMapItem
Marker(item: mapItem)

Annotation

坐标处的完全自定义视图：

Annotation("Custom Pin", coordinate: coord) {
    VStack {
        Image(systemName: "mappin.circle.fill")
            .font(.title)
            .foregroundStyle(.red)
        Text("Here")
            .font(.caption)
    }
}

// Anchor point (default is bottom center)
Annotation("Pin", coordinate: coord, anchor: .center) {
    Circle()
        .fill(.blue)
        .frame(width: 20, height: 20)
}

UserAnnotation

当前用户位置指示器：

UserAnnotation()

// Custom appearance
UserAnnotation(anchor: .center) {
    Image(systemName: "location.circle.fill")
        .foregroundStyle(.blue)
}

形状覆盖层

// Circle
MapCircle(center: coord, radius: 1000)  // radius in meters
    .foregroundStyle(.blue.opacity(0.2))
    .stroke(.blue, lineWidth: 2)

// Polygon
MapPolygon(coordinates: polygonCoords)
    .foregroundStyle(.green.opacity(0.3))
    .stroke(.green, lineWidth: 2)

// Polyline
MapPolyline(coordinates: routeCoords)
    .stroke(.blue, lineWidth: 4)

// From MKRoute
MapPolyline(route.polyline)
    .stroke(.blue, lineWidth: 5)

聚类

ForEach(locations) { location in
    Marker(location.name, coordinate: location.coordinate)
        .tag(location.id)
}
.mapItemClusteringIdentifier("locations")

---

第 4 部分：MKMapView 生命周期与代理

在 SwiftUI 中创建 MKMapView

struct MapViewWrapper: UIViewRepresentable {
    @Binding var region: MKCoordinateRegion
    let annotations: [MKAnnotation]

    func makeUIView(context: Context) -> MKMapView {
        let mapView = MKMapView()
        mapView.delegate = context.coordinator
        mapView.showsUserLocation = true
        mapView.register(
            MKMarkerAnnotationView.self,
            forAnnotationViewWithReuseIdentifier: "marker"
        )
        return mapView
    }

    func updateUIView(_ mapView: MKMapView, context: Context) {
        // Guard against infinite loops
        if !regionsAreEqual(mapView.region, region) {
            mapView.setRegion(region, animated: true)
        }

        // Diff annotations instead of removing all
        let current = Set(mapView.annotations.compactMap { $0 as? MyAnnotation })
        let desired = Set(annotations.compactMap { $0 as? MyAnnotation })
        let toAdd = desired.subtracting(current)
        let toRemove = current.subtracting(desired)
        mapView.addAnnotations(Array(toAdd))
        mapView.removeAnnotations(Array(toRemove))
    }

    func makeCoordinator() -> Coordinator {
        Coordinator(self)
    }

    static func dismantleUIView(_ mapView: MKMapView, coordinator: Coordinator) {
        mapView.removeAnnotations(mapView.annotations)
        mapView.removeOverlays(mapView.overlays)
    }
}

关键 MKMapViewDelegate 方法

class Coordinator: NSObject, MKMapViewDelegate {
    var parent: MapViewWrapper

    init(_ parent: MapViewWrapper) {
        self.parent = parent
    }

    // Annotation view customization
    func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
        guard !(annotation is MKUserLocation) else { return nil }  // Use default for user

        let view = mapView.dequeueReusableAnnotationView(
            withIdentifier: "marker",
            for: annotation
        ) as! MKMarkerAnnotationView
        view.markerTintColor = .systemRed
        view.glyphImage = UIImage(systemName: "mappin")
        view.clusteringIdentifier = "poi"
        view.canShowCallout = true
        return view
    }

    // Overlay rendering
    func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
        if let circle = overlay as? MKCircle {
            let renderer = MKCircleRenderer(circle: circle)
            renderer.fillColor = UIColor.systemBlue.withAlphaComponent(0.2)
            renderer.strokeColor = .systemBlue
            renderer.lineWidth = 2
            return renderer
        }
        if let polyline = overlay as? MKPolyline {
            let renderer = MKPolylineRenderer(polyline: polyline)
            renderer.strokeColor = .systemBlue
            renderer.lineWidth = 4
            return renderer
        }
        if let polygon = overlay as? MKPolygon {
            let renderer = MKPolygonRenderer(polygon: polygon)
            renderer.fillColor = UIColor.systemGreen.withAlphaComponent(0.3)
            renderer.strokeColor = .systemGreen
            renderer.lineWidth = 2
            return renderer
        }
        return MKOverlayRenderer(overlay: overlay)
    }

    // Region change tracking
    func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool) {
        parent.region = mapView.region
    }

    // Annotation selection
    func mapView(_ mapView: MKMapView, didSelect annotation: MKAnnotation) {
        // Handle tap
    }

    // Cluster annotation
    func mapView(
        _ mapView: MKMapView,
        clusterAnnotationForMemberAnnotations memberAnnotations: [MKAnnotation]
    ) -> MKClusterAnnotation {
        MKClusterAnnotation(memberAnnotations: memberAnnotations)
    }
}

---

第 5 部分：标注类型与自定义

MKMarkerAnnotationView（iOS 11+）

带有字形的气球形标记：

let view = MKMarkerAnnotationView(annotation: annotation, reuseIdentifier: "marker")
view.markerTintColor = .systemPurple
view.glyphImage = UIImage(systemName: "star.fill")
view.glyphText = "A"                    // Text glyph (overrides image)
view.displayPriority = .required        // Always visible
view.clusteringIdentifier = "category"  // Enable clustering
view.canShowCallout = true
view.titleVisibility = .adaptive        // Show title based on space
view.subtitleVisibility = .hidden

MKAnnotationView

完全自定义的标注视图：

let view = MKAnnotationView(annotation: annotation, reuseIdentifier: "custom")
view.image = UIImage(named: "custom-pin")
view.centerOffset = CGPoint(x: 0, y: -view.image!.size.height / 2)
view.canShowCallout = true
view.leftCalloutAccessoryView = UIImageView(image: thumbnail)
view.rightCalloutAccessoryView = UIButton(type: .detailDisclosure)

自定义标注气泡

func mapView(
    _ mapView: MKMapView,
    annotationView view: MKAnnotationView,
    calloutAccessoryControlTapped control: UIControl
) {
    guard let annotation = view.annotation as? MyAnnotation else { return }
    // Navigate to detail view
}

重用标注视图

始终使用 dequeueReusableAnnotationView(withIdentifier:for:)：

// Register in makeUIView (once)
mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: "marker")

// Dequeue in delegate (every time)
func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
    let view = mapView.dequeueReusableAnnotationView(withIdentifier: "marker", for: annotation)
    // Configure...
    return view
}

不进行重用：1000 个标注 = 内存中有 1000 个视图。 进行重用：用户滚动时循环使用约 20-30 个视图。

---

第 6 部分：MKLocalSearch 和 MKLocalSearchCompleter

MKLocalSearchCompleter — 实时自动补全

let completer = MKLocalSearchCompleter()
completer.delegate = self
completer.resultTypes = [.pointOfInterest, .address]
completer.region = visibleMapRegion    // Bias results to visible area

// Update on each keystroke
completer.queryFragment = "coffee"

// Delegate receives results
func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
    let results = completer.results  // [MKLocalSearchCompletion]
    for result in results {
        // result.title — "Starbucks"
        // result.subtitle — "123 Main St, San Francisco, CA"
        // result.titleHighlightRanges — Ranges matching query
    }
}

func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
    // Network error, rate limit, etc.
}

MKLocalSearch — 完整搜索

// From autocomplete completion
let request = MKLocalSearch.Request(completion: selectedCompletion)

// From natural language
let request = MKLocalSearch.Request()
request.naturalLanguageQuery = "coffee shops"
request.region = mapRegion                        // Bias results
request.resultTypes = .pointOfInterest            // Filter type
request.pointOfInterestFilter = MKPointOfInterestFilter(
    including: [.cafe, .restaurant]
)

let search = MKLocalSearch(request: request)
let response = try await search.start()

for item in response.mapItems {
    // item.name — "Starbucks"
    // item.placemark — MKPlacemark with address
    // item.placemark.coordinate — CLLocationCoordinate2D
    // item.phoneNumber — optional phone
    // item.url — optional website
    // item.pointOfInterestCategory — .cafe, .restaurant, etc.
}

结果类型

// Filter what kind of results to return
request.resultTypes = .address           // Street addresses only
request.resultTypes = .pointOfInterest   // Businesses, landmarks
request.resultTypes = .physicalFeature   // Mountains, lakes, parks
request.resultTypes = .query             // Suggested search queries (iOS 18+)
request.resultTypes = [.pointOfInterest, .address]  // Multiple types

速率限制

• MKLocalSearchCompleter 会自行处理节流，可安全地在每次按键时调用
• MKLocalSearch — Apple 会对其进行速率限制，请勿以超过约每秒 1 次的频率发起请求
• 如果触发速率限制，完成处理程序会收到错误
• 重用 MKLocalSearchCompleter 实例，不要为每次查询都创建新实例

---

第 7 部分：MKDirections 和 MKRoute

计算路线

let request = MKDirections.Request()
request.source = MKMapItem.forCurrentLocation()
request.destination = destinationMapItem
request.transportType = .automobile
request.requestsAlternateRoutes = true   // Get multiple routes

let directions = MKDirections(request: request)
let response = try await directions.calculate()

for route in response.routes {
    route.polyline                  // MKPolyline — display on map
    route.expectedTravelTime       // TimeInterval in seconds
    route.distance                 // CLLocationDistance in meters
    route.name                     // "I-280 S" — route name
    route.advisoryNotices          // [String] — warnings
    route.steps                    // [MKRoute.Step] — turn-by-turn
}

交通方式

.automobile    // Driving directions
.walking       // Pedestrian directions
.transit       // Public transit (where available)
.any           // All modes

仅获取预计到达时间（更快）

let directions = MKDirections(request: request)
let eta = try await directions.calculateETA()
eta.expectedTravelTime     // TimeInterval
eta.distance               // CLLocationDistance
eta.expectedArrivalDate    // Date
eta.expectedDepartureDate  // Date
eta.transportType          // MKDirectionsTransportType

逐向导航步骤

for step in route.steps {
    step.instructions    // "Turn right onto Main St"
    step.distance        // CLLocationDistance in meters
    step.polyline        // MKPolyline for this step's segment
    step.transportType   // May change for transit routes
    step.notice          // Optional advisory
}

---

第 8 部分：Look Around

检查可用性

let request = MKLookAroundSceneRequest(coordinate: coordinate)
do {
    let scene = try await request.scene
    // scene is non-nil — Look Around available at this coordinate
} catch {
    // Look Around not available here
}

SwiftUI

@State private var lookAroundScene: MKLookAroundScene?

LookAroundPreview(scene: $lookAroundScene)
    .frame(height: 200)

// Load scene
func loadLookAround(for coordinate: CLLocationCoordinate2D) async {
    let request = MKLookAroundSceneRequest(coordinate: coordinate)
    lookAroundScene = try? await request.scene
}

UIKit

let controller = MKLookAroundViewController(scene: scene)
// Present modally or embed as child view controller

静态快照

let snapshotter = MKLookAroundSnapshotter(scene: scene, options: .init())
let snapshot = try await snapshotter.snapshot
let image = snapshot.image  // UIImage

---

第 9 部分：覆盖层与渲染器

添加覆盖层（MKMapView）

// Circle
let circle = MKCircle(center: coordinate, radius: 1000)
mapView.addOverlay(circle)

// Polygon
let polygon = MKPolygon(coordinates: &coords, count: coords.count)
mapView.addOverlay(polygon)

// Polyline
let polyline = MKPolyline(coordinates: &coords, count: coords.count)
mapView.addOverlay(polyline, level: .aboveRoads)

// Custom tile overlay
let template = "https://tile.example.com/{z}/{x}/{y}.png"
let tileOverlay = MKTileOverlay(urlTemplate: template)
tileOverlay.canReplaceMapContent = true  // Hides Apple Maps base layer
mapView.addOverlay(tileOverlay, level: .aboveLabels)

渲染器代理

func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
    switch overlay {
    case let circle as MKCircle:
        let renderer = MKCircleRenderer(circle: circle)
        renderer.fillColor = UIColor.systemBlue.withAlphaComponent(0.2)
        renderer.strokeColor = .systemBlue
        renderer.lineWidth = 2
        return renderer

    case let polyline as MKPolyline:
        let renderer = MKPolylineRenderer(polyline: polyline)
        renderer.strokeColor = .systemBlue
        renderer.lineWidth = 4
        return renderer

    case let polygon as MKPolygon:
        let renderer = MKPolygonRenderer(polygon: polygon)
        renderer.fillColor = UIColor.systemGreen.withAlphaComponent(0.3)
        renderer.strokeColor = .systemGreen
        renderer.lineWidth = 2
        return renderer

    case let tile as MKTileOverlay:
        return MKTileOverlayRenderer(tileOverlay: tile)

    default:
        return MKOverlayRenderer(overlay: overlay)
    }
}

覆盖层级别

mapView.addOverlay(overlay, level: .aboveRoads)    // Above roads, below labels
mapView.addOverlay(overlay, level: .aboveLabels)   // Above everything

渐变折线

let renderer = MKGradientPolylineRenderer(polyline: polyline)
renderer.setColors([.green, .yellow, .red], locations: [0.0, 0.5, 1.0])
renderer.lineWidth = 6

---

第 10 部分：地图快照

生成静态地图图像，用于分享、缩略图或离线显示：

let options = MKMapSnapshotter.Options()
options.region = MKCoordinateRegion(
    center: coordinate,
    span: MKCoordinateSpan(latitudeDelta: 0.01, longitudeDelta: 0.01)
)
options.size = CGSize(width: 300, height: 200)
options.scale = UIScreen.main.scale           // Retina support
options.mapType = .standard
options.showsBuildings = true
options.pointOfInterestFilter = .excludingAll  // Clean map

let snapshotter = MKMapSnapshotter(options: options)
let snapshot = try await snapshotter.start()
let image = snapshot.image

// Draw custom annotations on snapshot
UIGraphicsBeginImageContextWithOptions(image.size, true, image.scale)
image.draw(at: .zero)

let pinImage = UIImage(systemName: "mappin.circle.fill")!
let point = snapshot.point(for: coordinate)
pinImage.draw(at: CGPoint(
    x: point.x - pinImage.size.width / 2,
    y: point.y - pinImage.size.height
))

let finalImage = UIGraphicsGetImageFromCurrentImageContext()
UIGraphicsEndImageContext()

快照坐标转换

// Convert coordinate to point in snapshot image
let point = snapshot.point(for: coordinate)

// Check if coordinate is in snapshot bounds
let isVisible = CGRect(origin: .zero, size: snapshot.image.size).contains(point)

第 11 部分：iOS 版本功能矩阵

功能	iOS 版本
MKMapView	3.0+
MKLocalSearch	6.1+
MKDirections	7.0+
MKMarkerAnnotationView	11.0+
MKMapSnapshotter	7.0+
MKLookAroundSceneRequest	16.0+
LookAroundPreview (SwiftUI)	17.0+
SwiftUI Map (content builder)	17.0+
MapCameraPosition	17.0+
.mapSelection	17.0+
.mapCameraKeyframeAnimator	17.0+
.onMapCameraChange	17.0+
MapUserLocationButton	17.0+
MapCompass	17.0+
MapScaleView	17.0+
.mapInteractionModes	17.0+
MKLocalSearch.ResultType.query	18.0+
GeoToolbox / PlaceDescriptor	26.0+
MKGeocodingRequest	26.0+
MKReverseGeocodingRequest	26.0+
MKAddress	26.0+

---

第 12 部分：GeoToolbox 和地理编码

GeoToolbox 框架

GeoToolbox 提供 PlaceDescriptor，用于标准化表示物理位置，并兼容 MapKit 和第三方地图服务。

import GeoToolbox

// From address
let fountain = PlaceDescriptor(
    representations: [.address("121-122 James's St \n Dublin 8 \n D08 ET27 \n Ireland")],
    commonName: "Obelisk Fountain"
)

// From coordinates
let tower = PlaceDescriptor(
    representations: [.coordinate(CLLocationCoordinate2D(latitude: 48.8584, longitude: 2.2945))],
    commonName: "Eiffel Tower"
)

// Multiple representations
let statue = PlaceDescriptor(
    representations: [
        .coordinate(CLLocationCoordinate2D(latitude: 40.6892, longitude: -74.0445)),
        .address("Liberty Island, New York, NY 10004, United States")
    ],
    commonName: "Statue of Liberty"
)

// From MKMapItem
let descriptor = PlaceDescriptor(item: mapItem)  // Returns optional

PlaceRepresentation

使用常见地图概念表示地点的枚举：

枚举项	用法
.coordinate(CLLocationCoordinate2D)	纬度／经度
.address(String)	完整地址字符串

PlaceDescriptor 上的便捷访问器：

descriptor.coordinate  // CLLocationCoordinate2D?
descriptor.address     // String?
descriptor.commonName  // String?

SupportingPlaceRepresentation

来自不同地图服务的地点专属标识符：

let place = PlaceDescriptor(
    representations: [.coordinate(CLLocationCoordinate2D(latitude: 51.5074, longitude: -0.1278))],
    commonName: "London Eye",
    supportingRepresentations: [
        .serviceIdentifiers([
            "com.apple.maps": "AppleMapsID123",
            "com.google.maps": "GoogleMapsID456"
        ])
    ]
)

// Retrieve a specific service identifier
let appleID = place.serviceIdentifier(for: "com.apple.maps")

MKGeocodingRequest — 正向地理编码

将地址字符串转换为地图项（地址转换为坐标）：

guard let request = MKGeocodingRequest(addressString: "1 Apple Park Way, Cupertino, CA") else {
    return
}
let mapItems = try await request.mapItems

MKReverseGeocodingRequest — 反向地理编码

将坐标转换为地图项（坐标转换为地址）：

let location = CLLocation(latitude: 37.3349, longitude: -122.0090)
guard let request = MKReverseGeocodingRequest(location: location) else {
    return
}
let mapItems = try await request.mapItems

MKAddress

从 PlaceDescriptor 创建 MKMapItem 时使用的结构化地址类型：

if let coordinate = descriptor.coordinate {
    let location = CLLocation(latitude: coordinate.latitude, longitude: coordinate.longitude)
    let address = MKAddress()
    let mapItem = MKMapItem(location: location, address: address)
}

地理编码与 MKLocalSearch

需求	使用
将地址字符串转换为坐标	MKGeocodingRequest
将坐标转换为地址	MKReverseGeocodingRequest
自然语言地点搜索	MKLocalSearch
自动补全建议	MKLocalSearchCompleter
跨服务地点标识符	配合 SupportingPlaceRepresentation 使用 PlaceDescriptor

---

资源

WWDC：2023-10043, 2024-10094

文档：/mapkit, /mapkit/map, /mapkit/mklocalsearch, /mapkit/mkdirections, /geotoolbox, /geotoolbox/placedescriptor, /mapkit/mkgeocodingrequest, /mapkit/mkreversegeocodingrequest, /mapkit/mkaddress

技能：mapkit, mapkit-diag, core-location-ref