Android 高德地图 SDK 集成（一）：基础地图显示

从今天开始我记录一下在 Android 应用中集成高德地图 3D SDK，兵实时位置追踪、电子围栏等功能。本文以 Java 语言开发，包名 com.example.smartpetlink。

---

1. 准备工作

1.1 注册高德开放平台并获取 API Key

1. 访问 高德开放平台 注册/登录。

2. 进入控制台 → 应用管理 → 创建新应用，选择 Android 平台。

3. 获取 API Key （例如 abc123...），后续代码中需要填入。keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

1.2 创建 Android 项目

新建 Empty Views Activity 项目，包名 com.example.smartpetlink，最低 SDK 21，语言 Java。

---

2. 配置依赖与权限

2.1 添加高德地图 SDK 依赖

编辑 app/build.gradle.kts（如果使用 Groovy 则对应 build.gradle），关键配置如下：

android {
    namespace = "com.example.smartpetlink"
    compileSdk = 33

    defaultConfig {
        applicationId = "com.example.smartpetlink"
        minSdk = 21
        targetSdk = 33
        versionCode = 1
        versionName = "1.0"

        // 指定 so 库架构，解决 native 库加载问题
        ndk {
            abiFilters.addAll(listOf("armeabi-v7a", "arm64-v8a"))
        }
    }
}

dependencies {
    implementation("com.amap.api:3dmap:10.0.600")
    // 其他基础依赖省略...
}

说明 ：高德地图 3D SDK 已包含地图显示所需的所有功能，无需额外引入定位包。abiFilters 配置可确保 so 库正确打包。

2.2 添加网络权限和 API Key

在 AndroidManifest.xml 中声明：

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

<application ...>
    <meta-data
        android:name="com.amap.api.v2.apikey"
        android:value="你的API Key" />
</application>

---

3. 实现地图显示

3.1 布局文件 activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    
    <com.amap.api.maps.TextureMapView
        android:id="@+id/map_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
        
</FrameLayout>

提示 ：使用 TextureMapView 可避免部分机型上的渲染黑屏问题。

3.2 Activity 核心代码 MainActivity.java

package com.example.smartpetlink;

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.amap.api.maps.AMap;
import com.amap.api.maps.TextureMapView;
import com.amap.api.maps.model.LatLng;
import com.amap.api.maps.model.MarkerOptions;

public class MainActivity extends AppCompatActivity {
    private TextureMapView mapView;
    private AMap aMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // 隐私合规（必须最先调用）
        com.amap.api.maps.MapsInitializer.updatePrivacyShow(this, true, true);
        com.amap.api.maps.MapsInitializer.updatePrivacyAgree(this, true);

        mapView = findViewById(R.id.map_view);
        mapView.onCreate(savedInstanceState);

        aMap = mapView.getMap();
        aMap.setMapType(AMap.MAP_TYPE_NORMAL);

        // 添加一个测试标记
        LatLng beijing = new LatLng(39.904989, 116.405285);
        aMap.addMarker(new MarkerOptions().position(beijing).title("天安门"));
        aMap.moveCamera(com.amap.api.maps.CameraUpdateFactory.newLatLngZoom(beijing, 12));
    }

    // 生命周期管理
    @Override protected void onResume() { super.onResume(); mapView.onResume(); }
    @Override protected void onPause() { super.onPause(); mapView.onPause(); }
    @Override protected void onDestroy() { super.onDestroy(); mapView.onDestroy(); }
    @Override protected void onSaveInstanceState(Bundle outState) { super.onSaveInstanceState(outState); mapView.onSaveInstanceState(outState); }
}

---

4. 常见问题与解决

4.1 地图黑屏但左下角有"高德地图"字样

• 原因：so 库未正确加载或 CPU 架构不匹配。

• 解决：在 build.gradle 中配置 abiFilters（如上述），并确保使用 TextureMapView。

4.2 UnsatisfiedLinkError: No implementation found

• 原因：so 库未打包进 APK。

• 解决：检查 abiFilters 配置，Clean 并 Rebuild 项目。

4.3 地图显示空白或网格

• 原因：网络问题或 API Key 无效。

• 解决：确认网络畅通，Key 已启用地图服务，并检查 AndroidManifest.xml 中 Key 的配置。

---

5. 结语

至此，你已经成功在应用中集成了高德地图，并看到地图显示。下一步我们将实现从云平台获取宠物实时位置并在地图上标记，敬请期待后续教程。

6. 结果展示