Skill: lbs-bmap/baidu-map-android-sdk (version 1.0.2)

--- name: baidu-map-android-sdk description: 百度地图 Android SDK 集成与开发规范。覆盖地图展示、MapView/BaiduMap 生命周期、定位、标注与覆盖物、POI 检索、路线规划、步骑行导航；输出符合隐私与 AK 配置的 Android 地图方案。在开发 Android 地图应用、集成百度地图 SDK、MapView、路线规划、POI、导航时使用。 compatibility: Android, Gradle, Android Studio --- # 百度地图 Android SDK ## 目标与边界 - **目标**：在 Android 工程中正确集成百度地图 SDK，并给出符合隐私、AK、坐标系规范的实现方案。 - **负责**：地图展示、MapView 生命周期、覆盖物、POI/路线/地理编码检索、步骑行导航等；以技能内 references 为准。 - **不负责**：服务端逻辑、非百度 SDK、UI 视觉设计。 ## 使用时机 满足其一即启用本技能： - 关键词：百度地图 Android、MapView、BaiduMap、AK、路线规划、POI 检索、步骑行导航、BD09、坐标类型 - 需求类型：地图展示、定位、标注与覆盖物、POI/地点检索、路线规划与画线、步行/骑行实时导航、地理编码 **按需加载**：先根据需求在 [reference.md](references/reference.md) 中选定文档，再引用对应 references 内容；需求含糊时先向用户澄清**再给方案**。 ## 必须遵守的规则 1. **隐私与初始化（v7.5.0+）** - 调用 SDK 任何接口前必须先调用隐私合规接口，且**必须在 `SDKInitializer.initialize` 之前**调用。见 [overview.md](references/overview.md) 隐私合规小节。 - Application 中：`SDKInitializer.initialize(this)`；自 4.3.0 起可用 `SDKInitializer.setCoordType(CoordType.BD09LL)` 或 `CoordType.GCJ02`。 2. **AK 与配置** - 使用前需在控制台申请 Android SDK 密钥（AK），应用类型选「Android SDK」，填写包名、SHA1。AK 配置到 AndroidManifest 或 `SDKInitializer.setApiKey`；包名与签名须与申请一致。见 [overview.md](references/overview.md)。 3. **MapView 生命周期** - Activity 的 `onResume`/`onPause`/`onDestroy` 中必须分别调用 `mMapView.onResume()`、`mMapView.onPause()`、`mMapView.onDestroy()`。见 [mapview.md](references/mapview.md)。 4. **坐标系** - 国内默认 BD09LL；可与 GCJ02 通过 `SDKInitializer.setCoordType` 统一。与定位混用时与定位 SDK 坐标类型一致；转换见 [coordinate.md](references/coordinate.md)。 5. **检索与路线** - **监听先于请求**：先 `setOnGetPoiSearchResultListener` 再 `searchNearby` 等；先 `setOnGetRoutePlanResultListener` 再 `drivingSearch` 等，否则可能拿不到回调。用完后 `destroy()` 释放实例。 6. **版本与 API 以工程为准** - 用户已集成 SDK 时，以其实机/工程内版本为准。若某类或方法**不存在**（编译报错或依赖中无此符号），**提示用户将对应依赖更新到兼容版本**后再重试，勿强行写不存在的 API。 7. **步骑行：按需求区分** - **路线规划（算路+画线）**：RoutePlanSearch（驾车/步行/骑行/公交），得到路线后自绘折线或使用开源 Overlay。见 [route.md](references/route.md)。 - **步骑行实时导航**：步行/骑行导航引擎、诱导、TTS、偏航纠偏等，类见 [overview.md](references/overview.md) 与 [class-reference.md](references/class-reference.md)。 - 二者是**不同服务**：仅需画线用 route；需实时诱导/TTS 用步骑行导航。给出方案前先按开发者需求选对文档。 ## 输出规范（可评估） - **可落地**：含具体类名、方法、调用顺序与必要配置（AndroidManifest、Application、AK、隐私）。 - **可验证**：隐私与 AK 明确；检索/路线监听顺序正确；若涉及定位/鉴权失败，方案可指向 [location.md](references/location.md) 或 [project-config.md](references/project-config.md) 的排查项。 - **可组合**：按 [reference.md](references/reference.md) 选文档与常见组合。无特殊要求时界面与交互遵循 [ui-standards.md](references/ui-standards.md)。 方案结构：需求 → 对应文档 → 配置与依赖 → 关键 API → 示例片段 → 注意事项。 ## 参考索引 - 按需求选文档与常见组合：[reference.md](references/reference.md) - Gradle 集成（依赖、冲突、NDK、环境与国内镜像）：[gradle.md](references/gradle.md) - AndroidManifest、主题、混淆、集成经验与常见问题：[project-config.md](references/project-config.md) - 集成、AK、隐私、生命周期、核心类：[overview.md](references/overview.md) - 地图容器、类型、层级、方法交互：[mapview.md](references/mapview.md) - 显示定位、定位模式、自定义图标：[location.md](references/location.md) - 点标记、Marker 属性与事件：[marker.md](references/marker.md) - 折线、多边形、Polyline 属性：[overlays.md](references/overlays.md) - POI、地理编码、逆地理：[search.md](references/search.md) - 路线规划与 Overlay：[route.md](references/route.md) - 坐标转换与坐标系：[coordinate.md](references/coordinate.md) - 距离/面积、点与图形关系、调起地图、短地址分享：[tools.md](references/tools.md) - 错误码：[errorcode.md](references/errorcode.md) - 类与包速查：[class-reference.md](references/class-reference.md) - 检索/路线/选点/弹窗/Logo 等 UI 与交互约定：[ui-standards.md](references/ui-standards.md)

