mapkit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMapKit
MapKit
Build map-based and location-aware features targeting iOS 17+ with SwiftUI
MapKit and modern CoreLocation async APIs. Use with
for views, for streaming location, and
for geofencing.
MapMapContentBuilderCLLocationUpdate.liveUpdates()CLMonitorSee references/mapkit-patterns.md for extended MapKit patterns and
references/mapkit-corelocation-patterns.md for CoreLocation patterns.
基于 iOS 17+,使用 SwiftUI MapKit 和现代 CoreLocation 异步 API 构建地图类与位置感知功能。使用搭配 的 实现视图,通过 流式获取位置数据,使用 实现地理围栏。
MapContentBuilderMapCLLocationUpdate.liveUpdates()CLMonitor查看 references/mapkit-patterns.md 了解更多 MapKit 实践模式,查看 references/mapkit-corelocation-patterns.md 了解 CoreLocation 实践模式。
Contents
目录
Workflow
工作流
1. Add a map with markers or annotations
1. 添加带标记或标注的地图
- Import .
MapKit - Create a view with optional
Mapbinding.MapCameraPosition - Add ,
Marker,Annotation,MapPolyline, orMapPolygoninside theMapCircleclosure.MapContentBuilder - Configure map style with .
.mapStyle() - Add map controls with .
.mapControls { } - Handle selection with a binding.
selection:
- 导入 。
MapKit - 创建绑定可选 的
MapCameraPosition视图。Map - 在 闭包中添加
MapContentBuilder、Marker、Annotation、MapPolyline或MapPolygon。MapCircle - 通过 配置地图样式。
.mapStyle() - 通过 添加地图控件。
.mapControls { } - 用 绑定处理选中事件。
selection:
2. Track user location
2. 追踪用户位置
- Add to Info.plist.
NSLocationWhenInUseUsageDescription - On iOS 18+, create a to manage authorization.
CLServiceSession - Iterate in a
CLLocationUpdate.liveUpdates().Task - Filter updates by distance or accuracy before updating the UI.
- Stop the task when location tracking is no longer needed.
- 在 Info.plist 中添加 。
NSLocationWhenInUseUsageDescription - 在 iOS 18+ 系统中,创建 管理授权。
CLServiceSession - 在 中遍历
Task。CLLocationUpdate.liveUpdates() - 更新 UI 前按距离或精度过滤位置更新。
- 不需要位置追踪时停止任务。
3. Search for places
3. 搜索地点
- Configure for autocomplete suggestions.
MKLocalSearchCompleter - Debounce user input (at least 300ms) before setting the query.
- Convert selected completion to for full results.
MKLocalSearch.Request - Display results as markers or in a list.
- 配置 实现自动补全建议。
MKLocalSearchCompleter - 设置查询前对用户输入做防抖处理(至少300ms)。
- 将选中的补全结果转换为 以获取完整结果。
MKLocalSearch.Request - 将结果以标记或列表形式展示。
4. Get directions and display a route
4. 获取导航路线并展示
- Create an with source and destination
MKDirections.Request.MKMapItem - Set (
transportType,.automobile,.walking,.transit)..cycling - Await .
MKDirections.calculate() - Draw the route with .
MapPolyline(route.polyline)
- 用起点和终点 创建
MKMapItem。MKDirections.Request - 设置 (
transportType驾车、.automobile步行、.walking公共交通、.transit骑行)。.cycling - 等待 执行完成。
MKDirections.calculate() - 用 绘制路线。
MapPolyline(route.polyline)
5. Review existing map/location code
5. 评审现有地图/位置相关代码
Run through the Review Checklist at the end of this file.
对照本文末尾的评审 Checklist 逐一检查。
SwiftUI Map View (iOS 17+)
SwiftUI 地图视图(iOS 17+)
swift
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()
}
}
}swift
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 and Annotation
Marker 和 Annotation
swift
// Balloon marker -- simplest way to pin a location
Marker("Cafe", systemImage: "cup.and.saucer.fill", coordinate: cafeCoord)
.tint(.brown)
// Annotation -- custom SwiftUI view at a coordinate
Annotation("You", coordinate: userCoord, anchor: .bottom) {
Image(systemName: "figure.wave")
.padding(6)
.background(.blue.gradient, in: .circle)
.foregroundStyle(.white)
}swift
// Balloon marker -- simplest way to pin a location
Marker("Cafe", systemImage: "cup.and.saucer.fill", coordinate: cafeCoord)
.tint(.brown)
// Annotation -- custom SwiftUI view at a coordinate
Annotation("You", coordinate: userCoord, anchor: .bottom) {
Image(systemName: "figure.wave")
.padding(6)
.background(.blue.gradient, in: .circle)
.foregroundStyle(.white)
}Overlays: Polyline, Polygon, Circle
覆盖层:Polyline、Polygon、Circle
swift
Map {
// Polyline from coordinates
MapPolyline(coordinates: routeCoords)
.stroke(.blue, lineWidth: 4)
// Polygon (area highlight)
MapPolygon(coordinates: parkBoundary)
.foregroundStyle(.green.opacity(0.3))
.stroke(.green, lineWidth: 2)
// Circle (radius around a point)
MapCircle(center: storeCoord, radius: 500)
.foregroundStyle(.red.opacity(0.15))
.stroke(.red, lineWidth: 1)
}swift
Map {
// Polyline from coordinates
MapPolyline(coordinates: routeCoords)
.stroke(.blue, lineWidth: 4)
// Polygon (area highlight)
MapPolygon(coordinates: parkBoundary)
.foregroundStyle(.green.opacity(0.3))
.stroke(.green, lineWidth: 2)
// Circle (radius around a point)
MapCircle(center: storeCoord, radius: 500)
.foregroundStyle(.red.opacity(0.15))
.stroke(.red, lineWidth: 1)
}Camera Position
相机位置
MapCameraPositionswift
// Center on a region
@State private var position: MapCameraPosition = .region(
MKCoordinateRegion(
center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
)
)
// Follow user location
@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
// Specific camera angle (3D perspective)
@State private var position: MapCameraPosition = .camera(
MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
)
// Frame specific items
position = .item(MKMapItem.forCurrentLocation())
position = .rect(MKMapRect(...))MapCameraPositionswift
// Center on a region
@State private var position: MapCameraPosition = .region(
MKCoordinateRegion(
center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
)
)
// Follow user location
@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
// Specific camera angle (3D perspective)
@State private var position: MapCameraPosition = .camera(
MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
)
// Frame specific items
position = .item(MKMapItem.forCurrentLocation())
position = .rect(MKMapRect(...))Map Style
地图样式
swift
.mapStyle(.standard) // Default road map
.mapStyle(.standard(elevation: .realistic, showsTraffic: true))
.mapStyle(.imagery) // Satellite
.mapStyle(.imagery(elevation: .realistic)) // 3D satellite
.mapStyle(.hybrid) // Satellite + labels
.mapStyle(.hybrid(elevation: .realistic, showsTraffic: true))swift
.mapStyle(.standard) // Default road map
.mapStyle(.standard(elevation: .realistic, showsTraffic: true))
.mapStyle(.imagery) // Satellite
.mapStyle(.imagery(elevation: .realistic)) // 3D satellite
.mapStyle(.hybrid) // Satellite + labels
.mapStyle(.hybrid(elevation: .realistic, showsTraffic: true))Map Interaction Modes
地图交互模式
swift
.mapInteractionModes(.all) // Default: pan, zoom, rotate, pitch
.mapInteractionModes(.pan) // Pan only
.mapInteractionModes([.pan, .zoom]) // Pan and zoom
.mapInteractionModes([]) // Static map (no interaction)swift
.mapInteractionModes(.all) // Default: pan, zoom, rotate, pitch
.mapInteractionModes(.pan) // Pan only
.mapInteractionModes([.pan, .zoom]) // Pan and zoom
.mapInteractionModes([]) // Static map (no interaction)Map Selection
地图选中事件
swift
@State private var selectedMarker: MKMapItem?
Map(selection: $selectedMarker) {
ForEach(places) { place in
Marker(place.name, coordinate: place.coordinate)
.tag(place.mapItem) // Tag must match selection type
}
}
.onChange(of: selectedMarker) { _, newValue in
guard let item = newValue else { return }
// React to selection
}swift
@State private var selectedMarker: MKMapItem?
Map(selection: $selectedMarker) {
ForEach(places) { place in
Marker(place.name, coordinate: place.coordinate)
.tag(place.mapItem) // Tag must match selection type
}
}
.onChange(of: selectedMarker) { _, newValue in
guard let item = newValue else { return }
// React to selection
}CoreLocation Modern API
CoreLocation 现代 API
CLLocationUpdate.liveUpdates() (iOS 17+)
CLLocationUpdate.liveUpdates()(iOS 17+)
Replace callbacks with a single async sequence.
Each iteration yields a containing an optional .
CLLocationManagerDelegateCLLocationUpdateCLLocationswift
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 }
// Filter by horizontal accuracy
guard location.horizontalAccuracy < 50 else { continue }
await MainActor.run {
self.currentLocation = location
}
}
}
}
func stopTracking() {
updateTask?.cancel()
updateTask = nil
}
}用单一异步序列替代 回调,每次迭代返回一个包含可选 的 对象。
CLLocationManagerDelegateCLLocationCLLocationUpdateswift
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 }
// Filter by horizontal accuracy
guard location.horizontalAccuracy < 50 else { continue }
await MainActor.run {
self.currentLocation = location
}
}
}
}
func stopTracking() {
updateTask?.cancel()
updateTask = nil
}
}CLServiceSession (iOS 18+)
CLServiceSession(iOS 18+)
Declare authorization requirements for a feature's lifetime. Hold a reference
to the session for as long as you need location services.
swift
// When-in-use authorization with full accuracy preference
let session = CLServiceSession(
authorization: .whenInUse,
fullAccuracyPurposeKey: "NearbySearchPurpose"
)
// Hold `session` as a stored property; release it when done.On iOS 18+, and take an implicit
if you do not create one explicitly. Create one explicitly
when you need authorization or full accuracy.
CLLocationUpdate.liveUpdates()CLMonitorCLServiceSession.always声明功能生命周期内的授权要求,只要需要使用位置服务就持有该会话的引用。
swift
// When-in-use authorization with full accuracy preference
let session = CLServiceSession(
authorization: .whenInUse,
fullAccuracyPurposeKey: "NearbySearchPurpose"
)
// Hold `session` as a stored property; release it when done.iOS 18+ 系统中,如果你没有显式创建 , 和 会隐式创建一个。当需要 授权或全精度定位时请显式创建会话。
CLServiceSessionCLLocationUpdate.liveUpdates()CLMonitor.alwaysAuthorization Flow
授权流程
swift
// Info.plist keys (required):
// NSLocationWhenInUseUsageDescription
// NSLocationAlwaysAndWhenInUseUsageDescription (only if .always needed)
// Check authorization and guide user to Settings when denied
struct LocationPermissionView: View {
@Environment(\.openURL) private var openURL
var body: some View {
ContentUnavailableView {
Label("Location Access Denied", systemImage: "location.slash")
} description: {
Text("Enable location access in Settings to use this feature.")
} actions: {
Button("Open Settings") {
if let url = URL(string: UIApplication.openSettingsURLString) {
openURL(url)
}
}
}
}
}swift
// Info.plist keys (required):
// NSLocationWhenInUseUsageDescription
// NSLocationAlwaysAndWhenInUseUsageDescription (only if .always needed)
// Check authorization and guide user to Settings when denied
struct LocationPermissionView: View {
@Environment(\.openURL) private var openURL
var body: some View {
ContentUnavailableView {
Label("Location Access Denied", systemImage: "location.slash")
} description: {
Text("Enable location access in Settings to use this feature.")
} actions: {
Button("Open Settings") {
if let url = URL(string: UIApplication.openSettingsURLString) {
openURL(url)
}
}
}
}
}Geocoding
地理编码
CLGeocoder (iOS 8+)
CLGeocoder(iOS 8+)
swift
let geocoder = CLGeocoder()
// Forward geocoding: address string -> coordinates
let placemarks = try await geocoder.geocodeAddressString("1 Apple Park Way, Cupertino")
if let location = placemarks.first?.location {
print(location.coordinate) // CLLocationCoordinate2D
}
// Reverse geocoding: coordinates -> placemark
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: ", ")
}swift
let geocoder = CLGeocoder()
// Forward geocoding: address string -> coordinates
let placemarks = try await geocoder.geocodeAddressString("1 Apple Park Way, Cupertino")
if let location = placemarks.first?.location {
print(location.coordinate) // CLLocationCoordinate2D
}
// Reverse geocoding: coordinates -> placemark
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 and MKReverseGeocodingRequest (iOS 26+)
MKGeocodingRequest 和 MKReverseGeocodingRequest(iOS 26+)
New MapKit-native geocoding that returns with richer data and
/ for flexible address formatting.
MKMapItemMKAddressMKAddressRepresentationsswift
@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
}MapKit 原生地理编码能力,返回包含更丰富数据的 ,以及支持灵活地址格式化的 / 。
MKMapItemMKAddressMKAddressRepresentationsswift
@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
}Search
搜索
MKLocalSearchCompleter (Autocomplete)
MKLocalSearchCompleter(自动补全)
swift
@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 = []
}
}swift
@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 (Full Search)
MKLocalSearch(全量搜索)
swift
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
}
// Search by natural language query within a 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
}swift
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
}
// Search by natural language query within a 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
}Directions
导航路线
swift
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
}swift
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
}Display Route on Map
在地图上展示路线
swift
@State private var route: MKRoute?
Map {
if let route {
MapPolyline(route.polyline)
.stroke(.blue, lineWidth: 5)
}
Marker("Start", coordinate: startCoord)
Marker("End", coordinate: endCoord)
}
.task {
route = try? await getDirections(from: startItem, to: endItem)
}swift
@State private var route: MKRoute?
Map {
if let route {
MapPolyline(route.polyline)
.stroke(.blue, lineWidth: 5)
}
Marker("Start", coordinate: startCoord)
Marker("End", coordinate: endCoord)
}
.task {
route = try? await getDirections(from: startItem, to: endItem)
}ETA Calculation
预计到达时间计算
swift
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
}swift
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
}Cycling Directions (iOS 26+)
骑行路线(iOS 26+)
swift
@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
}swift
@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+)
PlaceDescriptor(iOS 26+)
Create rich place references from coordinates or addresses without needing a
Place ID. Requires .
import GeoToolboxswift
@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
}无需 Place ID 即可通过坐标或地址创建丰富的地点引用,需要导入 。
GeoToolboxswift
@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
}Common Mistakes
常见错误
DON'T: Request upfront — users distrust broad permissions.
DO: Start with , escalate to only when the user enables a background feature.
.authorizedAlways.requestWhenInUseAuthorization().alwaysDON'T: Use for simple location fetches on iOS 17+.
DO: Use async stream for cleaner, more concise code.
CLLocationManagerDelegateCLLocationUpdate.liveUpdates()DON'T: Keep location updates running when the map/view is not visible (drains battery).
DO: Use in SwiftUI so updates cancel automatically on disappear.
.task { }DON'T: Force-unwrap properties — they are all optional.
DO: Use nil-coalescing: .
CLPlacemarkplacemark.locality ?? "Unknown"DON'T: Fire queries on every keystroke.
DO: Debounce with + .
MKLocalSearchCompleter.task(id: searchText)Task.sleep(for: .milliseconds(300))DON'T: Silently fail when location authorization is denied.
DO: Detect status and show an alert with a Settings deep link.
.deniedDON'T: Assume geocoding always succeeds — handle empty results and network errors.
不要: 一开始就申请 权限 —— 用户会对大范围权限产生不信任。
推荐: 先申请 ,仅当用户启用后台功能时再升级到 权限。
.authorizedAlways.requestWhenInUseAuthorization().always不要: iOS 17+ 系统中简单的位置获取仍使用 。
推荐: 使用 异步流实现更简洁清晰的代码。
CLLocationManagerDelegateCLLocationUpdate.liveUpdates()不要: 地图/视图不可见时仍保持位置更新运行(会消耗电池)。
推荐: 在 SwiftUI 中使用 ,这样视图消失时更新会自动取消。
.task { }不要: 强制解包 属性 —— 所有属性都是可选的。
推荐: 使用空合运算符:。
CLPlacemarkplacemark.locality ?? "Unknown"不要: 每次按键都触发 查询。
推荐: 通过 + 实现防抖。
MKLocalSearchCompleter.task(id: searchText)Task.sleep(for: .milliseconds(300))不要: 位置授权被拒绝时静默失败。
推荐: 检测到 状态时展示弹窗,提供跳转设置页的深链。
.denied不要: 假设地理编码总是成功 —— 要处理空结果和网络错误。
Review Checklist
评审 Checklist
- Info.plist has with specific reason
NSLocationWhenInUseUsageDescription - Authorization denial handled with Settings deep link
- task cancelled when not needed (battery)
CLLocationUpdate - Location accuracy appropriate for the use case
- Map annotations use data with stable IDs
Identifiable - Geocoding errors handled (network failure, no results)
- Search completer input debounced
- limited to 20 conditions, instance kept alive
CLMonitor - Background location uses
CLBackgroundActivitySession - Map tested with VoiceOver
- Map annotation view models and location UI updates are -isolated
@MainActor
- Info.plist 中包含带有明确使用理由的
NSLocationWhenInUseUsageDescription - 授权被拒绝时提供跳转设置页的深链
- 不需要时取消 任务(节省电量)
CLLocationUpdate - 位置精度适配使用场景
- 地图标注使用带有稳定 ID 的 数据
Identifiable - 地理编码错误已处理(网络失败、无结果)
- 搜索补全输入已做防抖处理
- 限制在20个条件以内,实例保持存活
CLMonitor - 后台定位使用
CLBackgroundActivitySession - 地图已通过 VoiceOver 测试
- 地图标注视图模型和位置 UI 更新已做 隔离
@MainActor
References
参考资料
- references/mapkit-patterns.md — Map setup, annotations, search, routes, clustering, Look Around, snapshots.
- references/mapkit-corelocation-patterns.md — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.
- references/mapkit-patterns.md —— 地图配置、标注、搜索、路线、聚类、环视、截图。
- references/mapkit-corelocation-patterns.md —— CLLocationUpdate、CLMonitor、CLServiceSession、后台定位、测试。