Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Maps SDK for Android 快速入门

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

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

关于开发环境

我们建议您使用最新稳定版的 Android Studio 和 Android Gradle 插件。

设置 Android 设备

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

如要使用 Android 设备，请按照在硬件设备上运行应用一文中的说明操作。
如要使用 Android 模拟器，您可以使用 Android Studio 随附的设备管理器来创建虚拟设备并安装模拟器。
注意：如果您选择使用 Android 模拟器，请务必选择带有 Google Play 图标（显示在 Play 列中）的设备配置文件。此图标表明相应设备的配置完全符合 CTS 规范，并且可以使用包含 Play 商店应用的系统映像：

Android Studio 设备管理器中的 Add Device 对话框，其中显示了虚拟设备配置，Play 列中带有 Google Play 图标。

在 Android Studio 中创建 Google 地图项目

打开 Android Studio，然后在 Welcome to Android Studio 窗口中点击 New Project。
在 New Project 窗口的 Phone and Tablet 类别下，选择 No Activity，然后点击 Next。

注意：如果您从默认的 Empty Activity (Jetpack Compose) 模板（而非 No Activity）开始，并在稍后添加 Google Maps Views Activity，则 MapsActivity (AppCompatActivity) 会在启动时崩溃并显示 IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity，因为 Compose 模板会将 res/values/themes.xml 中的主题父级设置为 android:Theme.Material.Light.NoActionBar。为避免此崩溃问题，请将 res/values/themes.xml 中主题的 parent 更新为 Theme.AppCompat.DayNight.NoActionBar，并确保 .MapsActivity 在 AndroidManifest.xml 中配置为 MAIN/LAUNCHER activity。
填写 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 版本要求的最新信息，请参阅版本说明。
  
  注意：如果不确定要选择哪个 SDK 版本，请点击 Help me choose 链接，以显示受支持的 Android SDK 的分发版本信息。例如，如果您选择 Android API 级别 23 ("Marshmallow"; Android 6.0)，那么您的应用应该可以在超过 99% 的 Android 设备上运行。
- 将 Build configuration language 设置为“Kotlin DSL”或“Groovy DSL”。这两种 build 配置语言的代码段如以下步骤所示。
点击完成。

Android Studio 会启动 Gradle 并构建此项目。此过程可能需要一段时间。
添加 Google Maps Views Activity：
1. 右键点击您项目中的 app 文件夹。
2. 依次选择 New > Google > Google Maps Views Activity：
  
  从 Android Studio 中的 app 上下文菜单添加 Google Maps Views Activity。
3. 在 New Android Activity 对话框中，选中 Launcher Activity 复选框。
4. 选择完成。
  
  如需了解详情，请参阅基于模板添加代码。
构建完成后，Android Studio 会打开 AndroidManifest.xml 和 MapsActivity 文件。您的 activity 可以具有不同的名称，具体取决于您在设置期间配置的内容。

注意：如果不进行额外配置，Google 地图视图 activity 模板生成的项目将无法运行。虽然该模板会将 Android 版 Secrets Gradle 插件添加到 libs.versions.toml 和 build.gradle.kts，但它不会配置 secrets.properties，而是直接在 AndroidManifest.xml 中放置 YOUR_API_KEY 占位符（其中包含引用 local.properties 的旧版注释）。请勿将 API 密钥直接粘贴到 AndroidManifest.xml 中，也不要将其添加到 local.properties 中。 您应按照设置 Google Cloud 项目和将 API 密钥添加到应用中的说明，将 MAPS_API_KEY 存储在 secrets.properties 文件中，在模块级 Gradle 文件中配置 secrets 代码块，并在 AndroidManifest.xml 中设置 android:value="${MAPS_API_KEY}"。

设置您的 Google Cloud 项目

完成以下必需的 Cloud 控制台设置步骤：

第 1 步：设置项目

控制台

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

转到项目选择器页面
确保您的 Cloud 项目已启用结算功能。确认您的项目已启用结算功能。

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

Cloud SDK

gcloud projects create "PROJECT"

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

gcloud projects create

第 2 步：启用 API 或 SDK

如要使用 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 密钥。如需创建新密钥或向现有密钥添加 API 或 SDK，请按照以下说明操作。

控制台

前往 Google Maps Platform > 密钥和凭证页面。

前往“密钥和凭证”页面
如果出现提示，请选择您的项目。
执行以下其中一项操作：
- 创建新密钥：
  1. 点击创建凭据 > API 密钥。
  2. 在创建 API 密钥面板中，打开选择 API 限制列表。
  3. 清除此密钥不需要的所有 API，并确保 Maps SDK for Android 保持选中状态。
  4. 点击创建。该面板会显示您的新 API 密钥。
- 使用现有密钥：
  1. 点击密钥的名称。
  2. 在选择 API 限制列表中，选择 Maps SDK for Android。
  3. 点击保存。
在此处选择 API 并不会启用它。确保已在其 API 库页面上启用 Maps SDK for Android。
如需稍后查看密钥字符串，请前往密钥和凭证页面，然后点击相应密钥的显示密钥。