path: _meta.json
content: ownerId: kn72hkpg708gjrfmw7934hatex82qkkj
slug: baidu-map-android-sdk
version: 1.0.1
publishedAt: 1773219403336

path: references/mapview.md
content: # 地图容器与 BaiduMap

## 配置与初始化

- **AndroidManifest**：在 `<application>` 内配置 AK：`<meta-data android:name="com.baidu.lbsapi.API_KEY" android:value="您的AK"/>`。在 `<application>` 外声明权限（如网络、定位等）；自 Android 6.0 起部分权限需代码动态申请。
- **初始化**：在自定义 Application 的 `onCreate` 中调用 `SDKInitializer.initialize(this)` 和 `SDKInitializer.setCoordType(CoordType.BD09LL)`（或 GCJ02）。隐私接口必须在 initialize 之前调用，见 [overview.md](overview.md)。

## 布局与获取 BaiduMap

- 布局中声明：`<com.baidu.mapapi.map.MapView android:id="@+id/bmapView" ... />`。
- 代码获取：`MapView mMapView = findViewById(R.id.bmapView);`，`BaiduMap mBaiduMap = mMapView.getMap();`。
- 纯代码：`MapView mapView = new MapView(this);` 然后 `setContentView(mapView)`。也可用 `BaiduMapOptions` 构造带初始状态的 MapView：`new MapView(this, options)`。

## MapView 生命周期（必须）

在 Activity 中：
- `onResume()` 内调用 `mMapView.onResume()`
- `onPause()` 内调用 `mMapView.onPause()`
- `onDestroy()` 内调用 `mMapView.onDestroy()`

## BaiduMapOptions 可选状态

| 状态 | 含义 |
|------|------|
| mapStatus | 地图状态 |
| compassEnable | 是否开启指南针，默认开启 |
| mapType | 地图模式，默认普通地图 |
| rotateGesturesEnabled | 是否允许旋转手势 |
| scrollGesturesEnabled | 是否允许拖拽 |
| overlookingGesturesEnabled | 是否允许俯视手势 |
| zoomControlsEnabled | 是否显示缩放按钮 |
| zoomControlsPosition | 缩放控件位置 |
| zoomGesturesEnabled | 是否允许缩放手势 |
| scaleControlEnabled | 是否显示比例尺 |
| scaleControlPosition | 比例尺位置 |
| logoPosition | Logo 位置 |

## 地图类型与图层

- **地图类型**（`mBaiduMap.setMapType(...)`）：
  - `BaiduMap.MAP_TYPE_NORMAL`：普通地图（含 3D）
  - `BaiduMap.MAP_TYPE_SATELLITE`：卫星图
  - `BaiduMap.MAP_TYPE_NONE`：空白地图（不下载瓦片，可叠瓦片或覆盖物）
- **实时路况**：`mBaiduMap.setTrafficEnabled(true)`。V4.5.0+ 可自定义路况颜色：`setCustomTrafficColor(严重拥堵, 拥堵, 缓行, 畅通)`，颜色格式 `#AARRGGBB`，不需显示的可将 AA 设为 00。
- **百度城市热力图**：`mBaiduMap.setBaiduHeatMapEnabled(true)`；仅 11–20 级可显示。

## 显示层级与比例尺

- 缩放等级：2D 地图 4–21，3D 地图 19–21，卫星 4–20，路况/热力 11–21，室内 17–22。自 v5.0.0 起由 3–21 改为 4–21。
- 设置缩放：`MapStatus.Builder builder = new MapStatus.Builder(); builder.zoom(18.0f); mBaiduMap.setMapStatus(MapStatusUpdateFactory.newMapStatus(builder.build()));`

## 常用地图容器

- **GLSurfaceView 系**：MapView、MapFragment、SupportMapFragment。
- **TextureView 系**：TextureMapView、TextureMapFragment、TextureSupportMapFragment。与其它 GLSurfaceView（如相机）叠加或放在 ScrollView 时建议用 Texture 系，避免穿透、黑屏。需 Android 4.4+ 且开启硬件加速。
- SupportMapFragment 使用：`SupportMapFragment.newInstance(mapOptions)`，再通过 FragmentTransaction 添加或替换到容器。

## 多实例

同一页面可放多个 MapView/SupportMapFragment，分别操作互不干扰。每个通过 `getBaiduMap()`/`getMapView()` 获取控制器与视图，分别设置 `MapStatusUpdate`、`setLogoPosition` 等。

## 方法交互（BaiduMap）

