萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

Android 接入百度地圖 SDK 完整教程:Key 申請、工程配置、地圖顯示、定位、檢索與生命週期管理

前言

百度地圖 Android SDK 提供地圖展示、定位、檢索、路線規劃、鷹眼軌跡等 LBS 能力。本文覆蓋 **Key 申請、Gradle 依賴/手動導入、Manifest 權限與組件配置、地圖容器初始化、定位 SDK 聯動、POI 檢索、生命週期綁定、常見坑點** 的完整流程。

1. 申請 AK (Access Key)

  1. 訪問 百度地圖開放平台 → 控制台 → 應用管理 → 創建應用。
  2. 應用類型選 **Android SDK**,填寫包名 (如 `com.example.mapdemo`)、簽名 SHA1 (Release/Debug 皆需)。
    獲取 SHA1:`./gradlew signingReport` 或 `keytool -list -v -keystore debug.keystore -alias androiddebugkey -storepass android -keypass android`。
  3. 提交審核 (通常即時通過),獲得 **AK (字母數字串)**。

2. 工程接入 (Gradle 推薦)

// 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`。

3. AndroidManifest.xml 完整配置

<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>

4. Application 中初始化 BMapManager (全局單例)

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 `` 指定。

5. 地圖 Activity 生命週期綁定 (核心!)

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 調用
    }
}

6. 佈局文件

<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" />

7. 定位功能 (LocationClient)

// 在 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();

8. POI 檢索 (關鍵字/周邊/區域)

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));

9. 常見坑點與解決

問題原因與解決
地圖白屏/灰格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` 強依賴。

現代化建議

  • 新專案考慮 **Mapbox / Google Maps SDK / 高德地圖 / 騰訊位置服務**,根據業務區域 (國內/海外)、授權成本、功能豐富度選型。
  • 百度地圖 SDK 更新頻率較低,部分 API 設計較舊 (Listener 介面、同步回呼),建議封裝 **協程/Flow/Kotlin 封裝層** 統一錯誤處理與生命週期。
  • 使用 **ViewBinding/DataBinding** 綁定 `MapView`,避免 `findViewById`。

總結

接入百度地圖 SDK 關鍵在於:**正確 AK + Manifest 權限與 Meta-data + Application 全局 BMapManager 初始化 + Activity 生命週期精確綁定 (start/stop/onDestroy) + 定位/檢索 API 正確參數**。遵循本文流程並注意版本適配,即可穩定接入地圖、定位、搜索核心能力。

copyright © 萬盛學電腦網 all rights reserved