Back to Details

mapkit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apple MapKit Integration

Apple MapKit 集成

Help developers integrate MapKit into iOS/macOS/visionOS apps using SwiftUI or UIKit.
帮助开发者使用SwiftUI或UIKit将MapKit集成到iOS/macOS/visionOS应用中。

Quick Reference

快速参考

  • Full API documentation: See 
    references/MapKit.md
    for complete MapKit API details
  • Default to SwiftUI for new projects (iOS 17+), offer UIKit for older targets or specific needs
  • 完整API文档：查看
    references/MapKit.md
    获取完整的MapKit API详情
  • 新项目默认使用SwiftUI（iOS 17+），针对旧版本目标或特定需求可提供UIKit方案

Common Workflows

常见工作流程

1. Display a Basic Map

1. 显示基础地图

SwiftUI (iOS 17+)
swift
import MapKit
import SwiftUI

struct ContentView: View {
    var body: some View {
        Map()
    }
}
SwiftUI with initial position
swift
struct ContentView: View {
    @State private var position: MapCameraPosition = .region(
        MKCoordinateRegion(
            center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
            span: MKCoordinateSpan(latitudeDelta: 0.1, longitudeDelta: 0.1)
        )
    )
    
    var body: some View {
        Map(position: $position)
    }
}
UIKit
swift
import MapKit
import UIKit

class MapViewController: UIViewController {
    private let mapView = MKMapView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        mapView.frame = view.bounds
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
        
        let region = MKCoordinateRegion(
            center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
            span: MKCoordinateSpan(latitudeDelta: 0.1, longitudeDelta: 0.1)
        )
        mapView.setRegion(region, animated: false)
    }
}
SwiftUI (iOS 17+)
swift
import MapKit
import SwiftUI

struct ContentView: View {
    var body: some View {
        Map()
    }
}
带初始位置的SwiftUI实现
swift
struct ContentView: View {
    @State private var position: MapCameraPosition = .region(
        MKCoordinateRegion(
            center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
            span: MKCoordinateSpan(latitudeDelta: 0.1, longitudeDelta: 0.1)
        )
    )
    
    var body: some View {
        Map(position: $position)
    }
}
UIKit实现
swift
import MapKit
import UIKit

class MapViewController: UIViewController {
    private let mapView = MKMapView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        mapView.frame = view.bounds
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
        
        let region = MKCoordinateRegion(
            center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
            span: MKCoordinateSpan(latitudeDelta: 0.1, longitudeDelta: 0.1)
        )
        mapView.setRegion(region, animated: false)
    }
}

2. Show User Location

2. 展示用户位置

Required: Add 
NSLocationWhenInUseUsageDescription
to Info.plist
SwiftUI (iOS 17+)
swift
import CoreLocation
import MapKit
import SwiftUI

struct ContentView: View {
    @State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
    
    var body: some View {
        Map(position: $position) {
            UserAnnotation()
        }
        .mapControls {
            MapUserLocationButton()
            MapCompass()
        }
    }
}
UIKit
swift
class MapViewController: UIViewController, CLLocationManagerDelegate {
    private let mapView = MKMapView()
    private let locationManager = CLLocationManager()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupMapView()
        locationManager.delegate = self
        locationManager.requestWhenInUseAuthorization()
    }
    
    func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
        if manager.authorizationStatus == .authorizedWhenInUse {
            mapView.showsUserLocation = true
            mapView.userTrackingMode = .follow
        }
    }
}
必要配置：在Info.plist中添加
NSLocationWhenInUseUsageDescription
字段
SwiftUI (iOS 17+)
swift
import CoreLocation
import MapKit
import SwiftUI

struct ContentView: View {
    @State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
    
    var body: some View {
        Map(position: $position) {
            UserAnnotation()
        }
        .mapControls {
            MapUserLocationButton()
            MapCompass()
        }
    }
}
UIKit实现
swift
class MapViewController: UIViewController, CLLocationManagerDelegate {
    private let mapView = MKMapView()
    private let locationManager = CLLocationManager()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupMapView()
        locationManager.delegate = self
        locationManager.requestWhenInUseAuthorization()
    }
    
    func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
        if manager.authorizationStatus == .authorizedWhenInUse {
            mapView.showsUserLocation = true
            mapView.userTrackingMode = .follow
        }
    }
}