- **缩放**：`MapStatusUpdateFactory.zoomTo(level)`、`zoomIn()`、`zoomOut()`、`zoomBy(delta)`；`setMapStatus()` 为跳变，`animateMapStatus()` 为动画。级别超出范围时按最大/最小级别显示。
- **操作区内边距**：`mBaiduMap.setViewPadding(left, top, right, bottom)`；地图加载完成后生效，可通过 `OnMapLoadedCallback.onMapLoaded()` 监听。不得遮挡百度 Logo 与版权。布局模式、面板高度、与 fitBounds 区分见 [ui-standards.md](ui-standards.md)。
- **显示范围**：`MapStatusUpdateFactory.newLatLngBounds(bounds)` 或 `newLatLngBounds(bounds, width, height)`，bounds 由 `LatLngBounds.Builder().include(...).include(...).build()` 构造。
- **中心点**：`MapStatusUpdateFactory.newLatLng(latLng)`。
- **底图 POI**：`mBaiduMap.showMapPoi(false)` 可隐藏底图标注仅留道路。POI 标签按类型控制：`setPoiTagEnable(PoiTagType, boolean)`、`getPoiTagEnable(PoiTagType)`；PoiTagType 含 All、Epidemic、Travel、Shop 等。
- **空白地图背景色**：仅当 `setMapType(MAP_TYPE_NONE)` 时生效，`mBaiduMap.setMapBackgroundColor(Color.argb(...))`。


path: references/search.md
content: # POI 检索与地理编码

## 通用规则

- **监听先于请求**：先 `setOnGetPoiSearchResultListener` 或 `setOnGetGeoCodeResultListener`，再调用检索方法，否则可能收不到回调。
- 用完后调用 `destroy()` 释放 PoiSearch / GeoCoder 实例。

---

## POI 检索

### 实例与监听

- `PoiSearch mPoiSearch = PoiSearch.newInstance();`
- `OnGetPoiSearchResultListener` 实现：`onGetPoiResult(PoiResult)`、`onGetPoiDetailResult(PoiDetailSearchResult)`、`onGetPoiIndoorResult(PoiIndoorResult)`（按需）。先 `mPoiSearch.setOnGetPoiSearchResultListener(listener)`，再发起检索。

### 城市内检索（关键字）

- `mPoiSearch.searchInCity(new PoiCitySearchOption().city("北京").keyword("美食").pageNum(0));` city 与 keyword 必填。
- PoiCitySearchOption 其它常用：pageNum、pageCapacity、tag、scope（1 或空为基本信息，2 为详情）、cityLimit（是否限制在城市内）、poiFilter、isExtendAdcode、serverType（如 PoiServerType.POI_SERVER_TYPE_ABROAD 海外）。

### POI 结果错误码（result.error）

- PoiResult 有 **result.error** 字段（类型 `SearchResult.ERRORNO`）：
  - `result.error == SearchResult.ERRORNO.NO_ERROR`：成功，用 `result.getAllPoi()`、`result.getPoiResult()` 等。
  - `result.error == SearchResult.ERRORNO.RESULT_NOT_FOUND`：未找到结果。
  - `result.error == SearchResult.ERRORNO.AMBIGUOUS_KEYWORD`：关键字在本市无结果但在其他城市有，可 `result.getSuggestCityList()` 提示用户。

### POI 详情

- 从 PoiResult 取 PoiInfo，用 uid：`mPoiSearch.searchPoiDetail(new PoiDetailSearchOption().poiUids(poi.uid));` 最多 10 个 uid，逗号分隔。结果在 `onGetPoiDetailResult(PoiDetailSearchResult)`。自 V5.2.0 起废弃 onGetPoiDetailResult(PoiDetailResult)，改用 PoiDetailSearchResult。

### 周边检索

- `mPoiSearch.searchNearby(new PoiNearbySearchOption().location(centerLatLng).radius(radius).keyword("餐厅").pageNum(0));` 多关键字用 `$` 分隔，最多 10 个。

### 区域检索（矩形）

- `LatLngBounds searchBounds = new LatLngBounds.Builder().include(sw).include(ne).build();`
- `mPoiSearch.searchInBound(new PoiBoundSearchOption().bound(searchBounds).keyword("餐厅"));`

### 检索结果展示

- 可使用开源 PoiOverlay（overlayutil 包）：`PoiOverlay overlay = new PoiOverlay(mBaiduMap); overlay.setData(poiResult); overlay.addToMap(); overlay.zoomToSpan();`
- 有底部面板时可用 `overlay.zoomToSpanPaddingBounds(padding, padding, padding, bottomPadding)` 使 POI 落在可视区内。

### 注意

- Android 7.5.2+ 支持 adCode；PoiCitySearchOption.isExtendAdcode(true) 时结果含 adCode。

---

## 地理编码（地址 → 坐标）

- `GeoCoder mCoder = GeoCoder.newInstance();`
- `OnGetGeoCoderResultListener` 实现 `onGetGeoCodeResult(GeoCodeResult)` 与 `onGetReverseGeoCodeResult(ReverseGeoCodeResult)`。
- `mCoder.setOnGetGeoCodeResultListener(listener);`
- 发起：`mCoder.geocode(new GeoCodeOption().city("北京").address("北京上地十街10号"));` city 与 address 必填。
- 结果：`geoCodeResult.getLocation()` 得 LatLng，需判 error 是否为 NO_ERROR。

---

## 逆地理编码（坐标 → 地址）

