用途:面向 iOS 17+,用 SwiftUI MapKit 与现代 CoreLocation 异步 API 构建或审查地图与位置感知功能;使用 Map 搭配 MapContentBuilder 构建视图,用 CLLocationUpdate.liveUpdates() 流式获取位置,用 CLMonitor 实现地理围栏。
主要能力:地图视图、相机控制、标注与覆盖物、用户位置、地理编码、地点搜索与补全、路线、聚合、Look Around、快照;位置更新生命周期、地理围栏、后台定位、隐私键与测试。涉及搜索、路线、Look Around、快照或 iOS 26 地点 API 时查阅 references/mapkit-patterns.md;涉及位置更新、地理围栏、后台定位、测试或隐私键时查阅 references/mapkit-corelocation-patterns.md。
必要用法:先明确所需的地图/位置能力并只申请对应授权;选择 SwiftUI Map 或 UIKit 承载,确定相机归属、选中状态、标注与覆盖物标识;搜索、地理编码、路线与实时定位任务需可取消并限定当前查询/会话;处理拒绝、受限与降低精度状态;验证空结果、移动、相机变化、路线失败、本地化、离线切换与后台规则。
限制与注意:不要从 API 可用性或缓存的非空位置推断授权;标注与覆盖物用稳定标识;输入变化时防抖并取消搜索/地理编码;将尺寸、视口与交互视为实时状态。iOS 18+ 用 when-in-use 起步,保持 CLServiceSession,仅后台功能才申请 .always;iOS 17+ 简单定位用 liveUpdates() 而非 CLLocationManagerDelegate;处理拒绝诊断并提供设置引导;视图消失后取消任务、过滤无效/不精确/过期定位;CLPlacemark 属性均可选,用空合并处理;搜索补全需防抖(如 .task(id:) 加 Task.sleep 300ms);地理编码失败要处理;CLMonitor 上限 20 个条件并保持实例存活;后台定位用 CLBackgroundActivitySession;地图需测试 VoiceOver;相关视图模型与位置 UI 更新用 @MainActor 隔离。