3. Add Annotations/Markers

3. 添加注解/标记

SwiftUI (iOS 17+)
swift
struct Place: Identifiable {
    let id = UUID()
    let name: String
    let coordinate: CLLocationCoordinate2D
}

struct ContentView: View {
    let places = [
        Place(name: "San Francisco", coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)),
        Place(name: "Oakland", coordinate: CLLocationCoordinate2D(latitude: 37.8044, longitude: -122.2712))
    ]
    
    var body: some View {
        Map {
            ForEach(places) { place in
                Marker(place.name, coordinate: place.coordinate)
            }
        }
    }
}
Custom annotation content
swift
Map {
    ForEach(places) { place in
        Annotation(place.name, coordinate: place.coordinate) {
            VStack {
                Image(systemName: "mappin.circle.fill")
                    .font(.title)
                    .foregroundStyle(.red)
                Text(place.name)
                    .font(.caption)
            }
        }
    }
}
UIKit
swift
class PlaceAnnotation: NSObject, MKAnnotation {
    let title: String?
    let coordinate: CLLocationCoordinate2D
    
    init(title: String, coordinate: CLLocationCoordinate2D) {
        self.title = title
        self.coordinate = coordinate
    }
}

// In view controller:
let annotation = PlaceAnnotation(
    title: "San Francisco",
    coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)
)
mapView.addAnnotation(annotation)
SwiftUI (iOS 17+)
swift
struct Place: Identifiable {
    let id = UUID()
    let name: String
    let coordinate: CLLocationCoordinate2D
}

struct ContentView: View {
    let places = [
        Place(name: "San Francisco", coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)),
        Place(name: "Oakland", coordinate: CLLocationCoordinate2D(latitude: 37.8044, longitude: -122.2712))
    ]
    
    var body: some View {
        Map {
            ForEach(places) { place in
                Marker(place.name, coordinate: place.coordinate)
            }
        }
    }
}
自定义注解内容
swift
Map {
    ForEach(places) { place in
        Annotation(place.name, coordinate: place.coordinate) {
            VStack {
                Image(systemName: "mappin.circle.fill")
                    .font(.title)
                    .foregroundStyle(.red)
                Text(place.name)
                    .font(.caption)
            }
        }
    }
}
UIKit实现
swift
class PlaceAnnotation: NSObject, MKAnnotation {
    let title: String?
    let coordinate: CLLocationCoordinate2D
    
    init(title: String, coordinate: CLLocationCoordinate2D) {
        self.title = title
        self.coordinate = coordinate
    }
}

// 在视图控制器中：
let annotation = PlaceAnnotation(
    title: "San Francisco",
    coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)
)
mapView.addAnnotation(annotation)

4. Marker/Annotation Clustering

4. 标记/注解聚类

SwiftUI (iOS 17+) — Use 
MapContentBuilder
with 
.annotationTitles(.hidden)
for clustering behavior, or use 
MKClusterAnnotation
in UIKit.
UIKit with clustering
swift
class ClusterableAnnotation: NSObject, MKAnnotation {
    let coordinate: CLLocationCoordinate2D
    let title: String?
    
    init(coordinate: CLLocationCoordinate2D, title: String?) {
        self.coordinate = coordinate
        self.title = title
    }
}

class MapViewController: UIViewController, MKMapViewDelegate {
    private let mapView = MKMapView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        mapView.delegate = self
        mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: MKMapViewDefaultAnnotationViewReuseIdentifier)
        mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: MKMapViewDefaultClusterAnnotationViewReuseIdentifier)
    }
    
    func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
        guard !(annotation is MKUserLocation) else { return nil }
        
        if let cluster = annotation as? MKClusterAnnotation {
            let view = mapView.dequeueReusableAnnotationView(withIdentifier: MKMapViewDefaultClusterAnnotationViewReuseIdentifier, for: annotation) as! MKMarkerAnnotationView
            view.markerTintColor = .blue
            view.glyphText = "\(cluster.memberAnnotations.count)"
            return view
        }
        
        let view = mapView.dequeueReusableAnnotationView(withIdentifier: MKMapViewDefaultAnnotationViewReuseIdentifier, for: annotation) as! MKMarkerAnnotationView
        view.clusteringIdentifier = "places" // Enable clustering
        view.markerTintColor = .red
        return view
    }
}
SwiftUI (iOS 17+) — 使用带
.annotationTitles(.hidden)
的
MapContentBuilder
实现聚类行为，或在UIKit中使用
MKClusterAnnotation
。
带聚类的UIKit实现
swift
class ClusterableAnnotation: NSObject, MKAnnotation {
    let coordinate: CLLocationCoordinate2D
    let title: String?
    