- 同一 GeoCoder 与 listener，在 `onGetReverseGeoCodeResult(ReverseGeoCodeResult)` 中处理。
- 发起：`mCoder.reverseGeoCode(new ReverseGeoCodeOption().location(latLng).newVersion(1).radius(500));` newVersion 0 不返回新版，1 返回；radius 为 POI 召回半径 0–1000 米。
- 结果：`getAddress()`、`getAdcode()`（新版用 getAdcode，与旧版 cityCode 不同）；周边 POI 用 `getPoiList()`。
- V4.5.2+ 通过 ReverseGeoCodeOption.newVersion(1) 获取新版数据。


path: references/reference.md
content: # 百度地图 Android SDK 参考索引

按需选下表文档；通用规则（隐私、AK、MapView 生命周期、监听先于请求、步骑行选型）见 [SKILL.md](../SKILL.md)。

**步骑行**：算路画线（route）与实时导航为**不同服务**——仅画线用 [route.md](route.md)，要诱导/TTS/偏航用步骑行导航（overview + class-reference）。

## 按需求选文档

| 你要做的 | 用到的文档 |
|----------|------------|
| Gradle 依赖、Maven 仓库、地图/检索/工具/定位/步骑行/导航组件、冲突说明 | [gradle.md](gradle.md) |
| AndroidManifest（AK、权限、定位 Service）、混淆、资源与 assets | [project-config.md](project-config.md) |
| 集成步骤、AK、SHA1、包名、Application 初始化、隐私接口 | [overview.md](overview.md) |
| 显示地图、MapView、BaiduMap、生命周期、地图类型、缩放与视野 | [mapview.md](mapview.md) |
| 显示定位、定位图层、定位模式、自定义定位图标 | [location.md](location.md) |
| 点标记、Marker 属性、点击/拖拽、碰撞、Title、3D Marker | [marker.md](marker.md) |
| 折线、多边形、PolylineOptions 属性、虚线、分段颜色/纹理、点击 | [overlays.md](overlays.md) |
| POI 城市/周边/区域/详情、地理编码、逆地理编码 | [search.md](search.md) |
| 驾车/步行/骑行/公交路线规划、Overlay 绘制 | [route.md](route.md) |
| 坐标转换、BD09LL/GCJ02/WGS84、CoordinateConverter | [coordinate.md](coordinate.md) |
| 距离/面积、点与圆/多边形/折线关系、调起百度地图、短地址分享、收藏夹 | [tools.md](tools.md) |
| 检索/路线返回错误码含义 | [errorcode.md](errorcode.md) |
| 类与包速查 | [class-reference.md](class-reference.md) |
| 地图布局、检索/路线面板、Logo/padding、选点/弹窗等 UI 约定 | [ui-standards.md](ui-standards.md) |

## 常见组合

| 需求 | 文档组合 |
|------|----------|
| 地图 + 定位 | gradle → project-config → overview → mapview + location（坐标系统一） |
| 地图 + 路线画线 | mapview + route + search（选点）；步骑行仅画线用 route |
| 步骑行实时导航 | overview → 步行/骑行导航（引擎初始化 → 算路 → 诱导页 → TTS；具体类见 overview 与 class-reference） |
| 标注 + 点聚合 | mapview + marker（点聚合逻辑见 overlay 开源或自实现） |
| POI / 选点 | mapview + search（POI 或地理编码） |
| 定位/鉴权失败、地图闪退 | [location.md](location.md)（如有鉴权排查）+ [project-config.md](project-config.md)（主题、compileSdk、集成经验与常见问题）+ Logcat |

## 文档边界（一览）

| 文档 | 内容 | 边界 |
|------|------|------|
| [gradle.md](gradle.md) | 依赖、冲突、NDK、环境与国内镜像 | 构建报错见 project-config |
| [project-config.md](project-config.md) | AndroidManifest、主题、混淆、集成经验与常见问题 | 仅百度 SDK 相关配置 |
| [overview.md](overview.md) | 集成、AK、隐私、Application、核心类 | 具体 API 见各功能文档 |
| [mapview.md](mapview.md) | MapView、BaiduMap、生命周期、类型、视野 | 不含 Marker/Overlay 具体类型 |
| [location.md](location.md) | 定位图层、模式、自定义图标 | 不含步骑行导航内部定位 |
| [marker.md](marker.md) | Marker、碰撞、Title、3D | 与 overlays 组合使用 |
| [overlays.md](overlays.md) | Polyline、Polygon、折线属性 | 路线 Overlay 见 route |
| [search.md](search.md) | POI、地理编码、逆地理 | 路线算路见 route |
| [route.md](route.md) | RoutePlanSearch、驾车/步行/骑行/公交算路与画线 | 与步骑行实时导航不同；仅算路+画线用本文档 |
| [coordinate.md](coordinate.md) | 坐标转换、BD09LL/GCJ02 | 与 overview 坐标类型一致 |
| [tools.md](tools.md) | 距离、面积、调起地图、短地址 | 工具类，与其它文档组合 |
| [errorcode.md](errorcode.md) | 错误码 | 检索/路线返回码 |
| [class-reference.md](class-reference.md) | 类与包速查 | 用法与示例见各功能文档 |
| [ui-standards.md](ui-standards.md) | 布局结构、面板高度、setViewPadding、fitBounds、检索/路线/选点/弹窗/Logo、触控与边距 | 无特殊要求时按此实现 |