如果控制台与这些步骤不同，请参阅 Google Cloud 文档中的创建 API 密钥和添加 API 限制。

Cloud SDK

在以下命令中，将 PROJECT_ID 替换为您的项目 ID。

创建新密钥：运行以下命令，并将 DISPLAY_NAME 替换为密钥的名称。

gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=maps-android-backend.googleapis.com

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

gcloud services api-keys create

使用现有密钥：运行以下命令，并将 KEY_ID 替换为密钥的 ID。--append 标志会保留密钥已允许的 API。如果不使用此参数，该命令会替换这些标签。
```
gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=maps-android-backend.googleapis.com
```
详细了解 Google Cloud SDK、Cloud SDK 安装和以下命令：
- gcloud services api-keys update
- gcloud services api-keys list
键 ID 不是键字符串或显示名称。如需查找该 ID，请运行 gcloud services api-keys list --project="PROJECT_ID"。该 ID 是 name 字段的最后一部分：projects/PROJECT_NUMBER/locations/global/keys/KEY_ID。

如需查看密钥字符串，请运行 gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID"。

向您的应用添加 API 密钥

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

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

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

在 Android Studio 中，打开顶级 build.gradle.kts 或 build.gradle 文件，并将以下代码添加到 plugins 代码块中。

Kotlin

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

Groovy

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

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

Kotlin

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

Groovy

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

如果您使用的是 Android Studio，请将项目与 Gradle 同步。
在顶级目录中打开 secrets.properties 文件，然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。请务必将 secrets.properties 添加到 .gitignore 文件中（或以其他方式将其从版本控制系统中排除），以免将 API 密钥签入版本控制系统。
注意：如果 secrets.properties 文件不存在，请在 local.properties 文件所在的文件夹中创建该文件。
```
MAPS_API_KEY=YOUR_API_KEY
```
在顶级目录（即 secrets.properties 文件所在的文件夹）中创建 local.defaults.properties 文件，然后添加以下代码。

注意：请按下方所示输入代码。不要将 DEFAULT_API_KEY 替换为您的 API 密钥。
```
MAPS_API_KEY=DEFAULT_API_KEY
```
此文件的作用是为 API 密钥提供备用位置，以免在找不到 secrets.properties 文件的情况下构建失败。如果您是从省略 secrets.properties 的版本控制系统中克隆应用，而您还没有在本地创建 secrets.properties 文件来提供 API 密钥，就可能会出现构建失败。
在 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 中，打开模块级 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 root directory (the same folder as the root 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"
}

Groovy

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
}

查看代码

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

地图 activity 文件

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

地图 activity 的主要元素如下：

SupportMapFragment 对象 - 此对象可管理地图的生命周期，是应用界面的父元素。
GoogleMap 对象 - 此对象可用于访问地图数据和视图，是 Maps SDK for Android 的主类。地图对象指南详细介绍了 SupportMapFragment 和 GoogleMap 对象。
moveCamera 函数 - 此函数可将地图中心设置为澳大利亚悉尼的 LatLng 坐标。添加地图时，首先要配置的设置通常是地图位置和镜头设置，如视角、地图方向和缩放级别。如需了解详情，请参阅镜头和视图指南。
addMarker 函数 - 此函数可向悉尼的坐标添加一个标记。如需了解详情，请参阅标记指南。

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

Java

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

模块 Gradle 文件

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

Kotlin

dependencies {

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

Groovy

dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.0.0"
}

如果您的项目使用 Gradle 版本目录 (gradle/libs.versions.toml)，请在 libs.versions.toml 中定义 play-services-maps 依赖项：

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

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

XML 布局文件

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

tools:context - 此元素会将 fragment 的默认 activity 设置为地图 activity 文件中定义的 MapsActivity。
android:name - 此元素会将 fragment 的类名称设置为 SupportMapFragment，即 Google 地图活动记录文件中使用的 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" />

部署并运行应用

地图的屏幕截图，在中心位置的澳大利亚悉尼上有一个标记。

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

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

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

后续步骤

设置地图：此文档介绍了如何设置地图的初始设置和运行时设置，例如镜头位置、地图类型、界面组件和手势。
将地图添加到您的 Android 应用 (Kotlin)：此 Codelab 将引导您构建一款应用，从而演示 Maps SDK for Android 的一些其他功能。
使用 Maps Android KTX 库：此 Kotlin 扩展 (KTX) 库可让您在使用 Maps SDK for Android 的同时利用多种 Kotlin 语言功能。

Maps SDK for Android 快速入门 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

关于开发环境

设置 Android 设备

在 Android Studio 中创建 Google 地图项目

设置您的 Google Cloud 项目

第 1 步：设置项目

控制台

Cloud SDK

第 2 步：启用 API 或 SDK

控制台

Cloud SDK

第 3 步：获取 API 密钥

控制台

Cloud SDK

向您的应用添加 API 密钥

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Groovy

查看代码

地图 activity 文件

Kotlin

Java

模块 Gradle 文件

Kotlin

Groovy

XML 布局文件

部署并运行应用

后续步骤

Maps SDK for Android 快速入门