    init(coordinate: CLLocationCoordinate2D, title: String?) {
        self.coordinate = coordinate
        self.title = title
    }
}

class MapViewController: UIViewController, MKMapViewDelegate {
    private let mapView = MKMapView()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        mapView.delegate = self
        mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: MKMapViewDefaultAnnotationViewReuseIdentifier)
        mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: MKMapViewDefaultClusterAnnotationViewReuseIdentifier)
    }
    
    func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
        guard !(annotation is MKUserLocation) else { return nil }
        
        if let cluster = annotation as? MKClusterAnnotation {
            let view = mapView.dequeueReusableAnnotationView(withIdentifier: MKMapViewDefaultClusterAnnotationViewReuseIdentifier, for: annotation) as! MKMarkerAnnotationView
            view.markerTintColor = .blue
            view.glyphText = "\(cluster.memberAnnotations.count)"
            return view
        }
        
        let view = mapView.dequeueReusableAnnotationView(withIdentifier: MKMapViewDefaultAnnotationViewReuseIdentifier, for: annotation) as! MKMarkerAnnotationView
        view.clusteringIdentifier = "places" // 启用聚类
        view.markerTintColor = .red
        return view
    }
}

5. Directions and Routing

5. 导航与路线规划

SwiftUI (iOS 17+)
swift
struct DirectionsView: View {
    @State private var route: MKRoute?
    @State private var position: MapCameraPosition = .automatic
    
    let start = CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)
    let end = CLLocationCoordinate2D(latitude: 37.8044, longitude: -122.2712)
    
    var body: some View {
        Map(position: $position) {
            Marker("Start", coordinate: start)
            Marker("End", coordinate: end)
            if let route {
                MapPolyline(route.polyline)
                    .stroke(.blue, lineWidth: 5)
            }
        }
        .task {
            await calculateRoute()
        }
    }
    
    func calculateRoute() async {
        let request = MKDirections.Request()
        request.source = MKMapItem(placemark: MKPlacemark(coordinate: start))
        request.destination = MKMapItem(placemark: MKPlacemark(coordinate: end))
        request.transportType = .automobile
        
        let directions = MKDirections(request: request)
        if let response = try? await directions.calculate() {
            route = response.routes.first
        }
    }
}
UIKit
swift
func calculateAndDisplayRoute(from source: CLLocationCoordinate2D, to destination: CLLocationCoordinate2D) {
    let request = MKDirections.Request()
    request.source = MKMapItem(placemark: MKPlacemark(coordinate: source))
    request.destination = MKMapItem(placemark: MKPlacemark(coordinate: destination))
    request.transportType = .automobile
    
    let directions = MKDirections(request: request)
    directions.calculate { [weak self] response, error in
        guard let route = response?.routes.first else { return }
        self?.mapView.addOverlay(route.polyline)
        self?.mapView.setVisibleMapRect(route.polyline.boundingMapRect, edgePadding: UIEdgeInsets(top: 50, left: 50, bottom: 50, right: 50), animated: true)
    }
}

// MKMapViewDelegate
func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
    if let polyline = overlay as? MKPolyline {
        let renderer = MKPolylineRenderer(polyline: polyline)
        renderer.strokeColor = .systemBlue
        renderer.lineWidth = 5
        return renderer
    }
    return MKOverlayRenderer(overlay: overlay)
}
SwiftUI (iOS 17+)
swift
struct DirectionsView: View {
    @State private var route: MKRoute?
    @State private var position: MapCameraPosition = .automatic
    