## 能力一览（技能内已覆盖）

- **地图**：MapView/SupportMapFragment/TextureMapView、BaiduMap、地图类型（普通/卫星/空白）、路况/热力、缩放 4–21 级（室内至 22）、BaiduMapOptions、多实例、视野与内边距、底图 POI 显示控制。
- **定位**：定位图层、MyLocationConfiguration、NORMAL/FOLLOWING/COMPASS、自定义图标与精度圈、v7.5.7 自定义中心图/箭头/GIF。
- **覆盖物**：Marker（含动画、碰撞、Title、3D）、Polyline（虚线、分段颜色/纹理、大地曲线、渐变色、发光）、Polygon、信息窗、点聚合、路线 Overlay（开源）。
- **检索**：POI 城市/周边/区域/详情、GeoCoder 正逆地理、输入提示、行政区、AOI、公交、天气等（部分见 search 与 class-reference）。
- **路线**：驾车/步行/骑行/公交规划、PlanNode、RoutePlanSearch、DrivingRouteOverlay 等开源 Overlay。
- **导航**：步行导航、骑行导航（含电动车）、诱导、TTS、偏航纠正（类见 overview/class-reference）。
- **工具**：Gradle 集成、工程配置与混淆、坐标转换、距离/面积、点与图形关系、调起百度地图、短地址分享、地图收藏夹、错误码。


path: references/overview.md
content: # 百度地图 Android SDK 集成与核心 API 摘要

SDK 集成方式：推荐通过 **Gradle** 依赖（见 [gradle.md](gradle.md)）；AndroidManifest、混淆等见 [project-config.md](project-config.md)。

## 使用准备与 AK

1. 申请百度账号并完成开发者认证。
2. 在控制台「应用管理 - 我的应用」创建应用，应用类型选 **Android SDK**，填写：
   - 应用名称、**包名**（与 build.gradle 的 applicationId 一致）、**SHA1**（debug/release 可各填一个）。
   - 勾选所需服务（地图、检索、路线等），未勾选则对应接口可能返回无权限。
3. 将生成的 AK 配置到工程：AndroidManifest 的 `<application>` 内 `<meta-data android:name="com.baidu.lbsapi.API_KEY" android:value="您的AK"/>`，或代码中 `SDKInitializer.setApiKey("ak")`（须在 `initialize` 之前）。包名与签名须与申请一致。鉴权结果由 SDK 通过广播回调（成功/失败/网络错误），失败时 Intent 带错误码与错误信息，排查与广播 Action 见 [project-config.md](project-config.md)。

**SHA1**：调试版 `keytool -list -v -keystore ~/.android/debug.keystore`，默认口令 `android`。发布版用 release keystore。

## 隐私合规（v7.5.0+）

- 调用 SDK 任何接口前必须先调用隐私合规接口，且**必须在 `SDKInitializer.initialize` 之前**调用。
- 定位 SDK：不同意则无法正常获取位置；地图 SDK：不同意则检索、路线等请求异常。
- 统一接口：`SDKInitializer.setAgreePrivacy(Context context, boolean isEnable)`，context 必须为 Application Context；`isEnable` 为 true 表示用户同意隐私政策。
- 推荐写法：在 Application 中先 `setAgreePrivacy`，再在 try-catch 中 `initialize`（可捕获 BaiduMapSDKException）。可按用户是否同意隐私分别设置；未同意时 `setAgreePrivacy(context, false)`，同意后再设为 true 并初始化。

```java
// 用户同意后，必须在 initialize 之前调用
SDKInitializer.setAgreePrivacy(getApplicationContext(), true);
try {
    SDKInitializer.initialize(this);
} catch (BaiduMapSDKException e) {
    // 初始化失败可记录日志
}
SDKInitializer.setCoordType(CoordType.BD09LL);
```

## Application 初始化

```java
public class DemoApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        SDKInitializer.setAgreePrivacy(getApplicationContext(), true); // 必须先于 initialize
        try {
            SDKInitializer.initialize(this);
        } catch (BaiduMapSDKException e) { }
        SDKInitializer.setCoordType(CoordType.BD09LL); // 或 CoordType.GCJ02，自 4.3.0
    }
}
```

## MapView 与 BaiduMap 生命周期

- 布局中声明 `MapView`（或代码 `new MapView(this)`），Activity 中 `mMapView.getMap()` 得到 `BaiduMap`。
- **必须在 Activity 中调用**：`onResume()` → `mMapView.onResume()`；`onPause()` → `mMapView.onPause()`；`onDestroy()` → `mMapView.onDestroy()`。

## 核心类速查

