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。

      添加一个地图 activity。

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

    4. 选择 Finish。

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

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

设置 Google Cloud 项目

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

第 1 步

控制台

  1. 在 Google Cloud 控制台中，打开项目选择器页面，点击创建项目以开始创建新的 Cloud 项目。

    转到项目选择器页面

  2. 确保您的 Cloud 项目已启用结算功能。 确认您的项目已启用结算功能。

    Google Cloud 提供免费试用。试用期将在 90 天后或者账号费用累积达到 300 美元时（以先到者为准）结束。您随时可以取消试用。Google Maps Platform 每月定期提供 200 美元的赠金。如需了解详情，请参阅结算账号赠金和结算。

Cloud SDK

gcloud projects create "PROJECT"

您可以详细了解 Google Cloud SDK、Cloud SDK 安装和以下命令：

第 2 步

如要使用 Google Maps Platform，您必须启用计划用于项目的 API 或 SDK。

控制台

启用 Maps SDK for Android

Cloud SDK

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

您可以详细了解 Google Cloud SDK、Cloud SDK 安装和以下命令：

第 3 步

此步骤仅包含 API 密钥的创建流程。如要在生产环境中使用 API 密钥，强烈建议您为相应密钥设置限制。如需了解详情，请参阅相应产品的使用 API 密钥页面。

API 密钥是唯一标识符，用于对与您的项目相关联的请求进行身份验证，以便计算用量和执行结算。您必须至少有一个与您项目相关联的 API 密钥。

如需创建 API 密钥，请执行以下操作：

控制台

  1. 前往 Google Maps Platform > 凭据页面。

    前往“凭据”页面

  2. 在凭据页面上，依次点击创建凭据 > API 密钥。
    已创建的 API 密钥对话框会显示您新创建的 API 密钥。
  3. 点击关闭。
    新的 API 密钥即会列在凭据页面的 API 密钥下。
    （在生产环境中使用 API 密钥之前，请务必对 API 密钥设置限制。）

Cloud SDK

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

您可以详细了解 Google Cloud SDK、Cloud SDK 安装和以下命令：

向应用添加 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}" />

    Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

  10. In Android Studio, open your module-level build.gradle.kts or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other 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 语言功能。