    let start = CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)
    let end = CLLocationCoordinate2D(latitude: 37.8044, longitude: -122.2712)
    
    var body: some View {
        Map(position: $position) {
            Marker("Start", coordinate: start)
            Marker("End", coordinate: end)
            if let route {
                MapPolyline(route.polyline)
                    .stroke(.blue, lineWidth: 5)
            }
        }
        .task {
            await calculateRoute()
        }
    }
    
    func calculateRoute() async {
        let request = MKDirections.Request()
        request.source = MKMapItem(placemark: MKPlacemark(coordinate: start))
        request.destination = MKMapItem(placemark: MKPlacemark(coordinate: end))
        request.transportType = .automobile
        
        let directions = MKDirections(request: request)
        if let response = try? await directions.calculate() {
            route = response.routes.first
        }
    }
}
UIKit实现
swift
func calculateAndDisplayRoute(from source: CLLocationCoordinate2D, to destination: CLLocationCoordinate2D) {
    let request = MKDirections.Request()
    request.source = MKMapItem(placemark: MKPlacemark(coordinate: source))
    request.destination = MKMapItem(placemark: MKPlacemark(coordinate: destination))
    request.transportType = .automobile
    
    let directions = MKDirections(request: request)
    directions.calculate { [weak self] response, error in
        guard let route = response?.routes.first else { return }
        self?.mapView.addOverlay(route.polyline)
        self?.mapView.setVisibleMapRect(route.polyline.boundingMapRect, edgePadding: UIEdgeInsets(top: 50, left: 50, bottom: 50, right: 50), animated: true)
    }
}

// MKMapViewDelegate方法
func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
    if let polyline = overlay as? MKPolyline {
        let renderer = MKPolylineRenderer(polyline: polyline)
        renderer.strokeColor = .systemBlue
        renderer.lineWidth = 5
        return renderer
    }
    return MKOverlayRenderer(overlay: overlay)
}

6. Local Search (Find Places)

6. 本地搜索（查找地点）

swift
func searchForPlaces(query: String, region: MKCoordinateRegion) async -> [MKMapItem] {
    let request = MKLocalSearch.Request()
    request.naturalLanguageQuery = query
    request.region = region
    
    let search = MKLocalSearch(request: request)
    if let response = try? await search.start() {
        return response.mapItems
    }
    return []
}

// Usage
let results = await searchForPlaces(query: "coffee", region: mapView.region)
for item in results {
    print("\(item.name ?? "") - \(item.placemark.coordinate)")
}
Search completions (autocomplete)
swift
class SearchCompleter: NSObject, ObservableObject, MKLocalSearchCompleterDelegate {
    @Published var results: [MKLocalSearchCompletion] = []
    private let completer = MKLocalSearchCompleter()
    
    override init() {
        super.init()
        completer.delegate = self
        completer.resultTypes = [.address, .pointOfInterest]
    }
    
    func search(query: String) {
        completer.queryFragment = query
    }
    
    func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
        results = completer.results
    }
}
swift
func searchForPlaces(query: String, region: MKCoordinateRegion) async -> [MKMapItem] {
    let request = MKLocalSearch.Request()
    request.naturalLanguageQuery = query
    request.region = region
    
    let search = MKLocalSearch(request: request)
    if let response = try? await search.start() {
        return response.mapItems
    }
    return []
}

// 使用示例
let results = await searchForPlaces(query: "coffee", region: mapView.region)
for item in results {
    print("\(item.name ?? "") - \(item.placemark.coordinate)")
}
搜索补全（自动完成）
swift
class SearchCompleter: NSObject, ObservableObject, MKLocalSearchCompleterDelegate {
    @Published var results: [MKLocalSearchCompletion] = []
    private let completer = MKLocalSearchCompleter()
    
    override init() {
        super.init()
        completer.delegate = self
        completer.resultTypes = [.address, .pointOfInterest]
    }
    
    func search(query: String) {
        completer.queryFragment = query
    }
    
    func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
        results = completer.results
    }
}

7. Map Overlays (Polylines, Polygons, Circles)

7. 地图覆盖层（折线、多边形、圆形）