| 用途 | 类/接口 |
|------|---------|
| 初始化、坐标类型 | SDKInitializer、CoordType |
| 地图控件与控制器 | MapView、BaiduMap、SupportMapFragment、TextureMapView |
| 地图状态 | MapStatus、MapStatusUpdate、MapStatusUpdateFactory、MapStatus.Builder |
| 经纬度 | LatLng |
| 点标记 | Marker、MarkerOptions、BitmapDescriptor、BitmapDescriptorFactory |
| 折线/多边形 | Polyline、PolylineOptions、Polygon、PolygonOptions |
| POI 检索 | PoiSearch、PoiCitySearchOption、PoiNearbySearchOption、PoiBoundSearchOption、PoiDetailSearchOption、OnGetPoiSearchResultListener、PoiResult、PoiDetailSearchResult |
| 地理编码 | GeoCoder、GeoCodeOption、ReverseGeoCodeOption、OnGetGeoCoderResultListener、GeoCodeResult、ReverseGeoCodeResult |
| 路线规划 | RoutePlanSearch、DrivingRoutePlanOption、PlanNode、OnGetRoutePlanResultListener、DrivingRouteResult；步行/骑行/公交对应 Option/Result |
| 路线 Overlay（开源） | DrivingRouteOverlay、WalkingRouteOverlay、BikingRouteOverlay、TransitRouteOverlay、PoiOverlay |
| 步行/骑行导航 | WalkNavigateHelper、BikeNavigateHelper、WalkNaviLaunchParam、BikeNaviLaunchParam、诱导与 TTS 监听 |
| 定位 | LocationClient、LocationClientOption、BDAbstractLocationListener、MyLocationData、MyLocationConfiguration、LocationMode |
| 室内图 | BaiduMap.setOnBaseIndoorMapListener、switchBaseIndoorMapFloor |
| 坐标转换 | CoordinateConverter、CoordType.GPS/COMMON/BD09MC 等 |

## 检索与路线注意点

- **监听先于请求**：POI 先 `setOnGetPoiSearchResultListener` 再 `searchInCity`/`searchNearby`/`searchInBound`/`searchPoiDetail`；路线先 `setOnGetRoutePlanResultListener` 再 `drivingSearch`/`walkingSearch` 等。
- 使用完毕后 `destroy()` 释放 PoiSearch、RoutePlanSearch、GeoCoder 等实例。

## 系统与包说明

- 支持 Android 4.0+；支持 armeabi-v7a、arm64-v8a、x86、x86_64。
- 自 V3.6.0 起覆盖物相关类开源（OverlayManager、PoiOverlay、TransitRouteOverlay、WalkingRouteOverlay、DrivingRouteOverlay、BusLineOverlay 等），可从 Demo 的 overlayutil 包获取。
- 自 v4.5.0 支持 HTTPS，V5.3.2 起默认 HTTPS；Android P+ 禁止明文，检索建议用 HTTPS 或配置 network_security_config。


path: references/location.md
content: # 显示定位

## 坐标系说明

- 定位 SDK 支持国内输出：国测局坐标、百度墨卡托、百度经纬度；海外仅 WGS84。定位 SDK 默认输出 GCJ02，地图 SDK 默认 BD09LL；混用时需统一，见 [coordinate.md](coordinate.md)。

## 前置条件

- 开发包需包含定位能力（下载 SDK 时勾选基本定位）。
- AndroidManifest：声明定位相关权限；在 `<application>` 内声明定位 Service 组件。

## 开启定位图层与传数据

1. 开启：`mBaiduMap.setMyLocationEnabled(true)`。
2. 继承 `BDAbstractLocationListener`，在 `onReceiveLocation(BDLocation location)` 中构造 `MyLocationData` 并传给地图：
   - `MyLocationData.Builder().accuracy(radius).direction(direction).latitude(lat).longitude(lng).build()`
   - `mBaiduMap.setMyLocationData(locData)`。
3. 使用 `LocationClient`：`LocationClient option = new LocationClient(context)`，`LocationClientOption` 设置 `setOpenGps`、`setCoorType("bd09ll")`、`setScanSpan` 等，`setLocOption(option)`，`registerLocationListener(myLocationListener)`，`start()`。
4. 生命周期：在 `onDestroy` 中 `mLocationClient.stop()`、`mBaiduMap.setMyLocationEnabled(false)`，再执行 MapView 的 `onDestroy()`。

## MyLocationConfiguration（自定义样式）

构造：`MyLocationConfiguration(LocationMode mode, boolean enableDirection, BitmapDescriptor customMarker, int accuracyCircleFillColor, int accuracyCircleStrokeColor)`。

- **定位模式**：`LocationMode.NORMAL`（普通）、`LocationMode.FOLLOWING`（跟随）、`LocationMode.COMPASS`（罗盘）。
- **自定义定位图标**：`BitmapDescriptorFactory.fromResource(R.drawable.xxx)` 传入。
- **精度圈**：填充色、边框色用 ARGB；精度圈大小由定位精度自动决定，不可手动设。
- 设置：`mBaiduMap.setMyLocationConfiguration(config)`。

## 自定义定位图标（v7.5.7+）

- Builder 构造：`MyLocationConfiguration.Builder(LocationMode locationMode, boolean enableArrow)`，enableArrow 为 true 表示箭头模式，false 为整体模式。
- 方法：`setCustomMarker(BitmapDescriptor)`、`setMarkerSize(float)`（0.2~3 倍）、`setArrow(BitmapDescriptor)`、`setArrowSize(float)`、`setAnimation(boolean)`（中心图呼吸动画，非箭头模式 false）、`setGifMarker(String gifPath)`（中心 gif）。设置后通过 `setMyLocationConfiguration` 生效。

