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 模拟器，请务必选择带有 Play 图标（，显示在 Play 商店 列下方）的设备配置文件。此图标表明相应设备的配置完全 CTS 规范，并且可以使用包含 Play 商店应用的系统映像。

在 Android Studio 中创建 Google 地图项目

打开 Android Studio，然后在 Welcome to Android Studio 窗口中点击 New Project 。
在 New Project 窗口的 Phone and Tablet 类别下，选择 No Activity ，然后点击 Next 。
填写 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 配置语言的代码段如以下步骤所示。
点击 Finish 。

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

注意：AndroidManifest.xml 文件包含有关如何获取 Google 地图 API 密钥并将其添加到 local.properties 文件的说明。请勿将您的 API 密钥添加到 local.properties 文件。请改为按照设置 Google Cloud 项目和向应用中添加 API 密钥中的说明，使用 Android 版 Secrets Gradle 插件将 API 密钥存储在单独的 secrets.properties文件中。

设置您的 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 步

如要使用 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 密钥，请执行以下操作：

控制台

前往 Google Maps Platform > 凭据页面。

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

Cloud SDK

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

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

gcloud services api-keys create

向您的应用添加 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 设置为 Google 地图活动记录文件中定义的 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 步

控制台

Cloud SDK

第 3 步

控制台

Cloud SDK

向您的应用添加 API 密钥

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Groovy

查看代码

地图 activity 文件

Kotlin

Java

模块 Gradle 文件

Kotlin

Groovy

XML 布局文件

部署并运行应用

后续步骤

Maps SDK for Android 快速入门