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 5.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 19.0.x 版所要求的最低版本，也就是 Android API 级别 21（“Lollipop”；Android 5.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 alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

向应用添加 API 密钥

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

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

如需在 Google 地图项目中安装 Android 版 Secret Gradle 插件，请执行以下操作：

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

   Kotlin

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

   Groovy

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

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

   Kotlin

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

   Groovy

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

3. 在模块级 build.gradle.kts 或 build.gradle 文件中，请务必将 targetSdk 和 compileSdk 设置为 34。
4. 保存文件并将项目与 Gradle 同步。
5. 在顶级目录中打开 secrets.properties 文件，然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。secrets.properties 不会签入版本控制系统，因此请将您的密钥存储在此文件中。

   MAPS_API_KEY=YOUR_API_KEY

6. 保存文件。

7. 在顶级目录（即 secrets.properties 文件所在的文件夹）中创建 local.defaults.properties 文件，然后添加以下代码。

   MAPS_API_KEY=DEFAULT_API_KEY

   此文件的作用是为 API 密钥提供备用位置，以免在找不到 secrets.properties 文件的情况下构建失败。如果您是从省略 secrets.properties 的版本控制系统中克隆应用，而您还没有在本地创建 secrets.properties 文件来提供 API 密钥，就可能会出现构建失败。

8. 保存文件。
9. 在 AndroidManifest.xml 文件中，定位到 com.google.android.geo.API_KEY 并更新 android:value attribute。如果 <meta-data> 标记不存在，请创建该标记作为 <application> 标记的子标记。

   <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 Maps API v2 的身份验证。应用只能指定其中一个 API 密钥元数据名称。如果两个都指定，API 会抛出异常。

10. 在 Android Studio 中，打开模块级 build.gradle.kts 或 build.gradle 文件，然后修改 secrets 属性。如果 secrets 属性不存在，请添加该属性。

    修改该插件的属性，将 propertiesFileName 设置为 secrets.properties、将 defaultPropertiesFileName 设置为 local.defaults.properties，并设置任何其他属性。

    Kotlin

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Groovy

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

查看代码

您应检查此模板提供的代码，特别是要查看 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("com.google.android.gms:play-services-maps:19.0.0")
}

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

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 语言功能。