## 注意

- 定位频次在 LocationClientOption 中设置；详见定位 SDK 文档。
- 定位指针方向依赖陀螺仪，需自行处理，不在地图 SDK 范畴。


path: references/marker.md
content: # 点标记（Marker）

## 添加 Marker

- `LatLng point = new LatLng(lat, lng);`
- `BitmapDescriptor bitmap = BitmapDescriptorFactory.fromResource(R.drawable.xxx);`
- `OverlayOptions option = new MarkerOptions().position(point).icon(bitmap);`
- `mBaiduMap.addOverlay(option);` 返回 Overlay，可强转为 Marker。

## MarkerOptions 常用属性

| 名称 | 说明 |
|------|------|
| icon | 图标 BitmapDescriptor |
| animateType | 动画类型：MarkerAnimateType.none / drop / grow / jump |
| alpha | 透明度 |
| position | 位置 LatLng |
| perspective | 是否近大远小，默认 true |
| draggable | 是否可拖拽 |
| flat | 是否平贴地图（俯视效果） |
| anchor | 锚点比例 |
| rotate | 旋转角度 |
| title | 标题 |
| visible | 是否可见 |
| extraInfo | 额外信息 Bundle |

示例：`.position(point).icon(bitmap).draggable(true).flat(true).alpha(0.5f)`。

## 事件

- **点击**：`mBaiduMap.setOnMarkerClickListener(BaiduMap.OnMarkerClickListener)`，`onMarkerClick(Marker marker)`，返回 true 表示消费事件。
- **拖拽**：需在 MarkerOptions 中 `draggable(true)`；`setOnMarkerDragListener`，回调 `onMarkerDrag`、`onMarkerDragEnd`、`onMarkerDragStart`。

## 底图标注

- `mBaiduMap.showMapPoi(false)` 可隐藏底图 POI，仅显示道路。

## Marker 碰撞策略（v7.5.0+）

- 属性：`isJoinCollision`（是否参与碰撞）、`isForceDisplay`（参与后是否强制展示）、`priority`（碰撞优先级，默认整型最大）、`startLevel`/`endLevel`（最小/最大展示层级，室外默认 4–21，室内至 22）。
- 使用：`MarkerOptions().position(...).icon(...).isJoinCollision(true).isForceDisplay(true).priority(9)`，再 `addOverlay` 即生效。

## 3D Marker（v7.5.2+）

- 带高度的 Marker：先设高度，用 `projection.geoPoint3toScreenLocation(LatLng, height)` 转成屏幕点，再用 `projection.fromScreenLocation(Point)` 转回经纬度，然后按普通 Marker 添加。

## Marker 的 Title（v7.5.7+）

- 通过 `TitleOptions`：titleBgColor、titleFrontColor、titleFrontSize、titleAnchorX/Y、titileOffsetX/Y、titleRotate。
- `MarkerOptions.titleOptions(titleOptions)`。

## Marker 碰撞 POI（v7.5.7+）

- `MarkerOptions.poiCollided(true)` 使 Marker 及其 title 可与底图 POI 碰撞。


path: references/gradle.md
content: # Gradle 集成 SDK

Android 推荐通过 Gradle 依赖集成百度地图 SDK（国内版）。Google 渠道等需使用一体化包时请从官网下载后按「本地依赖」方式集成。

**版本**：以下以 7.6.x / 9.6.x 为例，实际以官网更新为准。不写版本号可改为 `+` 或具体版本号；API 以工程内依赖版本为准，类/方法不存在时提示更新依赖，见 [SKILL.md](../SKILL.md) 规则 6。

## 1. 配置仓库

在 **Project** 的 `build.gradle` 中配置 `repositories`，添加 mavenCentral：

```gradle
allprojects {
    repositories {
        mavenCentral()
    }
}
```

若项目已使用 `dependencyResolutionManagement`（Gradle 7+），在 `settings.gradle` 或对应块中为百度 SDK 提供 mavenCentral 即可。

## 2. 主工程依赖（app/build.gradle）

在 **app** 的 `build.gradle` 的 `dependencies` 中按需添加。常用组合示例：

| SDK | 依赖 |
|-----|------|
| 地图组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Map:7.6.7'` |
| 检索组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Search:7.6.7'` |
| 工具组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Util:7.6.7'` |
| 步骑行导航组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Map-BWNavi:7.6.7'` |
| 基础定位组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Location:9.6.6'` |
| 全量定位组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Location_All:9.6.6'` |
| 驾车导航组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Map-Navi:7.6.7'` |
| 驾车+步骑行导航 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Map-AllNavi:7.6.7'` |
| TTS 组件 | `implementation 'com.baidu.lbsyun:NaviTts:3.2.13'` |
| 全景组件 | `implementation 'com.baidu.lbsyun:BaiduMapSDK_Panorama:2.9.0'` |

**仅地图+检索+工具**示例：

```gradle
dependencies {
    implementation 'com.baidu.lbsyun:BaiduMapSDK_Map:7.6.7'
    implementation 'com.baidu.lbsyun:BaiduMapSDK_Search:7.6.7'
    implementation 'com.baidu.lbsyun:BaiduMapSDK_Util:7.6.7'
}
```

