MapKit
Erstellen Sie kartenbasierte und standortbezogene Funktionen für iOS 17+ mit SwiftUI MapKit und modernen CoreLocation Async-APIs. Verwenden Sie Map mit MapContentBuilder für Ansichten, CLLocationUpdate.liveUpdates() für das Streaming von Standorten und CLMonitor für Geofencing.
Siehe references/mapkit-patterns.md für erweiterte MapKit-Muster und references/mapkit-corelocation-patterns.md für CoreLocation-Muster.
Inhaltsverzeichnis
- Workflow
- SwiftUI Map View (iOS 17+)
- CoreLocation Modern API
- Geokodierung
- Suche
- Routen
- PlaceDescriptor (iOS 26+)
- Häufige Fehler
- Überprüfungsliste
- Referenzen
Workflow
1. Karte mit Markierungen oder Annotationen hinzufügen
- Importieren Sie
MapKit. - Erstellen Sie eine
Map-Ansicht mit optionalerMapCameraPosition-Bindung. - Fügen Sie
Marker,Annotation,MapPolyline,MapPolygonoderMapCircleinnerhalb desMapContentBuilder-Closures hinzu. - Konfigurieren Sie den Kartenstil mit
.mapStyle(). - Fügen Sie Kartensteuerelemente mit
.mapControls { }hinzu. - Behandeln Sie die Auswahl mit einer
selection:-Bindung.
2. Benutzerstandort verfolgen
- Fügen Sie
NSLocationWhenInUseUsageDescriptionzur Info.plist hinzu. - Erstellen Sie auf iOS 18+ eine
CLServiceSession, um die Autorisierung zu verwalten. - Iterieren Sie
CLLocationUpdate.liveUpdates()in einemTask. - Filtern Sie Updates nach Entfernung oder Genauigkeit, bevor Sie die Benutzeroberfläche aktualisieren.
- Stoppen Sie den Task, wenn die Standortverfolgung nicht mehr benötigt wird.
3. Orte suchen
- Konfigurieren Sie
MKLocalSearchCompleterfür Autovervollständigungsvorschläge. - Entprellen Sie Benutzereingaben (mindestens 300 ms), bevor Sie die Abfrage setzen.
- Konvertieren Sie die ausgewählte Vervollständigung in
MKLocalSearch.Requestfür vollständige Ergebnisse. - Zeigen Sie Ergebnisse als Markierungen oder in einer Liste an.
4. Routen abrufen und anzeigen
- Erstellen Sie einen
MKDirections.Requestmit Quell- und Ziel-MKMapItem. - Setzen Sie
transportType(.automobile,.walking,.transit,.cycling). - Warten Sie auf
MKDirections.calculate(). - Zeichnen Sie die Route mit
MapPolyline(route.polyline).
5. Vorhandenen Karten-/Standortcode überprüfen
Durchlaufen Sie die Überprüfungsliste am Ende dieser Datei.
SwiftUI Map View (iOS 17+)
import MapKit
import SwiftUI
struct PlaceMap: View {
@State private var position: MapCameraPosition = .automatic
var body: some View {
Map(position: $position) {
Marker("Apple Park", coordinate: applePark)
Marker("Infinite Loop", systemImage: "building.2",
coordinate: infiniteLoop)
}
.mapStyle(.standard(elevation: .realistic))
.mapControls {
MapUserLocationButton()
MapCompass()
MapScaleView()
}
}
}
Marker und Annotation
// Ballon-Marker – einfachste Möglichkeit, einen Ort zu markieren
Marker("Café", systemImage: "cup.and.saucer.fill", coordinate: cafeCoord)
.tint(.brown)
// Annotation – benutzerdefinierte SwiftUI-Ansicht an einer Koordinate
Annotation("Sie", coordinate: userCoord, anchor: .bottom) {
Image(systemName: "figure.wave")
.padding(6)
.background(.blue.gradient, in: .circle)
.foregroundStyle(.white)
}
Overlays: Polyline, Polygon, Circle
Map {
// Polylinie aus Koordinaten
MapPolyline(coordinates: routeCoords)
.stroke(.blue, lineWidth: 4)
// Polygon (Bereich hervorheben)
MapPolygon(coordinates: parkBoundary)
.foregroundStyle(.green.opacity(0.3))
.stroke(.green, lineWidth: 2)
// Kreis (Radius um einen Punkt)
MapCircle(center: storeCoord, radius: 500)
.foregroundStyle(.red.opacity(0.15))
.stroke(.red, lineWidth: 1)
}
Kameraposition
MapCameraPosition steuert, was die Karte anzeigt. Binden Sie sie, damit der Benutzer interagieren und die Kamera programmatisch bewegen kann.
// Auf eine Region zentrieren
@State private var position: MapCameraPosition = .region(
MKCoordinateRegion(
center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
)
)
// Benutzerstandort folgen
@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
// Bestimmter Kamerawinkel (3D-Perspektive)
@State private var position: MapCameraPosition = .camera(
MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
)
// Bestimmte Elemente einrahmen
position = .item(MKMapItem.forCurrentLocation())
position = .rect(MKMapRect(...))
Kartenstil
.mapStyle(.standard) // Standard-Straßenkarte
.mapStyle(.standard(elevation: .realistic, showsTraffic: true))
.mapStyle(.imagery) // Satellit
.mapStyle(.imagery(elevation: .realistic)) // 3D-Satellit
.mapStyle(.hybrid) // Satellit + Beschriftungen
.mapStyle(.hybrid(elevation: .realistic, showsTraffic: true))
Karteninteraktionsmodi
.mapInteractionModes(.all) // Standard: schwenken, zoomen, drehen, neigen
.mapInteractionModes(.pan) // Nur schwenken
.mapInteractionModes([.pan, .zoom]) // Schwenken und zoomen
.mapInteractionModes([]) // Statische Karte (keine Interaktion)
Kartenauswahl
@State private var selectedMarker: MKMapItem?
Map(selection: $selectedMarker) {
ForEach(places) { place in
Marker(place.name, coordinate: place.coordinate)
.tag(place.mapItem) // Tag muss dem Auswahltyp entsprechen
}
}
.onChange(of: selectedMarker) { _, newValue in
guard let item = newValue else { return }
// Auf Auswahl reagieren
}
CoreLocation Modern API
CLLocationUpdate.liveUpdates() (iOS 17+)
Ersetzen Sie CLLocationManagerDelegate-Callbacks durch eine einzelne Async-Sequenz. Jede Iteration liefert ein CLLocationUpdate, das ein optionales CLLocation enthält.
import CoreLocation
@Observable
final class LocationTracker: @unchecked Sendable {
var currentLocation: CLLocation?
private var updateTask: Task<Void, Never>?
func startTracking() {
updateTask = Task {
let updates = CLLocationUpdate.liveUpdates()
for try await update in updates {
guard let location = update.location else { continue }
// Nach horizontaler Genauigkeit filtern
guard location.horizontalAccuracy < 50 else { continue }
await MainActor.run {
self.currentLocation = location
}
}
}
}
func stopTracking() {
updateTask?.cancel()
updateTask = nil
}
}
CLServiceSession (iOS 18+)
Deklarieren Sie Autorisierungsanforderungen für die Lebensdauer einer Funktion. Halten Sie einen Verweis auf die Sitzung, solange Sie Standortdienste benötigen.
// Autorisierung bei Nutzung mit Präferenz für volle Genauigkeit
let session = CLServiceSession(
authorization: .whenInUse,
fullAccuracyPurposeKey: "NearbySearchPurpose"
)
// Halten Sie `session` als gespeicherte Eigenschaft; geben Sie sie frei, wenn Sie fertig sind.
Auf iOS 18+ verwenden CLLocationUpdate.liveUpdates() und CLMonitor eine implizite CLServiceSession, wenn Sie keine explizit erstellen. Erstellen Sie explizit eine, wenn Sie .always-Autorisierung oder volle Genauigkeit benötigen.
Autorisierungsablauf
// Info.plist-Schlüssel (erforderlich):
// NSLocationWhenInUseUsageDescription
// NSLocationAlwaysAndWhenInUseUsageDescription (nur wenn .always benötigt)
// Autorisierung prüfen und Benutzer bei Verweigerung zu den Einstellungen führen
struct LocationPermissionView: View {
@Environment(\.openURL) private var openURL
var body: some View {
ContentUnavailableView {
Label("Standortzugriff verweigert", systemImage: "location.slash")
} description: {
Text("Aktivieren Sie den Standortzugriff in den Einstellungen, um diese Funktion zu nutzen.")
} actions: {
Button("Einstellungen öffnen") {
if let url = URL(string: UIApplication.openSettingsURLString) {
openURL(url)
}
}
}
}
}
Geokodierung
CLGeocoder (iOS 8+)
let geocoder = CLGeocoder()
// Vorwärts-Geokodierung: Adresszeichenfolge -> Koordinaten
let placemarks = try await geocoder.geocodeAddressString("1 Apple Park Way, Cupertino")
if let location = placemarks.first?.location {
print(location.coordinate) // CLLocationCoordinate2D
}
// Rückwärts-Geokodierung: Koordinaten -> Ortsmarke
let location = CLLocation(latitude: 37.3349, longitude: -122.0090)
let placemarks = try await geocoder.reverseGeocodeLocation(location)
if let placemark = placemarks.first {
let address = [placemark.name, placemark.locality, placemark.administrativeArea]
.compactMap { $0 }
.joined(separator: ", ")
}
MKGeocodingRequest und MKReverseGeocodingRequest (iOS 26+)
Neue MapKit-native Geokodierung, die MKMapItem mit umfangreicheren Daten und MKAddress / MKAddressRepresentations für flexible Adressformatierung zurückgibt.
@available(iOS 26, *)
func reverseGeocode(location: CLLocation) async throws -> MKMapItem? {
guard let request = MKReverseGeocodingRequest(location: location) else {
return nil
}
let mapItems = try await request.mapItems
return mapItems.first
}
@available(iOS 26, *)
func forwardGeocode(address: String) async throws -> [MKMapItem] {
guard let request = MKGeocodingRequest(addressString: address) else { return [] }
return try await request.mapItems
}
Suche
MKLocalSearchCompleter (Autovervollständigung)
@Observable
final class SearchCompleter: NSObject, MKLocalSearchCompleterDelegate {
var results: [MKLocalSearchCompletion] = []
var query: String = "" { didSet { completer.queryFragment = query } }
private let completer = MKLocalSearchCompleter()
override init() {
super.init()
completer.delegate = self
completer.resultTypes = [.address, .pointOfInterest]
}
func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
results = completer.results
}
func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
results = []
}
}
MKLocalSearch (Volltextsuche)
func search(for completion: MKLocalSearchCompletion) async throws -> [MKMapItem] {
let request = MKLocalSearch.Request(completion: completion)
request.resultTypes = [.pointOfInterest, .address]
let search = MKLocalSearch(request: request)
let response = try await search.start()
return response.mapItems
}
// Suche nach natürlichsprachlicher Abfrage innerhalb einer Region
func searchNearby(query: String, region: MKCoordinateRegion) async throws -> [MKMapItem] {
let request = MKLocalSearch.Request()
request.naturalLanguageQuery = query
request.region = region
let search = MKLocalSearch(request: request)
let response = try await search.start()
return response.mapItems
}
Routen
func getDirections(from source: MKMapItem, to destination: MKMapItem,
transport: MKDirectionsTransportType = .automobile) async throws -> MKRoute? {
let request = MKDirections.Request()
request.source = source
request.destination = destination
request.transportType = transport
let directions = MKDirections(request: request)
let response = try await directions.calculate()
return response.routes.first
}
Route auf Karte anzeigen
@State private var route: MKRoute?
Map {
if let route {
MapPolyline(route.polyline)
.stroke(.blue, lineWidth: 5)
}
Marker("Start", coordinate: startCoord)
Marker("Ziel", coordinate: endCoord)
}
.task {
route = try? await getDirections(from: startItem, to: endItem)
}
ETA-Berechnung
func getETA(from source: MKMapItem, to destination: MKMapItem) async throws -> TimeInterval {
let request = MKDirections.Request()
request.source = source
request.destination = destination
let directions = MKDirections(request: request)
let response = try await directions.calculateETA()
return response.expectedTravelTime
}
Radrouten (iOS 26+)
@available(iOS 26, *)
func getCyclingDirections(to destination: MKMapItem) async throws -> MKRoute? {
let request = MKDirections.Request()
request.source = MKMapItem.forCurrentLocation()
request.destination = destination
request.transportType = .cycling
let directions = MKDirections(request: request)
let response = try await directions.calculate()
return response.routes.first
}
PlaceDescriptor (iOS 26+)
Erstellen Sie umfangreiche Ortsverweise aus Koordinaten oder Adressen, ohne eine Orts-ID zu benötigen. Erfordert import GeoToolbox.
@available(iOS 26, *)
func lookupPlace(name: String, coordinate: CLLocationCoordinate2D) async throws -> MKMapItem {
let descriptor = PlaceDescriptor(
representations: [.coordinate(coordinate)],
commonName: name
)
let request = MKMapItemRequest(placeDescriptor: descriptor)
return try await request.mapItem
}
Häufige Fehler
NICHT: Fordern Sie nicht sofort .authorizedAlways an – Benutzer misstrauen weitreichenden Berechtigungen.
DO: Beginnen Sie mit .requestWhenInUseAuthorization() und eskalieren Sie zu .always nur, wenn der Benutzer eine Hintergrundfunktion aktiviert.
NICHT: Verwenden Sie CLLocationManagerDelegate für einfache Standortabfragen unter iOS 17+.
DO: Verwenden Sie den Async-Stream CLLocationUpdate.liveUpdates() für saubereren, präziseren Code.
NICHT: Lassen Sie Standortaktualisierungen laufen, wenn die Karte/Ansicht nicht sichtbar ist (entlädt den Akku).
DO: Verwenden Sie .task { } in SwiftUI, sodass Aktualisierungen beim Verschwinden automatisch abgebrochen werden.
NICHT: Erzwingen Sie das Entpacken von CLPlacemark-Eigenschaften – sie sind alle optional.
DO: Verwenden Sie Nil-Coalescing: placemark.locality ?? "Unbekannt".
NICHT: Lösen Sie MKLocalSearchCompleter.queryFragment bei jeder Tastatureingabe aus – das führt zu übermäßigen API-Aufrufen.
DO: Entprellen Sie die Eingabe mit Task.sleep(nanoseconds:) oder Combine.
NICHT: Ignorieren Sie CLAuthorizationStatus.notDetermined – Ihr Handler muss die erste Autorisierungsanfrage stellen.
DO: Erstellen Sie eine CLLocationUpdate.liveUpdates()-Sequenz (oder CLServiceSession auf iOS 18+), um die Autorisierungsaufforderung automatisch auszulösen.
Überprüfungsliste
Code-Struktur
- Importiert nur
MapKit, keinMapKit+ separate Legacy-Frameworks. - Verwendet
MapContentBuilderfür Kinder; kein LegacyMKMapViewviaUIViewRepresentablefür iOS 17+. - Entfernt verworfene APIs wie
MKMapView,MKPointAnnotation,MKPlacemark,CLLocationManagerDelegate(für reine iOS 17+-Ziele). - Alle
MKMapItem-Erstellungen geben einenMKMapItemRequestoderMKMapItem(for:)an, nicht direktMKPlacemark.
Standortberechtigungen
-
NSLocationWhenInUseUsageDescriptioninInfo.plistvorhanden. -
NSLocationAlwaysAndWhenInUseUsageDescriptionnur vorhanden, wenn die App Hintergrund-Standortzugriff benötigt. -
NSLocationTemporaryUsageDescriptionDictionaryfür Präzisionsverlust konfiguriert (sofern zutreffend). - Verwendet
CLServiceSession(iOS 18+), um Autorisierung und Genauigkeit über Funktionen hinweg zu deklarieren. - Implementiert UI zur Führung der Benutzer zu den Einstellungen, wenn die Autorisierung verweigert wurde.
Leistung
-
CLLocationUpdate.liveUpdates()bricht Task ab, wenn die Ansicht verschwindet. - Standortaktualisierungen filtern nach
horizontalAccuracyunddistanceFilter, bevor die Benutzeroberfläche aktualisiert wird. - Suchergebnisse entprellt (≥300 ms Verzögerung), bevor
queryFragmentgesetzt wird. - Richtet Region für
MKLocalSearchso ein, dass sie auf den sichtbaren Kartenbereich begrenzt ist. - Vermeidet das Erstellen von
CLLocation-Instanzen ohne Filterung oder Zwischenspeicherung. - Annotationen und Overlays werden nicht jedes Mal neu erstellt, wenn sich die Kameraposition ändert.
- Orte im
MapContentBuildersind mit klarenid:oder durchIdentifiablestabil.
Barrierefreiheit (Accessibility)
-
Markerund Annotationen haben aussagekräftigeLabels; Symbole sind dekorativ. - Benutzerdefinierte
Annotation-Inhalte setzen.accessibilityLabel(). - Interaktive Overlays haben
.accessibilityRespondsToUserInteraction()= false, es sei denn, sie sind tatsächlich interaktiv. -
mapControls {}sind vorhanden (Kompass, Maßstab, Benutzerstandort).
Kartenkonfiguration
-
mapStyleist explizit gesetzt (.standard,.imagery,.hybrid), nicht nur Standard. -
mapInteractionModessind angemessen eingeschränkt (reine Anzeige vs. voll interaktiv). -
MapCameraPositionist gebunden, sodass die Karte auf Benutzeraktionen und programmatische Änderungen reagiert.
Fehlerbehandlung
-
MKDirections.calculate()behandelt Fehler (keine Route gefunden, Netzwerk, eingeschränkter Modus). -
MKDirections.calculateETA()behandelt Fehler. -
CLLocationUpdate.liveUpdates()behandelt Fehler durch den Update-Stream. -
MKLocalSearch.start()hattry/catchmit bedeutungsvoller UI-Rückmeldung. -
CLGeocoder-Aufgaben haben Timeouts (Standard ist ausreichend, aber bewusst konfiguriert). - Szenarien mit fehlender Netzwerkverbindung führen zu klaren Benutzernachrichten, nicht zu unbestimmten Ladeanzeigen.