Maps SDK for Android 快速入门

您可以使用适用于 Android Studio 的 Google 地图景观模板来开发能显示地图的 Android 应用。如要设置现有的 Android Studio 项目，请参阅设置 Android Studio 项目。

本快速入门指南面向熟悉 Kotlin 或 Java，能够使用它们进行基本 Android 开发的开发者。

关于开发环境

本快速入门指南演示的是使用 Android Studio Hedgehog 和 Android Gradle 插件 8.2 版的开发环境。

设置 Android 设备

如要运行使用 Maps SDK for Android 的应用，您必须将其部署到搭载 Android 6.0 或更高版本且包含 Google API 的 Android 设备或 Android 模拟器上。

• 如要使用 Android 设备，请按照在硬件设备上运行应用一文中的说明操作。
• 如要使用 Android 模拟器，您可以使用 Android Studio 随附的 Android 虚拟设备 (AVD) 管理器来创建虚拟设备并安装模拟器。

在 Android Studio 中创建 Google 地图项目

在 Flamingo 及更高版本的 Android Studio 中，创建 Google 地图项目的步骤有所更改。

1. 打开 Android Studio，然后在 Welcome to Android Studio 窗口中点击 New Project。

2. 在 New Project 窗口的 Phone and Tablet 类别下，选择 No Activity，然后点击 Next。

3. 填写 New Project 表单：

   • 将 Language 设置为“Java”或“Kotlin”。Maps SDK for Android 完全支持这两种语言。如需详细了解 Kotlin，请参阅使用 Kotlin 开发 Android 应用一文。

   • 将 Minimum SDK 设置为与您的测试设备兼容的 SDK 版本。您选择的版本必须高于 Maps SDK for Android 20.0.x 版所要求的最低版本，即 Android API 级别 23（“Marshmallow”；Android 6.0）或更高级别。如需了解有关 SDK 版本要求的最新信息，请参阅版本说明。

   • 将 Build configuration language 设置为“Kotlin DSL”或“Groovy DSL”。这两种 build 配置语言的代码段如以下步骤所示。

4. 点击 Finish。

   Android Studio 会启动 Gradle 并构建此项目。此过程可能需要一段时间。

5. 添加 Google Maps Views Activity：

   1. 右键点击您项目中的 app 文件夹。

   2. 依次点击 New > Google > Google Maps Views Activity。

      

   3. 在 New Android Activity 对话框中，选中 Launcher Activity 复选框。

   4. 选择 Finish。

      如需了解详情，请参阅基于模板添加代码

6. 构建完成后，Android Studio 会打开 AndroidManifest.xml 和 MapsActivity 文件。您的 activity 名称可能与示例中显示的不同，但会是您在设置过程中配置的名称。

设置您的 Google Cloud 项目

请依次点击以下标签页，完成所需的 Cloud 控制台设置步骤：

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

向您的应用添加 API 密钥

本部分介绍了如何存储 API 密钥，以便您的应用可以安全引用相应密钥。您不应将 API 密钥签入版本控制系统，因此建议您将其存储在项目根目录下的 secrets.properties 文件中。如需详细了解 secrets.properties 文件，请参阅 Gradle 属性文件。

为了简化此任务，建议您使用 Android 版 Secret Gradle 插件。

如需安装 Android 版 Secrets Gradle 插件并存储您的 API 密钥，请执行以下操作：

1. 在 Android Studio 中，打开根级 build.gradle 文件，并将以下代码添加到 buildscript 下的 dependencies 元素中。

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

2. 打开应用级 build.gradle 文件，并将以下代码添加到 plugins 元素中。

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. 如果您使用 Android Studio，请将项目与 Gradle 同步。
4. 在项目级目录中打开 local.properties，然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。

   MAPS_API_KEY=YOUR_API_KEY

5. 在 AndroidManifest.xml 文件中，定位到 com.google.android.geo.API_KEY 并按如下所示更新 android:value 属性：

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   注意：建议使用 com.google.android.geo.API_KEY 作为 API 密钥的元数据名称。您可以使用采用该名称的密钥接受 Android 平台上多个基于 Google 地图的 API（包括 Maps SDK for Android）的身份验证。为了实现向后兼容性，该 API 还支持使用 com.google.android.maps.v2.API_KEY 作为名称。但使用该旧名称时，密钥只能接受 Android 地图 API v2 的身份验证。应用只能指定其中一个 API 密钥元数据名称。如果两个都指定，API 会抛出异常。

查看代码

您应检查此模板提供的代码，特别是要查看 Android Studio 项目中的下列文件。

地图 activity 文件

地图 activity 文件是应用的主要 activity，包含用于管理和显示地图的代码。默认情况下，该 activity 是由名为 MapsActivity.java 的文件定义的；如果您将 Kotlin 设置为编写应用的语言，则由名为 MapsActivity.kt 的文件来定义。

地图 activity 的主要元素如下：

• SupportMapFragment 对象 - 此对象可管理地图的生命周期，是应用界面的父元素。

• GoogleMap 对象 - 此对象可用于访问地图数据和视图，是 Maps SDK for Android 的主类。地图对象指南详细介绍了 SupportMapFragment 和 GoogleMap 对象。

• moveCamera 函数 - 此函数可将地图中心设置为澳大利亚悉尼的 LatLng 坐标。添加地图时，首先要配置的设置通常是地图位置和镜头设置，如视角、地图方向和缩放级别。如需了解详情，请参阅镜头和视图指南。

• addMarker 函数 - 此函数可向悉尼的坐标添加一个标记。如需了解详情，请参阅标记指南。

模块 Gradle 文件

模块 build.gradle.kts 文件包含以下地图依赖项，这是 Maps SDK for Android 所必需的。

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

如需详细了解如何管理地图依赖项，请参阅版本控制。

XML 布局文件

activity_maps.xml 文件是定义应用界面结构的 XML 布局文件。该文件位于 res/layout 目录中。activity_maps.xml 文件会声明包含以下元素的 fragment：

• tools:context - 此元素会将 fragment 的默认 activity 设置为地图 activity 文件中定义的 MapsActivity。
• android:name - 此元素会将 fragment 的类名称设置为 SupportMapFragment，即地图 activity 文件中使用的 fragment 类型。

XML 布局文件包含以下代码：

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

部署并运行应用

应用成功运行后，将会显示一个以澳大利亚悉尼为中心的地图，且在该城市上会带有一个标记，如以下屏幕截图所示。

如需部署并运行应用，请按以下步骤操作：

1. 在 Android Studio 中，点击 Run 菜单选项（或 Play 按钮图标），以运行您的应用。
2. 当系统提示您选择设备时，请选择以下选项之一：
   • 选择与您计算机相连的 Android 设备。
   • 或者选择 Launch emulator 单选按钮，然后选择您设置过的虚拟设备。
3. 点击 OK。Android Studio 将启动 Gradle 来构建您的应用，然后在设备或模拟器上显示结果。应用可能需要几分钟才能启动。

后续步骤

• 设置地图：此文档介绍了如何设置地图的初始设置和运行时设置，例如镜头位置、地图类型、界面组件和手势。

• 将地图添加到您的 Android 应用 (Kotlin)：此 Codelab 将引导您构建一款应用，从而演示 Maps SDK for Android 的一些其他功能。

• 使用 Maps Android KTX 库：此 Kotlin 扩展 (KTX) 库可让您在使用 Maps SDK for Android 的同时利用多种 Kotlin 语言功能。