## 3. 组件冲突说明

以下各组内**只能选其一**，不能同时引入：

| 组 | 可选依赖 |
|----|----------|
| 定位 | 基础定位 `BaiduMapSDK_Location` **或** 全量定位 `BaiduMapSDK_Location_All` |
| 地图/导航 | 地图 `BaiduMapSDK_Map`、步骑行 `BaiduMapSDK_Map-BWNavi`、驾车导航 `BaiduMapSDK_Map-Navi`、全部导航 `BaiduMapSDK_Map-AllNavi` 中选一（后三者已含地图） |

按需求选：仅展示地图+检索用 Map+Search+Util；要步骑行实时导航用 Map-BWNavi；要驾车导航用 Map-Navi 或 Map-AllNavi。

## 4. NDK 架构（abiFilters）

在 app 的 `build.gradle` 的 `android.defaultConfig` 中配置 so 架构，按需保留：

```gradle
android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
        }
    }
}
```

说明：官方文档曾包含 "armeabi"，目前新包多已不再提供，以实际 SDK 为准。

## 5. 注意事项

- **Gradle 仅支持国内版**：若需 Google 渠道或其它定制包，请到官网下载一体化包，采用「下载 SDK 本地依赖」方式（jar + so 放入 libs/jniLibs，并在 build.gradle 中配置 sourceSets 与 implementation fileTree）。
- 集成完成后需配置 **AndroidManifest**（AK、权限、定位 Service）与 **混淆规则**，见 [project-config.md](project-config.md)；Application 初始化与隐私见 [overview.md](overview.md)。

## 6. 环境与镜像（集成经验）

以下为实际构建时的常见问题与处理，便于 Sync / 运行一次通过。

| 问题 | 处理 |
|------|------|
| **Java 21 与 Gradle 8.2 不兼容** | 升级到 Gradle 8.7（或 8.5+），并同步升级 Android Gradle Plugin（如 8.5.2）。在 `gradle-wrapper.properties` 中设置 `distributionUrl=.../gradle-8.7-bin.zip`。 |
| **Downloading gradle-8.7-bin.zip timeout** | 国内网络可将 `distributionUrl` 改为腾讯云镜像：`https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip`；并把 `networkTimeout=10000` 改为 `60000`。 |
| **NoClassDefFoundError: org/gradle/wrapper/IDownload** | 工程里的 `gradle-wrapper.jar` 与 Gradle 版本不一致（如仍为 8.2 的 jar 却用 8.7 的 distribution）。需替换为与 8.7 对应的 [官方 gradle-wrapper.jar](https://raw.githubusercontent.com/gradle/gradle/v8.7.0/gradle/wrapper/gradle-wrapper.jar)，校验 SHA-256 见 [Gradle release-checksums](https://gradle.org/release-checksums/)。 |
| **无法定位 Java Runtime** | 终端/IDE 需能找到 JDK。macOS 下可把 Android Studio 自带 JDK 写入 `~/.zshrc`：`export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"` 与 `export PATH="$JAVA_HOME/bin:$PATH"`。 |


path: references/errorcode.md
content: # 错误码对照表

检索、路线等接口返回结果中带 error/errorCode 时，可参考下表。更多可查官方错误码文档。

| 状态码 | 含义 |
|--------|------|
| 0 | 正常 |
| 1 | 服务器内部错误（超时或系统错误） |
| 10 | 上传内容超过 8M |
| 101 | AK 参数不存在 |
| 102 | mcode 参数不存在（Mobile 类型必需 Mcode） |
| 200 | APP 不存在，AK 有误 |
| 201 | APP 被用户禁用 |
| 202 | APP 被管理员删除 |
| 203 | APP 类型错误（Server/Mobile/Browser 等） |
| 210 | APP IP 校验失败 |
| 211 | APP SN 校验失败 |
| 220 | APP Referer 校验失败 |
| 230 | APP Mcode 校验失败 |
| 240 | APP 服务被禁用 |
| 250 | 用户不存在 |
| 251 | 用户被自己删除 |
| 252 | 用户被管理员删除 |
| 260 | 服务不存在 |
| 261 | 服务被禁用 |
| 301 | 永久配额超限 |
| 302 | 天配额超限 |
| 401 | 并发量超过约定并发配额 |
| 402 | 并发超限且总并发也超总配额 |

检索/路线结果判断：结果类（如 PoiResult、DrivingRouteResult）有 **result.error** 字段，类型为 **SearchResult.ERRORNO**（枚举）。成功：`result.error == SearchResult.ERRORNO.NO_ERROR`。

### 路线规划常用 ERRORNO

| 枚举值 | 含义 |
|--------|------|
| NO_ERROR | 成功 |
| RESULT_NOT_FOUND | 未找到路线 |
| AMBIGUOUS_ROURE_ADDR | 起终点或途经点地址歧义，可 result.getSuggestAddrInfo() |

### POI 检索常用 ERRORNO

| 枚举值 | 含义 |
|--------|------|
| NO_ERROR | 成功 |
| RESULT_NOT_FOUND | 未找到 |
| AMBIGUOUS_KEYWORD | 关键字在本市无、其他城市有，可 result.getSuggestCityList() |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)