百度地圖 Android SDK 提供地圖展示、定位、檢索、路線規劃、鷹眼軌跡等 LBS 能力。本文覆蓋 **Key 申請、Gradle 依賴/手動導入、Manifest 權限與組件配置、地圖容器初始化、定位 SDK 聯動、POI 檢索、生命週期綁定、常見坑點** 的完整流程。
// build.gradle (Project)
allprojects {
repositories {
google()
mavenCentral()
maven { url 'https://mapopen-website-wiki.bj.bcebos.com/android-sdk/' } // 百度 Maven 倉庫
}
}
// build.gradle (Module)
dependencies {
implementation 'com.baidu.mapapi:base:7.5.0' // 基礎庫 (必須)
implementation 'com.baidu.mapapi:map:7.5.0' // 地圖功能
implementation 'com.baidu.mapapi:search:7.5.0' // 檢索功能 (POI/路線/地理編碼)
implementation 'com.baidu.mapapi:location:7.5.0' // 定位功能
implementation 'com.baidu.mapapi:util:7.5.0' // 工具類
// 若需步行/騎行/駕車導航
implementation 'com.baidu.mapapi:navi:7.5.0'
}
手動導入 (不推薦):下載開發包 → `libs/` 放入 `.jar`、`jniLibs/arm64-v8a/armeabi-v7a/` 放入 `.so` → `File > New > Module > Import .JAR/.AAR` 或配置 `sourceSets`。
<manifest ...>
<!-- 權限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" /> <!-- 定位 SDK 需 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <!-- 緩存地圖數據,Android 10+ 可不寫 -->
<application ...>
<!-- 全域 AK 設定 (Meta-data 名固定) -->
<meta-data
android:name="com.baidu.lbsapi.API_KEY"
android:value="您的_AK_字串" />
<!-- 地圖 Activity 需配置 configChanges 防止旋轉重建 -->
<activity
android:name=".MapActivity"
android:configChanges="orientation|screenSize|keyboardHidden"
android:screenOrientation="sensor"
android:exported="true">
</activity>
<!-- 定位 Service (SDK 內部使用) -->
<service
android:name="com.baidu.location.f"
android:enabled="true"
android:exported="false"
android:process=":remote" />
</application>
</manifest>
public class MapApp extends Application {
public static BMapManager mapManager;
@Override
public void onCreate() {
super.onCreate();
initMapManager();
}
private void initMapManager() {
if (mapManager == null) {
mapManager = new BMapManager(this);
}
// 初始化:AK + 通用事件監聽 (網路錯誤、Key 驗證失敗等)
boolean success = mapManager.init(getString(R.string.baidu_map_ak), new MKGeneralListener() {
@Override
public void onGetPermissionState(int iError) {
if (iError != 0) Log.e(TAG, "AK 驗證失敗: " + iError); // 非 0 為失敗
}
@Override
public void onGetNetworkState(int iError) {
if (iError != 0) Log.w(TAG, "網路異常: " + iError);
}
});
if (!success) Log.e(TAG, "BMapManager init failed");
}
}
在 Manifest `
public class MapActivity extends AppCompatActivity {
private MapView mapView;
private BMapManager mapManager;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// 1. 獲取全局 BMapManager
mapManager = MapApp.mapManager;
if (mapManager == null) { finish(); return; }
// 2. 啟動 SDK (每個使用地圖/定位/檢索的 Activity 必須在 onCreate/onResume 調用)
mapManager.start();
setContentView(R.layout.activity_map);
mapView = findViewById(R.id.bmapView);
// 3. 地圖基礎配置
mapView.setBuiltInZoomControls(true); // 內置縮放控件
mapView.getController().setZoom(16); // 初始縮放級別 3-21
mapView.getController().enableClick(true);
}
@Override
protected void onResume() {
super.onResume();
mapManager.start(); // 重新啟動 (配合 onPause.stop)
mapView.onResume(); // MapView 自身生命週期
}
@Override
protected void onPause() {
super.onPause();
mapManager.stop(); // 停止 SDK (釋放網路、傳感器、定位)
mapView.onPause();
}
@Override
protected void onDestroy() {
super.onDestroy();
mapView.onDestroy(); // 釋放地圖資源 (關鍵!防洩漏)
// 注意:BMapManager.destroy() 僅在 Application onTerminate/進程結束時調用,不要在 Activity 調用
}
}
<com.baidu.mapapi.map.MapView
xmlns:android="https://schemas.android.com/apk/res/android"
android:id="@+id/bmapView"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:clickable="true" />
// 在 MapActivity 或獨立 Service 中
LocationClient locationClient = new LocationClient(getApplicationContext());
LocationClientOption option = new LocationClientOption();
option.setLocationMode(LocationClientOption.LocationMode.Hight_Accuracy); // 高精度 (GPS+網路)
option.setCoorType("bd09ll"); // 返回百度經緯度 (bd09ll/gcj02/bd09)
option.setScanSpan(5000); // 定時定位間隔 5 秒 (≥1000ms)
option.setIsNeedAddress(true); // 返回地址信息
option.setOpenGps(true); // 使用 GPS
option.setLocationNotify(true); // 位置變化通知
locationClient.setLocOption(option);
locationClient.registerLocationListener(new BDLocationListener() {
@Override
public void onReceiveLocation(BDLocation location) {
if (location == null || mapView == null) return;
// 更新地圖中心點
LatLng ll = new LatLng(location.getLatitude(), location.getLongitude());
MapStatusUpdate u = MapStatusUpdateFactory.newLatLngZoom(ll, 18);
mapView.getController().animateMapStatus(u);
// 顯示定位圖層 (MyLocationOverlay 已棄用,新版用 MyLocationConfiguration)
MyLocationConfiguration config = new MyLocationConfiguration(
MyLocationConfiguration.LocationMode.FOLLOWING, true, null);
mapView.setMyLocationConfiguration(config);
mapView.setMyLocationEnabled(true);
}
});
locationClient.start(); // 啟動定位
// 需停止時:locationClient.stop();
PoiSearch poiSearch = PoiSearch.newInstance();
poiSearch.setOnGetPoiSearchResultListener(new OnGetPoiSearchResultListener() {
@Override
public void onGetPoiResult(PoiResult result) {
if (result.error == SearchResult.ERRORNO.NO_ERROR) {
// result.getAllPoi() 列表,添加 Marker 到地圖
for (PoiInfo poi : result.getAllPoi()) {
MarkerOptions o = new MarkerOptions().position(poi.location).title(poi.name);
mapView.getController().addMarker(o);
}
}
}
@Override public void onGetPoiDetailResult(PoiDetailResult result) { /* 詳情 */ }
@Override public void onGetPoiIndoorResult(PoiIndoorResult result) { /* 室內 */ }
});
// 關鍵字檢索
poiSearch.searchInCity(new PoiCitySearchOption()
.city("北京")
.keyword("咖啡")
.pageNum(0)
.pageCapacity(20));
// 周邊檢索
poiSearch.searchNearby(new PoiNearbySearchOption()
.location(new LatLng(39.9, 116.4))
.keyword("餐廳")
.radius(1000));
| 問題 | 原因與解決 |
|---|---|
| 地圖白屏/灰格 | AK 錯誤/包名不匹配/簽名 SHA1 錯誤/網路不通/未調用 `mapManager.start()`。檢查 Logcat `MKGeneralListener.onGetPermissionState` 非 0 錯誤碼。 |
| 定位失敗/偏移大 | 未開啟 GPS/定位權限被拒/室內無 GPS/坐標系不匹配 (百度用 bd09ll,高德/Google 用 gcj02/wgs84)。 |
| 崩潰 `UnsatisfiedLinkError` | .so 架構不匹配 (缺 arm64-v8a/armeabi-v7a)、未正確載入、多進程衝突 (定位 Service `:remote` 進程)。 |
| 記憶體洩漏/OOM | 未在 `onDestroy` 調用 `mapView.onDestroy()`、大量 Marker 不回收、Bitmap 未復用。 |
| Android 10+ 儲存權限 | 地圖緩存目錄遷移至 `getExternalFilesDir()`,移除 `WRITE_EXTERNAL_STORAGE` 強依賴。 |
接入百度地圖 SDK 關鍵在於:**正確 AK + Manifest 權限與 Meta-data + Application 全局 BMapManager 初始化 + Activity 生命週期精確綁定 (start/stop/onDestroy) + 定位/檢索 API 正確參數**。遵循本文流程並注意版本適配,即可穩定接入地圖、定位、搜索核心能力。