SwiftUI (iOS 17+)
swift
Map {
    // Polyline
    MapPolyline(coordinates: [
        CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
        CLLocationCoordinate2D(latitude: 37.8044, longitude: -122.2712)
    ])
    .stroke(.blue, lineWidth: 3)
    
    // Circle
    MapCircle(center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194), radius: 1000)
        .foregroundStyle(.blue.opacity(0.3))
        .stroke(.blue, lineWidth: 2)
    
    // Polygon
    MapPolygon(coordinates: [
        CLLocationCoordinate2D(latitude: 37.77, longitude: -122.42),
        CLLocationCoordinate2D(latitude: 37.78, longitude: -122.40),
        CLLocationCoordinate2D(latitude: 37.76, longitude: -122.40)
    ])
    .foregroundStyle(.green.opacity(0.3))
    .stroke(.green, lineWidth: 2)
}
SwiftUI (iOS 17+)
swift
Map {
    // 折线
    MapPolyline(coordinates: [
        CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
        CLLocationCoordinate2D(latitude: 37.8044, longitude: -122.2712)
    ])
    .stroke(.blue, lineWidth: 3)
    
    // 圆形
    MapCircle(center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194), radius: 1000)
        .foregroundStyle(.blue.opacity(0.3))
        .stroke(.blue, lineWidth: 2)
    
    // 多边形
    MapPolygon(coordinates: [
        CLLocationCoordinate2D(latitude: 37.77, longitude: -122.42),
        CLLocationCoordinate2D(latitude: 37.78, longitude: -122.40),
        CLLocationCoordinate2D(latitude: 37.76, longitude: -122.40)
    ])
    .foregroundStyle(.green.opacity(0.3))
    .stroke(.green, lineWidth: 2)
}

8. Map Configuration

8. 地图配置

SwiftUI
swift
Map {
    // content
}
.mapStyle(.standard) // .imagery, .hybrid, .standard(elevation: .realistic)
.mapControls {
    MapUserLocationButton()
    MapCompass()
    MapScaleView()
    MapPitchToggle()
}
UIKit
swift
mapView.mapType = .standard // .satellite, .hybrid, .satelliteFlyover, .hybridFlyover
mapView.showsCompass = true
mapView.showsScale = true
mapView.isZoomEnabled = true
mapView.isScrollEnabled = true
mapView.isPitchEnabled = true
mapView.isRotateEnabled = true
SwiftUI实现
swift
Map {
    // 内容
}
.mapStyle(.standard) // 可选值：.imagery, .hybrid, .standard(elevation: .realistic)
.mapControls {
    MapUserLocationButton()
    MapCompass()
    MapScaleView()
    MapPitchToggle()
}
UIKit实现
swift
mapView.mapType = .standard // 可选值：.satellite, .hybrid, .satelliteFlyover, .hybridFlyover
mapView.showsCompass = true
mapView.showsScale = true
mapView.isZoomEnabled = true
mapView.isScrollEnabled = true
mapView.isPitchEnabled = true
mapView.isRotateEnabled = true

Key Considerations

关键注意事项

  1. Privacy: Always add location usage descriptions to Info.plist
  2. Maps capability: Enable in Xcode under Signing & Capabilities for directions
  3. iOS version: SwiftUI Map API significantly improved in iOS 17; use UIKit for older targets
  4. Clustering: Set 
    clusteringIdentifier
    on annotation views (UIKit) to enable automatic clustering
  5. Performance: For many annotations (1000+), consider clustering or custom tile overlays
  1. 隐私合规：务必在Info.plist中添加位置使用描述
  2. Maps权限：在Xcode的“Signing & Capabilities”中启用Maps权限以使用导航功能
  3. iOS版本：SwiftUI Map API在iOS 17中大幅改进；旧版本目标请使用UIKit方案
  4. 聚类功能：在UIKit中为注解视图设置
    clusteringIdentifier
    即可启用自动聚类
  5. 性能优化：当注解数量较多（1000+）时，建议使用聚类或自定义瓦片覆盖层

When to Consult Full Reference

何时查阅完整参考文档

Search 
references/MapKit.md
for:
  • Complete API signatures and parameters
  • LookAround implementation details
  • MKMapItem and place details
  • GeoJSON decoding
  • Indoor mapping (IMDF)
  • Point of interest categories and filtering
  • Snapshot generation
  • All MKMapViewDelegate methods
如需以下内容，请搜索
references/MapKit.md
：
  • 完整的API签名和参数
  • LookAround实现细节
  • MKMapItem和地点详情
  • GeoJSON解码
  • 室内地图（IMDF）
  • 兴趣点分类与过滤
  • 快照生成
  • 所有MKMapViewDelegate方法