{"id":"62530660-794a-4826-bf3c-43b0f962c368","entityType":"agent","slug":"clawhub-baidu-maps-baidu-map-ios-sdk","name":"Baidu Map IOS SDK（百度地图官方IOS SKills）","canonicalUrl":"https://www.xpersona.co/agent/clawhub-baidu-maps-baidu-map-ios-sdk","canonicalPath":"/agent/clawhub-baidu-maps-baidu-map-ios-sdk","generatedAt":"2026-10-10T17:34:47.814Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T15:15:35.151Z","emptyReason":null},"description":"百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。 Skill: Baidu Map IOS SDK（百度地图官方IOS SKills） Owner: baidu-maps Summary: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。 Tags: latest:1.0.2 Version history: v1.0.2 | 2026-06-01T03:40:38.452Z | user baidu-map-ios-sdk 1.0.2 - 移除元数据文件 _meta.json。 - 移除技能简介卡片 skill-card.md。 - 保持主功能、集成文档和规则不变，仅精简技能包结构。 v1.0.1 | 2026-04-07T04:07:47.729Z | user Initial release","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s178nge8tvzzhnan6cc08q0ech84dmtm:baidu-map-ios-sdk","sourceUrl":"https://clawhub.ai/baidu-maps/baidu-map-ios-sdk","homepage":"https://clawhub.ai/baidu-maps/skills/baidu-map-ios-sdk","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/baidu-maps/baidu-map-ios-sdk","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/baidu-maps/skills/baidu-map-ios-sdk","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。 Skill: Baidu Map IOS SDK（百度地图官方IOS SKills） O"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T15:15:35.151Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T15:15:35.151Z","emptyReason":null},"stars":null,"forks":null,"downloads":1365,"packageName":null,"latestVersion":"1.0.2","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T15:15:35.150Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T15:15:35.151Z","lastCrawledAt":"2026-10-10T15:15:35.150Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T15:15:35.150Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.2","createdAt":"2026-06-01T03:40:38.452Z","changelog":"baidu-map-ios-sdk 1.0.2 - 移除元数据文件 _meta.json。 - 移除技能简介卡片 skill-card.md。 - 保持主功能、集成文档和规则不变，仅精简技能包结构。","fileCount":17,"zipByteSize":59241},{"version":"1.0.1","createdAt":"2026-04-07T04:07:47.729Z","changelog":"Initial release of baidu-map-ios-sdk skill. - Provides integration and usage guidelines for Baidu Map iOS SDK and BMKLocationKit. - Covers configuration for map, location, walking/cycling navigation, search, routes, markers, overlays, and use of professional map features. - Details explicit integration steps (CocoaPods, AK & Bundle instructions), privacy compliance, and Info.plist/Launch Screen requirements. - Enforces use of BMKIconMarker/BMKTextMarker for point markers and prioritizes texture usage for routes and icons. - Includes rules for coordinate systems, logo non-obstruction, route viewport fitting, and toolkit selection for walking/cycling scenarios. - Defines output and documentation standards for solutions, ensuring proposals are actionable, verifiable, and code is build-validated.","fileCount":17,"zipByteSize":59240},{"version":"1.0.0","createdAt":"2026-03-11T09:15:09.770Z","changelog":"baidu-map-ios-sdk 1.0.0 - 初始发布，提供百度地图 iOS SDK 集成与开发规范，涵盖地图、定位、步骑行导航等主要能力。 - 明确集成顺序与开发者须知，包括 AK 配置、Bundle 校验、Launch Screen 必配、隐私声明弹窗与 Info.plist 设置等关键要求。 - 细化关键点：点标注优先用 Marker、路线优先用纹理、Logo 不可被遮挡、路线需适配视野。 - 输出标准化：方案需落地、可验证、可组合，强调代码编译必须通过，流程自动化至构建通过为止。","fileCount":16,"zipByteSize":57589}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s178nge8tvzzhnan6cc08q0ech84dmtm:baidu-map-ios-sdk","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T17:34:47.811Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-baidu-maps-baidu-map-ios-sdk/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T15:15:35.151Z","emptyReason":null},"readme":"Skill: Baidu Map IOS SDK（百度地图官方IOS SKills）\n\nOwner: baidu-maps\n\nSummary: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。\n\nTags: latest:1.0.2\n\nVersion history:\n\nv1.0.2 | 2026-06-01T03:40:38.452Z | user\n\nbaidu-map-ios-sdk 1.0.2\n\n- 移除元数据文件 _meta.json。\n- 移除技能简介卡片 skill-card.md。\n- 保持主功能、集成文档和规则不变，仅精简技能包结构。\n\nv1.0.1 | 2026-04-07T04:07:47.729Z | user\n\nInitial release of baidu-map-ios-sdk skill.\n\n- Provides integration and usage guidelines for Baidu Map iOS SDK and BMKLocationKit.\n- Covers configuration for map, location, walking/cycling navigation, search, routes, markers, overlays, and use of professional map features.\n- Details explicit integration steps (CocoaPods, AK & Bundle instructions), privacy compliance, and Info.plist/Launch Screen requirements.\n- Enforces use of BMKIconMarker/BMKTextMarker for point markers and prioritizes texture usage for routes and icons.\n- Includes rules for coordinate systems, logo non-obstruction, route viewport fitting, and toolkit selection for walking/cycling scenarios.\n- Defines output and documentation standards for solutions, ensuring proposals are actionable, verifiable, and code is build-validated.\n\nv1.0.0 | 2026-03-11T09:15:09.770Z | user\n\nbaidu-map-ios-sdk 1.0.0\n\n- 初始发布，提供百度地图 iOS SDK 集成与开发规范，涵盖地图、定位、步骑行导航等主要能力。\n- 明确集成顺序与开发者须知，包括 AK 配置、Bundle 校验、Launch Screen 必配、隐私声明弹窗与 Info.plist 设置等关键要求。\n- 细化关键点：点标注优先用 Marker、路线优先用纹理、Logo 不可被遮挡、路线需适配视野。\n- 输出标准化：方案需落地、可验证、可组合，强调代码编译必须通过，流程自动化至构建通过为止。\n\nArchive index:\n\nArchive v1.0.2: 17 files, 59241 bytes\n\nFiles: references/annotations.md (3338b), references/assets.md (1239b), references/class-index.md (7708b), references/cocoapods.md (1760b), references/location.md (10966b), references/mapview.md (21046b), references/navi.md (5233b), references/overlays.md (20945b), references/project-config.md (5675b), references/reference.md (3753b), references/route.md (12187b), references/search.md (11745b), references/ui-standards.md (12422b), references/utils.md (6283b), skill-card.md (3429b), SKILL.md (11419b), _meta.json (136b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: baidu-map-ios-sdk\ndescription: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。\ncompatibility: iOS, Xcode, CocoaPods\n---\n\n# 百度地图 iOS SDK\n\n## 目标与边界\n\n- **目标**：在 iOS 工程中正确集成百度地图/定位/步骑行导航，并给出符合隐私与坐标系规范的实现方案。\n- **负责**：BaiduMapKit、BMKLocationKit、BaiduWalkNaviKit 的集成、配置、API 选用与示例；与技能内 reference 文档一致。\n- **不负责**：驾车导航细节（百度地图驾车导航文档）、服务端逻辑、非百度 SDK、UI 视觉设计（仅遵循 [ui-standards.md](references/ui-standards.md) 的规范）。\n\n## 使用时机\n\n满足其一即启用本技能：\n\n- 关键词：百度地图、BMKMapView、BMKLocationKit、步骑行导航、BaiduWalkNaviKit、标注、路线规划、CocoaPods 集成、BD09、定位鉴权\n- 需求类型：地图展示、单次/连续/后台定位、步行或骑行实时导航、POI/标注/覆盖物、路线绘制、逆地理、轨迹动画、点聚合、隐私弹窗\n\n**按需加载**：先根据需求在 [reference.md](references/reference.md) 中选定文档，再引用对应 references 内容；需求含糊时先向用户澄清再给方案。\n\n## 集成与编码顺序\n\n- **未集成百度地图 SDK 时**：先配置并执行 CocoaPods（编写/补全 Podfile → 执行 `pod install` → 使用生成的 `.xcworkspace` 打开），**在能正确导入 SDK 头文件之后**再编写调用地图/定位/检索等的代码。这样既避免使用 `#if __has_include(...)` 做条件编译，也能以实际 SDK 头文件为准写代码，减少接口不一致或编译错误。\n- **本地已集成 SDK 时**：直接按需导入头文件并写代码，**以当前工程内的 SDK 版本、头文件及接口为准**；类名、方法、参数与本地头文件一致，不写不存在的 API。若编译报错提示符号不存在，提示开发者核对或更新 Pod 版本后再重试。\n\n## Agent 执行要求\n\n1. **AK 与 Bundle 主动提示**  \n   在编写或集成使用地图/定位 SDK 的代码时，**主动提示开发者**：\n   - 在 [百度 LBS 控制台](https://lbsyun.baidu.com/) 申请 **iOS 应用 AK**，且应用的 **Bundle Identifier** 必须与工程中 `PRODUCT_BUNDLE_IDENTIFIER` 一致；\n   - 在代码或配置中预留/替换 AK 的位置（如 `AppDelegate` 中的 key、或说明需在控制台配置），并注明「将 `YOUR_AK` 替换为实际 AK」。\n   - 若工程尚未配置 Bundle ID，提醒开发者设置并与控制台申请时填写的包名一致。\n\n2. **代码写完自动执行编译修复，编译无误后停止**  \n   完成与百度地图/定位相关的代码修改后，**必须**按以下流程执行，**不得在编译未通过时结束**：\n   - **自动执行编译**：使用 `xcodebuild -workspace xxx.xcworkspace -scheme xxx -destination 'generic/platform=iOS' build`（或等价命令；CocoaPods 工程用 workspace，纯工程用 project）。\n   - **若编译报错**：根据报错信息**立即修复**（类名、方法签名、头文件、ARC、协议声明等），修复后**再次执行编译**。\n   - **循环**：重复「编译 → 若有错误则修复 → 再编译」，直至**编译通过、无错误**。\n   - **编译无误后停止**：仅当 build 成功（BUILD SUCCEEDED）后，才结束本轮代码修改与修复，不再继续做与编译无关的额外修改。\n\n3. **配置 Launch Screen 避免 App 非全屏**  \n   集成地图或涉及全屏展示时，**必须**确保工程已配置 Launch Screen，避免运行后出现黑边、非全屏。具体见 [project-config.md](references/project-config.md)「窗口初始化/Launch Screen」：\n   - 工程内存在 **LaunchScreen.storyboard**（或等效 Launch 资源），并加入 target 的 Resources；\n   - Info.plist 中配置 **UILaunchStoryboardName** 为 `LaunchScreen`；\n   - 若缺失，主动创建或补充说明，并提醒开发者添加该配置。\n\n## 必须遵守的规则\n\n1. **隐私与配置**\n   - 首次使用前必须弹窗让用户阅读并同意隐私政策，再调用对应接口。\n   - **地图**：`[BMKMapManager setAgreePrivacy:YES]`（**类方法**，勿用 `sharedInstance`；未同意时检索可返回 nil）。\n   - **定位**：通过 **BMKLocationAuth** 的 **setAgreePrivacy** 在用户同意后再初始化 BMKLocationManager 等；详见 [location.md](references/location.md)。\n   - Info.plist 必配 **CFBundleDisplayName**；使用定位时配 NSLocationWhenInUseUsageDescription 等。详见 [project-config.md](references/project-config.md)。\n   - **AK 与 Bundle**：编写集成代码时主动提示开发者提供/配置 AK，且 Bundle Identifier 与百度控制台申请一致（见上文「Agent 执行要求」）。\n   - **Launch Screen**：必须配置 LaunchScreen.storyboard 与 Info.plist 的 UILaunchStoryboardName，避免运行后 App 非全屏、黑边；见 [project-config.md](references/project-config.md)。\n\n2. **坐标系**\n   - 地图 SDK 全局 **BD09**；定位 SDK 默认 **GCJ02**。与地图混用时须统一为 BD09：将定位 **coordinateType** 设为 **BMKLocationCoordinateTypeBMK09LL**，或使用 [utils.md](references/utils.md) 的 BMKCoordTrans 转换。\n\n3. **标注与几何（必须遵守）**\n   - **点标注优先使用 Marker，不得使用 Annotation/PinAnnotation**：点标注**必须优先**使用 **BMKIconMarker/BMKTextMarker**（addOverlay 体系），**禁止**使用 BMKPointAnnotation、BMKAnnotationView、BMKPinAnnotationView（addAnnotation 体系）除非以下例外：点聚合（BMKClusterManager 必须用 BMKPointAnnotation）、固定屏选点（isLockedToScreen）等仅 addAnnotation 能实现的场景。起终点、小车、普通图钉等一律用 Marker。详见 [overlays.md](references/overlays.md)、[annotations.md](references/annotations.md)。\n   - 距离、视野、方位等用 [utils.md](references/utils.md) 的 BMKGeometry 等，勿手写。\n   - **路线与起终点须优先使用纹理**：绘制**路线**时优先使用 **BMKPolylineView.textureImage**（图片宽高须为 2 的 n 次幂）或路况场景使用 **BMKMultiTexturePolylineView** + [assets](references/assets.md) 路况纹理；**起终点**的 BMKIconMarker.icon 须优先使用 [assets](references/assets.md) 的 **icon_start、icon_end**；仅当无可用纹理时再使用 strokeColor/纯色或自绘。见 [overlays.md](references/overlays.md)「路线与起终点：纹理优先」。\n   - **路线小车纹理**：路线上的小车图标**必须优先使用**本技能 [assets](references/assets.md)（`assets/images/`）提供的纹理图（如 icon_car、car_triangle、track_car）；仅当无可用纹理时，才使用纯色或自绘图片。\n\n4. **步骑行：按需求区分两种方案**\n   - **路线规划（算路+画线）**：BMKRouteSearch（BaiduMapKit），walkingSearch/ridingSearch，得到路线后自绘折线。见 [route.md](references/route.md)。\n   - **步骑行实时导航**：BaiduWalkNaviKit，Manager + 诱导、TTS、偏航纠偏、多实例/无UI。见 [navi.md](references/navi.md)。\n   - 二者是**不同服务**：仅需画线用 route；需实时导航用 navi。给出方案前先按开发者需求选对文档。\n\n5. **版本与 API 以本地为准**（与上文「集成与编码顺序」一致）\n   - 已集成 SDK：**以工程内 SDK 版本与头文件为准**，类名、方法、参数与头文件一致；不写 `#if __has_include`，直接导入头文件后写代码。\n   - 若某类、方法或属性在用户工程中**不存在**（编译报错或头文件无此符号），**提示用户将对应 Pod 更新到最新版本**后再重试，勿强行按文档写不存在的 API。\n\n6. **Logo 不可遮挡与路线视野适配（必须考虑）**\n   - **Logo 不能被遮挡**：百度地图 Logo 不可移除、不允许被 UI 遮挡。有浮动栏/底部栏时**必须**使用 `setMapPadding` 预留边界（如顶部预留检索面板、底部预留 barH+4），使 Logo 落在可见内容区内。详见 [ui-standards.md](references/ui-standards.md)「地图 Logo、指南针与 mapPadding」。\n   - **路线适配视野必须做**：有路线绘制时**必须**调用 `fitVisibleMapRect:edgePadding:withAnimated:` 做视野适配，edgePadding 按 [ui-standards.md](references/ui-standards.md)「路线视野适配」预留（顶部检索面板+50+marker、底部底部栏+20+marker、左右 50+marker 等），避免路线或起终点被裁切或被 UI 遮挡。mapPadding 与 fitVisibleMapRect 的 edgePadding 分开使用，勿混用。\n\n## 输出规范（可评估）\n\n给出方案时需满足：\n\n- **可落地**：含具体类名、方法、调用顺序与必要配置（如 Info.plist、隐私调用时机、Launch Screen）。\n- **可验证**：隐私与坐标系处理明确；若涉及定位鉴权失败，方案中可指向 [location.md](references/location.md) 的「鉴权失败排查」。\n- **可组合**：按 [reference.md](references/reference.md) 选文档与常见组合；步骑行选型见规则 4。\n- **AK/Bundle 提示**：涉及地图/定位初始化时，明确提示开发者配置 AK 与 Bundle Identifier。\n- **编写后编译直至通过**：完成代码编写后，自动执行 xcodebuild 编译；若有报错则根据错误修复并重新编译，循环直至编译无误，再停止。\n- **全屏与 Launch Screen**：涉及地图全屏或窗口大小时，确认或说明已配置 LaunchScreen.storyboard 与 UILaunchStoryboardName，避免运行后非全屏、黑边。\n- **Logo 不遮挡**：涉及地图且有浮动栏/底部栏时，方案中**必须**包含 setMapPadding，并说明底部预留尽量小（如 barH+4），确保 Logo 不被遮挡。\n- **路线视野适配**：涉及路线绘制时，方案中**必须**包含 fitVisibleMapRect 的 edgePadding 设置，按 ui-standards 预留顶底左右，确保路线与起终点在可视区内且不被 UI 遮挡。\n- **点标注用 Marker**：涉及地图点标注（起终点、小车、图钉等）时，**必须**使用 BMKIconMarker/BMKTextMarker（addOverlay），不得使用 BMKPointAnnotation/BMKPinAnnotationView，除非点聚合、固定屏选点等例外场景。\n- **路线与起终点纹理优先**：涉及路线折线或起终点 Marker 时，**必须**优先使用纹理（路线：BMKPolylineView.textureImage 或 BMKMultiTexturePolylineView；起终点：BMKIconMarker.icon 使用 [assets](references/assets.md) 的 icon_start/icon_end），仅无可用纹理时再写 strokeColor 或自绘；见 [overlays.md](references/overlays.md)「路线与起终点：纹理优先」。\n\n方案结构：需求 → 对应文档 → 配置与依赖（含 AK/Bundle、Launch Screen）→ 关键 API → 示例片段 → 注意事项（含 Logo/路线视野、Marker 优先）。\n\n## 参考索引\n\n- 选文档与边界：[reference.md](references/reference.md)\n- 类速查：[class-index.md](references/class-index.md)\n- 定位/鉴权：[location.md](references/location.md) \n- 步骑行导航：[navi.md](references/navi.md) \n- 资源：[assets.md](references/assets.md)\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn778b6bf766ym71fdvrc5yvg98319rv\",\n  \"slug\": \"baidu-map-ios-sdk\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1780285238452\n}\n\nFile v1.0.2:references/annotations.md\n\n# 标注 (Annotation)\n\n**边界**：addAnnotation 体系；覆盖物见 [overlays.md](overlays.md)。**必须遵守**：点标注**优先使用 Marker**（BMKIconMarker/BMKTextMarker，addOverlay），**不得使用** Annotation/PinAnnotation 做起终点、小车、普通图钉等；**仅**点聚合、固定屏选点等必须用 addAnnotation 的场景才用本 API。见 [SKILL.md](../SKILL.md) 规则 3。\n\n## 使用须知\n- **Delegate**：addAnnotation 前必须设置 `mapView.delegate`，并实现 `mapView:viewForAnnotation:`。\n- **复用**：使用 `dequeueReusableAnnotationViewWithIdentifier`，identifier 建议唯一。\n- **起终点**：推荐 BMKIconMarker（addOverlay），见 [overlays.md](overlays.md)。\n\n## 核心类\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKAnnotation | BMKAnnotation.h | 标注协议，`coordinate`、`title` |\n| BMKPointAnnotation | BMKPointAnnotation.h | 点标注 |\n| BMKAnnotationView | BMKAnnotationView.h | 标注视图基类 |\n| BMKPinAnnotationView | BMKPinAnnotationView.h | 大头针样式 |\n| BMKActionPaopaoView | BMKActionPaopaoView.h | 气泡视图 |\n\n**标注规范**：使用 `dequeueReusableAnnotationViewWithIdentifier` 复用，identifier 建议唯一。自定义图片用 BMKAnnotationView + image。\n\n## 固定屏幕标注（地图选点）\n\n`BMKPointAnnotation.isLockedToScreen = YES` + `screenPointToLock`，需在 `mapViewDidFinishLoading` 后设置。常用于地图选点。\n\n**方式 B（BMKIconMarker）**：Marker 无 isLockedToScreen，需在 `regionDidChangeAnimated:reason:` 中（reason == BMKRegionChangeReasonGesture）同步 `marker.coordinate = mapView.centerCoordinate`。**区域回调**：regionWillChange 跳起，regionDidChange 落下 + 逆地理。**选点动画**见 [ui-standards.md](ui-standards.md)。\n\n## BMKPinAnnotationView 常用属性\n\n`centerOffset`、`calloutOffset`（正偏移朝右下方）、`enabled3D`、`canShowCallout`、`leftCalloutAccessoryView`/`rightCalloutAccessoryView`（默认气泡最大 32×41）、`pinColor`（Red/Green/Purple）、`animatesDrop`、`draggable`。直接设置 `selected` 时，非 PinAnnotation 需在设置后调用 `mapForceRefresh`。\n\n## 碰撞检测与展示优先级\n\n`BMKAnnotationView.displayPriority`（如 `BMKFeatureDisplayPriorityDefaultHigh`）、`isOpenCollisionDetection`、`collisionDetectionPriority`（数值越大越优先）、`isForceDisplay`（强制展示）、`displayMaxLevel`/`displayMinLevel`（层级限制）。\n\n## 点聚合中的标注\n\n点聚合（BMKClusterManager + BMKPointAnnotation）将大量标注按 zoom 聚合。`viewForAnnotation` 按 cluster.size 区分单点/聚合点；size>1 可显示数量、按档设圆点大小。**点击拆簇**：`annotationViewForBubble` 中 zoomIn。聚合逻辑见 [overlays.md](overlays.md)。\n\n---\n\n## 按需方案\n\n| 需求 | 基础能力 |\n|------|----------|\n| 普通点标注 | BMKPointAnnotation + BMKAnnotationView |\n| 大头针 | BMKPointAnnotation + BMKPinAnnotationView |\n| 固定屏幕选点 | BMKPointAnnotation（isLockedToScreen + screenPointToLock）或 BMKIconMarker |\n| 起终点大头针 | BMKPointAnnotation + BMKAnnotationView（起终点推荐 BMKIconMarker，见 [overlays.md](overlays.md)） |\n| 点聚合标注 | BMKClusterManager + BMKPointAnnotation，viewForAnnotation 按 size 展示 |\n\nFile v1.0.2:references/assets.md\n\n# 图片资源\n\n**边界**：技能内 `assets/images/` 图片及用途；集成与构建见 [cocoapods.md](cocoapods.md)、[project-config.md](project-config.md)。\n\n**路线小车**：路线上的小车图标**必须优先使用**本技能提供的纹理图（下表 icon_car / car_triangle / track_car）；仅当无可用纹理时，才使用纯色或自绘图片。实现时先 `[UIImage imageNamed:@\"icon_car\"]`（或对应名称），为 nil 再回退。\n\n| 图片 | 用途 |\n|------|------|\n| icon_car | 小车 marker（**路线小车优先**） |\n| car_triangle | 带方向小车（车头朝上） |\n| track_car | 带方向小车（车头朝右），**轨迹动画推荐** |\n| icon_start | 起点标注 |\n| icon_end | 终点标注 |\n| icon_via | 途经点 |\n| **路况纹理**（BMKMultiPolyline + BMKMultiTexturePolylineView，drawIndexs 来自 BMKDrivingStep.traffics） | |\n| traffic_texture_unknown | 无数据（traffics=0，drawIndex 0） |\n| traffic_texture_smooth | 畅通（traffics=1，drawIndex 1） |\n| traffic_texture_slow | 缓行（traffics=2，drawIndex 2） |\n| traffic_texture_congestion | 拥堵（traffics=3，drawIndex 3） |\n| traffic_texture_severe_congestion | 严重拥堵（traffics=4，drawIndex 4） |\n\nFile v1.0.2:references/class-index.md\n\n# 类速查表\n\n**边界**：按头文件组织的类速查；用法与示例见 [annotations.md](annotations.md)、[overlays.md](overlays.md) 等各功能文档。下表记录类名、头文件及主要方法/属性名，便于不依赖外链查阅。\n\n## 地图核心\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKMapManager | BMKMapManager.h | 主引擎 |\n| BMKMapView | BMKMapView.h | 地图视图 |\n| BMKMapStatus | BMKMapStatus.h | 地图状态 |\n| BMKMapViewDelegate | BMKMapView.h | 地图回调 |\n\n## 标注\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKAnnotation | BMKAnnotation.h | 标注协议 |\n| BMKPointAnnotation | BMKPointAnnotation.h | 点标注 |\n| BMKAnnotationView | BMKAnnotationView.h | 标注视图基类 |\n| BMKPinAnnotationView | BMKPinAnnotationView.h | 大头针样式 |\n| BMKActionPaopaoView | BMKActionPaopaoView.h | 气泡视图 |\n\n## 覆盖物\n\n### 基础\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKOverlay | BMKOverlay.h | 覆盖物协议 |\n| BMKOverlayView | BMKOverlayView.h | 覆盖物视图基类 |\n| BMKPolyline | BMKPolyline.h | 单色/单纹理折线 |\n| BMKPolylineView | BMKPolylineView.h | 折线视图 |\n| BMKMultiPolyline | BMKMultiPolyline.h | 分段折线，需 drawIndexs |\n| BMKMultiColorPolylineView | BMKMultiPolylineView.h | 分段颜色 |\n| BMKMultiTexturePolylineView | BMKMultiPolylineView.h | 分段纹理（路况） |\n| BMKCircle | BMKCircle.h | 圆形 |\n| BMKCircleView | BMKCircleView.h | 圆形视图 |\n| BMKPolygon | BMKPolygon.h | 多边形 |\n| BMKPolygonView | BMKPolygonView.h | 多边形视图 |\n| BMKGroundOverlay | BMKGroundOverlay.h | 图片图层 |\n| BMKGroundOverlayView | BMKGroundOverlayView.h | 图片图层视图 |\n| BMKTileLayer | BMKTileLayer.h | 瓦片图层基类 |\n| BMKURLTileLayer | BMKTileLayer.h | URL 瓦片图层 |\n\n### 曲线与渐变\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKArcline | BMKArcline.h | 圆弧 |\n| BMKArclineView | BMKArclineView.h | 圆弧视图 |\n| BMKGradientLine | BMKGradientLine.h | 渐变线 |\n| BMKGradientLineView | BMKGradientLineView.h | 渐变线视图 |\n| BMKGradientCircleView | BMKGradientCircleView.h | 渐变圆 |\n| BMKGeodesicLine | BMKGeodesicLine.h | 大地线 |\n| BMKGeodesicLineView | BMKGeodesicLineView.h | 大地线视图 |\n\n### Marker\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKIconMarker | BMKIconMarker.h | 图标 Marker |\n| BMKIconMarkerView | BMKIconMarkerView.h | 图标 Marker 视图 |\n| BMKTextMarker | BMKTextMarker.h | 文本 Marker |\n| BMKTextMarkerView | BMKTextMarkerView.h | 文本 Marker 视图 |\n| BMKTextPathMarker | BMKTextPathMarker.h | 沿路径文字 |\n| BMKTextPathMarkerView | BMKTextPathMarkerView.h | 沿路径文字视图 |\n\n### 文本与海量点\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKText | BMKText.h | 文本 overlay |\n| BMKTextView | BMKTextView.h | 文本 overlay 视图 |\n| BMKMultiPointOverlay | BMKMultiPointOverlay.h | 海量点 |\n| BMKMultiPointOverlayView | BMKMultiPointOverlayView.h | 海量点视图 |\n| BMKMultiPointItem | BMKMultiPointOverlay.h | 海量点数据项 |\n\n### 3D 与轨迹\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMK3DModelOverlay | BMK3DModelOverlay.h | 3D 模型 |\n| BMK3DModelOverlayView | BMK3DModelOverlayView.h | 3D 模型视图 |\n| BMKPrismOverlay | BMKPrismOverlay.h | 棱柱/3D 建筑 |\n| BMKPrismOverlayView | BMKPrismOverlayView.h | 棱柱视图 |\n| BMKTraceOverlay | BMKTraceOverlay.h | 路书轨迹 |\n| BMKTraceOverlayView | BMKTraceOverlayView.h | 路书轨迹视图 |\n| BMK3DTraceOverlay | BMK3DTraceOverlay.h | 3D 轨迹 |\n| BMK3DTraceOverlayView | BMK3DTraceOverlayView.h | 3D 轨迹视图 |\n| BMKMapTrackAnimation | BMKMapAnimation.h | 轨迹动画 |\n| BMKCommonDef | BMKCommonDef.h | 枚举定义 |\n\n详见 [annotations.md](annotations.md)、[overlays.md](overlays.md)。\n\n## 检索\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKSuggestionSearch | BMKSuggestionSearch.h | 建议检索 |\n| BMKGeoCodeSearch | BMKGeoCodeSearch.h | 地理编码 |\n| BMKPOISearch | BMKPOISearch.h | POI |\n| BMKBusLineSearch | BMKBusLineSearch.h | 公交线路 |\n| BMKRouteSearch | BMKRouteSearch.h | 路线检索（算路见路线规划） |\n\n## 路线规划\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKRouteSearch | BMKRouteSearch.h | 路线检索 |\n| BMKDrivingRoutePlanOption | BMKRouteSearchOption.h | 驾车 |\n| BMKWalkingRoutePlanOption | BMKRouteSearchOption.h | 步行 |\n| BMKRidingRoutePlanOption | BMKRouteSearchOption.h | 骑行 |\n| BMKTransitRoutePlanOption | BMKRouteSearchOption.h | 公交 |\n| BMKPlanNode | BMKTypes.h | 路线节点（pt、name、cityName、cityID） |\n| BMKDrivingRouteResult / BMKWalkingRouteResult 等 | BMKRouteSearchResult.h | 算路结果 |\n| BMKDrivingStep / BMKWalkingStep 等 | BMKRouteSearchType.h | 路线步骤类型 |\n\n## 步骑行导航（BaiduWalkNaviKit）\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKWalkNavigationManager | BMKWalkNavigationManager.h | 步行导航管理，单例；destroy、initNaviEngine、routePlanWithParams、startWalkNaviWithParentController、getBackgroundNavigationView |\n| BMKCycleNavigationManager | BMKCycleNavigationManager.h | 骑行导航管理，单例；destroy、initNaviEngine、routePlanWithParams、naviCalcRoute:、startCycleNaviWithParentController、getBackgroundNavigationView |\n| BMKWalkNaviLaunchParam | BMKWalkNaviLaunchParam.h | 步行算路参数（startNode/endNode，BMKWalkNaviRouteNodeInfo） |\n| BMKCycleNaviLaunchParam | BMKCycleNaviLaunchParam.h | 骑行算路参数（startNode/endNode） |\n| BMKWalkNaviRouteNodeInfo | BMKWalkNaviRouteNodeInfo.h | 步行起/终点节点（type BMKWalkNavigationRouteNodeLocation 等） |\n| BMKCycleNaviRouteNodeInfo | BMKCycleNaviRouteNodeInfo.h | 骑行起/终点节点 |\n| BMKWalkCycleNavigationOptions | BMKWalkCycleNavigationOptions.h | 初始化选项（displayOption 等） |\n| BMKWalkCycleNavigationDisplayOption | BMKWalkCycleNavigationDisplayOption.h | 展示选项 |\n| BMKWalkCycleSampleGuideInfo | BMKWalkCycleSampleGuideInfo.h | 诱导信息（SampleGuide） |\n| BMKMultiNaviView | BMKMultiNaviView.h | 多实例导航地图 View（getNaviMapView） |\n\n后台投屏类（BMKBackgroundMapView、BMKBackgroundNavigationView、BMKBackgroundRoadNetView）见下「后台与导航」。\n\n详见 [navi.md](navi.md)。\n\n## 热力图\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKHeatMap | BMKHeatMap.h | 热力图 |\n| BMKHexagonHeatMap | BMKHexagonHeatMap.h | 六边形热力图 |\n\n## 后台与导航\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKBackgroundMapView | BMKBackgroundMapView.h | 后台投屏容器（mapview + roadNetView + navigationView） |\n| BMKBackgroundNavigationView | BMKBackgroundNavigationView.h | 导航层：路线、车标、罗盘、起终点；步骑行由 Manager.getBackgroundNavigationView 获取 |\n| BMKBackgroundRoadNetView | BMKBackgroundRoadNetView.h | 路网层：路网、路况、路名；从 backgroundMapView.roadNetView 获取 |\n| BMKNavigation | BMKNavigation.h | 调起百度地图 |\n| BMKNaviPara | BMKNaviPara.h | 导航参数 |\n\n## 坐标与结构体\n\n| 类型 | 说明 |\n|------|------|\n| CLLocationCoordinate2D | 经纬度（BD09） |\n| BMKMapRect | 直角地理坐标矩形 |\n| BMKMapPoint | 直角地理坐标点 |\n| BMKCoordinateRegion | 经纬度区域 |\n| BMKCoordinateBounds | 经纬度边界 |\n\n## 工具\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKGeometry | BMKGeometry.h | 坐标转换、几何计算 |\n| BMKInterpolator | BMKInterpolator.h | 动画插值器 |\n| BMKCommonDef | BMKCommonDef.h | 枚举定义 |\n\n详见 [utils.md](utils.md)。\n\nFile v1.0.2:references/cocoapods.md\n\n# CocoaPods 集成\n\n**版本**：不写版本号即使用最新；写版本号则锁定。API 以本地头文件为准，类/方法不存在时提示更新 Pod，见 [SKILL.md](../SKILL.md) 规则 5。\n\n## 安装 CocoaPods（未安装时）\n\n```bash\ngem sources -l\ngem sources --remove https://rubygems.org/\ngem sources -a https://gems.ruby-china.com\nsudo gem update --system\nsudo gem install -n /usr/local/bin cocoapods  # macOS > 10.11\npod setup\n```\n\n## Podfile 模板\n\n**仅定位**（BMKLocationKit，无地图）：\n```ruby\nplatform :ios, '9.0'\ntarget 'YourProjectTarget' do\n  pod 'BMKLocationKit', '2.1.3'\nend\n```\n\n**基础地图**（BaiduMapKit，不写版本号即使用最新）：\n```ruby\nplatform :ios, '10.0'\ntarget 'YourProjectTarget' do\n    pod 'BaiduMapKit'\n    # pod 'BaiduMapKit/Map'\n    # pod 'BaiduMapKit/Search'\n    # pod 'BaiduMapKit/Utils'\nend\n```\n\n**步骑行导航**（BaiduWalkNaviKit，含基础地图，步行/骑行实时导航）：\n```ruby\nplatform :ios, '10.0'\ntarget 'YourProjectTarget' do\n    pod 'BaiduWalkNaviKit'\nend\n```\n步骑行导航依赖、配置与示例见 [navi.md](navi.md)。\n\n## 常用命令\n\n```bash\npod install          # 安装后用 .xcworkspace 打开\npod repo update\npod update\n```\n\n## pod search 找不到类库\n\n```bash\npod setup\nrm ~/Library/Caches/CocoaPods/search_index.json\npod search BaiduMapKit   # 或 pod search BMKLocationKit\n```\n\n---\n\n## 后续配置\n\nInfo.plist、隐私协议弹窗见 [project-config.md](project-config.md)，图片资源见 [assets.md](assets.md)。\n\n**构建报错**：若出现 `Sandbox: bash deny file-write-create .../Pods/resources-to-copy-xxx.txt`，需关闭 User Script Sandboxing，见 [project-config.md](project-config.md) 的「CocoaPods 构建沙盒」小节。\n\nFile v1.0.2:references/location.md\n\n# 百度 iOS 定位 SDK（BMKLocationKit）\n\n**边界**：单次/连续/后台/室内定位、地理围栏、鉴权；与地图独立，可单独或与 BaiduMapKit 配合。与地图混用须统一坐标系，见 [utils.md](utils.md)。不含步骑行导航内部定位。\n\n## CocoaPods 集成\n\nPod 库名：**BMKLocationKit**。在 Podfile 同目录执行 `pod install`，使用生成的 `.xcworkspace` 打开工程。\n\n```ruby\nplatform :ios, '9.0'\ntarget 'YourProjectTarget' do  # 替换为工程名\n  pod 'BMKLocationKit', '2.1.3'\nend\n```\n\n常用命令：`pod install`、`pod repo update`、`pod update`。若 `pod search` 找不到类库：`pod setup` → 删除 `~/Library/Caches/CocoaPods/search_index.json` → 再执行 `pod search BMKLocationKit`。\n\n## 隐私与初始化（必须遵守）\n\n**必须通过 BMKLocationAuth 的 setAgreePrivacy 在用户同意隐私政策后再进行定位 SDK 的初始化。**\n\n- 首次使用前弹窗让用户阅读并同意隐私政策（隐私政策地址可跳转：https://lbsyun.baidu.com/index.php?title=openprivacy）。\n- 用户同意后调用 `[[BMKLocationAuth sharedInstance] setAgreePrivacy:YES]`，**再**初始化定位相关逻辑（如 BMKLocationManager 等）。\n- 用户不同意时调用 `setAgreePrivacy:NO`，且不要初始化定位 SDK。\n- 与地图 SDK 区分：地图使用 `[BMKMapManager setAgreePrivacy:YES]`；定位使用 **BMKLocationAuth** 的 setAgreePrivacy。\n\n## 鉴权失败排查（无法返回定位/地址时）\n\n若出现 **「鉴权失败导致无法返回定位、地址等信息」**（或错误码 BMKLocationErrorFailureAuth），按下列顺序检查：\n\n| 排查项 | 说明 |\n|--------|------|\n| **1. setAgreePrivacy 顺序** | 必须在 **BMKLocationManager、BMKGeoFenceManager 等实例化之前** 调用 `[[BMKLocationAuth sharedInstance] setAgreePrivacy:YES]`。顺序：先 setAgreePrivacy(YES) → 再创建/初始化 BMKLocationManager → 再发起定位。若先初始化再设隐私，会导致鉴权失败。 |\n| **2. AK（密钥）配置** | 在百度 LBS 控制台申请 **iOS 应用** 的 AK，且 **Bundle Identifier** 必须与当前应用一致。在任意定位 SDK 类初始化前完成 AK 校验/配置（如 BMKLocationAuth 的 checkPermisionWithKey: 等）。多应用需分别申请 AK。 |\n| **3. 网络与权限** | 确认设备网络正常；确认已向用户申请并授予定位权限（Info.plist 配置 NSLocationWhenInUseUsageDescription 等）。 |\n\n## 坐标系（与地图 SDK 一致）\n\n**地图 SDK 全局使用 BD09**。**定位 SDK** 通过 **coordinateType**（类型 BMKLocationCoordinateType）设定定位坐标系，**默认为 BMKLocationCoordinateTypeGCJ02**。将定位结果用于地图展示、标注、路线或与地图 API 混用时，必须统一为 BD09：将 **coordinateType 设为 BMKLocationCoordinateTypeBMK09LL**，或使用地图 [utils.md](utils.md) 的 `BMKCoordTrans:fromType:toType:` 将 GCJ02 转为 BD09 后再传给地图。否则会出现偏移或错误。\n\n## 核心类与接口（含默认值，避免与预期不一致）\n\n### BMKLocationAuth\n\n头文件：BMKLocationAuth.h。**初始化 BMKLocationManager 之前必须设置 BMKLocationAuth 中的 APIKey，否则无法正常使用服务。**\n\n| 接口/属性 | 说明 |\n|-----------|------|\n| `sharedInstance` | 单例 |\n| `setAgreePrivacy:` | 设置用户是否同意隐私政策，须在 BMKLocationManager/BMKGeoFenceManager 实例化前调用 |\n| `checkPermisionWithKey:...` | AK 校验，须在任意定位 SDK 类使用前调用 |\n\n---\n\n### BMKLocationManager（类参考，含属性默认值）\n\n头文件：BMKLocationManager.h。使用前须在 BMKLocationAuth 中设置 APIKey 并 setAgreePrivacy:YES。\n\n#### 属性（含默认值）\n\n| 属性 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| delegate | id\\<BMKLocationManagerDelegate\\> | — | 连续定位/错误回调等 |\n| distanceFilter | CLLocationDistance | **kCLDistanceFilterNone** | 定位最小更新距离 |\n| headingFilter | CLLocationDegrees | **1**（since 2.0.5） | 设备朝向最小更新角度 |\n| desiredAccuracy | CLLocationAccuracy | **kCLLocationAccuracyBest** | 定位精度 |\n| activityType | CLActivityType | **CLActivityTypeAutomotiveNavigation** | 定位类型 |\n| showsBackgroundLocationIndicator | BOOL | **NO**（iOS11+） | 后台定位时状态栏是否显示指示器；“始终授权”下设置有效 |\n| coordinateType | BMKLocationCoordinateType | **BMKLocationCoordinateTypeGCJ02** | 定位坐标系类型。与地图混用须设为 BMKLocationCoordinateTypeBMK09LL |\n| pausesLocationUpdatesAutomatically | BOOL | **NO** | 定位是否被系统自动暂停 |\n| allowsBackgroundLocationUpdates | BOOL | **NO**（iOS9+） | 是否允许后台定位；设为 YES 时须开启 Background Modes → Location updates，且在定位未开始或已停止时修改才生效 |\n| locationTimeout | NSInteger | **10**（秒） | 单次定位超时时间，最小 2s；在单次定位请求前设置；从定位权限非 NotDetermined 后开始计时 |\n| reGeocodeTimeout | NSInteger | **10**（秒） | 单次逆地理超时时间，最小 2s；单次定位请求前设置 |\n| locatingWithReGeocode | BOOL | **YES** | 连续定位是否返回逆地理信息 |\n| isNeedNewVersionReGeocode | BOOL | **YES**（1.9 起） | 是否需要最新版逆地理数据（如城市变更实时更新） |\n| userID | NSString * | — | 开发者指定用户 ID，便于排查问题 |\n| accuracyAuthorization | BMKLAccuracyAuthorization | （只读） | 定位精度等级，iOS14+ 用户可控制；用于适配不同精度下的产品逻辑 |\n\n#### 实例方法\n\n| 方法 | 说明 |\n|------|------|\n| `requestLocationWithReGeocode:withNetworkState:completionBlock:` | 单次定位。正在连续定位时调用会失败返回 NO。按 desiredAccuracy 获取定位，精度不足会等待至超时后回调精度最高结果。可用 stopUpdatingLocation 取消。参数：withReGeocode 是否带逆地理（需联网），withNetWorkState 是否带移动热点识别（需联网） |\n| `startUpdatingLocation` | 开始连续定位；会 cancel 所有单次定位请求 |\n| `stopUpdatingLocation` | 停止连续定位；会 cancel 所有单次定位请求，也可用于取消单次定位 |\n| `requestNetworkState` | 请求网络状态结果回调 |\n| `startUpdatingHeading` | 开始设备朝向事件回调 |\n| `stopUpdatingHeading` | 停止设备朝向事件回调 |\n| `tryIndoorLocation` | 尝试高精度室内定位（仅室内定位版本生效） |\n| `stopIndoorLocation` | 关闭高精度室内定位（仅室内定位版本生效） |\n| `authorizationStatus` | 返回当前定位权限（CLAuthorizationStatus） |\n| `requestTemporaryFullAccuracyAuthorizationWithPurposeKey:completion:` | 无全量精度权限时临时请求一次全量精度，系统弹框；purposeKey 对应 Info.plist 中 NSLocationTemporaryUsageDescriptionDictionary 的 key（iOS14+） |\n| `requestTemporaryFullAccuracyAuthorizationWithPurposeKey:` | 请求一次全量定位精度等级（iOS14+） |\n\n#### BMKLocationManagerDelegate 回调（头文件 BMKLocationManager.h）\n\n| 方法 | 说明 |\n|------|------|\n| `BMKLocationManager:didUpdateLocation:` | 连续定位位置更新，location 为 BMKLocation |\n| `BMKLocationManager:didFailWithError:` | 定位失败，error 含 BMKLocationErrorFailureAuth 等 |\n| `BMKLocationManager:didUpdateHeading:` | 设备朝向更新（需先 startUpdatingHeading） |\n\n单次定位结果在 `requestLocationWithReGeocode:...completionBlock:` 的 block 中返回。\n\n#### 类方法\n\n| 方法 | 说明 |\n|------|------|\n| `+ headingAvailable` | 设备是否支持朝向事件回调 |\n| `+ BMKLocationCoordinateConvert:SrcType:DesType:` | 坐标转换。参数：coordinate 待转换经纬度，srctype 源坐标系类型，destype 目标百度坐标系类型（bd09ll、bd09mc）。返回目标百度坐标系经纬度 |\n| `+ BMKLocationDataAvailableForCoordinate:withCoorType:` | 判断经纬度是否在大陆及港、澳地区。参数：coordinate 待判断经纬度，coortype 该经纬度的坐标系类型。返回 YES 表示境内 |\n\n### BMKGeoFenceManager\n\n地理围栏：创建、查询、删除围栏等，须在 setAgreePrivacy:YES 之后实例化。\n\n**国内外/境内判断**：使用 `[BMKLocationManager BMKLocationDataAvailableForCoordinate:withCoorType:]`，coortype 传 `BMKLocationCoordinateTypeBMK09LL`，返回 YES 表示国内。与地图配合见 [utils.md](utils.md)。\n\n## 获取位置信息（能力与对应方式）\n\n| 能力 | 说明 |\n|------|------|\n| 单次定位 | BMKLocationManager 的 requestLocationWithReGeocode: completionBlock: |\n| 连续定位 | startUpdatingLocation，通过 BMKLocationManagerDelegate 回调 |\n| 后台定位 | allowsBackgroundLocationUpdates = YES，UIBackgroundModes 含 location，并配置 Info.plist 定位相关说明 |\n| 室内定位 | 使用室内定位相关 API（具体见 BMKLocationKit 头文件） |\n\n## 辅助功能（能力与对应类/接口）\n\n| 能力 | 说明 |\n|------|------|\n| 地理围栏 | BMKGeoFenceManager，创建/删除围栏、状态回调 |\n| 移动热点识别 | 定位 SDK 提供的热点相关接口 |\n| 国内外位置判断 | BMKLocationManager 的 BMKLocationDataAvailableForCoordinate:withCoorType: |\n| 坐标转换 | 定位 SDK 内坐标类型配置（coordinateType）或配合地图 utils 的 BMKCoordTrans |\n| 防作弊 | 定位 SDK 提供的防作弊相关接口 |\n\n错误码（如 BMKLocationErrorFailureAuth）、iOS 14 适配、提交 App Store 注意事项、HTTPS 等请查阅百度 LBS 开放平台 iOS 定位 SDK 文档。\n\n## 与地图 SDK 的关系\n\n- **仅需定位**：只集成 BMKLocationKit 即可。\n- **地图 + 定位**：同时集成 BaiduMapKit 与 BMKLocationKit；地图上「我的位置」、定位图层等见 [mapview.md](mapview.md)（LocationViewAPI）；坐标转换、国内外判断等见 [utils.md](utils.md)。\n- **隐私**：定位 SDK 必须通过 **BMKLocationAuth** 的 **setAgreePrivacy** 在用户同意后再初始化；地图 SDK 使用 BMKMapManager 的 setAgreePrivacy。详见上文「隐私与初始化」。\n\n---\n\n## 按需方案\n\n| 需求 | 说明 |\n|------|------|\n| 仅需定位、无地图 | BMKLocationKit，BMKLocationAuth setAgreePrivacy → BMKLocationManager，coordinateType 按需设置 |\n| 地图上显示我的位置 | BaiduMapKit + BMKLocationKit，mapview 的 showsUserLocation / userTrackingMode / updateLocationData；定位结果 coordinateType 建议 BMK09LL |\n| 国内外/境内判断 | BMKLocationManager 的 BMKLocationDataAvailableForCoordinate:withCoorType:，见 [utils.md](utils.md) |\n| 单次/连续/后台/室内定位 | BMKLocationManager requestLocationWithReGeocode、startUpdatingLocation、allowsBackgroundLocationUpdates 等 |\n| 地理围栏/热点/坐标转换/防作弊 | BMKGeoFenceManager、coordinateType、及 SDK 对应辅助接口 |\n\nFile v1.0.2:references/mapview.md\n\n# BMKMapView 地图视图\n\n**边界**：地图视图、属性、生命周期、控制（BMKMapView）；标注见 [annotations.md](annotations.md)，覆盖物见 [overlays.md](overlays.md)。\n\n## 概述\n\n`BMKMapView` 继承 `UIView`，用于显示地图并执行相关操作。需配合 `BMKMapViewDelegate` 使用。\n\n### 示例：创建地图与生命周期\n\n```objc\n#import <BaiduMapAPI_Base/BMKBaseComponent.h>\n#import <BaiduMapAPI_Map/BMKMapComponent.h>\n\n@property (nonatomic, strong) BMKMapView *mapView;\n\n- (void)viewDidLoad {\n    [super viewDidLoad];\n    _mapView = [[BMKMapView alloc] initWithFrame:self.view.bounds];\n    _mapView.delegate = self;\n    [self.view addSubview:_mapView];\n    // 可选：设置中心与缩放（改 centerCoordinate 不改变 zoomLevel）\n    _mapView.centerCoordinate = CLLocationCoordinate2DMake(39.917, 116.379);\n    _mapView.zoomLevel = 18;\n}\n\n- (void)viewWillAppear:(BOOL)animated {\n    [super viewWillAppear:animated];\n    [_mapView viewWillAppear];\n}\n- (void)viewWillDisappear:(BOOL)animated {\n    [super viewWillDisappear:animated];\n    [_mapView viewWillDisappear];\n}\n```\n\n### 示例：设置地图状态（带动画、指定时长）\n\n```objc\n// 使用 BMKMapStatus 设置层级与中心，带动画且指定动画时长(ms)\nBMKMapStatus *status = [[BMKMapStatus alloc] init];\nstatus.fLevel = 10;\nstatus.targetGeoPt = CLLocationCoordinate2DMake(51.50556, -0.07556);\n[_mapView setMapStatus:status withAnimation:YES withAnimationTime:1000];\n```\n\n### 示例：室内图\n\n```objc\n_mapView.baseIndoorMapEnabled = YES;\n_mapView.showIndoorMapPoi = YES;\n// 进入/移出室内图回调：mapView:baseIndoorMapWithIn:baseIndoorMapInfo:\n```\n\n## 地图引擎与生命周期\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKMapManager | BMKMapManager.h | 主引擎，`start:`、`setAgreePrivacy:` |\n| BMKMapView | BMKMapView.h | 地图视图 |\n| BMKMapStatus | BMKMapStatus.h | 地图状态（中心、缩放、旋转） |\n\n**生命周期（必须调用）**：viewWillAppear/viewWillDisappear 必须调 mapView 对应方法，否则地图状态异常。\n\n```objc\n- (void)viewWillAppear:(BOOL)animated {\n    [super viewWillAppear:animated];\n    [_mapView viewWillAppear];\n}\n- (void)viewWillDisappear:(BOOL)animated {\n    [super viewWillDisappear:animated];\n    [_mapView viewWillDisappear];\n}\n```\n\n### 地图显示当前定位\n\n- 设置 **showsUserLocation = YES**，再通过 **updateLocationData:** 传入 **BMKUserLocation**（含 `location`、可选 `heading`），地图会绘制定位点。\n- 定位数据需自行获取（如 BMKLocationManager 单次/连续定位）；与地图混用时坐标系须为 BD09（coordinateType 或转换），见 [location.md](location.md)。\n\n```objc\n_mapView.showsUserLocation = YES;\n// 在拿到定位结果后（主线程）：\nBMKUserLocation *userLoc = [BMKUserLocation new];\nuserLoc.location = [[CLLocation alloc] initWithLatitude:lat longitude:lng];\nuserLoc.updating = NO;\n[_mapView updateLocationData:userLoc];\n```\n\n**注意**：仅在设置 showsUserLocation 且至少调用一次 updateLocationData 传入有效 CLLocation 后，地图上才会显示蓝点；未授权或定位失败时可不调用 updateLocationData。\n\n**俯仰角**：`overlooking` 范围 -45～0，更陡需设 `minOverlooking`（-79～0）。`overlookEnabled` 是否支持俯仰角手势。\n\n---\n\n## 核心属性\n\n### Delegate 与手势\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| delegate | id\\<BMKMapViewDelegate\\> | 地图回调 |\n| gestureDelegate | id\\<BMKMapGestureDelegate\\> | 手势回调，返回 YES 时拦截地图处理 |\n\n### 地图类型与语言\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| mapType | BMKMapType | 标准/卫星地图 |\n| languageType | BMKMapLanguageType | 中/英文地图（since 6.4.0），V6.6.2 起英文不支持个性化地图 |\n| backgroundColor | UIColor | 空白地图背景色（since 6.5.4） |\n| backgroundImage | UIImage | 底图加载时背景网格（since 6.5.9，≤500KB） |\n\n### 显示范围与中心\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| region | BMKCoordinateRegion | 当前经纬度范围 |\n| limitMapRegion | BMKCoordinateRegion | 限制显示范围 |\n| centerCoordinate | CLLocationCoordinate2D | 中心点（改值不改变 zoomLevel） |\n| visibleMapRect | BMKMapRect | 当前可见范围（直角坐标） |\n\n### 比例尺与视角\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| zoomLevel | float | 比例尺级别，手机 4～21 |\n| minZoomLevel / maxZoomLevel | float | 自定义最小/最大级别 |\n| rotation | int | 旋转角度 -180～180 |\n| overlooking | int | 俯视角度 -45～0 |\n| minOverlooking | int | 俯视最小值 -79～0 |\n| fontSizeLevel | NSInteger | 字体大小 0～3（小/标准/大/特大，since 6.3.0） |\n\n### 控件与 UI\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| compassPosition | CGPoint | 指南针位置（以左上角为原点） |\n| compassSize | CGSize | 指南针宽高（只读） |\n| showMapScaleBar | BOOL | 是否显示比例尺 |\n| mapScaleBarPosition | CGPoint | 比例尺位置（以 BMKMapView 左上角为原点）；默认与 Logo 重叠，需手动设置使比例尺在 Logo 上方，见 [ui-standards.md](ui-standards.md) |\n| mapScaleBarSize | CGSize | 比例尺宽高（只读） |\n| mapScaleBarColor / mapScaleBarTextColor | UIColor | 比例尺颜色 |\n| logoPosition | BMKLogoPosition | Logo 位置 |\n\n### 图层与显示\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| buildingsEnabled | BOOL | 3D 楼块 |\n| showMapPoi | BOOL | 底图 POI 标注 |\n| trafficEnabled | BOOL | 路况图层 |\n| customTrafficColorEnabled | BOOL | 自定义路况颜色生效（since 6.6.3） |\n| baiduHeatMapEnabled | BOOL | 百度城市热力图（层级>11 可显示） |\n\n### 手势\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| gesturesEnabled | BOOL | 所有手势 |\n| doubleTapHoldPanEnabled | BOOL | 单指双击滑动缩放，默认 NO |\n| zoomEnabled | BOOL | 双指缩放 |\n| zoomEnabledWithTap | BOOL | 双击/双指单击缩放 |\n| scrollEnabled | BOOL | 移动地图 |\n| overlookEnabled | BOOL | 俯仰角 |\n| rotateEnabled | BOOL | 旋转 |\n| forceTouchEnabled | BOOL | 3D Touch 回调 |\n| gestureZoomAnimationEnabled | BOOL | 手势缩放动画（since 6.5.2） |\n\n**手势冲突（地图+ScrollView 共存）**：实现 `shouldRecognizeSimultaneouslyWithGestureRecognizer:` 返回 YES。ScrollView 配置见 [ui-standards.md](ui-standards.md)。\n\n**BMKMapGestureDelegate**：handleTapGesture、handlePanGesture、handleFlyingGesture、handleLongGesture、handleDoubleTapGesture、handleTwoFingersTapGesture、handleTwoFingersPanGesture、handleRotationGesture、handlePinchGesture；返回 YES 时地图不处理。用于与底部抽屉、侧滑菜单等共存。\n\n**BMKAnnotationView/BMKActionPaopaoView**：不推荐直接添加手势，会覆盖点击、长按；如必须添加，将手势 delegate 设到对应 View 并实现协调方法。\n\n### 其他\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| mapPadding | UIEdgeInsets | 地图预留边界；设置后 Logo、比例尺、指南针会避开该区域 |\n| updateTargetScreenPtWhenMapPaddingChanged | BOOL | mapPadding 改变时中心是否跟着变 |\n| ChangeWithTouchPointCenterEnabled | BOOL | 双指以手势中心/地图中心旋转缩放 |\n| ChangeCenterWithDoubleTouchPointEnabled | BOOL | 双击以双击位置/地图中心放大 |\n| supportBackgroundDraw | BOOL | 后台绘制（since 6.6.6，进出前后台时设置） |\n\n**mapPadding 与 fitVisibleMapRect edgePadding 区别**：mapPadding 影响指南针、Logo、比例尺位置，用于解决控件被 UI 遮挡；fitVisibleMapRect 的 edgePadding 用于路线视野适配（含 UI 边距和 marker 尺寸）。二者解决不同问题，详见 [ui-standards.md](ui-standards.md)。\n\n---\n\n## 类方法（创建前设置）\n\n| 方法 | 说明 |\n|------|------|\n| `+ setBaiduMapSDKMetalEnable:` | 是否用 Metal 绘制（V6.5.2，创建前有效） |\n| `+ getBaiduMapSDKMetalEnable` | 获取 Metal 开关（V6.6.3） |\n| `+ setBaiduMapSDKOverlayNewVersionEnable:` | 覆盖物新版逻辑（V6.5.9，启动期间仅一次） |\n| `+ getBaiduMapSDKOverlayNewVersionEnable` | 获取覆盖物新版开关（V6.6.3） |\n\n---\n\n## 实例方法\n\n### 生命周期（必须调用）\n\n| 方法 | 说明 |\n|------|------|\n| `viewWillAppear` | 即将显示时调用，恢复状态 |\n| `viewWillDisappear` | 即将隐藏时调用，存储状态 |\n\n### 地图控制\n\n| 方法 | 说明 |\n|------|------|\n| `setRegion:animated:` | 设定显示范围 |\n| `setCenterCoordinate:animated:` | 设定中心点 |\n| `setVisibleMapRect:animated:` | 设定可见范围（直角坐标） |\n| `setVisibleMapRect:edgePadding:animated:` | 设定范围并留边距 |\n| `fitVisibleMapRect:edgePadding:withAnimated:` | 适配 mapRect 到可见区域 |\n| `zoomIn` / `zoomOut` | 放大/缩小一级 |\n| `mapForceRefresh` | 强制刷新 |\n| `cleanCacheWithMapType:` | 清空缓存 |\n\n### 坐标转换\n\n| 方法 | 说明 |\n|------|------|\n| `convertCoordinate:toPointToView:` | 经纬度→View 坐标 |\n| `convertPoint:toCoordinateFromView:` | View 坐标→经纬度 |\n| `convertRegion:toRectToView:` | 经纬度区域→View 矩形 |\n| `convertRect:toRegionFromView:` | View 矩形→经纬度区域 |\n| `convertMapRect:toRectToView:` | BMKMapRect→View 矩形 |\n| `convertRect:toMapRectFromView:` | View 矩形→BMKMapRect |\n| `screenPointFromMapPoint3:` | 三维地理坐标→屏幕坐标（since 6.5.2） |\n| `glPointForMapPoint:` | BMKMapPoint→OpenGL 坐标 |\n| `glPointsForMapPoints:count:` | 批量 BMKMapPoint→OpenGL 坐标 |\n\n### 地图状态\n\n| 方法 | 说明 |\n|------|------|\n| `getMapStatus` | 获取地图状态 |\n| `setMapStatus:` | 设置地图状态 |\n| `setMapStatus:withAnimation:` | 设置并动画 |\n| `setMapStatus:withAnimation:withAnimationTime:` | 指定动画时长(ms) |\n| `getMapStatusFromCoordinateRegion:edgePadding:` | 根据区域和边距计算 BMKMapStatus |\n| `setMapCenterToScreenPt:` | 设置中心点屏幕坐标 |\n\n**设置状态并动画**：见上文「示例：设置地图状态（带动画、指定时长）」；不指定时长用 `setMapStatus:withAnimation:` 则使用 SDK 默认动画时长。\n\n### 截图与路况\n\n| 方法 | 说明 |\n|------|------|\n| `takeSnapshot` | 可视区域截图 |\n| `takeSnapshot:` | 指定区域截图 |\n| `setCompassImage:` | 设置罗盘图片 |\n| `setCustomTrafficColorForSmooth:slow:congestion:severeCongestion:` | 自定义路况颜色（4 种全设） |\n| `isSurpportBaiduHeatMap` | 当前区域是否支持百度热力图 |\n\n### OpenGL（3D 绘制）\n\n| 方法 | 说明 |\n|------|------|\n| `getProjectionMatrix` | 获取投影矩阵 |\n| `getViewMatrix` | 获取视图矩阵 |\n\n---\n\n## Category：CustomMapAPI\n\n| 方法 | 说明 |\n|------|------|\n| `setCustomMapStylePath:` | 个性化地图样式路径（创建后调用，V6.6.2 英文不支持） |\n| `setCustomMapStylePath:mode:` | mode 0 本地 1 在线 |\n| `setCustomMapStyleEnable:` | 个性化样式开关 |\n| `setCustomMapStyleWithOption:preLoad:success:failure:` | 在线个性化样式 |\n\n---\n\n## Category：IndoorMapAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| baseIndoorMapEnabled | 是否显示室内图 |\n| showIndoorMapPoi | 室内图标注 |\n| showDotPoi | 麻点 POI |\n| `switchBaseIndoorMapFloor:withID:` | 切换楼层 |\n| `getFocusedBaseIndoorMapInfo` | 当前聚焦室内图信息 |\n\n---\n\n## Category：LocationViewAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| showsUserLocation | 是否显示定位图层 |\n| userTrackingMode | 定位模式 |\n| userLocationVisible | 定位点是否在可视区域（只读） |\n| `updateLocationViewWithParam:` | 定制我的位置样式 |\n| `updateLocationData:` | 更新定位数据 |\n\n---\n\n## Category：AnnotationAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| annotations | 已添加标注数组（只读） |\n| isSelectedAnnotationViewFront | 选中标注是否置顶 |\n| `addAnnotation:` / `addAnnotations:` | 添加标注 |\n| `removeAnnotation:` / `removeAnnotations:` | 移除标注 |\n| `viewForAnnotation:` | 查找标注对应 View |\n| `dequeueReusableAnnotationViewWithIdentifier:` | 复用标注 View |\n| `selectAnnotation:animated:` / `deselectAnnotation:animated:` | 选中/取消选中 |\n| `showAnnotations:animated:` | 显示区域包含所有标注 |\n| `showAnnotations:padding:animated:` | 带边距（since 6.5.7） |\n| `annotationsInCoordinateBounds:` | 矩形区域内标注 |\n\n---\n\n## Category：OverlaysAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| overlays | 已添加 overlay 数组（只读） |\n| `addOverlay:` / `addOverlays:` | 添加 overlay |\n| `removeOverlay:` / `removeOverlays:` | 移除 overlay |\n| `insertOverlay:atIndex:` | 指定索引插入 |\n| `exchangeOverlayAtIndex:withOverlayAtIndex:` | 交换 |\n| `insertOverlay:aboveOverlay:` / `belowOverlay:` | 相对插入 |\n| `viewForOverlay:` | 查找 overlay 对应 View |\n\n---\n\n## Category：HeatMapAPI\n\n| 方法 | 说明 |\n|------|------|\n| `addHeatMap:` | 添加热力图 |\n| `updateHeatMap:` | 更新热力图（会重置动画） |\n| `removeHeatMap` | 移除热力图 |\n| `startHeatMapFrameAnimation` / `stopHeatMapFrameAnimation` | 开始/暂停动画 |\n| `setHeatMapFrameAnimationIndex:` | 控制帧索引 |\n\n---\n\n## Category：HexagonHeatMapAPI（since 6.6.0）\n\n| 属性/方法 | 说明 |\n|------|------|\n| showHexagonHeatMap | 是否显示蜂窝热力图 |\n| `addHexagonHeatMap:` | 添加 |\n| `removeHexagonHeatMap` | 删除 |\n\n---\n\n## Category：MapLayerAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| showOperateLayer | 运营图层（since 6.4.0） |\n| showOperatePOILayer | 运营 POI 图层（since 6.6.3） |\n| showTrafficUGCLayer | 路况事件图层（since 6.6.3） |\n| showDEMLayer | 地形图层（since 6.5.9） |\n| `switchLayerOrder:otherLayer:` | 交换图层顺序（since 6.5.9） |\n| `switchOverlayLayerAndNavigationLayer:` | overlay 与导航图层交换 |\n| `switchOverlayLayerAndPOILayer:` | overlay 与 POI 图层交换（addOverlay 后调用） |\n| `getPoiTagEnable:` / `setPoiTagEnable:poiTagType:` | 底图 POI 标签显示 |\n\n---\n\n## Category：ParticleEffect（since 6.5.7）\n\n| 方法 | 说明 |\n|------|------|\n| `showParticleEffect:` | 显示粒子效果 |\n| `closeParticleEffect:` | 关闭粒子效果 |\n| `customParticleEffect:option:` | 自定义粒子效果 |\n\n---\n\n## BMKBackgroundMapView（后台投屏视图）\n\n**BMKBackgroundMapView**（BMKBackgroundMapView.h）用于将**地图或导航画面**渲染到自定 View，可置于外接屏、投屏窗口或本机副区域，常用于**步骑行多实例后台投屏**：导航进行时把同一段导航同时投到另一块屏或小窗。\n\n### 三层内容与对应类\n\nBMKBackgroundMapView 支持三类内容，通过以下属性挂接：\n\n| 属性 | 类型 | 支持的内容 | 说明 |\n|------|------|-------------|------|\n| **mapview** | BMKMapView | 底图 | 关联源地图，同步数据；步骑行多实例时可设为 `[multiNaviView getNaviMapView]` |\n| **roadNetView** | BMKBackgroundRoadNetView | 路网、路况、路名 | 只读获取，用于自定义路网样式（见下） |\n| **navigationView** | BMKBackgroundNavigationView | 导航路线、小车、罗盘、起终点等 | 步骑行由 Manager 的 `getBackgroundNavigationView` 得到并赋值（见下） |\n\n渲染控制：设置完成后调用 **`startRender`**，退出或暂停时 **`stopRender`**，再 `removeFromSuperview`。完整步骑行投屏流程见 [navi.md](navi.md)「多实例后台投屏」。\n\n### BMKBackgroundNavigationView 支持的内容\n\n用于在投屏上绘制**导航相关**内容，步骑行场景下由 **BMKWalkNavigationManager** / **BMKCycleNavigationManager** 的 **`getBackgroundNavigationView`** 返回，引擎会驱动路线与位置更新，无需自行调用 `updateRouteInfo:` 等。\n\n| 能力 | 属性/方法 | 说明 |\n|------|-----------|------|\n| 路线 | routeColor, routePassedColor, routePassedDisplayMode（如 Grayed） | 未走/已走路线颜色与显示模式 |\n| 起终点与途径点 | needDrawStartPoint, needDrawEndPoint, needDrawViaPoint；startPointIcon, endPointIcon, viaPointIcon 等 | 是否绘制及图标 |\n| 导航车标与罗盘 | navigationIcon, needDrawCompass, needFllowPhoneHeading | 车头朝向、罗盘、随手机朝向 |\n| 引导线（偏航） | needDrawGuideLine, guideLineColor, guideLineWidth | 偏离路线时的引导线 |\n| 路名 | needDrawRouteName, routeNameFont, routeNameTextColor 等 | 路线上的路名绘制 |\n| 数据更新（非步骑行自管时） | updateRouteInfo:, updateRouteSegmentsInfo:, updateNaviLocationInfo: | 自管数据源时使用；步骑行由 Manager 提供实例则不需要 |\n\n### BMKBackgroundRoadNetView 支持的内容\n\n从 **`backgroundMapView.roadNetView`** 只读获取，用于在底图之上自定义**路网层**样式（不改变地图数据，仅表现）。\n\n| 能力 | 属性 | 说明 |\n|------|------|------|\n| 路网 | needDrawRoadNet, roadNetColor | 是否绘制路网、路网颜色 |\n| 路况 | needDrawRoadTraffic, roadTrafficColor | 是否绘制路况；需关联 mapview 的 trafficEnabled 为 YES；颜色数组 count 为 5（未知/畅通/缓行/拥挤/严重拥堵） |\n| 路名 | needDrawRoadName, roadNameFont, roadNameTextColor | 是否绘制路名及字体、颜色 |\n\n渲染由 BMKBackgroundMapView 的 startRender 统一驱动；roadNetView 的 **mapview** 需与 backgroundMapView 的 mapview 一致以同步数据。\n\n### BMKBackgroundMapView 自身属性与接口\n\n| 属性/方法 | 类型/说明 |\n|-----------|-----------|\n| **mapview** | BMKMapView，关联源地图 |\n| **navigationView** | BMKBackgroundNavigationView，步骑行时设为 Manager 的 `getBackgroundNavigationView` |\n| **roadNetView** | BMKBackgroundRoadNetView（只读），用于配置路网/路况/路名 |\n| **frameRate** | NSInteger，渲染帧率，默认 30，范围 10～60 |\n| **enable3D** | BOOL，默认 YES |\n| **showScaleBar** | BOOL，是否显示比例尺 |\n| **mapScreenExtOffset** | CGPoint，地图额外偏移（微调车标位置等） |\n| **startRender** / **stopRender** | 开始/停止渲染 |\n| **takeSnapshot:needLogo:** | 截屏 |\n\n---\n\n## BMKMapViewDelegate 回调\n\n### 生命周期与渲染\n\n| 回调 | 说明 |\n|------|------|\n| `mapViewWillBackground:` | 退到后台前 |\n| `mapViewDidForeground:` | 进入前台后 |\n| `mapViewDidFinishLoading:` | 地图初始化完毕 |\n| `mapViewDidRenderValidData:withError:` | 绘制出有效数据 |\n| `mapViewDidFinishRendering:` | 渲染完毕 |\n| `mapView:onDrawMapFrame:` | 每帧绘制、重绘时 |\n\n### 区域变化\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:regionWillChangeAnimated:` | 区域即将改变 |\n| `mapView:regionWillChangeAnimated:reason:` | 带原因（Gesture/Event/APIs） |\n| `mapView:regionDidChangeAnimated:` | 区域改变完成 |\n| `mapView:regionDidChangeAnimated:reason:` | 带原因 |\n\n### 标注\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:viewForAnnotation:` | 根据 annotation 生成 View（必须实现） |\n| `mapView:didAddAnnotationViews:` | 新添加 annotation views |\n| `mapView:clickAnnotationView:` | 点击 annotation view |\n| `mapView:didSelectAnnotationView:` | 选中 |\n| `mapView:didDeselectAnnotationView:` | 取消选中 |\n| `mapView:annotationView:didChangeDragState:fromOldState:` | 拖拽状态变化 |\n| `mapView:annotationViewForBubble:` | 点击气泡 |\n\n### 覆盖物\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:viewForOverlay:` | 根据 overlay 生成 View（必须实现） |\n| `mapView:didAddOverlayViews:` | 新添加 overlay views |\n| `mapView:onClickedBMKOverlayView:` | 点击覆盖物 |\n\n### 地图点击\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:onClickedMapPoi:` | 点击底图标注 |\n| `mapView:onClickedMapBlank:` | 点击空白处 |\n| `mapview:onDoubleClick:` | 双击 |\n| `mapview:onLongClick:` | 长按 |\n| `mapview:onForceTouch:force:maximumPossibleForce:` | 3D Touch |\n\n### 其他\n\n| 回调 | 说明 |\n|------|------|\n| `mapStatusDidChanged:` | 地图状态改变完成 |\n| `mapview:baseIndoorMapWithIn:baseIndoorMapInfo:` | 进入/移出室内图 |\n| `mapView:didChangeUserTrackingMode:` | 定位模式切换 |\n| `mapViewOnClickCompass:` | 点击指南针 |\n\n---\n\n## 相关枚举与类型\n\n### BMKUserTrackingMode\n\n| 值 | 说明 |\n|------|------|\n| None | 普通定位 |\n| Heading | 定位方向 |\n| Follow | 定位跟随 |\n| FollowWithHeading | 定位罗盘 |\n\n### BMKLogoPosition\n\n左/中/右 × 上/下 共 6 种。\n\n### BMKRegionChangeReason\n\n| 值 | 说明 |\n|------|------|\n| Gesture | 手势 |\n| Event | 控件事件 |\n| APIs | 接口调用 |\n\n### BMKMapParticleEffect\n\n雪、雨、雾霾、沙尘暴、烟花、花瓣等。\n\n### BMKMapPoi\n\n底图点击返回：`text`、`pt`、`uid`、`trafficUGCType`。\n\n### BMKLayerType\n\nkBMKLayerSDKOverlay、kBMKLayerSDKHeatMap、kBMKLayerSDKHexagonHeatMap、kBMKLayerNewSDKDefaultOverlay。\n\nFile v1.0.2:references/navi.md\n\n# 导航\n\n**边界**：应用内步骑行实时导航（BaiduWalkNaviKit），与 BMKRouteSearch 算路画线为不同能力；多路线选路、诱导、TTS、偏航纠偏均属本能力。算路与画线见 [route.md](route.md)。\n\n---\n\n## 步骑行实时导航（BaiduWalkNaviKit）经验与注意事项\n\n### 基本原则\n\n1. **每次切换导航算路前必须销毁**：在发起新一轮算路（如再次点击「步行/骑行导航」或切换起终点）前，必须调用 **`[BMKWalkNavigationManager destroy]`** 与 **`[BMKCycleNavigationManager destroy]`**，再创建新 container 并 `initNaviEngine`、`routePlanWithParams`。否则上一次的引擎状态会干扰本次算路或导航，易出现无路线、回调错乱等问题。\n2. **Manager 与类型一致**：步行只用 `BMKWalkNavigationManager sharedManager`，骑行只用 `BMKCycleNavigationManager sharedManager`；LaunchParam 的 `naviType`（如 `BMK_WALK_CYCLE_NAVIGATION_TYPE_NORMAL_CYCLE`）与回调里的 `naviType` 判断一致，避免混用。\n3. **不在算路/导航进行中销毁**：仅在**新一轮算路开始前**调用 destroy；仅释放业务侧对「传给 initNaviEngine 的 container」的引用，且应在**启动导航之后**再置 nil（见下）。\n4. **多路线流程**：`enableMultiRoute = YES` 且设置 `routePlanDelegate`、`calcRouteDelegate` → `routePlanWithParams` → 多路线结果在 `onRoutePlanResult:naviType:` → 用 `getWalkNaviMulRouteInfos`/`getCycleNaviMulRouteInfos` 与 `displayRoutePlanResult:mapView` 在地图展示 → 用户选路线后调用 `naviCalcRoute:(routeIndex)` → 引擎算路完成后 `onNaviCalcRouteResult:naviType:` → 再 `startWalkNaviWithParentController`/`startCycleNaviWithParentController`。\n\n### 导航生命周期与 container\n\n- 传给 `initNaviEngine:` 的 **container（UIViewController）** 会被引擎用于地图/导航视图；若在回调里**过早**置 nil，引擎依赖的 controller 可能被释放，导致**进入导航无路线**。\n- **正确做法**：在 `onNaviCalcRouteResult` 中，**仅在算路失败时**置 nil container；**算路成功时**先调用 `startWalkNavi`/`startCycleNavi`，**在启动导航之后再**置 nil container（步行可紧接着置 nil；骑行建议在 `dispatch_async(main_queue)` 的 block 内先 `startCycleNavi` 再置 nil，并可保留 block 内对 container 的强引用以免提前释放）。\n\n示例（骑行，选路后进入导航）：\n\n```objc\n- (void)onNaviCalcRouteResult:(BMKWalkCycleRoutePlanErrorCode)errorCode naviType:(BMKWalkCycleNavigationType)naviType {\n    if (errorCode != BMK_WALK_CYCLE_ROUTEPLAN_RESULT_SUCCESS) {\n        _walkCycleNaviContainer = nil;\n        // 提示错误...\n        return;\n    }\n    if (naviType == BMK_WALK_CYCLE_NAVIGATION_TYPE_WALK) {\n        [[BMKWalkNavigationManager sharedManager] startWalkNaviWithParentController:self isPush:YES];\n        _walkCycleNaviContainer = nil;\n    } else if (naviType == BMK_WALK_CYCLE_NAVIGATION_TYPE_NORMAL_CYCLE || naviType == BMK_WALK_CYCLE_NAVIGATION_TYPE_ELECTRIC_CYCLE) {\n        __weak typeof(self) wself = self;\n        UIViewController *container = _walkCycleNaviContainer;\n        dispatch_async(dispatch_get_main_queue(), ^{\n            if (wself) [[BMKCycleNavigationManager sharedManager] startCycleNaviWithParentController:wself isPush:YES];\n            wself.walkCycleNaviContainer = nil;\n            (void)container;\n        });\n    }\n}\n```\n\n### 骑行多路线与展示\n\n- 骑行也支持多路线：`enableMultiRoute = YES`、`routePlanDelegate = self`，与步行一致；选路后对骑行调用 `[[BMKCycleNavigationManager sharedManager] naviCalcRoute:(NSInteger)index]`。\n- 骑行引擎建议用 `initNaviEngine:options:` 传入 `BMKWalkCycleNavigationOptions`（含 `displayOption`），并设置 `cycleNaviMode = BMK_CYCLE_NAVIGATION_MODE_NORMAL`；container 的 view 在 init 前可设 `frame = [UIScreen mainScreen].bounds` 以便路线正确布局。\n\n### 驾车与步骑行分工\n\n- **驾车**：可用 [utils.md](utils.md) 的 **BMKNavigation** `openBaiduMapNavigation:` 调起百度地图客户端。\n- **步骑行**：应用内导航用 BaiduWalkNaviKit 的 Walk/Cycle Manager，算路前需先拿到用户位置（如 BMKLocationManager 单次定位），再组 LaunchParam（startNode/endNode，type `BMKWalkNavigationRouteNodeLocation`）调用 `routePlanWithParams:`。\n\n---\n\n## 按需方案（导航相关）\n\n| 需求 | 能力组合 | 说明 |\n|------|----------|------|\n| 驾车调起导航 | BMKNavigation openBaiduMapNavigation: | 调起百度地图客户端，见 utils.md |\n| 步骑行多路线选路+应用内导航 | BaiduWalkNaviKit enableMultiRoute + routePlanDelegate + displayRoutePlanResult + naviCalcRoute | 多路线在地图展示折线，用户选路线后 naviCalcRoute(index)，onNaviCalcRouteResult 后再 start 导航；container 在启动导航后再置 nil |\n| 多实例后台投屏 | BMKBackgroundMapView + getBackgroundNavigationView | 步骑行导航画面投到外接屏/小窗：mapview、roadNetView、navigationView（由 Manager.getBackgroundNavigationView 获取），startRender/stopRender。详见 [mapview.md](mapview.md)「BMKBackgroundMapView」 |\n\nFile v1.0.2:references/overlays.md\n\n# 覆盖物 (Overlay)\n\n**边界**：addOverlay 体系；标注见 [annotations.md](annotations.md)，地图 API 见 [mapview.md](mapview.md)。**必须遵守**：点标注**优先使用 Marker**（本 addOverlay 体系），不得使用 BMKPointAnnotation/BMKPinAnnotationView，除非点聚合、固定屏选点等例外。见 [SKILL.md](../SKILL.md) 规则 3。\n\n## 路线与起终点：纹理优先（必须遵守）\n\n**绘制路线与起终点覆盖物时，须优先使用纹理，仅无可用纹理时再使用纯色或自绘。**\n\n- **路线折线**\n  - 单色/单纹理：`BMKPolyline` + `BMKPolylineView`。**优先**设置 `view.textureImage`（图片宽高须为 2 的 n 次幂），无纹理时再设 `view.strokeColor`。线宽 8pt，见 [ui-standards.md](ui-standards.md)。\n  - 路况分段：`BMKMultiPolyline` + `BMKMultiTexturePolylineView`，`textureImages` 使用 [assets](assets.md) 提供的 traffic_texture_* 等。\n- **起终点 Marker**\n  - `BMKIconMarker.icon` **须优先**使用 [assets](assets.md) 的 **icon_start**（起点）、**icon_end**（终点）；实现时先 `[UIImage imageNamed:@\"icon_start\"]` / `imageNamed:@\"icon_end\"`，为 nil 再回退到自绘或纯色。\n- **小车图标**：见 [SKILL.md](../SKILL.md) 规则 3「路线小车纹理」及 [assets](assets.md)。\n\n生成或修改覆盖物相关代码时，**必须先检查并应用上述纹理优先**，避免仅写 strokeColor/自绘导致规范未生效。\n\n## 使用须知\n- **Delegate**：addOverlay 前必须设置 `mapView.delegate`，并实现 `mapView:viewForOverlay:`。\n- **批量添加**：`addOverlays:` 可一次添加多个 overlay。\n- **起终点推荐 BMKIconMarker**：添加顺序为路线→起终点→小车。起终点 icon 须优先使用 [assets](assets.md) 的 icon_start/icon_end；小车图标须优先使用技能 [assets](assets.md) 纹理（icon_car 等），无则再颜色/自绘。样式见 [ui-standards.md](ui-standards.md)。\n- **步骑行多路线折线**：BaiduWalkNaviKit 的 `displayRoutePlanResult:mapView` 返回 `NSArray<BMKPolyline *>`；若由业务侧 addOverlay，需在 `mapView:viewForOverlay:` 中对 `BMKPolyline` 返回 `BMKPolylineView`（如 textureImage 或 strokeColor、lineWidth），否则路线不显示。\n\n## 示例：添加折线（Overlay，addOverlay）\n\n需实现 `mapView:viewForOverlay:`，根据 overlay 类型返回对应 View。\n\n```objc\nCLLocationCoordinate2D coords[2] = {\n    CLLocationCoordinate2DMake(39.915, 116.404),\n    CLLocationCoordinate2DMake(39.920, 116.410)\n};\nBMKPolyline *polyline = [BMKPolyline polylineWithCoordinates:coords count:2];\n[mapView addOverlay:polyline];\n\n#pragma mark - BMKMapViewDelegate\n- (BMKOverlayView *)mapView:(BMKMapView *)mapView viewForOverlay:(id<BMKOverlay>)overlay {\n    if ([overlay isKindOfClass:[BMKPolyline class]]) {\n        BMKPolylineView *view = [[BMKPolylineView alloc] initWithOverlay:overlay];\n        // 纹理优先：有纹理图时设置 textureImage（宽高须 2 的 n 次幂），无则 strokeColor\n        UIImage *tex = [UIImage imageNamed:@\"route_texture\"];  // 示例；可用 assets 或自备\n        if (tex) view.textureImage = tex;\n        else view.strokeColor = [UIColor blueColor];\n        view.lineWidth = 8.0f;  // 路线线宽 8pt，见 ui-standards\n        return view;\n    }\n    return nil;\n}\n```\n\n## 示例：添加图标 Marker（Overlay，addOverlay）\n\n点标注推荐用 BMKIconMarker（addOverlay），与地图坐标系一致；anchor 沿路线居中时设 0.5/0.5。\n\n```objc\nBMKIconMarker *marker = [[BMKIconMarker alloc] init];\nmarker.coordinate = CLLocationCoordinate2DMake(39.915, 116.404);\n// 起终点纹理优先：起点用 icon_start，终点用 icon_end，无则回退自绘/纯色\nmarker.icon = [UIImage imageNamed:@\"icon_start\"];  // 或 icon_end / icon_pin\nif (!marker.icon) marker.icon = [self drawDefaultPinImage];  // 回退\nmarker.anchorX = 0.5;  // 沿路线居中时 0.5/0.5，否则默认 anchorY=1 坐标在底部中心\nmarker.anchorY = 0.5;\n[mapView addOverlay:marker];\n\n#pragma mark - BMKMapViewDelegate\n- (BMKOverlayView *)mapView:(BMKMapView *)mapView viewForOverlay:(id<BMKOverlay>)overlay {\n    if ([overlay isKindOfClass:[BMKIconMarker class]]) {\n        BMKIconMarkerView *view = [[BMKIconMarkerView alloc] initWithOverlay:overlay];\n        view.isClickable = YES;  // 点击触发 mapView:onClickedBMKOverlayView:\n        return view;\n    }\n    return nil;\n}\n```\n\n## 常用默认值（易导致不生效或与预期不符）\n\n以下为地图/覆盖物相关类常见默认值，未显式设置时可能造成行为差异，建议按需显式赋值。\n\n| 类/接口 | 属性/方法 | 默认值 | 说明 |\n|---------|-----------|--------|------|\n| BMKMapTrackAnimation | setTrackPosRadio | **0.0 ~ 0.0**（无有效范围） | 轨迹动画**必须**显式调用 `setTrackPosRadio:0.0 to:1.0`，否则无有效播放范围 |\n| BMKMapTrackAnimation / BMKMapAnimationSet | start | **不自动 start** | 需手动调用 `start`；其他动画类型默认自动 start |\n| BMKIconMarker | anchorX / anchorY | **0.5 / 1.0** | 坐标在图标底部中心；沿路线居中时设 0.5/0.5 |\n| BMKMultiColorPolylineView | lineCapType | **kBMKLineCapButt** | 不支持虚线；kBMKLineCapRound 支持虚线 |\n| BMKMapView | setMapStatus:withAnimation: | 动画时长为 SDK 默认 | 需指定时长时用 `setMapStatus:withAnimation:withAnimationTime:`（单位 ms） |\n| 定位 SDK（BMKLocationManager） | coordinateType | **BMKLocationCoordinateTypeGCJ02** | 与地图（BD09）混用时须设为 BMK09LL 或做转换，见 [location.md](location.md) |\n\n## 覆盖物\n\n### 基础覆盖物\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKOverlay | BMKOverlay.h | 覆盖物协议 |\n| BMKOverlayView | BMKOverlayView.h | 覆盖物视图基类 |\n| BMKPolyline | BMKPolyline.h | 单色/单纹理折线 |\n| BMKPolylineView | BMKPolylineView.h | 折线视图，支持 textureImage、lineDashType |\n| BMKMultiPolyline | BMKMultiPolyline.h | 分段折线，需 drawIndexs |\n| BMKMultiColorPolylineView | BMKMultiPolylineView.h | 分段颜色 |\n| BMKMultiTexturePolylineView | BMKMultiPolylineView.h | 分段纹理（路况） |\n| BMKCircle | BMKCircle.h | 圆形 |\n| BMKCircleView | BMKCircleView.h | 圆形视图 |\n| BMKPolygon | BMKPolygon.h | 多边形 |\n| BMKPolygonView | BMKPolygonView.h | 多边形视图 |\n| BMKGroundOverlay | BMKGroundOverlay.h | 图片图层 |\n| BMKGroundOverlayView | BMKGroundOverlayView.h | 图片图层视图 |\n\n**折线**：`BMKPolyline polylineWithCoordinates:count:`。`BMKPolylineView.textureImage` 要求图片宽高为 2 的 n 次幂。**路线线宽**标准 **8pt**，见 [ui-standards.md](ui-standards.md)。`lineDashType`：`kBMKLineDashTypeDot`（圆点虚线）、`kBMKLineDashTypeSquare` 等。\n\n**分段折线**：`BMKMultiPolyline multiPolylineWithCoordinates:count:drawIndexs:`，drawIndexs 为 NSNumber 数组，对应 strokeColors 或 textureImages 索引。`BMKMultiColorPolylineView.lineCapType` 默认 `kBMKLineCapButt`（不支持虚线），`kBMKLineCapRound` 支持。`BMKMultiTexturePolylineView.lineJoinType`：`kBMKLineJoinRound`/`Bevel`/`Miter`。\n\n**镂空**：BMKCircle、BMKPolygon 支持 `hollowShapes`，可传入 BMKCircle、BMKPolygon 数组实现镂空。\n\n**圆形**：`BMKCircle circleWithCenterCoordinate:radius:`，radius 单位米。BMKCircleView 设置 `fillColor`、`strokeColor`、`lineWidth`。\n\n**多边形**：`BMKPolygon polygonWithCoordinates:count:`。BMKPolygonView 支持 `lineDashType`。\n\n**图片图层**：`BMKGroundOverlay groundOverlayWithBounds:icon:`（BMKCoordinateBounds：southWest、northEast）；或 `groundOverlayWithPosition:zoomLevel:anchor:icon:`。`alpha` 控制透明度 [0, 1]。\n\n### 曲线与渐变\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKArcline | BMKArcline.h | 圆弧（3 点确定） |\n| BMKArclineView | BMKArclineView.h | 圆弧视图 |\n| BMKGradientLine | BMKGradientLine.h | 渐变线 |\n| BMKGradientLineView | BMKGradientLineView.h | 渐变线视图 |\n| BMKGradientCircleView | BMKGradientCircleView.h | 渐变圆（BMKCircle + 渐变） |\n| BMKGeodesicLine | BMKGeodesicLine.h | 大地线（球面最短路径） |\n| BMKGeodesicLineView | BMKGeodesicLineView.h | 大地线视图 |\n\n**圆弧**：`BMKArcline arclineWithCoordinates:` 需传入 3 个点。\n\n**渐变线**：`BMKGradientLine gradientLineWithCoordinates:count:drawIndexs:`，用法类似 BMKMultiPolyline。BMKGradientLineView 设置 `strokeColors`、`lineWidth`。\n\n**渐变圆**：BMKGradientCircleView 用 `initWithOverlay:` 传入 BMKCircle。`radiusWeight`、`colorWeight` 控制渐变规则；`centerColor`、`sideColor` 为渐变起止色。\n\n**大地线**：`BMKGeodesicLine geodesicLineWithCoordinates:count:`。经度跨 180° 时须设置 `lineDirectionCross180`（如 `kBMKLineDirectionCross180TypeWEST_TO_EAST`）。**沿大地线模拟移动**：用球面线性插值 slerp 从 origin 到 dest，`coord = slerp(origin, dest, progress)`；`BMKGetDirectionFromCoords(current, slerp(origin,dest, progress+0.02))` 得切线方向。往返飞行：`routeDirection` 1 或 -1 切换，回程 `coord = slerp(dest, origin, 1-progress)`。slerp 公式见 [utils.md](utils.md)。\n\n### Marker 类（addOverlay）\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKIconMarker | BMKIconMarker.h | 图标 Marker |\n| BMKIconMarkerView | BMKIconMarkerView.h | 图标 Marker 视图 |\n| BMKTextMarker | BMKTextMarker.h | 文本 Marker |\n| BMKTextMarkerView | BMKTextMarkerView.h | 文本 Marker 视图 |\n| BMKTextPathMarker | BMKTextPathMarker.h | 沿路径文字 |\n| BMKTextPathMarkerView | BMKTextPathMarkerView.h | 沿路径文字视图 |\n\n**BMKIconMarker**：`icon` 单图，`icons` 图片组（按间隔轮播）。`scaleX`/`scaleY`、`anchorX`/`anchorY`（默认 0.5/1.0）。**沿路线居中**：设置 `anchorX = 0.5`、`anchorY = 0.5`，否则默认 anchorY=1 使坐标在图标底部中心，圆心会偏上。`addRichView:` 挂接 BMKRichView（BMKImageUIView、BMKLabelUIView、BMKVerticalLayout、BMKHorizontalLayout），RichView 无坐标，必须挂到 marker 上。\n\n**BMKIconMarker 旋转**：`marker.rotateFeature = BMKRotateItem | BMKRotateGeoNorth`（地理北为基准，与 BMKGetDirectionFromCoords 一致）。基准图标建议机头朝上，`marker.rotate = heading`；若方向相反可试 `rotate = -heading` 或 `heading ± 90`。沿大地线移动时用「当前点→路径稍前点」算切线：`BMKGetDirectionFromCoords(current, slerpCoord(origin,dest, progress+0.02))`。\n\n**BMKRichView 示例**：BMKLabelUIView + BMKTextStyle + BMKVerticalLayout，`richView.locate = BMKLocateBottom`、`offsetY` 控制位置。`rootView = layout`，`[marker addRichView:richView]`。\n\n**碰撞检测**：`marker.collisionBehavior = BMKCollisionWithInner | BMKCollisionHideByPriority`，`collisionPriority` 越大越不易被遮挡。RichView 同理。**注意**：动画中暂不支持，定时器驱动的位置更新可生效。\n\n**BMKTextMarker**：`text`、`style`（BMKTextStyle：fontSize、fontOption、borderWidth、textColor、borderColor）。\n\n**BMKTextPathMarker**（路线路名沿路径绘制）：用 `textPathMarkerWithPoints:count:` 或 `textPathMarkerWithCoordinates:count:` 传入路径点（如 BMKDrivingStep 的 points/count），再设 `text`（路名）、`style`（BMKTextStyle，如 22pt 黑字白边见 [ui-standards.md](ui-standards.md)）。View 为 **BMKTextPathMarkerView**，`initWithMarker:` 传入 marker。路线规划时每段 step 若有 `roadName` 可创建一条 BMKTextPathMarker 沿该 step 的 points 绘制，路名随路径走向展示。\n\n**动画**：BMKMapScaleAnimation、BMKMapRotateAnimation、BMKMapAlphaAnimation、BMKMapAnimationSet。BMKMapTrackAnimation、BMKMapAnimationSet 默认不自动 start，其他动画默认自动 start。`addAnimation:addAnimationSetOrderType:` 支持 `BMKAnimationSetOrderTypeWith`（并行）、`BMKAnimationSetOrderTypeThen`（串行）。\n\n**轨迹动画（BMKMapTrackAnimation）**：polyline 与 BMKIconMarker **必须共用同一 trackAnim**，否则小车不显示；只 `start` 一次。路线推荐 BMKMultiPolyline + BMKMultiTexturePolylineView；Forward=未走过（原色），Backward=已走过（灰度）。**走过置灰**（BMKGeometryView）：`strokeColorProgressForward`=原色（未走过）、`strokeColorProgressBackward`=灰色（已走过）；模拟导航同此。轨迹回放相反。驾车路况：drawIndexs 来自 traffics，textureImages 5 种（0 无数据/1 畅通/2 缓行/3 拥堵/4 严重拥堵），见 [assets.md](assets.md)。停止仅 `cancel`，勿解绑 overlay.animation。\n\n**动画不显示时排查**（不建议用 CADisplayLink 等手动方案替代）：\n\n| 检查项 | 说明 |\n|--------|------|\n| 共用同一实例 | `polyline.animation` 与 `marker.animation` 必须指向**同一个** BMKMapTrackAnimation |\n| setTrackLine | 调用 `[trackAnim setTrackLine:polyline]`；部分场景需**先 addOverlay:polyline 再 setTrackLine** |\n| setTrackPosRadio | **必须**调用 `[trackAnim setTrackPosRadio:0.0 to:1.0]`，默认 0~0 无有效范围 |\n| 添加顺序 | 先 `addOverlay:polyline`，再 `addOverlay:marker` |\n| trackBy | marker 设置 `trackBy = BMKAnimationTrackXY`；可加 `BMKAnimationTrackForward` 尝试使机头沿线段前进方向旋转（效果因场景而异，若方向仍不对改用 BMKRotateItem 手动计算 heading） |\n| 只 start 一次 | 对所有 trackAnim 只调用一次 `start`；可 `dispatch_async` 到下一 RunLoop |\n| polyline.isThined | 设为 NO，避免抽稀导致轨迹点丢失 |\n| 参考 Demo | 对照官方 `BMKPolylineMarkerTeackAnimationPage.mm` |\n\n**点击**：`BMKIconMarkerView`/`BMKTextMarkerView.isClickable = YES` 后，点击触发 `mapView:onClickedBMKOverlayView:`。\n\n### 文本与海量点\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKText | BMKText.h | 文本 overlay（中心+文字） |\n| BMKTextView | BMKTextView.h | 文本 overlay 视图 |\n| BMKMultiPointOverlay | BMKMultiPointOverlay.h | 海量点 |\n| BMKMultiPointOverlayView | BMKMultiPointOverlayView.h | 海量点视图 |\n| BMKMultiPointItem | BMKMultiPointOverlay.h | 海量点数据项 |\n\n**BMKText**：`textWithCenterCoordinate:text:`。BMKTextView 设置 `textColor`、`backgroundColor`、`fontSize`、`textFontType`、`textAlignment`、`textMaxLineWidth`、`textLineSpacing`、`textParagraphSpacing`、`textLineBreakMode`。点击回调 `mapView:onClickedBMKOverlayView:`。\n\n**海量点**：`BMKMultiPointOverlay multiPointOverlayWithMultiPointItems:`。BMKMultiPointOverlayView 设置 `icon`、`anchor`、`pointSize`、`delegate`。BMKMultiPointOverlayViewDelegate 的 `didItemTapped:` 处理点击。\n\n### 点聚合（SDK 未内置，参考 BMKPointCluster Demo）\n\n将大量 BMKPointAnnotation 按地理距离聚合，zoom 小时显示聚合点（带数量），zoom 大时拆分为单点。**核心类**：BMKClusterManager、BMKClusterQuadtree、BMKQuadItem、BMKCluster。**流程**：坐标→BMKQuadItem 加入 quadtree；`getClusters:zoomLevel` 按 zoom 获取聚合；`clusterCaches[zoom-3]` 缓存；`mapViewDidFinishLoading` 与 `onDrawMapFrame`（zoom 变化时）触发 updateClusters。**标注展示**见 [annotations.md](annotations.md)。\n\n### 3D 与轨迹\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMK3DModelOverlay | BMK3DModelOverlay.h | 3D 模型 |\n| BMK3DModelOverlayView | BMK3DModelOverlayView.h | 3D 模型视图 |\n| BMKPrismOverlay | BMKPrismOverlay.h | 棱柱/3D 建筑 |\n| BMKPrismOverlayView | BMKPrismOverlayView.h | 棱柱视图 |\n| BMKTraceOverlay | BMKTraceOverlay.h | 路书轨迹（发光、渐变色） |\n| BMKTraceOverlayView | BMKTraceOverlayView.h | 路书轨迹视图 |\n| BMK3DTraceOverlay | BMK3DTraceOverlay.h | 3D 轨迹 |\n| BMK3DTraceOverlayView | BMK3DTraceOverlayView.h | 3D 轨迹视图 |\n\n**3D 模型**：`BMK3DModelOverlay modelOverlayWithCenterCoordinate:option:`。BMK3DModelOption：`modelName`、`modelPath`、`scale`、`type`（BMK3DModelTypeGLTF）、`zoomFixed`、`rotateX`、`animationIsEnable`、`animationIndex`、`animationSpeed`、`animationRepeatCount`。3D 展示标准见 [ui-standards.md](ui-standards.md)。\n\n**棱柱**：`BMKPrismOverlay prismOverlayWithPoints:count:` 传入 BMKMapPoint 数组，`height` 设高度。BMKPrismOverlayView 设置 `sideFaceColor`、`topFaceColor`。可用 BMKDistrictSearch 获取区域边界转 BMKMapPoint。\n\n**3D 轨迹**：`BMK3DTraceOverlay traceOverlay3DWithCoordinates:count:option:`。BMK3DTraceOverlayOption：`traceType`、`duration`、`easingCurve`、`opacity`、`paletteOpacity`、`paletteImage`、`projectionPaletteImage`。BMK3DTraceOverlayView 的 `strokeHeights` 长度须与轨迹点数一致。BMK3DTraceOverlayAnimationDelegate 监听动画开始、进度、结束、实时位置。\n\n**BMKTraceOverlay**：`traceOverlayWithCoordinates:count:option:`。Option：`animate=YES`、`trackMove=YES`、`isRotateWhenTrack=YES`、`pointMove=YES`。**pointImage 箭头尖端须朝右**，SDK 旋转后指向行进方向；建议 80×80。BMKTraceOverlayView 设置 `strokeColors`、`strokeColor`、`fillColor`。\n\n**BMKMapTrackAnimation 图标**：polyline 与 BMKIconMarker 共用同一 trackAnim。marker 设置 `anchorX=0.5`、`anchorY=0.5`。**优先使用图片资源**（如 [assets.md](assets.md) 的 track_car 等），不合适时再自绘。旋转以图像**右侧**为行进方向。自绘时：40×40 画布，箭头尖端朝右；UIBezierPath 尖端在 `CGRectGetMaxX(rect) - w*0.05`，底座在左，`baseX + w*0.25` 为左侧凹进形成箭尾。\n\n### 热力图（addHeatMap，非 overlay）\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKHeatMap | BMKHeatMap.h | 热力图 |\n| BMKHexagonHeatMap | BMKHexagonHeatMap.h | 六边形热力图 |\n\n**BMKHeatMap**：`mDatas` 为 BMKHeatMapNode 二维数组（支持帧动画），`mMaxHight`、`mGradient`（BMKGradient）、`animation`、`frameAnimation`、`delegate`。`addHeatMap`/`removeHeatMap`。`startHeatMapFrameAnimation`/`stopHeatMapFrameAnimation`/`setHeatMapFrameAnimationIndex:`。\n\n**BMKHexagonHeatMap**：`mData`、`mRadius`、`mOpacity`、`mMaxIntensity`、`mGap`、`mHexagonType`（BMKHexagonTypeVertexUp）、`mGradient`。`addHexagonHeatMap`/`removeHexagonHeatMap`。\n\n### 自定义 Overlay\n\n继承 BMKShape，实现 `boundingMapRect`（用 BMKMapRect 包住所有点）。CustomOverlayView 继承 BMKOverlayView，重载 `glRender`。坐标用 `BMKMapPointForCoordinate` 转换。绘制：`renderLinesWithPoints:pointCount:strokeColor:lineWidth:looped:lineDashType:`、`renderRegionWithPoints:pointCount:fillColor:usingTriangleFan:`、`loadStrokeTextureImage:` + `renderTexturedLinesWithPoints:...`。纹理图片宽高须为 2 的 n 次幂。\n\n## 坐标与结构体\n\n| 类型 | 说明 |\n|------|------|\n| CLLocationCoordinate2D | 经纬度（BD09） |\n| BMKMapRect | 直角地理坐标矩形 |\n| BMKMapPoint | 直角地理坐标点 |\n| BMKCoordinateRegion | 经纬度区域 |\n| BMKCoordinateBounds | 经纬度边界（southWest、northEast） |\n\n**坐标转换**（BMKGeometry.h）：`BMKMapPointForCoordinate`、`BMKCoordinateForMapPoint`。自定义 overlay 用 BMKMapPoint 计算 boundingMapRect。\n\n---\n\n## 按需方案\n\n| 需求 | 基础能力 |\n|------|----------|\n| 起终点标记（推荐） | BMKIconMarker + addOverlay 顺序 |\n| 起终点大头针 | BMKPointAnnotation + BMKAnnotationView，见 [annotations.md](annotations.md) |\n| 单色路线 | BMKPolyline + BMKPolylineView，lineWidth 8pt（见 ui-standards） |\n| 路况路线 | BMKMultiPolyline + BMKMultiTexturePolylineView，lineWidth 8pt（见 ui-standards） |\n| 路线路名 | BMKTextPathMarker + BMKTextPathMarkerView（沿 step 路径绘制 roadName） |\n| 路线动画 | BMKMapTrackAnimation + BMKPolyline/MultiPolyline + BMKIconMarker（共用 trackAnim） |\n| 圆弧 | BMKArcline + BMKArclineView |\n| 渐变线 | BMKGradientLine + BMKGradientLineView |\n| 渐变圆 | BMKCircle + BMKGradientCircleView |\n| 大地线 | BMKGeodesicLine + BMKGeodesicLineView |\n| 图标按行进方向旋转 | BMKRotateItem \\| BMKRotateGeoNorth + rotate |\n| 航班/信息标签 | BMKRichView + BMKLabelUIView + BMKVerticalLayout |\n| 重叠时隐藏 | collisionBehavior + collisionPriority |\n| 沿大地线移动/往返 | slerp + BMKGetDirectionFromCoords + routeDirection |\n| 文本 overlay | BMKText + BMKTextView |\n| 海量点 | BMKMultiPointOverlay + BMKMultiPointItem |\n| 点聚合（海量标注） | BMKClusterManager + BMKClusterQuadtree + BMKPointAnnotation |\n| 3D 模型 | BMK3DModelOverlay + BMK3DModelOption |\n| 棱柱/建筑 | BMKPrismOverlay + BMKPrismOverlayView |\n| 路书轨迹 | BMKTraceOverlay + BMKTraceOverlayOption |\n| 3D 轨迹 | BMK3DTraceOverlay + BMK3DTraceOverlayOption |\n| 热力图 | BMKHeatMap + addHeatMap |\n| 六边形热力图 | BMKHexagonHeatMap + addHexagonHeatMap |\n\nFile v1.0.2:references/project-config.md\n\n# 工程配置\n\n**边界**：Info.plist、隐私弹窗、Launch Screen、CocoaPods 沙盒等百度 SDK 工程配置；Pod 集成见 [cocoapods.md](cocoapods.md)。\n\n**Agent 注意**：集成地图/定位 SDK 时，必须检查或配置 Launch Screen（见下「窗口初始化/Launch Screen」），避免运行后 App 非全屏、黑边；并主动提示开发者配置 AK 与 Bundle Identifier（与百度控制台一致）。\n\n## Info.plist 必配项\n\n**CFBundleExecutable**（使用自定义 Info.plist 且 `GENERATE_INFOPLIST_FILE = NO` 时必配）：指定主可执行文件名，未配置会导致真机安装失败，报错「missing or invalid CFBundleExecutable」「无法安装」「请稍后再试」（Code 3002 / MIInstallerErrorDomain 11）。须在 plist 中显式添加：\n\n```xml\n<key>CFBundleExecutable</key>\n<string>$(EXECUTABLE_NAME)</string>\n```\n\n编译时 Xcode 会将 `$(EXECUTABLE_NAME)` 展开为 target 的主可执行文件名（通常与 Product Name 一致）。\n\n**CFBundleDisplayName**：SDK 启动时校验，未配置会报错「启动引擎失败: info.plist 中必须配置 Bundle display name」。\n\n```xml\n<key>CFBundleDisplayName</key>\n<string>你的应用名称</string>\n```\n\n**定位权限**（使用定位时）：\n```xml\n<key>NSLocationWhenInUseUsageDescription</key>\n<string>需要获取您的位置以展示地图</string>\n```\n\n**调起百度地图客户端**（驾车/步行/骑行调起百度地图 App 时）：\n1. 必须在 Info.plist 中配置 **LSApplicationQueriesSchemes**（baidumap），否则无法调起百度地图 App。\n2. **指定返回自定义 scheme**：`appScheme` 按 **`scheme://host`** 格式填写（如 `yourapp://mapsdk.yourapp.com`）。scheme 名（`://` 前部分）须与 Info.plist 中 **CFBundleURLSchemes** 注册的一致，这样用户在百度地图内点击「返回」时才能通过该 URL 打开本 App。\n\nLSApplicationQueriesSchemes：\n```xml\n<key>LSApplicationQueriesSchemes</key>\n<array>\n    <string>baidumap</string>\n</array>\n```\n\n返回本 App 的 URL Scheme 注册（CFBundleURLSchemes 填 appScheme 的 scheme 部分，与格式 scheme://host 中的 scheme 一致）：\n```xml\n<key>CFBundleURLTypes</key>\n<array>\n    <dict>\n        <key>CFBundleTypeRole</key>\n        <string>Editor</string>\n        <key>CFBundleURLName</key>\n        <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>\n        <key>CFBundleURLSchemes</key>\n        <array>\n            <string>foodsearchdemo</string>\n        </array>\n    </dict>\n</array>\n```\n示例：若 `para.appScheme = @\"foodsearchdemo://mapsdk.foodsearchdemo.com\"`，则此处填 `foodsearchdemo`。\n\n**步行 AR 导航**（使用 BaiduWalkNaviKit 且进入 AR 导航时）：必须配置相机用途说明，否则访问摄像头会**直接崩溃**。\n```xml\n<key>NSCameraUsageDescription</key>\n<string>步行AR导航需要使用摄像头识别周围环境，为您提供实景导航指引</string>\n```\n\n## 隐私协议弹窗（必做）\n\n**首次使用前必须弹窗提示用户阅读并同意隐私政策**，再调用 `[BMKMapManager setAgreePrivacy:YES]`。未同意时调用 `[BMKMapManager setAgreePrivacy:NO]`。\n\n**注意**：`setAgreePrivacy:` 是 **BMKMapManager 的类方法**，必须写 `[BMKMapManager setAgreePrivacy:YES]`，**勿写** `[[BMKMapManager sharedInstance] setAgreePrivacy:YES]`（会报 \"Instance method '-setAgreePrivacy:' not found\"）。\n\n**隐私政策地址**：https://lbsyun.baidu.com/index.php?title=openprivacy（弹窗内需可点击跳转）。\n\nUI 标准见 [ui-standards.md](ui-standards.md)。**不同意时**：`setAgreePrivacy:NO`，BMKSearchBase 及其子类会返回 nil；需延迟创建检索对象，仅在用户同意后创建；未同意时使用检索前提示用户去同意。\n\n## CocoaPods 构建沙盒（Xcode 15+）\n\nCocoaPods 的 Copy Pods Resources 脚本需在 `Pods` 目录创建临时文件（如 `resources-to-copy-${TARGETNAME}.txt`）。Xcode 15 起默认开启 **User Script Sandboxing**，会阻止该写入，导致构建报错：\n\n```\nSandbox: bash deny(1) file-write-create .../Pods/resources-to-copy-xxx.txt\n```\n\n**解决**：在 target 的 Build Settings 中设置 `ENABLE_USER_SCRIPT_SANDBOXING = NO`。\n\n- **Xcode 图形界面**：选中 target → Build Settings → 搜索 \"User Script Sandboxing\" → 设为 **No**\n- **project.pbxproj**：在 target 的 XCBuildConfiguration（Debug/Release）的 buildSettings 中添加：\n  ```\n  ENABLE_USER_SCRIPT_SANDBOXING = NO;\n  ```\n\n## 窗口初始化/Launch Screen\n\n**现象**：地图未铺满屏幕、上下或左右出现黑边，地图只显示在中间一块区域。\n\n**原因**：未配置 Launch Screen 时，系统会按「未声明支持当前设备屏幕」处理，窗口或根视图的尺寸/安全区域可能异常，导致 `view.bounds` 不是全屏，地图即使用 `view.bounds` 设 frame 也会出现黑边。\n\n**必配**：工程需有 Launch Screen（LaunchScreen.storyboard 或同类），并在 Info.plist 中配置：\n\n```xml\n<key>UILaunchStoryboardName</key>\n<string>LaunchScreen</string>\n```\n\nLaunchScreen.storyboard 需设置 `launchScreen=\"YES\"`、`useSafeAreas=\"YES\"`，支持各尺寸 iPhone（含刘海屏）。内容可为白底 + 应用名等静态界面。\n\n**地图不全屏排查顺序**（Agent 必须遵守）：\n1. **先检查 Launch Screen**：是否有 LaunchScreen.storyboard（或 Launch Image）、Info.plist 是否含 `UILaunchStoryboardName`；缺则补上并加入 target Resources。\n2. **再检查布局**：地图视图的 frame 是否在 `viewDidLayoutSubviews` 中设为 `self.view.bounds`（避免在 viewDidLoad/首次创建时 bounds 未稳定导致尺寸错误）。\n\nFile v1.0.2:references/reference.md\n\n# 百度地图 iOS SDK 参考索引\n\n按需选下表文档；通用规则（隐私、坐标系、版本以本地为准）见 [SKILL.md](../SKILL.md)。\n\n## 按需求选文档\n\n| 你要做的 | 用到的文档 |\n|----------|------------|\n| 集成 Pod、选地图/定位/步骑行/导航套件 | [cocoapods.md](cocoapods.md) |\n| Info.plist、隐私弹窗、Launch Screen、构建沙盒 | [project-config.md](project-config.md) |\n| 单次/连续/后台/室内定位、地理围栏、鉴权失败 | [location.md](location.md) |\n| 地图视图、属性、生命周期、全屏 | [mapview.md](mapview.md) |\n| 点标注、固定屏、点聚合展示 | [annotations.md](annotations.md) |\n| 覆盖物、热力、点聚合逻辑、轨迹、Marker/RichView | [overlays.md](overlays.md) |\n| 检索/路线/选点/弹窗/视野/Logo 等 UI 规范 | [ui-standards.md](ui-standards.md) |\n| Sug、地理编码、逆地理、POI、公交 | [search.md](search.md) |\n| 驾车/步行/骑行/公交**算路与画线**（BMKRouteSearch，仅算路+画线） | [route.md](route.md) |\n| **步骑行实时导航**（BaiduWalkNaviKit，诱导、TTS、偏航纠偏、多实例） | [navi.md](navi.md) |\n| 坐标转换、几何、视野适配、调起地图 | [utils.md](utils.md) |\n| 图片资源路径与命名 | [assets.md](assets.md) |\n| 类与头文件速查 | [class-index.md](class-index.md) |\n\n**步骑行**：算路画线（route）与实时导航（navi）为**不同服务**——仅画线用 route，要诱导/TTS/偏航用 [navi.md](navi.md)。\n\n## 文档一览与边界\n\n| 文档 | 内容 | 边界 |\n|------|------|------|\n| [cocoapods.md](cocoapods.md) | Podfile、pod 命令、地图/定位/步骑行套件 | 构建报错见 [project-config.md](project-config.md) |\n| [project-config.md](project-config.md) | Info.plist、隐私弹窗、Launch Screen、CocoaPods 沙盒 | 仅百度 SDK 相关配置 |\n| [location.md](location.md) | BMKLocationKit、定位方式、鉴权排查、坐标系 | 不含步骑行导航内部定位 |\n| [mapview.md](mapview.md) | BMKMapView、状态、生命周期 | 不含标注/覆盖物具体类型 |\n| [annotations.md](annotations.md) | 标注、固定屏、点聚合展示 | 聚类逻辑见 [overlays.md](overlays.md) |\n| [overlays.md](overlays.md) | 覆盖物、热力、点聚合逻辑、轨迹、Marker | 与 annotations 组合使用 |\n| [ui-standards.md](ui-standards.md) | 检索/路线/选点/弹窗/视野/Logo 等 UI 标准 | 无特殊要求时方案按此实现 |\n| [search.md](search.md) | Sug、地理编码、逆地理、POI、公交 | 路线算路见 [route.md](route.md) |\n| [route.md](route.md) | BMKRouteSearch：驾车/步行/骑行/公交算路与画线、BMKPlanNode、路况 | 与 walkcyclenavi 不同服务；仅算路+画线用本文档 |\n| [navi.md](navi.md) | BaiduWalkNaviKit：步骑行实时导航、诱导、TTS、偏航、多实例、无UI | 与 route 不同服务；需实时导航用本文档 |\n| [utils.md](utils.md) | BMKCoordTrans、BMKGeometry、视野、调起地图 | 工具类，与其它文档组合 |\n| [assets.md](assets.md) | 图片资源 | 技能内 assets 目录 |\n| [class-index.md](class-index.md) | 类与头文件速查 | 用法与示例见各功能文档 |\n\n## 常见组合\n\n| 需求 | 文档组合 |\n|------|----------|\n| 地图 + 定位 | cocoapods → project-config → mapview + location（坐标系统一 BD09） |\n| 地图 + 路线画线 | mapview + route + search（选点）；步骑行仅画线用 route |\n| 步骑行实时导航 | cocoapods（BaiduWalkNaviKit）→ project-config → navi |\n| 标注 + 点聚合 | annotations + overlays（聚类与 Marker） |\n| 定位鉴权失败 | [location.md](location.md)「鉴权失败排查」+ project-config 隐私与 Info.plist |\n\nArchive v1.0.1: 17 files, 59240 bytes\n\nFiles: _meta.json (136b), references/annotations.md (3338b), references/assets.md (1239b), references/class-index.md (7708b), references/cocoapods.md (1760b), references/location.md (10966b), references/mapview.md (21046b), references/navi.md (5233b), references/overlays.md (20945b), references/project-config.md (5675b), references/reference.md (3753b), references/route.md (12187b), references/search.md (11745b), references/ui-standards.md (12422b), references/utils.md (6283b), skill-card.md (3210b), SKILL.md (11419b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: baidu-map-ios-sdk\ndescription: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。\ncompatibility: iOS, Xcode, CocoaPods\n---\n\n# 百度地图 iOS SDK\n\n## 目标与边界\n\n- **目标**：在 iOS 工程中正确集成百度地图/定位/步骑行导航，并给出符合隐私与坐标系规范的实现方案。\n- **负责**：BaiduMapKit、BMKLocationKit、BaiduWalkNaviKit 的集成、配置、API 选用与示例；与技能内 reference 文档一致。\n- **不负责**：驾车导航细节（百度地图驾车导航文档）、服务端逻辑、非百度 SDK、UI 视觉设计（仅遵循 [ui-standards.md](references/ui-standards.md) 的规范）。\n\n## 使用时机\n\n满足其一即启用本技能：\n\n- 关键词：百度地图、BMKMapView、BMKLocationKit、步骑行导航、BaiduWalkNaviKit、标注、路线规划、CocoaPods 集成、BD09、定位鉴权\n- 需求类型：地图展示、单次/连续/后台定位、步行或骑行实时导航、POI/标注/覆盖物、路线绘制、逆地理、轨迹动画、点聚合、隐私弹窗\n\n**按需加载**：先根据需求在 [reference.md](references/reference.md) 中选定文档，再引用对应 references 内容；需求含糊时先向用户澄清再给方案。\n\n## 集成与编码顺序\n\n- **未集成百度地图 SDK 时**：先配置并执行 CocoaPods（编写/补全 Podfile → 执行 `pod install` → 使用生成的 `.xcworkspace` 打开），**在能正确导入 SDK 头文件之后**再编写调用地图/定位/检索等的代码。这样既避免使用 `#if __has_include(...)` 做条件编译，也能以实际 SDK 头文件为准写代码，减少接口不一致或编译错误。\n- **本地已集成 SDK 时**：直接按需导入头文件并写代码，**以当前工程内的 SDK 版本、头文件及接口为准**；类名、方法、参数与本地头文件一致，不写不存在的 API。若编译报错提示符号不存在，提示开发者核对或更新 Pod 版本后再重试。\n\n## Agent 执行要求\n\n1. **AK 与 Bundle 主动提示**  \n   在编写或集成使用地图/定位 SDK 的代码时，**主动提示开发者**：\n   - 在 [百度 LBS 控制台](https://lbsyun.baidu.com/) 申请 **iOS 应用 AK**，且应用的 **Bundle Identifier** 必须与工程中 `PRODUCT_BUNDLE_IDENTIFIER` 一致；\n   - 在代码或配置中预留/替换 AK 的位置（如 `AppDelegate` 中的 key、或说明需在控制台配置），并注明「将 `YOUR_AK` 替换为实际 AK」。\n   - 若工程尚未配置 Bundle ID，提醒开发者设置并与控制台申请时填写的包名一致。\n\n2. **代码写完自动执行编译修复，编译无误后停止**  \n   完成与百度地图/定位相关的代码修改后，**必须**按以下流程执行，**不得在编译未通过时结束**：\n   - **自动执行编译**：使用 `xcodebuild -workspace xxx.xcworkspace -scheme xxx -destination 'generic/platform=iOS' build`（或等价命令；CocoaPods 工程用 workspace，纯工程用 project）。\n   - **若编译报错**：根据报错信息**立即修复**（类名、方法签名、头文件、ARC、协议声明等），修复后**再次执行编译**。\n   - **循环**：重复「编译 → 若有错误则修复 → 再编译」，直至**编译通过、无错误**。\n   - **编译无误后停止**：仅当 build 成功（BUILD SUCCEEDED）后，才结束本轮代码修改与修复，不再继续做与编译无关的额外修改。\n\n3. **配置 Launch Screen 避免 App 非全屏**  \n   集成地图或涉及全屏展示时，**必须**确保工程已配置 Launch Screen，避免运行后出现黑边、非全屏。具体见 [project-config.md](references/project-config.md)「窗口初始化/Launch Screen」：\n   - 工程内存在 **LaunchScreen.storyboard**（或等效 Launch 资源），并加入 target 的 Resources；\n   - Info.plist 中配置 **UILaunchStoryboardName** 为 `LaunchScreen`；\n   - 若缺失，主动创建或补充说明，并提醒开发者添加该配置。\n\n## 必须遵守的规则\n\n1. **隐私与配置**\n   - 首次使用前必须弹窗让用户阅读并同意隐私政策，再调用对应接口。\n   - **地图**：`[BMKMapManager setAgreePrivacy:YES]`（**类方法**，勿用 `sharedInstance`；未同意时检索可返回 nil）。\n   - **定位**：通过 **BMKLocationAuth** 的 **setAgreePrivacy** 在用户同意后再初始化 BMKLocationManager 等；详见 [location.md](references/location.md)。\n   - Info.plist 必配 **CFBundleDisplayName**；使用定位时配 NSLocationWhenInUseUsageDescription 等。详见 [project-config.md](references/project-config.md)。\n   - **AK 与 Bundle**：编写集成代码时主动提示开发者提供/配置 AK，且 Bundle Identifier 与百度控制台申请一致（见上文「Agent 执行要求」）。\n   - **Launch Screen**：必须配置 LaunchScreen.storyboard 与 Info.plist 的 UILaunchStoryboardName，避免运行后 App 非全屏、黑边；见 [project-config.md](references/project-config.md)。\n\n2. **坐标系**\n   - 地图 SDK 全局 **BD09**；定位 SDK 默认 **GCJ02**。与地图混用时须统一为 BD09：将定位 **coordinateType** 设为 **BMKLocationCoordinateTypeBMK09LL**，或使用 [utils.md](references/utils.md) 的 BMKCoordTrans 转换。\n\n3. **标注与几何（必须遵守）**\n   - **点标注优先使用 Marker，不得使用 Annotation/PinAnnotation**：点标注**必须优先**使用 **BMKIconMarker/BMKTextMarker**（addOverlay 体系），**禁止**使用 BMKPointAnnotation、BMKAnnotationView、BMKPinAnnotationView（addAnnotation 体系）除非以下例外：点聚合（BMKClusterManager 必须用 BMKPointAnnotation）、固定屏选点（isLockedToScreen）等仅 addAnnotation 能实现的场景。起终点、小车、普通图钉等一律用 Marker。详见 [overlays.md](references/overlays.md)、[annotations.md](references/annotations.md)。\n   - 距离、视野、方位等用 [utils.md](references/utils.md) 的 BMKGeometry 等，勿手写。\n   - **路线与起终点须优先使用纹理**：绘制**路线**时优先使用 **BMKPolylineView.textureImage**（图片宽高须为 2 的 n 次幂）或路况场景使用 **BMKMultiTexturePolylineView** + [assets](references/assets.md) 路况纹理；**起终点**的 BMKIconMarker.icon 须优先使用 [assets](references/assets.md) 的 **icon_start、icon_end**；仅当无可用纹理时再使用 strokeColor/纯色或自绘。见 [overlays.md](references/overlays.md)「路线与起终点：纹理优先」。\n   - **路线小车纹理**：路线上的小车图标**必须优先使用**本技能 [assets](references/assets.md)（`assets/images/`）提供的纹理图（如 icon_car、car_triangle、track_car）；仅当无可用纹理时，才使用纯色或自绘图片。\n\n4. **步骑行：按需求区分两种方案**\n   - **路线规划（算路+画线）**：BMKRouteSearch（BaiduMapKit），walkingSearch/ridingSearch，得到路线后自绘折线。见 [route.md](references/route.md)。\n   - **步骑行实时导航**：BaiduWalkNaviKit，Manager + 诱导、TTS、偏航纠偏、多实例/无UI。见 [navi.md](references/navi.md)。\n   - 二者是**不同服务**：仅需画线用 route；需实时导航用 navi。给出方案前先按开发者需求选对文档。\n\n5. **版本与 API 以本地为准**（与上文「集成与编码顺序」一致）\n   - 已集成 SDK：**以工程内 SDK 版本与头文件为准**，类名、方法、参数与头文件一致；不写 `#if __has_include`，直接导入头文件后写代码。\n   - 若某类、方法或属性在用户工程中**不存在**（编译报错或头文件无此符号），**提示用户将对应 Pod 更新到最新版本**后再重试，勿强行按文档写不存在的 API。\n\n6. **Logo 不可遮挡与路线视野适配（必须考虑）**\n   - **Logo 不能被遮挡**：百度地图 Logo 不可移除、不允许被 UI 遮挡。有浮动栏/底部栏时**必须**使用 `setMapPadding` 预留边界（如顶部预留检索面板、底部预留 barH+4），使 Logo 落在可见内容区内。详见 [ui-standards.md](references/ui-standards.md)「地图 Logo、指南针与 mapPadding」。\n   - **路线适配视野必须做**：有路线绘制时**必须**调用 `fitVisibleMapRect:edgePadding:withAnimated:` 做视野适配，edgePadding 按 [ui-standards.md](references/ui-standards.md)「路线视野适配」预留（顶部检索面板+50+marker、底部底部栏+20+marker、左右 50+marker 等），避免路线或起终点被裁切或被 UI 遮挡。mapPadding 与 fitVisibleMapRect 的 edgePadding 分开使用，勿混用。\n\n## 输出规范（可评估）\n\n给出方案时需满足：\n\n- **可落地**：含具体类名、方法、调用顺序与必要配置（如 Info.plist、隐私调用时机、Launch Screen）。\n- **可验证**：隐私与坐标系处理明确；若涉及定位鉴权失败，方案中可指向 [location.md](references/location.md) 的「鉴权失败排查」。\n- **可组合**：按 [reference.md](references/reference.md) 选文档与常见组合；步骑行选型见规则 4。\n- **AK/Bundle 提示**：涉及地图/定位初始化时，明确提示开发者配置 AK 与 Bundle Identifier。\n- **编写后编译直至通过**：完成代码编写后，自动执行 xcodebuild 编译；若有报错则根据错误修复并重新编译，循环直至编译无误，再停止。\n- **全屏与 Launch Screen**：涉及地图全屏或窗口大小时，确认或说明已配置 LaunchScreen.storyboard 与 UILaunchStoryboardName，避免运行后非全屏、黑边。\n- **Logo 不遮挡**：涉及地图且有浮动栏/底部栏时，方案中**必须**包含 setMapPadding，并说明底部预留尽量小（如 barH+4），确保 Logo 不被遮挡。\n- **路线视野适配**：涉及路线绘制时，方案中**必须**包含 fitVisibleMapRect 的 edgePadding 设置，按 ui-standards 预留顶底左右，确保路线与起终点在可视区内且不被 UI 遮挡。\n- **点标注用 Marker**：涉及地图点标注（起终点、小车、图钉等）时，**必须**使用 BMKIconMarker/BMKTextMarker（addOverlay），不得使用 BMKPointAnnotation/BMKPinAnnotationView，除非点聚合、固定屏选点等例外场景。\n- **路线与起终点纹理优先**：涉及路线折线或起终点 Marker 时，**必须**优先使用纹理（路线：BMKPolylineView.textureImage 或 BMKMultiTexturePolylineView；起终点：BMKIconMarker.icon 使用 [assets](references/assets.md) 的 icon_start/icon_end），仅无可用纹理时再写 strokeColor 或自绘；见 [overlays.md](references/overlays.md)「路线与起终点：纹理优先」。\n\n方案结构：需求 → 对应文档 → 配置与依赖（含 AK/Bundle、Launch Screen）→ 关键 API → 示例片段 → 注意事项（含 Logo/路线视野、Marker 优先）。\n\n## 参考索引\n\n- 选文档与边界：[reference.md](references/reference.md)\n- 类速查：[class-index.md](references/class-index.md)\n- 定位/鉴权：[location.md](references/location.md) \n- 步骑行导航：[navi.md](references/navi.md) \n- 资源：[assets.md](references/assets.md)\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn778b6bf766ym71fdvrc5yvg98319rv\",\n  \"slug\": \"baidu-map-ios-sdk\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1775534867729\n}\n\nFile v1.0.1:references/annotations.md\n\n# 标注 (Annotation)\n\n**边界**：addAnnotation 体系；覆盖物见 [overlays.md](overlays.md)。**必须遵守**：点标注**优先使用 Marker**（BMKIconMarker/BMKTextMarker，addOverlay），**不得使用** Annotation/PinAnnotation 做起终点、小车、普通图钉等；**仅**点聚合、固定屏选点等必须用 addAnnotation 的场景才用本 API。见 [SKILL.md](../SKILL.md) 规则 3。\n\n## 使用须知\n- **Delegate**：addAnnotation 前必须设置 `mapView.delegate`，并实现 `mapView:viewForAnnotation:`。\n- **复用**：使用 `dequeueReusableAnnotationViewWithIdentifier`，identifier 建议唯一。\n- **起终点**：推荐 BMKIconMarker（addOverlay），见 [overlays.md](overlays.md)。\n\n## 核心类\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKAnnotation | BMKAnnotation.h | 标注协议，`coordinate`、`title` |\n| BMKPointAnnotation | BMKPointAnnotation.h | 点标注 |\n| BMKAnnotationView | BMKAnnotationView.h | 标注视图基类 |\n| BMKPinAnnotationView | BMKPinAnnotationView.h | 大头针样式 |\n| BMKActionPaopaoView | BMKActionPaopaoView.h | 气泡视图 |\n\n**标注规范**：使用 `dequeueReusableAnnotationViewWithIdentifier` 复用，identifier 建议唯一。自定义图片用 BMKAnnotationView + image。\n\n## 固定屏幕标注（地图选点）\n\n`BMKPointAnnotation.isLockedToScreen = YES` + `screenPointToLock`，需在 `mapViewDidFinishLoading` 后设置。常用于地图选点。\n\n**方式 B（BMKIconMarker）**：Marker 无 isLockedToScreen，需在 `regionDidChangeAnimated:reason:` 中（reason == BMKRegionChangeReasonGesture）同步 `marker.coordinate = mapView.centerCoordinate`。**区域回调**：regionWillChange 跳起，regionDidChange 落下 + 逆地理。**选点动画**见 [ui-standards.md](ui-standards.md)。\n\n## BMKPinAnnotationView 常用属性\n\n`centerOffset`、`calloutOffset`（正偏移朝右下方）、`enabled3D`、`canShowCallout`、`leftCalloutAccessoryView`/`rightCalloutAccessoryView`（默认气泡最大 32×41）、`pinColor`（Red/Green/Purple）、`animatesDrop`、`draggable`。直接设置 `selected` 时，非 PinAnnotation 需在设置后调用 `mapForceRefresh`。\n\n## 碰撞检测与展示优先级\n\n`BMKAnnotationView.displayPriority`（如 `BMKFeatureDisplayPriorityDefaultHigh`）、`isOpenCollisionDetection`、`collisionDetectionPriority`（数值越大越优先）、`isForceDisplay`（强制展示）、`displayMaxLevel`/`displayMinLevel`（层级限制）。\n\n## 点聚合中的标注\n\n点聚合（BMKClusterManager + BMKPointAnnotation）将大量标注按 zoom 聚合。`viewForAnnotation` 按 cluster.size 区分单点/聚合点；size>1 可显示数量、按档设圆点大小。**点击拆簇**：`annotationViewForBubble` 中 zoomIn。聚合逻辑见 [overlays.md](overlays.md)。\n\n---\n\n## 按需方案\n\n| 需求 | 基础能力 |\n|------|----------|\n| 普通点标注 | BMKPointAnnotation + BMKAnnotationView |\n| 大头针 | BMKPointAnnotation + BMKPinAnnotationView |\n| 固定屏幕选点 | BMKPointAnnotation（isLockedToScreen + screenPointToLock）或 BMKIconMarker |\n| 起终点大头针 | BMKPointAnnotation + BMKAnnotationView（起终点推荐 BMKIconMarker，见 [overlays.md](overlays.md)） |\n| 点聚合标注 | BMKClusterManager + BMKPointAnnotation，viewForAnnotation 按 size 展示 |\n\nFile v1.0.1:references/assets.md\n\n# 图片资源\n\n**边界**：技能内 `assets/images/` 图片及用途；集成与构建见 [cocoapods.md](cocoapods.md)、[project-config.md](project-config.md)。\n\n**路线小车**：路线上的小车图标**必须优先使用**本技能提供的纹理图（下表 icon_car / car_triangle / track_car）；仅当无可用纹理时，才使用纯色或自绘图片。实现时先 `[UIImage imageNamed:@\"icon_car\"]`（或对应名称），为 nil 再回退。\n\n| 图片 | 用途 |\n|------|------|\n| icon_car | 小车 marker（**路线小车优先**） |\n| car_triangle | 带方向小车（车头朝上） |\n| track_car | 带方向小车（车头朝右），**轨迹动画推荐** |\n| icon_start | 起点标注 |\n| icon_end | 终点标注 |\n| icon_via | 途经点 |\n| **路况纹理**（BMKMultiPolyline + BMKMultiTexturePolylineView，drawIndexs 来自 BMKDrivingStep.traffics） | |\n| traffic_texture_unknown | 无数据（traffics=0，drawIndex 0） |\n| traffic_texture_smooth | 畅通（traffics=1，drawIndex 1） |\n| traffic_texture_slow | 缓行（traffics=2，drawIndex 2） |\n| traffic_texture_congestion | 拥堵（traffics=3，drawIndex 3） |\n| traffic_texture_severe_congestion | 严重拥堵（traffics=4，drawIndex 4） |\n\nFile v1.0.1:references/class-index.md\n\n# 类速查表\n\n**边界**：按头文件组织的类速查；用法与示例见 [annotations.md](annotations.md)、[overlays.md](overlays.md) 等各功能文档。下表记录类名、头文件及主要方法/属性名，便于不依赖外链查阅。\n\n## 地图核心\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKMapManager | BMKMapManager.h | 主引擎 |\n| BMKMapView | BMKMapView.h | 地图视图 |\n| BMKMapStatus | BMKMapStatus.h | 地图状态 |\n| BMKMapViewDelegate | BMKMapView.h | 地图回调 |\n\n## 标注\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKAnnotation | BMKAnnotation.h | 标注协议 |\n| BMKPointAnnotation | BMKPointAnnotation.h | 点标注 |\n| BMKAnnotationView | BMKAnnotationView.h | 标注视图基类 |\n| BMKPinAnnotationView | BMKPinAnnotationView.h | 大头针样式 |\n| BMKActionPaopaoView | BMKActionPaopaoView.h | 气泡视图 |\n\n## 覆盖物\n\n### 基础\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKOverlay | BMKOverlay.h | 覆盖物协议 |\n| BMKOverlayView | BMKOverlayView.h | 覆盖物视图基类 |\n| BMKPolyline | BMKPolyline.h | 单色/单纹理折线 |\n| BMKPolylineView | BMKPolylineView.h | 折线视图 |\n| BMKMultiPolyline | BMKMultiPolyline.h | 分段折线，需 drawIndexs |\n| BMKMultiColorPolylineView | BMKMultiPolylineView.h | 分段颜色 |\n| BMKMultiTexturePolylineView | BMKMultiPolylineView.h | 分段纹理（路况） |\n| BMKCircle | BMKCircle.h | 圆形 |\n| BMKCircleView | BMKCircleView.h | 圆形视图 |\n| BMKPolygon | BMKPolygon.h | 多边形 |\n| BMKPolygonView | BMKPolygonView.h | 多边形视图 |\n| BMKGroundOverlay | BMKGroundOverlay.h | 图片图层 |\n| BMKGroundOverlayView | BMKGroundOverlayView.h | 图片图层视图 |\n| BMKTileLayer | BMKTileLayer.h | 瓦片图层基类 |\n| BMKURLTileLayer | BMKTileLayer.h | URL 瓦片图层 |\n\n### 曲线与渐变\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKArcline | BMKArcline.h | 圆弧 |\n| BMKArclineView | BMKArclineView.h | 圆弧视图 |\n| BMKGradientLine | BMKGradientLine.h | 渐变线 |\n| BMKGradientLineView | BMKGradientLineView.h | 渐变线视图 |\n| BMKGradientCircleView | BMKGradientCircleView.h | 渐变圆 |\n| BMKGeodesicLine | BMKGeodesicLine.h | 大地线 |\n| BMKGeodesicLineView | BMKGeodesicLineView.h | 大地线视图 |\n\n### Marker\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKIconMarker | BMKIconMarker.h | 图标 Marker |\n| BMKIconMarkerView | BMKIconMarkerView.h | 图标 Marker 视图 |\n| BMKTextMarker | BMKTextMarker.h | 文本 Marker |\n| BMKTextMarkerView | BMKTextMarkerView.h | 文本 Marker 视图 |\n| BMKTextPathMarker | BMKTextPathMarker.h | 沿路径文字 |\n| BMKTextPathMarkerView | BMKTextPathMarkerView.h | 沿路径文字视图 |\n\n### 文本与海量点\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKText | BMKText.h | 文本 overlay |\n| BMKTextView | BMKTextView.h | 文本 overlay 视图 |\n| BMKMultiPointOverlay | BMKMultiPointOverlay.h | 海量点 |\n| BMKMultiPointOverlayView | BMKMultiPointOverlayView.h | 海量点视图 |\n| BMKMultiPointItem | BMKMultiPointOverlay.h | 海量点数据项 |\n\n### 3D 与轨迹\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMK3DModelOverlay | BMK3DModelOverlay.h | 3D 模型 |\n| BMK3DModelOverlayView | BMK3DModelOverlayView.h | 3D 模型视图 |\n| BMKPrismOverlay | BMKPrismOverlay.h | 棱柱/3D 建筑 |\n| BMKPrismOverlayView | BMKPrismOverlayView.h | 棱柱视图 |\n| BMKTraceOverlay | BMKTraceOverlay.h | 路书轨迹 |\n| BMKTraceOverlayView | BMKTraceOverlayView.h | 路书轨迹视图 |\n| BMK3DTraceOverlay | BMK3DTraceOverlay.h | 3D 轨迹 |\n| BMK3DTraceOverlayView | BMK3DTraceOverlayView.h | 3D 轨迹视图 |\n| BMKMapTrackAnimation | BMKMapAnimation.h | 轨迹动画 |\n| BMKCommonDef | BMKCommonDef.h | 枚举定义 |\n\n详见 [annotations.md](annotations.md)、[overlays.md](overlays.md)。\n\n## 检索\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKSuggestionSearch | BMKSuggestionSearch.h | 建议检索 |\n| BMKGeoCodeSearch | BMKGeoCodeSearch.h | 地理编码 |\n| BMKPOISearch | BMKPOISearch.h | POI |\n| BMKBusLineSearch | BMKBusLineSearch.h | 公交线路 |\n| BMKRouteSearch | BMKRouteSearch.h | 路线检索（算路见路线规划） |\n\n## 路线规划\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKRouteSearch | BMKRouteSearch.h | 路线检索 |\n| BMKDrivingRoutePlanOption | BMKRouteSearchOption.h | 驾车 |\n| BMKWalkingRoutePlanOption | BMKRouteSearchOption.h | 步行 |\n| BMKRidingRoutePlanOption | BMKRouteSearchOption.h | 骑行 |\n| BMKTransitRoutePlanOption | BMKRouteSearchOption.h | 公交 |\n| BMKPlanNode | BMKTypes.h | 路线节点（pt、name、cityName、cityID） |\n| BMKDrivingRouteResult / BMKWalkingRouteResult 等 | BMKRouteSearchResult.h | 算路结果 |\n| BMKDrivingStep / BMKWalkingStep 等 | BMKRouteSearchType.h | 路线步骤类型 |\n\n## 步骑行导航（BaiduWalkNaviKit）\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKWalkNavigationManager | BMKWalkNavigationManager.h | 步行导航管理，单例；destroy、initNaviEngine、routePlanWithParams、startWalkNaviWithParentController、getBackgroundNavigationView |\n| BMKCycleNavigationManager | BMKCycleNavigationManager.h | 骑行导航管理，单例；destroy、initNaviEngine、routePlanWithParams、naviCalcRoute:、startCycleNaviWithParentController、getBackgroundNavigationView |\n| BMKWalkNaviLaunchParam | BMKWalkNaviLaunchParam.h | 步行算路参数（startNode/endNode，BMKWalkNaviRouteNodeInfo） |\n| BMKCycleNaviLaunchParam | BMKCycleNaviLaunchParam.h | 骑行算路参数（startNode/endNode） |\n| BMKWalkNaviRouteNodeInfo | BMKWalkNaviRouteNodeInfo.h | 步行起/终点节点（type BMKWalkNavigationRouteNodeLocation 等） |\n| BMKCycleNaviRouteNodeInfo | BMKCycleNaviRouteNodeInfo.h | 骑行起/终点节点 |\n| BMKWalkCycleNavigationOptions | BMKWalkCycleNavigationOptions.h | 初始化选项（displayOption 等） |\n| BMKWalkCycleNavigationDisplayOption | BMKWalkCycleNavigationDisplayOption.h | 展示选项 |\n| BMKWalkCycleSampleGuideInfo | BMKWalkCycleSampleGuideInfo.h | 诱导信息（SampleGuide） |\n| BMKMultiNaviView | BMKMultiNaviView.h | 多实例导航地图 View（getNaviMapView） |\n\n后台投屏类（BMKBackgroundMapView、BMKBackgroundNavigationView、BMKBackgroundRoadNetView）见下「后台与导航」。\n\n详见 [navi.md](navi.md)。\n\n## 热力图\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKHeatMap | BMKHeatMap.h | 热力图 |\n| BMKHexagonHeatMap | BMKHexagonHeatMap.h | 六边形热力图 |\n\n## 后台与导航\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKBackgroundMapView | BMKBackgroundMapView.h | 后台投屏容器（mapview + roadNetView + navigationView） |\n| BMKBackgroundNavigationView | BMKBackgroundNavigationView.h | 导航层：路线、车标、罗盘、起终点；步骑行由 Manager.getBackgroundNavigationView 获取 |\n| BMKBackgroundRoadNetView | BMKBackgroundRoadNetView.h | 路网层：路网、路况、路名；从 backgroundMapView.roadNetView 获取 |\n| BMKNavigation | BMKNavigation.h | 调起百度地图 |\n| BMKNaviPara | BMKNaviPara.h | 导航参数 |\n\n## 坐标与结构体\n\n| 类型 | 说明 |\n|------|------|\n| CLLocationCoordinate2D | 经纬度（BD09） |\n| BMKMapRect | 直角地理坐标矩形 |\n| BMKMapPoint | 直角地理坐标点 |\n| BMKCoordinateRegion | 经纬度区域 |\n| BMKCoordinateBounds | 经纬度边界 |\n\n## 工具\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKGeometry | BMKGeometry.h | 坐标转换、几何计算 |\n| BMKInterpolator | BMKInterpolator.h | 动画插值器 |\n| BMKCommonDef | BMKCommonDef.h | 枚举定义 |\n\n详见 [utils.md](utils.md)。\n\nFile v1.0.1:references/cocoapods.md\n\n# CocoaPods 集成\n\n**版本**：不写版本号即使用最新；写版本号则锁定。API 以本地头文件为准，类/方法不存在时提示更新 Pod，见 [SKILL.md](../SKILL.md) 规则 5。\n\n## 安装 CocoaPods（未安装时）\n\n```bash\ngem sources -l\ngem sources --remove https://rubygems.org/\ngem sources -a https://gems.ruby-china.com\nsudo gem update --system\nsudo gem install -n /usr/local/bin cocoapods  # macOS > 10.11\npod setup\n```\n\n## Podfile 模板\n\n**仅定位**（BMKLocationKit，无地图）：\n```ruby\nplatform :ios, '9.0'\ntarget 'YourProjectTarget' do\n  pod 'BMKLocationKit', '2.1.3'\nend\n```\n\n**基础地图**（BaiduMapKit，不写版本号即使用最新）：\n```ruby\nplatform :ios, '10.0'\ntarget 'YourProjectTarget' do\n    pod 'BaiduMapKit'\n    # pod 'BaiduMapKit/Map'\n    # pod 'BaiduMapKit/Search'\n    # pod 'BaiduMapKit/Utils'\nend\n```\n\n**步骑行导航**（BaiduWalkNaviKit，含基础地图，步行/骑行实时导航）：\n```ruby\nplatform :ios, '10.0'\ntarget 'YourProjectTarget' do\n    pod 'BaiduWalkNaviKit'\nend\n```\n步骑行导航依赖、配置与示例见 [navi.md](navi.md)。\n\n## 常用命令\n\n```bash\npod install          # 安装后用 .xcworkspace 打开\npod repo update\npod update\n```\n\n## pod search 找不到类库\n\n```bash\npod setup\nrm ~/Library/Caches/CocoaPods/search_index.json\npod search BaiduMapKit   # 或 pod search BMKLocationKit\n```\n\n---\n\n## 后续配置\n\nInfo.plist、隐私协议弹窗见 [project-config.md](project-config.md)，图片资源见 [assets.md](assets.md)。\n\n**构建报错**：若出现 `Sandbox: bash deny file-write-create .../Pods/resources-to-copy-xxx.txt`，需关闭 User Script Sandboxing，见 [project-config.md](project-config.md) 的「CocoaPods 构建沙盒」小节。\n\nFile v1.0.1:references/location.md\n\n# 百度 iOS 定位 SDK（BMKLocationKit）\n\n**边界**：单次/连续/后台/室内定位、地理围栏、鉴权；与地图独立，可单独或与 BaiduMapKit 配合。与地图混用须统一坐标系，见 [utils.md](utils.md)。不含步骑行导航内部定位。\n\n## CocoaPods 集成\n\nPod 库名：**BMKLocationKit**。在 Podfile 同目录执行 `pod install`，使用生成的 `.xcworkspace` 打开工程。\n\n```ruby\nplatform :ios, '9.0'\ntarget 'YourProjectTarget' do  # 替换为工程名\n  pod 'BMKLocationKit', '2.1.3'\nend\n```\n\n常用命令：`pod install`、`pod repo update`、`pod update`。若 `pod search` 找不到类库：`pod setup` → 删除 `~/Library/Caches/CocoaPods/search_index.json` → 再执行 `pod search BMKLocationKit`。\n\n## 隐私与初始化（必须遵守）\n\n**必须通过 BMKLocationAuth 的 setAgreePrivacy 在用户同意隐私政策后再进行定位 SDK 的初始化。**\n\n- 首次使用前弹窗让用户阅读并同意隐私政策（隐私政策地址可跳转：https://lbsyun.baidu.com/index.php?title=openprivacy）。\n- 用户同意后调用 `[[BMKLocationAuth sharedInstance] setAgreePrivacy:YES]`，**再**初始化定位相关逻辑（如 BMKLocationManager 等）。\n- 用户不同意时调用 `setAgreePrivacy:NO`，且不要初始化定位 SDK。\n- 与地图 SDK 区分：地图使用 `[BMKMapManager setAgreePrivacy:YES]`；定位使用 **BMKLocationAuth** 的 setAgreePrivacy。\n\n## 鉴权失败排查（无法返回定位/地址时）\n\n若出现 **「鉴权失败导致无法返回定位、地址等信息」**（或错误码 BMKLocationErrorFailureAuth），按下列顺序检查：\n\n| 排查项 | 说明 |\n|--------|------|\n| **1. setAgreePrivacy 顺序** | 必须在 **BMKLocationManager、BMKGeoFenceManager 等实例化之前** 调用 `[[BMKLocationAuth sharedInstance] setAgreePrivacy:YES]`。顺序：先 setAgreePrivacy(YES) → 再创建/初始化 BMKLocationManager → 再发起定位。若先初始化再设隐私，会导致鉴权失败。 |\n| **2. AK（密钥）配置** | 在百度 LBS 控制台申请 **iOS 应用** 的 AK，且 **Bundle Identifier** 必须与当前应用一致。在任意定位 SDK 类初始化前完成 AK 校验/配置（如 BMKLocationAuth 的 checkPermisionWithKey: 等）。多应用需分别申请 AK。 |\n| **3. 网络与权限** | 确认设备网络正常；确认已向用户申请并授予定位权限（Info.plist 配置 NSLocationWhenInUseUsageDescription 等）。 |\n\n## 坐标系（与地图 SDK 一致）\n\n**地图 SDK 全局使用 BD09**。**定位 SDK** 通过 **coordinateType**（类型 BMKLocationCoordinateType）设定定位坐标系，**默认为 BMKLocationCoordinateTypeGCJ02**。将定位结果用于地图展示、标注、路线或与地图 API 混用时，必须统一为 BD09：将 **coordinateType 设为 BMKLocationCoordinateTypeBMK09LL**，或使用地图 [utils.md](utils.md) 的 `BMKCoordTrans:fromType:toType:` 将 GCJ02 转为 BD09 后再传给地图。否则会出现偏移或错误。\n\n## 核心类与接口（含默认值，避免与预期不一致）\n\n### BMKLocationAuth\n\n头文件：BMKLocationAuth.h。**初始化 BMKLocationManager 之前必须设置 BMKLocationAuth 中的 APIKey，否则无法正常使用服务。**\n\n| 接口/属性 | 说明 |\n|-----------|------|\n| `sharedInstance` | 单例 |\n| `setAgreePrivacy:` | 设置用户是否同意隐私政策，须在 BMKLocationManager/BMKGeoFenceManager 实例化前调用 |\n| `checkPermisionWithKey:...` | AK 校验，须在任意定位 SDK 类使用前调用 |\n\n---\n\n### BMKLocationManager（类参考，含属性默认值）\n\n头文件：BMKLocationManager.h。使用前须在 BMKLocationAuth 中设置 APIKey 并 setAgreePrivacy:YES。\n\n#### 属性（含默认值）\n\n| 属性 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| delegate | id\\<BMKLocationManagerDelegate\\> | — | 连续定位/错误回调等 |\n| distanceFilter | CLLocationDistance | **kCLDistanceFilterNone** | 定位最小更新距离 |\n| headingFilter | CLLocationDegrees | **1**（since 2.0.5） | 设备朝向最小更新角度 |\n| desiredAccuracy | CLLocationAccuracy | **kCLLocationAccuracyBest** | 定位精度 |\n| activityType | CLActivityType | **CLActivityTypeAutomotiveNavigation** | 定位类型 |\n| showsBackgroundLocationIndicator | BOOL | **NO**（iOS11+） | 后台定位时状态栏是否显示指示器；“始终授权”下设置有效 |\n| coordinateType | BMKLocationCoordinateType | **BMKLocationCoordinateTypeGCJ02** | 定位坐标系类型。与地图混用须设为 BMKLocationCoordinateTypeBMK09LL |\n| pausesLocationUpdatesAutomatically | BOOL | **NO** | 定位是否被系统自动暂停 |\n| allowsBackgroundLocationUpdates | BOOL | **NO**（iOS9+） | 是否允许后台定位；设为 YES 时须开启 Background Modes → Location updates，且在定位未开始或已停止时修改才生效 |\n| locationTimeout | NSInteger | **10**（秒） | 单次定位超时时间，最小 2s；在单次定位请求前设置；从定位权限非 NotDetermined 后开始计时 |\n| reGeocodeTimeout | NSInteger | **10**（秒） | 单次逆地理超时时间，最小 2s；单次定位请求前设置 |\n| locatingWithReGeocode | BOOL | **YES** | 连续定位是否返回逆地理信息 |\n| isNeedNewVersionReGeocode | BOOL | **YES**（1.9 起） | 是否需要最新版逆地理数据（如城市变更实时更新） |\n| userID | NSString * | — | 开发者指定用户 ID，便于排查问题 |\n| accuracyAuthorization | BMKLAccuracyAuthorization | （只读） | 定位精度等级，iOS14+ 用户可控制；用于适配不同精度下的产品逻辑 |\n\n#### 实例方法\n\n| 方法 | 说明 |\n|------|------|\n| `requestLocationWithReGeocode:withNetworkState:completionBlock:` | 单次定位。正在连续定位时调用会失败返回 NO。按 desiredAccuracy 获取定位，精度不足会等待至超时后回调精度最高结果。可用 stopUpdatingLocation 取消。参数：withReGeocode 是否带逆地理（需联网），withNetWorkState 是否带移动热点识别（需联网） |\n| `startUpdatingLocation` | 开始连续定位；会 cancel 所有单次定位请求 |\n| `stopUpdatingLocation` | 停止连续定位；会 cancel 所有单次定位请求，也可用于取消单次定位 |\n| `requestNetworkState` | 请求网络状态结果回调 |\n| `startUpdatingHeading` | 开始设备朝向事件回调 |\n| `stopUpdatingHeading` | 停止设备朝向事件回调 |\n| `tryIndoorLocation` | 尝试高精度室内定位（仅室内定位版本生效） |\n| `stopIndoorLocation` | 关闭高精度室内定位（仅室内定位版本生效） |\n| `authorizationStatus` | 返回当前定位权限（CLAuthorizationStatus） |\n| `requestTemporaryFullAccuracyAuthorizationWithPurposeKey:completion:` | 无全量精度权限时临时请求一次全量精度，系统弹框；purposeKey 对应 Info.plist 中 NSLocationTemporaryUsageDescriptionDictionary 的 key（iOS14+） |\n| `requestTemporaryFullAccuracyAuthorizationWithPurposeKey:` | 请求一次全量定位精度等级（iOS14+） |\n\n#### BMKLocationManagerDelegate 回调（头文件 BMKLocationManager.h）\n\n| 方法 | 说明 |\n|------|------|\n| `BMKLocationManager:didUpdateLocation:` | 连续定位位置更新，location 为 BMKLocation |\n| `BMKLocationManager:didFailWithError:` | 定位失败，error 含 BMKLocationErrorFailureAuth 等 |\n| `BMKLocationManager:didUpdateHeading:` | 设备朝向更新（需先 startUpdatingHeading） |\n\n单次定位结果在 `requestLocationWithReGeocode:...completionBlock:` 的 block 中返回。\n\n#### 类方法\n\n| 方法 | 说明 |\n|------|------|\n| `+ headingAvailable` | 设备是否支持朝向事件回调 |\n| `+ BMKLocationCoordinateConvert:SrcType:DesType:` | 坐标转换。参数：coordinate 待转换经纬度，srctype 源坐标系类型，destype 目标百度坐标系类型（bd09ll、bd09mc）。返回目标百度坐标系经纬度 |\n| `+ BMKLocationDataAvailableForCoordinate:withCoorType:` | 判断经纬度是否在大陆及港、澳地区。参数：coordinate 待判断经纬度，coortype 该经纬度的坐标系类型。返回 YES 表示境内 |\n\n### BMKGeoFenceManager\n\n地理围栏：创建、查询、删除围栏等，须在 setAgreePrivacy:YES 之后实例化。\n\n**国内外/境内判断**：使用 `[BMKLocationManager BMKLocationDataAvailableForCoordinate:withCoorType:]`，coortype 传 `BMKLocationCoordinateTypeBMK09LL`，返回 YES 表示国内。与地图配合见 [utils.md](utils.md)。\n\n## 获取位置信息（能力与对应方式）\n\n| 能力 | 说明 |\n|------|------|\n| 单次定位 | BMKLocationManager 的 requestLocationWithReGeocode: completionBlock: |\n| 连续定位 | startUpdatingLocation，通过 BMKLocationManagerDelegate 回调 |\n| 后台定位 | allowsBackgroundLocationUpdates = YES，UIBackgroundModes 含 location，并配置 Info.plist 定位相关说明 |\n| 室内定位 | 使用室内定位相关 API（具体见 BMKLocationKit 头文件） |\n\n## 辅助功能（能力与对应类/接口）\n\n| 能力 | 说明 |\n|------|------|\n| 地理围栏 | BMKGeoFenceManager，创建/删除围栏、状态回调 |\n| 移动热点识别 | 定位 SDK 提供的热点相关接口 |\n| 国内外位置判断 | BMKLocationManager 的 BMKLocationDataAvailableForCoordinate:withCoorType: |\n| 坐标转换 | 定位 SDK 内坐标类型配置（coordinateType）或配合地图 utils 的 BMKCoordTrans |\n| 防作弊 | 定位 SDK 提供的防作弊相关接口 |\n\n错误码（如 BMKLocationErrorFailureAuth）、iOS 14 适配、提交 App Store 注意事项、HTTPS 等请查阅百度 LBS 开放平台 iOS 定位 SDK 文档。\n\n## 与地图 SDK 的关系\n\n- **仅需定位**：只集成 BMKLocationKit 即可。\n- **地图 + 定位**：同时集成 BaiduMapKit 与 BMKLocationKit；地图上「我的位置」、定位图层等见 [mapview.md](mapview.md)（LocationViewAPI）；坐标转换、国内外判断等见 [utils.md](utils.md)。\n- **隐私**：定位 SDK 必须通过 **BMKLocationAuth** 的 **setAgreePrivacy** 在用户同意后再初始化；地图 SDK 使用 BMKMapManager 的 setAgreePrivacy。详见上文「隐私与初始化」。\n\n---\n\n## 按需方案\n\n| 需求 | 说明 |\n|------|------|\n| 仅需定位、无地图 | BMKLocationKit，BMKLocationAuth setAgreePrivacy → BMKLocationManager，coordinateType 按需设置 |\n| 地图上显示我的位置 | BaiduMapKit + BMKLocationKit，mapview 的 showsUserLocation / userTrackingMode / updateLocationData；定位结果 coordinateType 建议 BMK09LL |\n| 国内外/境内判断 | BMKLocationManager 的 BMKLocationDataAvailableForCoordinate:withCoorType:，见 [utils.md](utils.md) |\n| 单次/连续/后台/室内定位 | BMKLocationManager requestLocationWithReGeocode、startUpdatingLocation、allowsBackgroundLocationUpdates 等 |\n| 地理围栏/热点/坐标转换/防作弊 | BMKGeoFenceManager、coordinateType、及 SDK 对应辅助接口 |\n\nFile v1.0.1:references/mapview.md\n\n# BMKMapView 地图视图\n\n**边界**：地图视图、属性、生命周期、控制（BMKMapView）；标注见 [annotations.md](annotations.md)，覆盖物见 [overlays.md](overlays.md)。\n\n## 概述\n\n`BMKMapView` 继承 `UIView`，用于显示地图并执行相关操作。需配合 `BMKMapViewDelegate` 使用。\n\n### 示例：创建地图与生命周期\n\n```objc\n#import <BaiduMapAPI_Base/BMKBaseComponent.h>\n#import <BaiduMapAPI_Map/BMKMapComponent.h>\n\n@property (nonatomic, strong) BMKMapView *mapView;\n\n- (void)viewDidLoad {\n    [super viewDidLoad];\n    _mapView = [[BMKMapView alloc] initWithFrame:self.view.bounds];\n    _mapView.delegate = self;\n    [self.view addSubview:_mapView];\n    // 可选：设置中心与缩放（改 centerCoordinate 不改变 zoomLevel）\n    _mapView.centerCoordinate = CLLocationCoordinate2DMake(39.917, 116.379);\n    _mapView.zoomLevel = 18;\n}\n\n- (void)viewWillAppear:(BOOL)animated {\n    [super viewWillAppear:animated];\n    [_mapView viewWillAppear];\n}\n- (void)viewWillDisappear:(BOOL)animated {\n    [super viewWillDisappear:animated];\n    [_mapView viewWillDisappear];\n}\n```\n\n### 示例：设置地图状态（带动画、指定时长）\n\n```objc\n// 使用 BMKMapStatus 设置层级与中心，带动画且指定动画时长(ms)\nBMKMapStatus *status = [[BMKMapStatus alloc] init];\nstatus.fLevel = 10;\nstatus.targetGeoPt = CLLocationCoordinate2DMake(51.50556, -0.07556);\n[_mapView setMapStatus:status withAnimation:YES withAnimationTime:1000];\n```\n\n### 示例：室内图\n\n```objc\n_mapView.baseIndoorMapEnabled = YES;\n_mapView.showIndoorMapPoi = YES;\n// 进入/移出室内图回调：mapView:baseIndoorMapWithIn:baseIndoorMapInfo:\n```\n\n## 地图引擎与生命周期\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKMapManager | BMKMapManager.h | 主引擎，`start:`、`setAgreePrivacy:` |\n| BMKMapView | BMKMapView.h | 地图视图 |\n| BMKMapStatus | BMKMapStatus.h | 地图状态（中心、缩放、旋转） |\n\n**生命周期（必须调用）**：viewWillAppear/viewWillDisappear 必须调 mapView 对应方法，否则地图状态异常。\n\n```objc\n- (void)viewWillAppear:(BOOL)animated {\n    [super viewWillAppear:animated];\n    [_mapView viewWillAppear];\n}\n- (void)viewWillDisappear:(BOOL)animated {\n    [super viewWillDisappear:animated];\n    [_mapView viewWillDisappear];\n}\n```\n\n### 地图显示当前定位\n\n- 设置 **showsUserLocation = YES**，再通过 **updateLocationData:** 传入 **BMKUserLocation**（含 `location`、可选 `heading`），地图会绘制定位点。\n- 定位数据需自行获取（如 BMKLocationManager 单次/连续定位）；与地图混用时坐标系须为 BD09（coordinateType 或转换），见 [location.md](location.md)。\n\n```objc\n_mapView.showsUserLocation = YES;\n// 在拿到定位结果后（主线程）：\nBMKUserLocation *userLoc = [BMKUserLocation new];\nuserLoc.location = [[CLLocation alloc] initWithLatitude:lat longitude:lng];\nuserLoc.updating = NO;\n[_mapView updateLocationData:userLoc];\n```\n\n**注意**：仅在设置 showsUserLocation 且至少调用一次 updateLocationData 传入有效 CLLocation 后，地图上才会显示蓝点；未授权或定位失败时可不调用 updateLocationData。\n\n**俯仰角**：`overlooking` 范围 -45～0，更陡需设 `minOverlooking`（-79～0）。`overlookEnabled` 是否支持俯仰角手势。\n\n---\n\n## 核心属性\n\n### Delegate 与手势\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| delegate | id\\<BMKMapViewDelegate\\> | 地图回调 |\n| gestureDelegate | id\\<BMKMapGestureDelegate\\> | 手势回调，返回 YES 时拦截地图处理 |\n\n### 地图类型与语言\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| mapType | BMKMapType | 标准/卫星地图 |\n| languageType | BMKMapLanguageType | 中/英文地图（since 6.4.0），V6.6.2 起英文不支持个性化地图 |\n| backgroundColor | UIColor | 空白地图背景色（since 6.5.4） |\n| backgroundImage | UIImage | 底图加载时背景网格（since 6.5.9，≤500KB） |\n\n### 显示范围与中心\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| region | BMKCoordinateRegion | 当前经纬度范围 |\n| limitMapRegion | BMKCoordinateRegion | 限制显示范围 |\n| centerCoordinate | CLLocationCoordinate2D | 中心点（改值不改变 zoomLevel） |\n| visibleMapRect | BMKMapRect | 当前可见范围（直角坐标） |\n\n### 比例尺与视角\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| zoomLevel | float | 比例尺级别，手机 4～21 |\n| minZoomLevel / maxZoomLevel | float | 自定义最小/最大级别 |\n| rotation | int | 旋转角度 -180～180 |\n| overlooking | int | 俯视角度 -45～0 |\n| minOverlooking | int | 俯视最小值 -79～0 |\n| fontSizeLevel | NSInteger | 字体大小 0～3（小/标准/大/特大，since 6.3.0） |\n\n### 控件与 UI\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| compassPosition | CGPoint | 指南针位置（以左上角为原点） |\n| compassSize | CGSize | 指南针宽高（只读） |\n| showMapScaleBar | BOOL | 是否显示比例尺 |\n| mapScaleBarPosition | CGPoint | 比例尺位置（以 BMKMapView 左上角为原点）；默认与 Logo 重叠，需手动设置使比例尺在 Logo 上方，见 [ui-standards.md](ui-standards.md) |\n| mapScaleBarSize | CGSize | 比例尺宽高（只读） |\n| mapScaleBarColor / mapScaleBarTextColor | UIColor | 比例尺颜色 |\n| logoPosition | BMKLogoPosition | Logo 位置 |\n\n### 图层与显示\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| buildingsEnabled | BOOL | 3D 楼块 |\n| showMapPoi | BOOL | 底图 POI 标注 |\n| trafficEnabled | BOOL | 路况图层 |\n| customTrafficColorEnabled | BOOL | 自定义路况颜色生效（since 6.6.3） |\n| baiduHeatMapEnabled | BOOL | 百度城市热力图（层级>11 可显示） |\n\n### 手势\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| gesturesEnabled | BOOL | 所有手势 |\n| doubleTapHoldPanEnabled | BOOL | 单指双击滑动缩放，默认 NO |\n| zoomEnabled | BOOL | 双指缩放 |\n| zoomEnabledWithTap | BOOL | 双击/双指单击缩放 |\n| scrollEnabled | BOOL | 移动地图 |\n| overlookEnabled | BOOL | 俯仰角 |\n| rotateEnabled | BOOL | 旋转 |\n| forceTouchEnabled | BOOL | 3D Touch 回调 |\n| gestureZoomAnimationEnabled | BOOL | 手势缩放动画（since 6.5.2） |\n\n**手势冲突（地图+ScrollView 共存）**：实现 `shouldRecognizeSimultaneouslyWithGestureRecognizer:` 返回 YES。ScrollView 配置见 [ui-standards.md](ui-standards.md)。\n\n**BMKMapGestureDelegate**：handleTapGesture、handlePanGesture、handleFlyingGesture、handleLongGesture、handleDoubleTapGesture、handleTwoFingersTapGesture、handleTwoFingersPanGesture、handleRotationGesture、handlePinchGesture；返回 YES 时地图不处理。用于与底部抽屉、侧滑菜单等共存。\n\n**BMKAnnotationView/BMKActionPaopaoView**：不推荐直接添加手势，会覆盖点击、长按；如必须添加，将手势 delegate 设到对应 View 并实现协调方法。\n\n### 其他\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| mapPadding | UIEdgeInsets | 地图预留边界；设置后 Logo、比例尺、指南针会避开该区域 |\n| updateTargetScreenPtWhenMapPaddingChanged | BOOL | mapPadding 改变时中心是否跟着变 |\n| ChangeWithTouchPointCenterEnabled | BOOL | 双指以手势中心/地图中心旋转缩放 |\n| ChangeCenterWithDoubleTouchPointEnabled | BOOL | 双击以双击位置/地图中心放大 |\n| supportBackgroundDraw | BOOL | 后台绘制（since 6.6.6，进出前后台时设置） |\n\n**mapPadding 与 fitVisibleMapRect edgePadding 区别**：mapPadding 影响指南针、Logo、比例尺位置，用于解决控件被 UI 遮挡；fitVisibleMapRect 的 edgePadding 用于路线视野适配（含 UI 边距和 marker 尺寸）。二者解决不同问题，详见 [ui-standards.md](ui-standards.md)。\n\n---\n\n## 类方法（创建前设置）\n\n| 方法 | 说明 |\n|------|------|\n| `+ setBaiduMapSDKMetalEnable:` | 是否用 Metal 绘制（V6.5.2，创建前有效） |\n| `+ getBaiduMapSDKMetalEnable` | 获取 Metal 开关（V6.6.3） |\n| `+ setBaiduMapSDKOverlayNewVersionEnable:` | 覆盖物新版逻辑（V6.5.9，启动期间仅一次） |\n| `+ getBaiduMapSDKOverlayNewVersionEnable` | 获取覆盖物新版开关（V6.6.3） |\n\n---\n\n## 实例方法\n\n### 生命周期（必须调用）\n\n| 方法 | 说明 |\n|------|------|\n| `viewWillAppear` | 即将显示时调用，恢复状态 |\n| `viewWillDisappear` | 即将隐藏时调用，存储状态 |\n\n### 地图控制\n\n| 方法 | 说明 |\n|------|------|\n| `setRegion:animated:` | 设定显示范围 |\n| `setCenterCoordinate:animated:` | 设定中心点 |\n| `setVisibleMapRect:animated:` | 设定可见范围（直角坐标） |\n| `setVisibleMapRect:edgePadding:animated:` | 设定范围并留边距 |\n| `fitVisibleMapRect:edgePadding:withAnimated:` | 适配 mapRect 到可见区域 |\n| `zoomIn` / `zoomOut` | 放大/缩小一级 |\n| `mapForceRefresh` | 强制刷新 |\n| `cleanCacheWithMapType:` | 清空缓存 |\n\n### 坐标转换\n\n| 方法 | 说明 |\n|------|------|\n| `convertCoordinate:toPointToView:` | 经纬度→View 坐标 |\n| `convertPoint:toCoordinateFromView:` | View 坐标→经纬度 |\n| `convertRegion:toRectToView:` | 经纬度区域→View 矩形 |\n| `convertRect:toRegionFromView:` | View 矩形→经纬度区域 |\n| `convertMapRect:toRectToView:` | BMKMapRect→View 矩形 |\n| `convertRect:toMapRectFromView:` | View 矩形→BMKMapRect |\n| `screenPointFromMapPoint3:` | 三维地理坐标→屏幕坐标（since 6.5.2） |\n| `glPointForMapPoint:` | BMKMapPoint→OpenGL 坐标 |\n| `glPointsForMapPoints:count:` | 批量 BMKMapPoint→OpenGL 坐标 |\n\n### 地图状态\n\n| 方法 | 说明 |\n|------|------|\n| `getMapStatus` | 获取地图状态 |\n| `setMapStatus:` | 设置地图状态 |\n| `setMapStatus:withAnimation:` | 设置并动画 |\n| `setMapStatus:withAnimation:withAnimationTime:` | 指定动画时长(ms) |\n| `getMapStatusFromCoordinateRegion:edgePadding:` | 根据区域和边距计算 BMKMapStatus |\n| `setMapCenterToScreenPt:` | 设置中心点屏幕坐标 |\n\n**设置状态并动画**：见上文「示例：设置地图状态（带动画、指定时长）」；不指定时长用 `setMapStatus:withAnimation:` 则使用 SDK 默认动画时长。\n\n### 截图与路况\n\n| 方法 | 说明 |\n|------|------|\n| `takeSnapshot` | 可视区域截图 |\n| `takeSnapshot:` | 指定区域截图 |\n| `setCompassImage:` | 设置罗盘图片 |\n| `setCustomTrafficColorForSmooth:slow:congestion:severeCongestion:` | 自定义路况颜色（4 种全设） |\n| `isSurpportBaiduHeatMap` | 当前区域是否支持百度热力图 |\n\n### OpenGL（3D 绘制）\n\n| 方法 | 说明 |\n|------|------|\n| `getProjectionMatrix` | 获取投影矩阵 |\n| `getViewMatrix` | 获取视图矩阵 |\n\n---\n\n## Category：CustomMapAPI\n\n| 方法 | 说明 |\n|------|------|\n| `setCustomMapStylePath:` | 个性化地图样式路径（创建后调用，V6.6.2 英文不支持） |\n| `setCustomMapStylePath:mode:` | mode 0 本地 1 在线 |\n| `setCustomMapStyleEnable:` | 个性化样式开关 |\n| `setCustomMapStyleWithOption:preLoad:success:failure:` | 在线个性化样式 |\n\n---\n\n## Category：IndoorMapAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| baseIndoorMapEnabled | 是否显示室内图 |\n| showIndoorMapPoi | 室内图标注 |\n| showDotPoi | 麻点 POI |\n| `switchBaseIndoorMapFloor:withID:` | 切换楼层 |\n| `getFocusedBaseIndoorMapInfo` | 当前聚焦室内图信息 |\n\n---\n\n## Category：LocationViewAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| showsUserLocation | 是否显示定位图层 |\n| userTrackingMode | 定位模式 |\n| userLocationVisible | 定位点是否在可视区域（只读） |\n| `updateLocationViewWithParam:` | 定制我的位置样式 |\n| `updateLocationData:` | 更新定位数据 |\n\n---\n\n## Category：AnnotationAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| annotations | 已添加标注数组（只读） |\n| isSelectedAnnotationViewFront | 选中标注是否置顶 |\n| `addAnnotation:` / `addAnnotations:` | 添加标注 |\n| `removeAnnotation:` / `removeAnnotations:` | 移除标注 |\n| `viewForAnnotation:` | 查找标注对应 View |\n| `dequeueReusableAnnotationViewWithIdentifier:` | 复用标注 View |\n| `selectAnnotation:animated:` / `deselectAnnotation:animated:` | 选中/取消选中 |\n| `showAnnotations:animated:` | 显示区域包含所有标注 |\n| `showAnnotations:padding:animated:` | 带边距（since 6.5.7） |\n| `annotationsInCoordinateBounds:` | 矩形区域内标注 |\n\n---\n\n## Category：OverlaysAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| overlays | 已添加 overlay 数组（只读） |\n| `addOverlay:` / `addOverlays:` | 添加 overlay |\n| `removeOverlay:` / `removeOverlays:` | 移除 overlay |\n| `insertOverlay:atIndex:` | 指定索引插入 |\n| `exchangeOverlayAtIndex:withOverlayAtIndex:` | 交换 |\n| `insertOverlay:aboveOverlay:` / `belowOverlay:` | 相对插入 |\n| `viewForOverlay:` | 查找 overlay 对应 View |\n\n---\n\n## Category：HeatMapAPI\n\n| 方法 | 说明 |\n|------|------|\n| `addHeatMap:` | 添加热力图 |\n| `updateHeatMap:` | 更新热力图（会重置动画） |\n| `removeHeatMap` | 移除热力图 |\n| `startHeatMapFrameAnimation` / `stopHeatMapFrameAnimation` | 开始/暂停动画 |\n| `setHeatMapFrameAnimationIndex:` | 控制帧索引 |\n\n---\n\n## Category：HexagonHeatMapAPI（since 6.6.0）\n\n| 属性/方法 | 说明 |\n|------|------|\n| showHexagonHeatMap | 是否显示蜂窝热力图 |\n| `addHexagonHeatMap:` | 添加 |\n| `removeHexagonHeatMap` | 删除 |\n\n---\n\n## Category：MapLayerAPI\n\n| 属性/方法 | 说明 |\n|------|------|\n| showOperateLayer | 运营图层（since 6.4.0） |\n| showOperatePOILayer | 运营 POI 图层（since 6.6.3） |\n| showTrafficUGCLayer | 路况事件图层（since 6.6.3） |\n| showDEMLayer | 地形图层（since 6.5.9） |\n| `switchLayerOrder:otherLayer:` | 交换图层顺序（since 6.5.9） |\n| `switchOverlayLayerAndNavigationLayer:` | overlay 与导航图层交换 |\n| `switchOverlayLayerAndPOILayer:` | overlay 与 POI 图层交换（addOverlay 后调用） |\n| `getPoiTagEnable:` / `setPoiTagEnable:poiTagType:` | 底图 POI 标签显示 |\n\n---\n\n## Category：ParticleEffect（since 6.5.7）\n\n| 方法 | 说明 |\n|------|------|\n| `showParticleEffect:` | 显示粒子效果 |\n| `closeParticleEffect:` | 关闭粒子效果 |\n| `customParticleEffect:option:` | 自定义粒子效果 |\n\n---\n\n## BMKBackgroundMapView（后台投屏视图）\n\n**BMKBackgroundMapView**（BMKBackgroundMapView.h）用于将**地图或导航画面**渲染到自定 View，可置于外接屏、投屏窗口或本机副区域，常用于**步骑行多实例后台投屏**：导航进行时把同一段导航同时投到另一块屏或小窗。\n\n### 三层内容与对应类\n\nBMKBackgroundMapView 支持三类内容，通过以下属性挂接：\n\n| 属性 | 类型 | 支持的内容 | 说明 |\n|------|------|-------------|------|\n| **mapview** | BMKMapView | 底图 | 关联源地图，同步数据；步骑行多实例时可设为 `[multiNaviView getNaviMapView]` |\n| **roadNetView** | BMKBackgroundRoadNetView | 路网、路况、路名 | 只读获取，用于自定义路网样式（见下） |\n| **navigationView** | BMKBackgroundNavigationView | 导航路线、小车、罗盘、起终点等 | 步骑行由 Manager 的 `getBackgroundNavigationView` 得到并赋值（见下） |\n\n渲染控制：设置完成后调用 **`startRender`**，退出或暂停时 **`stopRender`**，再 `removeFromSuperview`。完整步骑行投屏流程见 [navi.md](navi.md)「多实例后台投屏」。\n\n### BMKBackgroundNavigationView 支持的内容\n\n用于在投屏上绘制**导航相关**内容，步骑行场景下由 **BMKWalkNavigationManager** / **BMKCycleNavigationManager** 的 **`getBackgroundNavigationView`** 返回，引擎会驱动路线与位置更新，无需自行调用 `updateRouteInfo:` 等。\n\n| 能力 | 属性/方法 | 说明 |\n|------|-----------|------|\n| 路线 | routeColor, routePassedColor, routePassedDisplayMode（如 Grayed） | 未走/已走路线颜色与显示模式 |\n| 起终点与途径点 | needDrawStartPoint, needDrawEndPoint, needDrawViaPoint；startPointIcon, endPointIcon, viaPointIcon 等 | 是否绘制及图标 |\n| 导航车标与罗盘 | navigationIcon, needDrawCompass, needFllowPhoneHeading | 车头朝向、罗盘、随手机朝向 |\n| 引导线（偏航） | needDrawGuideLine, guideLineColor, guideLineWidth | 偏离路线时的引导线 |\n| 路名 | needDrawRouteName, routeNameFont, routeNameTextColor 等 | 路线上的路名绘制 |\n| 数据更新（非步骑行自管时） | updateRouteInfo:, updateRouteSegmentsInfo:, updateNaviLocationInfo: | 自管数据源时使用；步骑行由 Manager 提供实例则不需要 |\n\n### BMKBackgroundRoadNetView 支持的内容\n\n从 **`backgroundMapView.roadNetView`** 只读获取，用于在底图之上自定义**路网层**样式（不改变地图数据，仅表现）。\n\n| 能力 | 属性 | 说明 |\n|------|------|------|\n| 路网 | needDrawRoadNet, roadNetColor | 是否绘制路网、路网颜色 |\n| 路况 | needDrawRoadTraffic, roadTrafficColor | 是否绘制路况；需关联 mapview 的 trafficEnabled 为 YES；颜色数组 count 为 5（未知/畅通/缓行/拥挤/严重拥堵） |\n| 路名 | needDrawRoadName, roadNameFont, roadNameTextColor | 是否绘制路名及字体、颜色 |\n\n渲染由 BMKBackgroundMapView 的 startRender 统一驱动；roadNetView 的 **mapview** 需与 backgroundMapView 的 mapview 一致以同步数据。\n\n### BMKBackgroundMapView 自身属性与接口\n\n| 属性/方法 | 类型/说明 |\n|-----------|-----------|\n| **mapview** | BMKMapView，关联源地图 |\n| **navigationView** | BMKBackgroundNavigationView，步骑行时设为 Manager 的 `getBackgroundNavigationView` |\n| **roadNetView** | BMKBackgroundRoadNetView（只读），用于配置路网/路况/路名 |\n| **frameRate** | NSInteger，渲染帧率，默认 30，范围 10～60 |\n| **enable3D** | BOOL，默认 YES |\n| **showScaleBar** | BOOL，是否显示比例尺 |\n| **mapScreenExtOffset** | CGPoint，地图额外偏移（微调车标位置等） |\n| **startRender** / **stopRender** | 开始/停止渲染 |\n| **takeSnapshot:needLogo:** | 截屏 |\n\n---\n\n## BMKMapViewDelegate 回调\n\n### 生命周期与渲染\n\n| 回调 | 说明 |\n|------|------|\n| `mapViewWillBackground:` | 退到后台前 |\n| `mapViewDidForeground:` | 进入前台后 |\n| `mapViewDidFinishLoading:` | 地图初始化完毕 |\n| `mapViewDidRenderValidData:withError:` | 绘制出有效数据 |\n| `mapViewDidFinishRendering:` | 渲染完毕 |\n| `mapView:onDrawMapFrame:` | 每帧绘制、重绘时 |\n\n### 区域变化\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:regionWillChangeAnimated:` | 区域即将改变 |\n| `mapView:regionWillChangeAnimated:reason:` | 带原因（Gesture/Event/APIs） |\n| `mapView:regionDidChangeAnimated:` | 区域改变完成 |\n| `mapView:regionDidChangeAnimated:reason:` | 带原因 |\n\n### 标注\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:viewForAnnotation:` | 根据 annotation 生成 View（必须实现） |\n| `mapView:didAddAnnotationViews:` | 新添加 annotation views |\n| `mapView:clickAnnotationView:` | 点击 annotation view |\n| `mapView:didSelectAnnotationView:` | 选中 |\n| `mapView:didDeselectAnnotationView:` | 取消选中 |\n| `mapView:annotationView:didChangeDragState:fromOldState:` | 拖拽状态变化 |\n| `mapView:annotationViewForBubble:` | 点击气泡 |\n\n### 覆盖物\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:viewForOverlay:` | 根据 overlay 生成 View（必须实现） |\n| `mapView:didAddOverlayViews:` | 新添加 overlay views |\n| `mapView:onClickedBMKOverlayView:` | 点击覆盖物 |\n\n### 地图点击\n\n| 回调 | 说明 |\n|------|------|\n| `mapView:onClickedMapPoi:` | 点击底图标注 |\n| `mapView:onClickedMapBlank:` | 点击空白处 |\n| `mapview:onDoubleClick:` | 双击 |\n| `mapview:onLongClick:` | 长按 |\n| `mapview:onForceTouch:force:maximumPossibleForce:` | 3D Touch |\n\n### 其他\n\n| 回调 | 说明 |\n|------|------|\n| `mapStatusDidChanged:` | 地图状态改变完成 |\n| `mapview:baseIndoorMapWithIn:baseIndoorMapInfo:` | 进入/移出室内图 |\n| `mapView:didChangeUserTrackingMode:` | 定位模式切换 |\n| `mapViewOnClickCompass:` | 点击指南针 |\n\n---\n\n## 相关枚举与类型\n\n### BMKUserTrackingMode\n\n| 值 | 说明 |\n|------|------|\n| None | 普通定位 |\n| Heading | 定位方向 |\n| Follow | 定位跟随 |\n| FollowWithHeading | 定位罗盘 |\n\n### BMKLogoPosition\n\n左/中/右 × 上/下 共 6 种。\n\n### BMKRegionChangeReason\n\n| 值 | 说明 |\n|------|------|\n| Gesture | 手势 |\n| Event | 控件事件 |\n| APIs | 接口调用 |\n\n### BMKMapParticleEffect\n\n雪、雨、雾霾、沙尘暴、烟花、花瓣等。\n\n### BMKMapPoi\n\n底图点击返回：`text`、`pt`、`uid`、`trafficUGCType`。\n\n### BMKLayerType\n\nkBMKLayerSDKOverlay、kBMKLayerSDKHeatMap、kBMKLayerSDKHexagonHeatMap、kBMKLayerNewSDKDefaultOverlay。\n\nFile v1.0.1:references/navi.md\n\n# 导航\n\n**边界**：应用内步骑行实时导航（BaiduWalkNaviKit），与 BMKRouteSearch 算路画线为不同能力；多路线选路、诱导、TTS、偏航纠偏均属本能力。算路与画线见 [route.md](route.md)。\n\n---\n\n## 步骑行实时导航（BaiduWalkNaviKit）经验与注意事项\n\n### 基本原则\n\n1. **每次切换导航算路前必须销毁**：在发起新一轮算路（如再次点击「步行/骑行导航」或切换起终点）前，必须调用 **`[BMKWalkNavigationManager destroy]`** 与 **`[BMKCycleNavigationManager destroy]`**，再创建新 container 并 `initNaviEngine`、`routePlanWithParams`。否则上一次的引擎状态会干扰本次算路或导航，易出现无路线、回调错乱等问题。\n2. **Manager 与类型一致**：步行只用 `BMKWalkNavigationManager sharedManager`，骑行只用 `BMKCycleNavigationManager sharedManager`；LaunchParam 的 `naviType`（如 `BMK_WALK_CYCLE_NAVIGATION_TYPE_NORMAL_CYCLE`）与回调里的 `naviType` 判断一致，避免混用。\n3. **不在算路/导航进行中销毁**：仅在**新一轮算路开始前**调用 destroy；仅释放业务侧对「传给 initNaviEngine 的 container」的引用，且应在**启动导航之后**再置 nil（见下）。\n4. **多路线流程**：`enableMultiRoute = YES` 且设置 `routePlanDelegate`、`calcRouteDelegate` → `routePlanWithParams` → 多路线结果在 `onRoutePlanResult:naviType:` → 用 `getWalkNaviMulRouteInfos`/`getCycleNaviMulRouteInfos` 与 `displayRoutePlanResult:mapView` 在地图展示 → 用户选路线后调用 `naviCalcRoute:(routeIndex)` → 引擎算路完成后 `onNaviCalcRouteResult:naviType:` → 再 `startWalkNaviWithParentController`/`startCycleNaviWithParentController`。\n\n### 导航生命周期与 container\n\n- 传给 `initNaviEngine:` 的 **container（UIViewController）** 会被引擎用于地图/导航视图；若在回调里**过早**置 nil，引擎依赖的 controller 可能被释放，导致**进入导航无路线**。\n- **正确做法**：在 `onNaviCalcRouteResult` 中，**仅在算路失败时**置 nil container；**算路成功时**先调用 `startWalkNavi`/`startCycleNavi`，**在启动导航之后再**置 nil container（步行可紧接着置 nil；骑行建议在 `dispatch_async(main_queue)` 的 block 内先 `startCycleNavi` 再置 nil，并可保留 block 内对 container 的强引用以免提前释放）。\n\n示例（骑行，选路后进入导航）：\n\n```objc\n- (void)onNaviCalcRouteResult:(BMKWalkCycleRoutePlanErrorCode)errorCode naviType:(BMKWalkCycleNavigationType)naviType {\n    if (errorCode != BMK_WALK_CYCLE_ROUTEPLAN_RESULT_SUCCESS) {\n        _walkCycleNaviContainer = nil;\n        // 提示错误...\n        return;\n    }\n    if (naviType == BMK_WALK_CYCLE_NAVIGATION_TYPE_WALK) {\n        [[BMKWalkNavigationManager sharedManager] startWalkNaviWithParentController:self isPush:YES];\n        _walkCycleNaviContainer = nil;\n    } else if (naviType == BMK_WALK_CYCLE_NAVIGATION_TYPE_NORMAL_CYCLE || naviType == BMK_WALK_CYCLE_NAVIGATION_TYPE_ELECTRIC_CYCLE) {\n        __weak typeof(self) wself = self;\n        UIViewController *container = _walkCycleNaviContainer;\n        dispatch_async(dispatch_get_main_queue(), ^{\n            if (wself) [[BMKCycleNavigationManager sharedManager] startCycleNaviWithParentController:wself isPush:YES];\n            wself.walkCycleNaviContainer = nil;\n            (void)container;\n        });\n    }\n}\n```\n\n### 骑行多路线与展示\n\n- 骑行也支持多路线：`enableMultiRoute = YES`、`routePlanDelegate = self`，与步行一致；选路后对骑行调用 `[[BMKCycleNavigationManager sharedManager] naviCalcRoute:(NSInteger)index]`。\n- 骑行引擎建议用 `initNaviEngine:options:` 传入 `BMKWalkCycleNavigationOptions`（含 `displayOption`），并设置 `cycleNaviMode = BMK_CYCLE_NAVIGATION_MODE_NORMAL`；container 的 view 在 init 前可设 `frame = [UIScreen mainScreen].bounds` 以便路线正确布局。\n\n### 驾车与步骑行分工\n\n- **驾车**：可用 [utils.md](utils.md) 的 **BMKNavigation** `openBaiduMapNavigation:` 调起百度地图客户端。\n- **步骑行**：应用内导航用 BaiduWalkNaviKit 的 Walk/Cycle Manager，算路前需先拿到用户位置（如 BMKLocationManager 单次定位），再组 LaunchParam（startNode/endNode，type `BMKWalkNavigationRouteNodeLocation`）调用 `routePlanWithParams:`。\n\n---\n\n## 按需方案（导航相关）\n\n| 需求 | 能力组合 | 说明 |\n|------|----------|------|\n| 驾车调起导航 | BMKNavigation openBaiduMapNavigation: | 调起百度地图客户端，见 utils.md |\n| 步骑行多路线选路+应用内导航 | BaiduWalkNaviKit enableMultiRoute + routePlanDelegate + displayRoutePlanResult + naviCalcRoute | 多路线在地图展示折线，用户选路线后 naviCalcRoute(index)，onNaviCalcRouteResult 后再 start 导航；container 在启动导航后再置 nil |\n| 多实例后台投屏 | BMKBackgroundMapView + getBackgroundNavigationView | 步骑行导航画面投到外接屏/小窗：mapview、roadNetView、navigationView（由 Manager.getBackgroundNavigationView 获取），startRender/stopRender。详见 [mapview.md](mapview.md)「BMKBackgroundMapView」 |\n\nFile v1.0.1:references/overlays.md\n\n# 覆盖物 (Overlay)\n\n**边界**：addOverlay 体系；标注见 [annotations.md](annotations.md)，地图 API 见 [mapview.md](mapview.md)。**必须遵守**：点标注**优先使用 Marker**（本 addOverlay 体系），不得使用 BMKPointAnnotation/BMKPinAnnotationView，除非点聚合、固定屏选点等例外。见 [SKILL.md](../SKILL.md) 规则 3。\n\n## 路线与起终点：纹理优先（必须遵守）\n\n**绘制路线与起终点覆盖物时，须优先使用纹理，仅无可用纹理时再使用纯色或自绘。**\n\n- **路线折线**\n  - 单色/单纹理：`BMKPolyline` + `BMKPolylineView`。**优先**设置 `view.textureImage`（图片宽高须为 2 的 n 次幂），无纹理时再设 `view.strokeColor`。线宽 8pt，见 [ui-standards.md](ui-standards.md)。\n  - 路况分段：`BMKMultiPolyline` + `BMKMultiTexturePolylineView`，`textureImages` 使用 [assets](assets.md) 提供的 traffic_texture_* 等。\n- **起终点 Marker**\n  - `BMKIconMarker.icon` **须优先**使用 [assets](assets.md) 的 **icon_start**（起点）、**icon_end**（终点）；实现时先 `[UIImage imageNamed:@\"icon_start\"]` / `imageNamed:@\"icon_end\"`，为 nil 再回退到自绘或纯色。\n- **小车图标**：见 [SKILL.md](../SKILL.md) 规则 3「路线小车纹理」及 [assets](assets.md)。\n\n生成或修改覆盖物相关代码时，**必须先检查并应用上述纹理优先**，避免仅写 strokeColor/自绘导致规范未生效。\n\n## 使用须知\n- **Delegate**：addOverlay 前必须设置 `mapView.delegate`，并实现 `mapView:viewForOverlay:`。\n- **批量添加**：`addOverlays:` 可一次添加多个 overlay。\n- **起终点推荐 BMKIconMarker**：添加顺序为路线→起终点→小车。起终点 icon 须优先使用 [assets](assets.md) 的 icon_start/icon_end；小车图标须优先使用技能 [assets](assets.md) 纹理（icon_car 等），无则再颜色/自绘。样式见 [ui-standards.md](ui-standards.md)。\n- **步骑行多路线折线**：BaiduWalkNaviKit 的 `displayRoutePlanResult:mapView` 返回 `NSArray<BMKPolyline *>`；若由业务侧 addOverlay，需在 `mapView:viewForOverlay:` 中对 `BMKPolyline` 返回 `BMKPolylineView`（如 textureImage 或 strokeColor、lineWidth），否则路线不显示。\n\n## 示例：添加折线（Overlay，addOverlay）\n\n需实现 `mapView:viewForOverlay:`，根据 overlay 类型返回对应 View。\n\n```objc\nCLLocationCoordinate2D coords[2] = {\n    CLLocationCoordinate2DMake(39.915, 116.404),\n    CLLocationCoordinate2DMake(39.920, 116.410)\n};\nBMKPolyline *polyline = [BMKPolyline polylineWithCoordinates:coords count:2];\n[mapView addOverlay:polyline];\n\n#pragma mark - BMKMapViewDelegate\n- (BMKOverlayView *)mapView:(BMKMapView *)mapView viewForOverlay:(id<BMKOverlay>)overlay {\n    if ([overlay isKindOfClass:[BMKPolyline class]]) {\n        BMKPolylineView *view = [[BMKPolylineView alloc] initWithOverlay:overlay];\n        // 纹理优先：有纹理图时设置 textureImage（宽高须 2 的 n 次幂），无则 strokeColor\n        UIImage *tex = [UIImage imageNamed:@\"route_texture\"];  // 示例；可用 assets 或自备\n        if (tex) view.textureImage = tex;\n        else view.strokeColor = [UIColor blueColor];\n        view.lineWidth = 8.0f;  // 路线线宽 8pt，见 ui-standards\n        return view;\n    }\n    return nil;\n}\n```\n\n## 示例：添加图标 Marker（Overlay，addOverlay）\n\n点标注推荐用 BMKIconMarker（addOverlay），与地图坐标系一致；anchor 沿路线居中时设 0.5/0.5。\n\n```objc\nBMKIconMarker *marker = [[BMKIconMarker alloc] init];\nmarker.coordinate = CLLocationCoordinate2DMake(39.915, 116.404);\n// 起终点纹理优先：起点用 icon_start，终点用 icon_end，无则回退自绘/纯色\nmarker.icon = [UIImage imageNamed:@\"icon_start\"];  // 或 icon_end / icon_pin\nif (!marker.icon) marker.icon = [self drawDefaultPinImage];  // 回退\nmarker.anchorX = 0.5;  // 沿路线居中时 0.5/0.5，否则默认 anchorY=1 坐标在底部中心\nmarker.anchorY = 0.5;\n[mapView addOverlay:marker];\n\n#pragma mark - BMKMapViewDelegate\n- (BMKOverlayView *)mapView:(BMKMapView *)mapView viewForOverlay:(id<BMKOverlay>)overlay {\n    if ([overlay isKindOfClass:[BMKIconMarker class]]) {\n        BMKIconMarkerView *view = [[BMKIconMarkerView alloc] initWithOverlay:overlay];\n        view.isClickable = YES;  // 点击触发 mapView:onClickedBMKOverlayView:\n        return view;\n    }\n    return nil;\n}\n```\n\n## 常用默认值（易导致不生效或与预期不符）\n\n以下为地图/覆盖物相关类常见默认值，未显式设置时可能造成行为差异，建议按需显式赋值。\n\n| 类/接口 | 属性/方法 | 默认值 | 说明 |\n|---------|-----------|--------|------|\n| BMKMapTrackAnimation | setTrackPosRadio | **0.0 ~ 0.0**（无有效范围） | 轨迹动画**必须**显式调用 `setTrackPosRadio:0.0 to:1.0`，否则无有效播放范围 |\n| BMKMapTrackAnimation / BMKMapAnimationSet | start | **不自动 start** | 需手动调用 `start`；其他动画类型默认自动 start |\n| BMKIconMarker | anchorX / anchorY | **0.5 / 1.0** | 坐标在图标底部中心；沿路线居中时设 0.5/0.5 |\n| BMKMultiColorPolylineView | lineCapType | **kBMKLineCapButt** | 不支持虚线；kBMKLineCapRound 支持虚线 |\n| BMKMapView | setMapStatus:withAnimation: | 动画时长为 SDK 默认 | 需指定时长时用 `setMapStatus:withAnimation:withAnimationTime:`（单位 ms） |\n| 定位 SDK（BMKLocationManager） | coordinateType | **BMKLocationCoordinateTypeGCJ02** | 与地图（BD09）混用时须设为 BMK09LL 或做转换，见 [location.md](location.md) |\n\n## 覆盖物\n\n### 基础覆盖物\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKOverlay | BMKOverlay.h | 覆盖物协议 |\n| BMKOverlayView | BMKOverlayView.h | 覆盖物视图基类 |\n| BMKPolyline | BMKPolyline.h | 单色/单纹理折线 |\n| BMKPolylineView | BMKPolylineView.h | 折线视图，支持 textureImage、lineDashType |\n| BMKMultiPolyline | BMKMultiPolyline.h | 分段折线，需 drawIndexs |\n| BMKMultiColorPolylineView | BMKMultiPolylineView.h | 分段颜色 |\n| BMKMultiTexturePolylineView | BMKMultiPolylineView.h | 分段纹理（路况） |\n| BMKCircle | BMKCircle.h | 圆形 |\n| BMKCircleView | BMKCircleView.h | 圆形视图 |\n| BMKPolygon | BMKPolygon.h | 多边形 |\n| BMKPolygonView | BMKPolygonView.h | 多边形视图 |\n| BMKGroundOverlay | BMKGroundOverlay.h | 图片图层 |\n| BMKGroundOverlayView | BMKGroundOverlayView.h | 图片图层视图 |\n\n**折线**：`BMKPolyline polylineWithCoordinates:count:`。`BMKPolylineView.textureImage` 要求图片宽高为 2 的 n 次幂。**路线线宽**标准 **8pt**，见 [ui-standards.md](ui-standards.md)。`lineDashType`：`kBMKLineDashTypeDot`（圆点虚线）、`kBMKLineDashTypeSquare` 等。\n\n**分段折线**：`BMKMultiPolyline multiPolylineWithCoordinates:count:drawIndexs:`，drawIndexs 为 NSNumber 数组，对应 strokeColors 或 textureImages 索引。`BMKMultiColorPolylineView.lineCapType` 默认 `kBMKLineCapButt`（不支持虚线），`kBMKLineCapRound` 支持。`BMKMultiTexturePolylineView.lineJoinType`：`kBMKLineJoinRound`/`Bevel`/`Miter`。\n\n**镂空**：BMKCircle、BMKPolygon 支持 `hollowShapes`，可传入 BMKCircle、BMKPolygon 数组实现镂空。\n\n**圆形**：`BMKCircle circleWithCenterCoordinate:radius:`，radius 单位米。BMKCircleView 设置 `fillColor`、`strokeColor`、`lineWidth`。\n\n**多边形**：`BMKPolygon polygonWithCoordinates:count:`。BMKPolygonView 支持 `lineDashType`。\n\n**图片图层**：`BMKGroundOverlay groundOverlayWithBounds:icon:`（BMKCoordinateBounds：southWest、northEast）；或 `groundOverlayWithPosition:zoomLevel:anchor:icon:`。`alpha` 控制透明度 [0, 1]。\n\n### 曲线与渐变\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKArcline | BMKArcline.h | 圆弧（3 点确定） |\n| BMKArclineView | BMKArclineView.h | 圆弧视图 |\n| BMKGradientLine | BMKGradientLine.h | 渐变线 |\n| BMKGradientLineView | BMKGradientLineView.h | 渐变线视图 |\n| BMKGradientCircleView | BMKGradientCircleView.h | 渐变圆（BMKCircle + 渐变） |\n| BMKGeodesicLine | BMKGeodesicLine.h | 大地线（球面最短路径） |\n| BMKGeodesicLineView | BMKGeodesicLineView.h | 大地线视图 |\n\n**圆弧**：`BMKArcline arclineWithCoordinates:` 需传入 3 个点。\n\n**渐变线**：`BMKGradientLine gradientLineWithCoordinates:count:drawIndexs:`，用法类似 BMKMultiPolyline。BMKGradientLineView 设置 `strokeColors`、`lineWidth`。\n\n**渐变圆**：BMKGradientCircleView 用 `initWithOverlay:` 传入 BMKCircle。`radiusWeight`、`colorWeight` 控制渐变规则；`centerColor`、`sideColor` 为渐变起止色。\n\n**大地线**：`BMKGeodesicLine geodesicLineWithCoordinates:count:`。经度跨 180° 时须设置 `lineDirectionCross180`（如 `kBMKLineDirectionCross180TypeWEST_TO_EAST`）。**沿大地线模拟移动**：用球面线性插值 slerp 从 origin 到 dest，`coord = slerp(origin, dest, progress)`；`BMKGetDirectionFromCoords(current, slerp(origin,dest, progress+0.02))` 得切线方向。往返飞行：`routeDirection` 1 或 -1 切换，回程 `coord = slerp(dest, origin, 1-progress)`。slerp 公式见 [utils.md](utils.md)。\n\n### Marker 类（addOverlay）\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKIconMarker | BMKIconMarker.h | 图标 Marker |\n| BMKIconMarkerView | BMKIconMarkerView.h | 图标 Marker 视图 |\n| BMKTextMarker | BMKTextMarker.h | 文本 Marker |\n| BMKTextMarkerView | BMKTextMarkerView.h | 文本 Marker 视图 |\n| BMKTextPathMarker | BMKTextPathMarker.h | 沿路径文字 |\n| BMKTextPathMarkerView | BMKTextPathMarkerView.h | 沿路径文字视图 |\n\n**BMKIconMarker**：`icon` 单图，`icons` 图片组（按间隔轮播）。`scaleX`/`scaleY`、`anchorX`/`anchorY`（默认 0.5/1.0）。**沿路线居中**：设置 `anchorX = 0.5`、`anchorY = 0.5`，否则默认 anchorY=1 使坐标在图标底部中心，圆心会偏上。`addRichView:` 挂接 BMKRichView（BMKImageUIView、BMKLabelUIView、BMKVerticalLayout、BMKHorizontalLayout），RichView 无坐标，必须挂到 marker 上。\n\n**BMKIconMarker 旋转**：`marker.rotateFeature = BMKRotateItem | BMKRotateGeoNorth`（地理北为基准，与 BMKGetDirectionFromCoords 一致）。基准图标建议机头朝上，`marker.rotate = heading`；若方向相反可试 `rotate = -heading` 或 `heading ± 90`。沿大地线移动时用「当前点→路径稍前点」算切线：`BMKGetDirectionFromCoords(current, slerpCoord(origin,dest, progress+0.02))`。\n\n**BMKRichView 示例**：BMKLabelUIView + BMKTextStyle + BMKVerticalLayout，`richView.locate = BMKLocateBottom`、`offsetY` 控制位置。`rootView = layout`，`[marker addRichView:richView]`。\n\n**碰撞检测**：`marker.collisionBehavior = BMKCollisionWithInner | BMKCollisionHideByPriority`，`collisionPriority` 越大越不易被遮挡。RichView 同理。**注意**：动画中暂不支持，定时器驱动的位置更新可生效。\n\n**BMKTextMarker**：`text`、`style`（BMKTextStyle：fontSize、fontOption、borderWidth、textColor、borderColor）。\n\n**BMKTextPathMarker**（路线路名沿路径绘制）：用 `textPathMarkerWithPoints:count:` 或 `textPathMarkerWithCoordinates:count:` 传入路径点（如 BMKDrivingStep 的 points/count），再设 `text`（路名）、`style`（BMKTextStyle，如 22pt 黑字白边见 [ui-standards.md](ui-standards.md)）。View 为 **BMKTextPathMarkerView**，`initWithMarker:` 传入 marker。路线规划时每段 step 若有 `roadName` 可创建一条 BMKTextPathMarker 沿该 step 的 points 绘制，路名随路径走向展示。\n\n**动画**：BMKMapScaleAnimation、BMKMapRotateAnimation、BMKMapAlphaAnimation、BMKMapAnimationSet。BMKMapTrackAnimation、BMKMapAnimationSet 默认不自动 start，其他动画默认自动 start。`addAnimation:addAnimationSetOrderType:` 支持 `BMKAnimationSetOrderTypeWith`（并行）、`BMKAnimationSetOrderTypeThen`（串行）。\n\n**轨迹动画（BMKMapTrackAnimation）**：polyline 与 BMKIconMarker **必须共用同一 trackAnim**，否则小车不显示；只 `start` 一次。路线推荐 BMKMultiPolyline + BMKMultiTexturePolylineView；Forward=未走过（原色），Backward=已走过（灰度）。**走过置灰**（BMKGeometryView）：`strokeColorProgressForward`=原色（未走过）、`strokeColorProgressBackward`=灰色（已走过）；模拟导航同此。轨迹回放相反。驾车路况：drawIndexs 来自 traffics，textureImages 5 种（0 无数据/1 畅通/2 缓行/3 拥堵/4 严重拥堵），见 [assets.md](assets.md)。停止仅 `cancel`，勿解绑 overlay.animation。\n\n**动画不显示时排查**（不建议用 CADisplayLink 等手动方案替代）：\n\n| 检查项 | 说明 |\n|--------|------|\n| 共用同一实例 | `polyline.animation` 与 `marker.animation` 必须指向**同一个** BMKMapTrackAnimation |\n| setTrackLine | 调用 `[trackAnim setTrackLine:polyline]`；部分场景需**先 addOverlay:polyline 再 setTrackLine** |\n| setTrackPosRadio | **必须**调用 `[trackAnim setTrackPosRadio:0.0 to:1.0]`，默认 0~0 无有效范围 |\n| 添加顺序 | 先 `addOverlay:polyline`，再 `addOverlay:marker` |\n| trackBy | marker 设置 `trackBy = BMKAnimationTrackXY`；可加 `BMKAnimationTrackForward` 尝试使机头沿线段前进方向旋转（效果因场景而异，若方向仍不对改用 BMKRotateItem 手动计算 heading） |\n| 只 start 一次 | 对所有 trackAnim 只调用一次 `start`；可 `dispatch_async` 到下一 RunLoop |\n| polyline.isThined | 设为 NO，避免抽稀导致轨迹点丢失 |\n| 参考 Demo | 对照官方 `BMKPolylineMarkerTeackAnimationPage.mm` |\n\n**点击**：`BMKIconMarkerView`/`BMKTextMarkerView.isClickable = YES` 后，点击触发 `mapView:onClickedBMKOverlayView:`。\n\n### 文本与海量点\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKText | BMKText.h | 文本 overlay（中心+文字） |\n| BMKTextView | BMKTextView.h | 文本 overlay 视图 |\n| BMKMultiPointOverlay | BMKMultiPointOverlay.h | 海量点 |\n| BMKMultiPointOverlayView | BMKMultiPointOverlayView.h | 海量点视图 |\n| BMKMultiPointItem | BMKMultiPointOverlay.h | 海量点数据项 |\n\n**BMKText**：`textWithCenterCoordinate:text:`。BMKTextView 设置 `textColor`、`backgroundColor`、`fontSize`、`textFontType`、`textAlignment`、`textMaxLineWidth`、`textLineSpacing`、`textParagraphSpacing`、`textLineBreakMode`。点击回调 `mapView:onClickedBMKOverlayView:`。\n\n**海量点**：`BMKMultiPointOverlay multiPointOverlayWithMultiPointItems:`。BMKMultiPointOverlayView 设置 `icon`、`anchor`、`pointSize`、`delegate`。BMKMultiPointOverlayViewDelegate 的 `didItemTapped:` 处理点击。\n\n### 点聚合（SDK 未内置，参考 BMKPointCluster Demo）\n\n将大量 BMKPointAnnotation 按地理距离聚合，zoom 小时显示聚合点（带数量），zoom 大时拆分为单点。**核心类**：BMKClusterManager、BMKClusterQuadtree、BMKQuadItem、BMKCluster。**流程**：坐标→BMKQuadItem 加入 quadtree；`getClusters:zoomLevel` 按 zoom 获取聚合；`clusterCaches[zoom-3]` 缓存；`mapViewDidFinishLoading` 与 `onDrawMapFrame`（zoom 变化时）触发 updateClusters。**标注展示**见 [annotations.md](annotations.md)。\n\n### 3D 与轨迹\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMK3DModelOverlay | BMK3DModelOverlay.h | 3D 模型 |\n| BMK3DModelOverlayView | BMK3DModelOverlayView.h | 3D 模型视图 |\n| BMKPrismOverlay | BMKPrismOverlay.h | 棱柱/3D 建筑 |\n| BMKPrismOverlayView | BMKPrismOverlayView.h | 棱柱视图 |\n| BMKTraceOverlay | BMKTraceOverlay.h | 路书轨迹（发光、渐变色） |\n| BMKTraceOverlayView | BMKTraceOverlayView.h | 路书轨迹视图 |\n| BMK3DTraceOverlay | BMK3DTraceOverlay.h | 3D 轨迹 |\n| BMK3DTraceOverlayView | BMK3DTraceOverlayView.h | 3D 轨迹视图 |\n\n**3D 模型**：`BMK3DModelOverlay modelOverlayWithCenterCoordinate:option:`。BMK3DModelOption：`modelName`、`modelPath`、`scale`、`type`（BMK3DModelTypeGLTF）、`zoomFixed`、`rotateX`、`animationIsEnable`、`animationIndex`、`animationSpeed`、`animationRepeatCount`。3D 展示标准见 [ui-standards.md](ui-standards.md)。\n\n**棱柱**：`BMKPrismOverlay prismOverlayWithPoints:count:` 传入 BMKMapPoint 数组，`height` 设高度。BMKPrismOverlayView 设置 `sideFaceColor`、`topFaceColor`。可用 BMKDistrictSearch 获取区域边界转 BMKMapPoint。\n\n**3D 轨迹**：`BMK3DTraceOverlay traceOverlay3DWithCoordinates:count:option:`。BMK3DTraceOverlayOption：`traceType`、`duration`、`easingCurve`、`opacity`、`paletteOpacity`、`paletteImage`、`projectionPaletteImage`。BMK3DTraceOverlayView 的 `strokeHeights` 长度须与轨迹点数一致。BMK3DTraceOverlayAnimationDelegate 监听动画开始、进度、结束、实时位置。\n\n**BMKTraceOverlay**：`traceOverlayWithCoordinates:count:option:`。Option：`animate=YES`、`trackMove=YES`、`isRotateWhenTrack=YES`、`pointMove=YES`。**pointImage 箭头尖端须朝右**，SDK 旋转后指向行进方向；建议 80×80。BMKTraceOverlayView 设置 `strokeColors`、`strokeColor`、`fillColor`。\n\n**BMKMapTrackAnimation 图标**：polyline 与 BMKIconMarker 共用同一 trackAnim。marker 设置 `anchorX=0.5`、`anchorY=0.5`。**优先使用图片资源**（如 [assets.md](assets.md) 的 track_car 等），不合适时再自绘。旋转以图像**右侧**为行进方向。自绘时：40×40 画布，箭头尖端朝右；UIBezierPath 尖端在 `CGRectGetMaxX(rect) - w*0.05`，底座在左，`baseX + w*0.25` 为左侧凹进形成箭尾。\n\n### 热力图（addHeatMap，非 overlay）\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKHeatMap | BMKHeatMap.h | 热力图 |\n| BMKHexagonHeatMap | BMKHexagonHeatMap.h | 六边形热力图 |\n\n**BMKHeatMap**：`mDatas` 为 BMKHeatMapNode 二维数组（支持帧动画），`mMaxHight`、`mGradient`（BMKGradient）、`animation`、`frameAnimation`、`delegate`。`addHeatMap`/`removeHeatMap`。`startHeatMapFrameAnimation`/`stopHeatMapFrameAnimation`/`setHeatMapFrameAnimationIndex:`。\n\n**BMKHexagonHeatMap**：`mData`、`mRadius`、`mOpacity`、`mMaxIntensity`、`mGap`、`mHexagonType`（BMKHexagonTypeVertexUp）、`mGradient`。`addHexagonHeatMap`/`removeHexagonHeatMap`。\n\n### 自定义 Overlay\n\n继承 BMKShape，实现 `boundingMapRect`（用 BMKMapRect 包住所有点）。CustomOverlayView 继承 BMKOverlayView，重载 `glRender`。坐标用 `BMKMapPointForCoordinate` 转换。绘制：`renderLinesWithPoints:pointCount:strokeColor:lineWidth:looped:lineDashType:`、`renderRegionWithPoints:pointCount:fillColor:usingTriangleFan:`、`loadStrokeTextureImage:` + `renderTexturedLinesWithPoints:...`。纹理图片宽高须为 2 的 n 次幂。\n\n## 坐标与结构体\n\n| 类型 | 说明 |\n|------|------|\n| CLLocationCoordinate2D | 经纬度（BD09） |\n| BMKMapRect | 直角地理坐标矩形 |\n| BMKMapPoint | 直角地理坐标点 |\n| BMKCoordinateRegion | 经纬度区域 |\n| BMKCoordinateBounds | 经纬度边界（southWest、northEast） |\n\n**坐标转换**（BMKGeometry.h）：`BMKMapPointForCoordinate`、`BMKCoordinateForMapPoint`。自定义 overlay 用 BMKMapPoint 计算 boundingMapRect。\n\n---\n\n## 按需方案\n\n| 需求 | 基础能力 |\n|------|----------|\n| 起终点标记（推荐） | BMKIconMarker + addOverlay 顺序 |\n| 起终点大头针 | BMKPointAnnotation + BMKAnnotationView，见 [annotations.md](annotations.md) |\n| 单色路线 | BMKPolyline + BMKPolylineView，lineWidth 8pt（见 ui-standards） |\n| 路况路线 | BMKMultiPolyline + BMKMultiTexturePolylineView，lineWidth 8pt（见 ui-standards） |\n| 路线路名 | BMKTextPathMarker + BMKTextPathMarkerView（沿 step 路径绘制 roadName） |\n| 路线动画 | BMKMapTrackAnimation + BMKPolyline/MultiPolyline + BMKIconMarker（共用 trackAnim） |\n| 圆弧 | BMKArcline + BMKArclineView |\n| 渐变线 | BMKGradientLine + BMKGradientLineView |\n| 渐变圆 | BMKCircle + BMKGradientCircleView |\n| 大地线 | BMKGeodesicLine + BMKGeodesicLineView |\n| 图标按行进方向旋转 | BMKRotateItem \\| BMKRotateGeoNorth + rotate |\n| 航班/信息标签 | BMKRichView + BMKLabelUIView + BMKVerticalLayout |\n| 重叠时隐藏 | collisionBehavior + collisionPriority |\n| 沿大地线移动/往返 | slerp + BMKGetDirectionFromCoords + routeDirection |\n| 文本 overlay | BMKText + BMKTextView |\n| 海量点 | BMKMultiPointOverlay + BMKMultiPointItem |\n| 点聚合（海量标注） | BMKClusterManager + BMKClusterQuadtree + BMKPointAnnotation |\n| 3D 模型 | BMK3DModelOverlay + BMK3DModelOption |\n| 棱柱/建筑 | BMKPrismOverlay + BMKPrismOverlayView |\n| 路书轨迹 | BMKTraceOverlay + BMKTraceOverlayOption |\n| 3D 轨迹 | BMK3DTraceOverlay + BMK3DTraceOverlayOption |\n| 热力图 | BMKHeatMap + addHeatMap |\n| 六边形热力图 | BMKHexagonHeatMap + addHexagonHeatMap |\n\nFile v1.0.1:references/project-config.md\n\n# 工程配置\n\n**边界**：Info.plist、隐私弹窗、Launch Screen、CocoaPods 沙盒等百度 SDK 工程配置；Pod 集成见 [cocoapods.md](cocoapods.md)。\n\n**Agent 注意**：集成地图/定位 SDK 时，必须检查或配置 Launch Screen（见下「窗口初始化/Launch Screen」），避免运行后 App 非全屏、黑边；并主动提示开发者配置 AK 与 Bundle Identifier（与百度控制台一致）。\n\n## Info.plist 必配项\n\n**CFBundleExecutable**（使用自定义 Info.plist 且 `GENERATE_INFOPLIST_FILE = NO` 时必配）：指定主可执行文件名，未配置会导致真机安装失败，报错「missing or invalid CFBundleExecutable」「无法安装」「请稍后再试」（Code 3002 / MIInstallerErrorDomain 11）。须在 plist 中显式添加：\n\n```xml\n<key>CFBundleExecutable</key>\n<string>$(EXECUTABLE_NAME)</string>\n```\n\n编译时 Xcode 会将 `$(EXECUTABLE_NAME)` 展开为 target 的主可执行文件名（通常与 Product Name 一致）。\n\n**CFBundleDisplayName**：SDK 启动时校验，未配置会报错「启动引擎失败: info.plist 中必须配置 Bundle display name」。\n\n```xml\n<key>CFBundleDisplayName</key>\n<string>你的应用名称</string>\n```\n\n**定位权限**（使用定位时）：\n```xml\n<key>NSLocationWhenInUseUsageDescription</key>\n<string>需要获取您的位置以展示地图</string>\n```\n\n**调起百度地图客户端**（驾车/步行/骑行调起百度地图 App 时）：\n1. 必须在 Info.plist 中配置 **LSApplicationQueriesSchemes**（baidumap），否则无法调起百度地图 App。\n2. **指定返回自定义 scheme**：`appScheme` 按 **`scheme://host`** 格式填写（如 `yourapp://mapsdk.yourapp.com`）。scheme 名（`://` 前部分）须与 Info.plist 中 **CFBundleURLSchemes** 注册的一致，这样用户在百度地图内点击「返回」时才能通过该 URL 打开本 App。\n\nLSApplicationQueriesSchemes：\n```xml\n<key>LSApplicationQueriesSchemes</key>\n<array>\n    <string>baidumap</string>\n</array>\n```\n\n返回本 App 的 URL Scheme 注册（CFBundleURLSchemes 填 appScheme 的 scheme 部分，与格式 scheme://host 中的 scheme 一致）：\n```xml\n<key>CFBundleURLTypes</key>\n<array>\n    <dict>\n        <key>CFBundleTypeRole</key>\n        <string>Editor</string>\n        <key>CFBundleURLName</key>\n        <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>\n        <key>CFBundleURLSchemes</key>\n        <array>\n            <string>foodsearchdemo</string>\n        </array>\n    </dict>\n</array>\n```\n示例：若 `para.appScheme = @\"foodsearchdemo://mapsdk.foodsearchdemo.com\"`，则此处填 `foodsearchdemo`。\n\n**步行 AR 导航**（使用 BaiduWalkNaviKit 且进入 AR 导航时）：必须配置相机用途说明，否则访问摄像头会**直接崩溃**。\n```xml\n<key>NSCameraUsageDescription</key>\n<string>步行AR导航需要使用摄像头识别周围环境，为您提供实景导航指引</string>\n```\n\n## 隐私协议弹窗（必做）\n\n**首次使用前必须弹窗提示用户阅读并同意隐私政策**，再调用 `[BMKMapManager setAgreePrivacy:YES]`。未同意时调用 `[BMKMapManager setAgreePrivacy:NO]`。\n\n**注意**：`setAgreePrivacy:` 是 **BMKMapManager 的类方法**，必须写 `[BMKMapManager setAgreePrivacy:YES]`，**勿写** `[[BMKMapManager sharedInstance] setAgreePrivacy:YES]`（会报 \"Instance method '-setAgreePrivacy:' not found\"）。\n\n**隐私政策地址**：https://lbsyun.baidu.com/index.php?title=openprivacy（弹窗内需可点击跳转）。\n\nUI 标准见 [ui-standards.md](ui-standards.md)。**不同意时**：`setAgreePrivacy:NO`，BMKSearchBase 及其子类会返回 nil；需延迟创建检索对象，仅在用户同意后创建；未同意时使用检索前提示用户去同意。\n\n## CocoaPods 构建沙盒（Xcode 15+）\n\nCocoaPods 的 Copy Pods Resources 脚本需在 `Pods` 目录创建临时文件（如 `resources-to-copy-${TARGETNAME}.txt`）。Xcode 15 起默认开启 **User Script Sandboxing**，会阻止该写入，导致构建报错：\n\n```\nSandbox: bash deny(1) file-write-create .../Pods/resources-to-copy-xxx.txt\n```\n\n**解决**：在 target 的 Build Settings 中设置 `ENABLE_USER_SCRIPT_SANDBOXING = NO`。\n\n- **Xcode 图形界面**：选中 target → Build Settings → 搜索 \"User Script Sandboxing\" → 设为 **No**\n- **project.pbxproj**：在 target 的 XCBuildConfiguration（Debug/Release）的 buildSettings 中添加：\n  ```\n  ENABLE_USER_SCRIPT_SANDBOXING = NO;\n  ```\n\n## 窗口初始化/Launch Screen\n\n**现象**：地图未铺满屏幕、上下或左右出现黑边，地图只显示在中间一块区域。\n\n**原因**：未配置 Launch Screen 时，系统会按「未声明支持当前设备屏幕」处理，窗口或根视图的尺寸/安全区域可能异常，导致 `view.bounds` 不是全屏，地图即使用 `view.bounds` 设 frame 也会出现黑边。\n\n**必配**：工程需有 Launch Screen（LaunchScreen.storyboard 或同类），并在 Info.plist 中配置：\n\n```xml\n<key>UILaunchStoryboardName</key>\n<string>LaunchScreen</string>\n```\n\nLaunchScreen.storyboard 需设置 `launchScreen=\"YES\"`、`useSafeAreas=\"YES\"`，支持各尺寸 iPhone（含刘海屏）。内容可为白底 + 应用名等静态界面。\n\n**地图不全屏排查顺序**（Agent 必须遵守）：\n1. **先检查 Launch Screen**：是否有 LaunchScreen.storyboard（或 Launch Image）、Info.plist 是否含 `UILaunchStoryboardName`；缺则补上并加入 target Resources。\n2. **再检查布局**：地图视图的 frame 是否在 `viewDidLayoutSubviews` 中设为 `self.view.bounds`（避免在 viewDidLoad/首次创建时 bounds 未稳定导致尺寸错误）。\n\nFile v1.0.1:references/reference.md\n\n# 百度地图 iOS SDK 参考索引\n\n按需选下表文档；通用规则（隐私、坐标系、版本以本地为准）见 [SKILL.md](../SKILL.md)。\n\n## 按需求选文档\n\n| 你要做的 | 用到的文档 |\n|----------|------------|\n| 集成 Pod、选地图/定位/步骑行/导航套件 | [cocoapods.md](cocoapods.md) |\n| Info.plist、隐私弹窗、Launch Screen、构建沙盒 | [project-config.md](project-config.md) |\n| 单次/连续/后台/室内定位、地理围栏、鉴权失败 | [location.md](location.md) |\n| 地图视图、属性、生命周期、全屏 | [mapview.md](mapview.md) |\n| 点标注、固定屏、点聚合展示 | [annotations.md](annotations.md) |\n| 覆盖物、热力、点聚合逻辑、轨迹、Marker/RichView | [overlays.md](overlays.md) |\n| 检索/路线/选点/弹窗/视野/Logo 等 UI 规范 | [ui-standards.md](ui-standards.md) |\n| Sug、地理编码、逆地理、POI、公交 | [search.md](search.md) |\n| 驾车/步行/骑行/公交**算路与画线**（BMKRouteSearch，仅算路+画线） | [route.md](route.md) |\n| **步骑行实时导航**（BaiduWalkNaviKit，诱导、TTS、偏航纠偏、多实例） | [navi.md](navi.md) |\n| 坐标转换、几何、视野适配、调起地图 | [utils.md](utils.md) |\n| 图片资源路径与命名 | [assets.md](assets.md) |\n| 类与头文件速查 | [class-index.md](class-index.md) |\n\n**步骑行**：算路画线（route）与实时导航（navi）为**不同服务**——仅画线用 route，要诱导/TTS/偏航用 [navi.md](navi.md)。\n\n## 文档一览与边界\n\n| 文档 | 内容 | 边界 |\n|------|------|------|\n| [cocoapods.md](cocoapods.md) | Podfile、pod 命令、地图/定位/步骑行套件 | 构建报错见 [project-config.md](project-config.md) |\n| [project-config.md](project-config.md) | Info.plist、隐私弹窗、Launch Screen、CocoaPods 沙盒 | 仅百度 SDK 相关配置 |\n| [location.md](location.md) | BMKLocationKit、定位方式、鉴权排查、坐标系 | 不含步骑行导航内部定位 |\n| [mapview.md](mapview.md) | BMKMapView、状态、生命周期 | 不含标注/覆盖物具体类型 |\n| [annotations.md](annotations.md) | 标注、固定屏、点聚合展示 | 聚类逻辑见 [overlays.md](overlays.md) |\n| [overlays.md](overlays.md) | 覆盖物、热力、点聚合逻辑、轨迹、Marker | 与 annotations 组合使用 |\n| [ui-standards.md](ui-standards.md) | 检索/路线/选点/弹窗/视野/Logo 等 UI 标准 | 无特殊要求时方案按此实现 |\n| [search.md](search.md) | Sug、地理编码、逆地理、POI、公交 | 路线算路见 [route.md](route.md) |\n| [route.md](route.md) | BMKRouteSearch：驾车/步行/骑行/公交算路与画线、BMKPlanNode、路况 | 与 walkcyclenavi 不同服务；仅算路+画线用本文档 |\n| [navi.md](navi.md) | BaiduWalkNaviKit：步骑行实时导航、诱导、TTS、偏航、多实例、无UI | 与 route 不同服务；需实时导航用本文档 |\n| [utils.md](utils.md) | BMKCoordTrans、BMKGeometry、视野、调起地图 | 工具类，与其它文档组合 |\n| [assets.md](assets.md) | 图片资源 | 技能内 assets 目录 |\n| [class-index.md](class-index.md) | 类与头文件速查 | 用法与示例见各功能文档 |\n\n## 常见组合\n\n| 需求 | 文档组合 |\n|------|----------|\n| 地图 + 定位 | cocoapods → project-config → mapview + location（坐标系统一 BD09） |\n| 地图 + 路线画线 | mapview + route + search（选点）；步骑行仅画线用 route |\n| 步骑行实时导航 | cocoapods（BaiduWalkNaviKit）→ project-config → navi |\n| 标注 + 点聚合 | annotations + overlays（聚类与 Marker） |\n| 定位鉴权失败 | [location.md](location.md)「鉴权失败排查」+ project-config 隐私与 Info.plist |\n\nArchive v1.0.0: 16 files, 57589 bytes\n\nFiles: references/annotations.md (3338b), references/assets.md (1239b), references/class-index.md (7708b), references/cocoapods.md (1760b), references/location.md (10966b), references/mapview.md (21046b), references/navi.md (5233b), references/overlays.md (20945b), references/project-config.md (5675b), references/reference.md (3753b), references/route.md (12187b), references/search.md (11745b), references/ui-standards.md (12422b), references/utils.md (6283b), SKILL.md (11419b), _meta.json (136b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: baidu-map-ios-sdk\ndescription: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。\ncompatibility: iOS, Xcode, CocoaPods\n---\n\n# 百度地图 iOS SDK\n\n## 目标与边界\n\n- **目标**：在 iOS 工程中正确集成百度地图/定位/步骑行导航，并给出符合隐私与坐标系规范的实现方案。\n- **负责**：BaiduMapKit、BMKLocationKit、BaiduWalkNaviKit 的集成、配置、API 选用与示例；与技能内 reference 文档一致。\n- **不负责**：驾车导航细节（百度地图驾车导航文档）、服务端逻辑、非百度 SDK、UI 视觉设计（仅遵循 [ui-standards.md](references/ui-standards.md) 的规范）。\n\n## 使用时机\n\n满足其一即启用本技能：\n\n- 关键词：百度地图、BMKMapView、BMKLocationKit、步骑行导航、BaiduWalkNaviKit、标注、路线规划、CocoaPods 集成、BD09、定位鉴权\n- 需求类型：地图展示、单次/连续/后台定位、步行或骑行实时导航、POI/标注/覆盖物、路线绘制、逆地理、轨迹动画、点聚合、隐私弹窗\n\n**按需加载**：先根据需求在 [reference.md](references/reference.md) 中选定文档，再引用对应 references 内容；需求含糊时先向用户澄清再给方案。\n\n## 集成与编码顺序\n\n- **未集成百度地图 SDK 时**：先配置并执行 CocoaPods（编写/补全 Podfile → 执行 `pod install` → 使用生成的 `.xcworkspace` 打开），**在能正确导入 SDK 头文件之后**再编写调用地图/定位/检索等的代码。这样既避免使用 `#if __has_include(...)` 做条件编译，也能以实际 SDK 头文件为准写代码，减少接口不一致或编译错误。\n- **本地已集成 SDK 时**：直接按需导入头文件并写代码，**以当前工程内的 SDK 版本、头文件及接口为准**；类名、方法、参数与本地头文件一致，不写不存在的 API。若编译报错提示符号不存在，提示开发者核对或更新 Pod 版本后再重试。\n\n## Agent 执行要求\n\n1. **AK 与 Bundle 主动提示**  \n   在编写或集成使用地图/定位 SDK 的代码时，**主动提示开发者**：\n   - 在 [百度 LBS 控制台](https://lbsyun.baidu.com/) 申请 **iOS 应用 AK**，且应用的 **Bundle Identifier** 必须与工程中 `PRODUCT_BUNDLE_IDENTIFIER` 一致；\n   - 在代码或配置中预留/替换 AK 的位置（如 `AppDelegate` 中的 key、或说明需在控制台配置），并注明「将 `YOUR_AK` 替换为实际 AK」。\n   - 若工程尚未配置 Bundle ID，提醒开发者设置并与控制台申请时填写的包名一致。\n\n2. **代码写完自动执行编译修复，编译无误后停止**  \n   完成与百度地图/定位相关的代码修改后，**必须**按以下流程执行，**不得在编译未通过时结束**：\n   - **自动执行编译**：使用 `xcodebuild -workspace xxx.xcworkspace -scheme xxx -destination 'generic/platform=iOS' build`（或等价命令；CocoaPods 工程用 workspace，纯工程用 project）。\n   - **若编译报错**：根据报错信息**立即修复**（类名、方法签名、头文件、ARC、协议声明等），修复后**再次执行编译**。\n   - **循环**：重复「编译 → 若有错误则修复 → 再编译」，直至**编译通过、无错误**。\n   - **编译无误后停止**：仅当 build 成功（BUILD SUCCEEDED）后，才结束本轮代码修改与修复，不再继续做与编译无关的额外修改。\n\n3. **配置 Launch Screen 避免 App 非全屏**  \n   集成地图或涉及全屏展示时，**必须**确保工程已配置 Launch Screen，避免运行后出现黑边、非全屏。具体见 [project-config.md](references/project-config.md)「窗口初始化/Launch Screen」：\n   - 工程内存在 **LaunchScreen.storyboard**（或等效 Launch 资源），并加入 target 的 Resources；\n   - Info.plist 中配置 **UILaunchStoryboardName** 为 `LaunchScreen`；\n   - 若缺失，主动创建或补充说明，并提醒开发者添加该配置。\n\n## 必须遵守的规则\n\n1. **隐私与配置**\n   - 首次使用前必须弹窗让用户阅读并同意隐私政策，再调用对应接口。\n   - **地图**：`[BMKMapManager setAgreePrivacy:YES]`（**类方法**，勿用 `sharedInstance`；未同意时检索可返回 nil）。\n   - **定位**：通过 **BMKLocationAuth** 的 **setAgreePrivacy** 在用户同意后再初始化 BMKLocationManager 等；详见 [location.md](references/location.md)。\n   - Info.plist 必配 **CFBundleDisplayName**；使用定位时配 NSLocationWhenInUseUsageDescription 等。详见 [project-config.md](references/project-config.md)。\n   - **AK 与 Bundle**：编写集成代码时主动提示开发者提供/配置 AK，且 Bundle Identifier 与百度控制台申请一致（见上文「Agent 执行要求」）。\n   - **Launch Screen**：必须配置 LaunchScreen.storyboard 与 Info.plist 的 UILaunchStoryboardName，避免运行后 App 非全屏、黑边；见 [project-config.md](references/project-config.md)。\n\n2. **坐标系**\n   - 地图 SDK 全局 **BD09**；定位 SDK 默认 **GCJ02**。与地图混用时须统一为 BD09：将定位 **coordinateType** 设为 **BMKLocationCoordinateTypeBMK09LL**，或使用 [utils.md](references/utils.md) 的 BMKCoordTrans 转换。\n\n3. **标注与几何（必须遵守）**\n   - **点标注优先使用 Marker，不得使用 Annotation/PinAnnotation**：点标注**必须优先**使用 **BMKIconMarker/BMKTextMarker**（addOverlay 体系），**禁止**使用 BMKPointAnnotation、BMKAnnotationView、BMKPinAnnotationView（addAnnotation 体系）除非以下例外：点聚合（BMKClusterManager 必须用 BMKPointAnnotation）、固定屏选点（isLockedToScreen）等仅 addAnnotation 能实现的场景。起终点、小车、普通图钉等一律用 Marker。详见 [overlays.md](references/overlays.md)、[annotations.md](references/annotations.md)。\n   - 距离、视野、方位等用 [utils.md](references/utils.md) 的 BMKGeometry 等，勿手写。\n   - **路线与起终点须优先使用纹理**：绘制**路线**时优先使用 **BMKPolylineView.textureImage**（图片宽高须为 2 的 n 次幂）或路况场景使用 **BMKMultiTexturePolylineView** + [assets](references/assets.md) 路况纹理；**起终点**的 BMKIconMarker.icon 须优先使用 [assets](references/assets.md) 的 **icon_start、icon_end**；仅当无可用纹理时再使用 strokeColor/纯色或自绘。见 [overlays.md](references/overlays.md)「路线与起终点：纹理优先」。\n   - **路线小车纹理**：路线上的小车图标**必须优先使用**本技能 [assets](references/assets.md)（`assets/images/`）提供的纹理图（如 icon_car、car_triangle、track_car）；仅当无可用纹理时，才使用纯色或自绘图片。\n\n4. **步骑行：按需求区分两种方案**\n   - **路线规划（算路+画线）**：BMKRouteSearch（BaiduMapKit），walkingSearch/ridingSearch，得到路线后自绘折线。见 [route.md](references/route.md)。\n   - **步骑行实时导航**：BaiduWalkNaviKit，Manager + 诱导、TTS、偏航纠偏、多实例/无UI。见 [navi.md](references/navi.md)。\n   - 二者是**不同服务**：仅需画线用 route；需实时导航用 navi。给出方案前先按开发者需求选对文档。\n\n5. **版本与 API 以本地为准**（与上文「集成与编码顺序」一致）\n   - 已集成 SDK：**以工程内 SDK 版本与头文件为准**，类名、方法、参数与头文件一致；不写 `#if __has_include`，直接导入头文件后写代码。\n   - 若某类、方法或属性在用户工程中**不存在**（编译报错或头文件无此符号），**提示用户将对应 Pod 更新到最新版本**后再重试，勿强行按文档写不存在的 API。\n\n6. **Logo 不可遮挡与路线视野适配（必须考虑）**\n   - **Logo 不能被遮挡**：百度地图 Logo 不可移除、不允许被 UI 遮挡。有浮动栏/底部栏时**必须**使用 `setMapPadding` 预留边界（如顶部预留检索面板、底部预留 barH+4），使 Logo 落在可见内容区内。详见 [ui-standards.md](references/ui-standards.md)「地图 Logo、指南针与 mapPadding」。\n   - **路线适配视野必须做**：有路线绘制时**必须**调用 `fitVisibleMapRect:edgePadding:withAnimated:` 做视野适配，edgePadding 按 [ui-standards.md](references/ui-standards.md)「路线视野适配」预留（顶部检索面板+50+marker、底部底部栏+20+marker、左右 50+marker 等），避免路线或起终点被裁切或被 UI 遮挡。mapPadding 与 fitVisibleMapRect 的 edgePadding 分开使用，勿混用。\n\n## 输出规范（可评估）\n\n给出方案时需满足：\n\n- **可落地**：含具体类名、方法、调用顺序与必要配置（如 Info.plist、隐私调用时机、Launch Screen）。\n- **可验证**：隐私与坐标系处理明确；若涉及定位鉴权失败，方案中可指向 [location.md](references/location.md) 的「鉴权失败排查」。\n- **可组合**：按 [reference.md](references/reference.md) 选文档与常见组合；步骑行选型见规则 4。\n- **AK/Bundle 提示**：涉及地图/定位初始化时，明确提示开发者配置 AK 与 Bundle Identifier。\n- **编写后编译直至通过**：完成代码编写后，自动执行 xcodebuild 编译；若有报错则根据错误修复并重新编译，循环直至编译无误，再停止。\n- **全屏与 Launch Screen**：涉及地图全屏或窗口大小时，确认或说明已配置 LaunchScreen.storyboard 与 UILaunchStoryboardName，避免运行后非全屏、黑边。\n- **Logo 不遮挡**：涉及地图且有浮动栏/底部栏时，方案中**必须**包含 setMapPadding，并说明底部预留尽量小（如 barH+4），确保 Logo 不被遮挡。\n- **路线视野适配**：涉及路线绘制时，方案中**必须**包含 fitVisibleMapRect 的 edgePadding 设置，按 ui-standards 预留","readmeExcerpt":"Skill: Baidu Map IOS SDK（百度地图官方IOS SKills） Owner: baidu-maps Summary: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。 Tags: latest:1.0.2 Version history: v1.0.2 | 2026-06-01T03:40:38.452Z | user baidu-map-ios-sdk 1.0.2 - 移除元数据文件 _meta.json。 - 移除技能简介卡片 skill-card.md。 - 保持主功能、集成文档和规则不变，仅精简技能包结构。 v1.0.1 | 2026-04-07T04:07:47.729Z | user Initial release ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"gem sources -l\ngem sources --remove https://rubygems.org/\ngem sources -a https://gems.ruby-china.com\nsudo gem update --system\nsudo gem install -n /usr/local/bin cocoapods  # macOS > 10.11\npod setup"},{"language":"ruby","snippet":"platform :ios, '9.0'\ntarget 'YourProjectTarget' do\n  pod 'BMKLocationKit', '2.1.3'\nend"},{"language":"ruby","snippet":"platform :ios, '10.0'\ntarget 'YourProjectTarget' do\n    pod 'BaiduMapKit'\n    # pod 'BaiduMapKit/Map'\n    # pod 'BaiduMapKit/Search'\n    # pod 'BaiduMapKit/Utils'\nend"},{"language":"ruby","snippet":"platform :ios, '10.0'\ntarget 'YourProjectTarget' do\n    pod 'BaiduWalkNaviKit'\nend"},{"language":"bash","snippet":"pod install          # 安装后用 .xcworkspace 打开\npod repo update\npod update"},{"language":"bash","snippet":"pod setup\nrm ~/Library/Caches/CocoaPods/search_index.json\npod search BaiduMapKit   # 或 pod search BMKLocationKit"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: baidu-map-ios-sdk\ndescription: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。\ncompatibility: iOS, Xcode, CocoaPods\n---\n\n# 百度地图 iOS SDK\n\n## 目标与边界\n\n- **目标**：在 iOS 工程中正确集成百度地图/定位/步骑行导航，并给出符合隐私与坐标系规范的实现方案。\n- **负责**：BaiduMapKit、BMKLocationKit、BaiduWalkNaviKit 的集成、配置、API 选用与示例；与技能内 reference 文档一致。\n- **不负责**：驾车导航细节（百度地图驾车导航文档）、服务端逻辑、非百度 SDK、UI 视觉设计（仅遵循 [ui-standards.md](references/ui-standards.md) 的规范）。\n\n## 使用时机\n\n满足其一即启用本技能：\n\n- 关键词：百度地图、BMKMapView、BMKLocationKit、步骑行导航、BaiduWalkNaviKit、标注、路线规划、CocoaPods 集成、BD09、定位鉴权\n- 需求类型：地图展示、单次/连续/后台定位、步行或骑行实时导航、POI/标注/覆盖物、路线绘制、逆地理、轨迹动画、点聚合、隐私弹窗\n\n**按需加载**：先根据需求在 [reference.md](references/reference.md) 中选定文档，再引用对应 references 内容；需求含糊时先向用户澄清再给方案。\n\n## 集成与编码顺序\n\n- **未集成百度地图 SDK 时**：先配置并执行 CocoaPods（编写/补全 Podfile → 执行 `pod install` → 使用生成的 `.xcworkspace` 打开），**在能正确导入 SDK 头文件之后**再编写调用地图/定位/检索等的代码。这样既避免使用 `#if __has_include(...)` 做条件编译，也能以实际 SDK 头文件为准写代码，减少接口不一致或编译错误。\n- **本地已集成 SDK 时**：直接按需导入头文件并写代码，**以当前工程内的 SDK 版本、头文件及接口为准**；类名、方法、参数与本地头文件一致，不写不存在的 API。若编译报错提示符号不存在，提示开发者核对或更新 Pod 版本后再重试。\n\n## Agent 执行要求\n\n1. **AK 与 Bundle 主动提示**  \n   在编写或集成使用地图/定位 SDK 的代码时，**主动提示开发者**：\n   - 在 [百度 LBS 控制台](https://lbsyun.baidu.com/) 申请 **iOS 应用 AK**，且应用的 **Bundle Identifier** 必须与工程中 `PRODUCT_BUNDLE_IDENTIFIER` 一致；\n   - 在代码或配置中预留/替换 AK 的位置（如 `AppDelegate` 中的 key、或说明需在控制台配置），并注明「将 `YOUR_AK` 替换为实际 AK」。\n   - 若工程尚未配置 Bundle ID，提醒开发者设置并与控制台申请时填写的包名一致。\n\n2. **代码写完自动执行编译修复，编译无误后停止**  \n   完成与百度地图/定位相关的代码修改后，**必须**按以下流程执行，**不得在编译未通过时结束**：\n   - **自动执行编译**：使用 `xcodebuild -workspace xxx.xcworkspace -scheme xxx -destination 'generic/platform=iOS' build`（或等价命令；CocoaPods 工程用 workspace，纯工程用 project）。\n   - **若编译报错**：根据报错信息**立即修复**（类名、方法签名、头文件、ARC、协议声明等），修复后**再次执行编译**。\n   - **循环**：重复「编译 → 若有错误则修复 → 再编译」，直至**编译通过、无错误**。\n   - **编译无误后停止**：仅当 build 成功（BUILD SUCCEEDED）后，才结束本轮代码修改与修复，不再继续做与编译无关的额外修改。\n\n3. **配置 Launch Screen 避免 App 非全屏**  \n   集成地图或涉及全屏展示时，**必须**确保工程已配置 Launch Screen，避免运行后出现黑边、非全屏。具体见 [project-config.md](references/project-config.md)「窗口初始化/Launch Screen」：\n   - 工程内存在 **LaunchScreen.storyboard**（或等效 Launch 资源），并加入 target 的 Resources；\n   - Info.plist 中配置 **UILaunchStoryboardName** 为 `LaunchScreen`；\n   - 若缺失，主动创建或补充说明，并提醒开发者添加该配置。\n\n## 必须遵守的规则\n\n1. **隐私与配置**\n   - 首次使用前必须弹窗让用户阅读并同意隐私政策，再调用对应接口。\n   - **地图**：`[BMKMapManager setAgreePrivacy:YES]`（**类方法**，勿用 `sharedInstance`；未同意时检索可返回 nil）。\n   - **定位**：通过 **BMKLocationAuth** 的 **setAgreePrivacy** 在用户同意后再初始化 BMKLocationManager 等；详见 [location.md](references/location.md)。\n   - Info.plist 必配 **CFBundleDisplayName**；使用定位时配 NSLocationWhenInUseUsageDescription 等。详见 [project-config.md](references/project-config.md)。\n   - **AK 与 Bundle**：编写集成代码时主动提示开发者提供/配置 AK，且 Bundle Identifier 与百度控制台申请一致（见上文「Agent 执行要求」）。\n   - **Launch Screen**：必须配置 LaunchScreen.storyboard 与 Info.plist 的 UILaunchStoryboardName，避免运行后 App 非全屏、黑边；见 [project-config.md](references/project-config.md)。\n\n2. **坐标系**\n   - 地图 SDK 全局 **BD09**；定位 SDK 默认 **GCJ02**。与地图混用时须统一为 BD09：将定位 **coordi"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn778b6bf766ym71fdvrc5yvg98319rv\",\n  \"slug\": \"baidu-map-ios-sdk\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1780285238452\n}"},{"path":"references/annotations.md","content":"# 标注 (Annotation)\n\n**边界**：addAnnotation 体系；覆盖物见 [overlays.md](overlays.md)。**必须遵守**：点标注**优先使用 Marker**（BMKIconMarker/BMKTextMarker，addOverlay），**不得使用** Annotation/PinAnnotation 做起终点、小车、普通图钉等；**仅**点聚合、固定屏选点等必须用 addAnnotation 的场景才用本 API。见 [SKILL.md](../SKILL.md) 规则 3。\n\n## 使用须知\n- **Delegate**：addAnnotation 前必须设置 `mapView.delegate`，并实现 `mapView:viewForAnnotation:`。\n- **复用**：使用 `dequeueReusableAnnotationViewWithIdentifier`，identifier 建议唯一。\n- **起终点**：推荐 BMKIconMarker（addOverlay），见 [overlays.md](overlays.md)。\n\n## 核心类\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKAnnotation | BMKAnnotation.h | 标注协议，`coordinate`、`title` |\n| BMKPointAnnotation | BMKPointAnnotation.h | 点标注 |\n| BMKAnnotationView | BMKAnnotationView.h | 标注视图基类 |\n| BMKPinAnnotationView | BMKPinAnnotationView.h | 大头针样式 |\n| BMKActionPaopaoView | BMKActionPaopaoView.h | 气泡视图 |\n\n**标注规范**：使用 `dequeueReusableAnnotationViewWithIdentifier` 复用，identifier 建议唯一。自定义图片用 BMKAnnotationView + image。\n\n## 固定屏幕标注（地图选点）\n\n`BMKPointAnnotation.isLockedToScreen = YES` + `screenPointToLock`，需在 `mapViewDidFinishLoading` 后设置。常用于地图选点。\n\n**方式 B（BMKIconMarker）**：Marker 无 isLockedToScreen，需在 `regionDidChangeAnimated:reason:` 中（reason == BMKRegionChangeReasonGesture）同步 `marker.coordinate = mapView.centerCoordinate`。**区域回调**：regionWillChange 跳起，regionDidChange 落下 + 逆地理。**选点动画**见 [ui-standards.md](ui-standards.md)。\n\n## BMKPinAnnotationView 常用属性\n\n`centerOffset`、`calloutOffset`（正偏移朝右下方）、`enabled3D`、`canShowCallout`、`leftCalloutAccessoryView`/`rightCalloutAccessoryView`（默认气泡最大 32×41）、`pinColor`（Red/Green/Purple）、`animatesDrop`、`draggable`。直接设置 `selected` 时，非 PinAnnotation 需在设置后调用 `mapForceRefresh`。\n\n## 碰撞检测与展示优先级\n\n`BMKAnnotationView.displayPriority`（如 `BMKFeatureDisplayPriorityDefaultHigh`）、`isOpenCollisionDetection`、`collisionDetectionPriority`（数值越大越优先）、`isForceDisplay`（强制展示）、`displayMaxLevel`/`displayMinLevel`（层级限制）。\n\n## 点聚合中的标注\n\n点聚合（BMKClusterManager + BMKPointAnnotation）将大量标注按 zoom 聚合。`viewForAnnotation` 按 cluster.size 区分单点/聚合点；size>1 可显示数量、按档设圆点大小。**点击拆簇**：`annotationViewForBubble` 中 zoomIn。聚合逻辑见 [overlays.md](overlays.md)。\n\n---\n\n## 按需方案\n\n| 需求 | 基础能力 |\n|------|----------|\n| 普通点标注 | BMKPointAnnotation + BMKAnnotationView |\n| 大头针 | BMKPointAnnotation + BMKPinAnnotationView |\n| 固定屏幕选点 | BMKPointAnnotation（isLockedToScreen + screenPointToLock）或 BMKIconMarker |\n| 起终点大头针 | BMKPointAnnotation + BMKAnnotationView（起终点推荐 BMKIconMarker，见 [overlays.md](overlays.md)） |\n| 点聚合标注 | BMKClusterManager + BMKPointAnnotation，viewForAnnotation 按 size 展示 |"},{"path":"references/assets.md","content":"# 图片资源\n\n**边界**：技能内 `assets/images/` 图片及用途；集成与构建见 [cocoapods.md](cocoapods.md)、[project-config.md](project-config.md)。\n\n**路线小车**：路线上的小车图标**必须优先使用**本技能提供的纹理图（下表 icon_car / car_triangle / track_car）；仅当无可用纹理时，才使用纯色或自绘图片。实现时先 `[UIImage imageNamed:@\"icon_car\"]`（或对应名称），为 nil 再回退。\n\n| 图片 | 用途 |\n|------|------|\n| icon_car | 小车 marker（**路线小车优先**） |\n| car_triangle | 带方向小车（车头朝上） |\n| track_car | 带方向小车（车头朝右），**轨迹动画推荐** |\n| icon_start | 起点标注 |\n| icon_end | 终点标注 |\n| icon_via | 途经点 |\n| **路况纹理**（BMKMultiPolyline + BMKMultiTexturePolylineView，drawIndexs 来自 BMKDrivingStep.traffics） | |\n| traffic_texture_unknown | 无数据（traffics=0，drawIndex 0） |\n| traffic_texture_smooth | 畅通（traffics=1，drawIndex 1） |\n| traffic_texture_slow | 缓行（traffics=2，drawIndex 2） |\n| traffic_texture_congestion | 拥堵（traffics=3，drawIndex 3） |\n| traffic_texture_severe_congestion | 严重拥堵（traffics=4，drawIndex 4） |"},{"path":"references/class-index.md","content":"# 类速查表\n\n**边界**：按头文件组织的类速查；用法与示例见 [annotations.md](annotations.md)、[overlays.md](overlays.md) 等各功能文档。下表记录类名、头文件及主要方法/属性名，便于不依赖外链查阅。\n\n## 地图核心\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKMapManager | BMKMapManager.h | 主引擎 |\n| BMKMapView | BMKMapView.h | 地图视图 |\n| BMKMapStatus | BMKMapStatus.h | 地图状态 |\n| BMKMapViewDelegate | BMKMapView.h | 地图回调 |\n\n## 标注\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKAnnotation | BMKAnnotation.h | 标注协议 |\n| BMKPointAnnotation | BMKPointAnnotation.h | 点标注 |\n| BMKAnnotationView | BMKAnnotationView.h | 标注视图基类 |\n| BMKPinAnnotationView | BMKPinAnnotationView.h | 大头针样式 |\n| BMKActionPaopaoView | BMKActionPaopaoView.h | 气泡视图 |\n\n## 覆盖物\n\n### 基础\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKOverlay | BMKOverlay.h | 覆盖物协议 |\n| BMKOverlayView | BMKOverlayView.h | 覆盖物视图基类 |\n| BMKPolyline | BMKPolyline.h | 单色/单纹理折线 |\n| BMKPolylineView | BMKPolylineView.h | 折线视图 |\n| BMKMultiPolyline | BMKMultiPolyline.h | 分段折线，需 drawIndexs |\n| BMKMultiColorPolylineView | BMKMultiPolylineView.h | 分段颜色 |\n| BMKMultiTexturePolylineView | BMKMultiPolylineView.h | 分段纹理（路况） |\n| BMKCircle | BMKCircle.h | 圆形 |\n| BMKCircleView | BMKCircleView.h | 圆形视图 |\n| BMKPolygon | BMKPolygon.h | 多边形 |\n| BMKPolygonView | BMKPolygonView.h | 多边形视图 |\n| BMKGroundOverlay | BMKGroundOverlay.h | 图片图层 |\n| BMKGroundOverlayView | BMKGroundOverlayView.h | 图片图层视图 |\n| BMKTileLayer | BMKTileLayer.h | 瓦片图层基类 |\n| BMKURLTileLayer | BMKTileLayer.h | URL 瓦片图层 |\n\n### 曲线与渐变\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKArcline | BMKArcline.h | 圆弧 |\n| BMKArclineView | BMKArclineView.h | 圆弧视图 |\n| BMKGradientLine | BMKGradientLine.h | 渐变线 |\n| BMKGradientLineView | BMKGradientLineView.h | 渐变线视图 |\n| BMKGradientCircleView | BMKGradientCircleView.h | 渐变圆 |\n| BMKGeodesicLine | BMKGeodesicLine.h | 大地线 |\n| BMKGeodesicLineView | BMKGeodesicLineView.h | 大地线视图 |\n\n### Marker\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKIconMarker | BMKIconMarker.h | 图标 Marker |\n| BMKIconMarkerView | BMKIconMarkerView.h | 图标 Marker 视图 |\n| BMKTextMarker | BMKTextMarker.h | 文本 Marker |\n| BMKTextMarkerView | BMKTextMarkerView.h | 文本 Marker 视图 |\n| BMKTextPathMarker | BMKTextPathMarker.h | 沿路径文字 |\n| BMKTextPathMarkerView | BMKTextPathMarkerView.h | 沿路径文字视图 |\n\n### 文本与海量点\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMKText | BMKText.h | 文本 overlay |\n| BMKTextView | BMKTextView.h | 文本 overlay 视图 |\n| BMKMultiPointOverlay | BMKMultiPointOverlay.h | 海量点 |\n| BMKMultiPointOverlayView | BMKMultiPointOverlayView.h | 海量点视图 |\n| BMKMultiPointItem | BMKMultiPointOverlay.h | 海量点数据项 |\n\n### 3D 与轨迹\n\n| 类 | 头文件 | 说明 |\n|----|--------|------|\n| BMK3DModelOverlay | BMK3DModelOverlay.h | 3D 模型 |\n| BMK3DModelOverlayView | BMK3DModelOverlayView.h | 3D 模型视图 |\n| BMKPrismOverlay | BMKPrismOverlay.h | 棱柱/3D 建筑 |\n| BMKPrismOverlayView | BMKPrismOverlayView.h | 棱柱视图 |\n| BMKTraceOverlay | BMKTraceOverlay.h | 路书轨迹 |\n| BMKTraceOverlayView | BMKTraceOverlayView.h | 路书轨迹视图 |\n| BMK3DTraceOverlay | BMK3DTraceOverlay.h | 3D 轨迹 |\n| BMK3DTraceOverlayView | BMK3DTraceOverlay"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。 Skill: Baidu Map IOS SDK（百度地图官方IOS SKills） Owner: baidu-maps Summary: 百度地图 iOS SDK 与 BMKLocationKit 集成与开发规范。覆盖地图、定位、步骑行导航、检索、路线、标注与覆盖物；输出专业地图方案。可快捷使用百度地图 SDK 的能力与数据，构建功能丰富、交互性强的专业地图类应用。 Tags: latest:1.0.2 Version history: v1.0.2 | 2026-06-01T03:40:38.452Z | user baidu-map-ios-sdk 1.0.2 - 移除元数据文件 _meta.json。 - 移除技能简介卡片 skill-card.md。 - 保持主功能、集成文档和规则不变，仅精简技能包结构。 v1.0.1 | 2026-04-07T04:07:47.729Z | user Initial release","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":981,"uniquenessScore":54,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T15:15:35.151Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T15:15:35.151Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:34:47.814Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}