Maps SDK for Android 快速入门

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

本快速入门指南面向熟悉如何使用 Java 或 Kotlin 进行基本 Android 开发的开发者。

设置开发环境

必须使用 Android Studio Arctic Fox 或更高版本。如果您尚未安装，请下载并安装。
确保您在 Android Studio 中使用的是 Android Gradle 插件 7.0 或更高版本。

设置 Android 设备

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

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

在 Android Studio 中创建 Google 地图项目

打开 Android Studio，然后在 Welcome to Android Studio 窗口中点击 Create New Project。
在 New Project 窗口的 Phone and Tablet 类别下，选择 Google Maps Activity，然后点击 Next。
填写 Google Maps Activity 表单：
- 将 Language 设置为 Java 或 Kotlin。这两种语言都完全受 Maps SDK for Android 支持。如需详细了解 Kotlin，请参阅使用 Kotlin 开发 Android 应用。
- 将 Minimum SDK 设置为与您的测试设备兼容的 SDK 版本。您选择的版本必须高于 Maps SDK for Android 18.0.x 版所要求的最低版本，目前为 Android API 19（Android 4.4，KitKat）或更高级别。如需了解有关 SDK 版本要求的最新信息，请参阅版本说明。
  
  注意：如果您不确定要选择哪个 SDK 版本，请选择 Help me choose 链接，以显示受支持的 Android SDK 的分发版本信息。例如，如果您选择 API 19: Android 4.4 (KitKat)，那么您的应用应该可以在超过 99% 的 Android 设备上运行。
点击 Finish。

Android Studio 随即便会启动 Gradle 并构建此项目。此过程可能需要一段时间。
构建完成后，Android Studio 会打开 AndroidManifest.xml 和 MapsActivity 文件。您的 activity 可能具有不同的名称，但它应是您在设置期间配置的名称。
AndroidManifest.xml 文件包含有关如何获取 Google Maps API 密钥并将其添加到 local.properties 文件的说明。请勿将您的 API 密钥添加到 AndroidManifest.xml 文件。这样做会降低 API 密钥的存储安全性。应改而按照下一部分中的说明，创建一个 Cloud 项目并配置 API 密钥。

设置您的 Google Cloud 项目

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

第 1 步

控制台

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

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

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

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 密钥。

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

控制台

前往 Google Maps Platform > 凭据页面。

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

Cloud SDK

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

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

gcloud alpha services api-keys create

向您的应用添加 API 密钥

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

为了简化此任务，我们建议您使用 Android 版 Secrets Gradle 插件。如需安装此插件并存储您的 API 密钥，请执行以下操作：

在 Android Studio 中，打开项目级 build.gradle 文件，并将以下代码添加到 buildscript 下的 dependencies 元素中。
```
plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
```
接下来，打开模块级 build.gradle 文件，并将以下代码添加到 plugins 元素中。
```
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    
```
保存文件并将项目与 Gradle 同步。
在项目级目录中打开 local.properties，然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。
```
MAPS_API_KEY=YOUR_API_KEY
    
```
保存文件。
在 AndroidManifest.xml 文件中，定位到 com.google.android.geo.API_KEY 并按如下所示更新 android:value attribute：
```
<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 会抛出异常。

查看代码

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

地图 activity 文件

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

地图 activity 的主要元素如下：

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

地图 activity 文件包含以下代码：

Java


import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

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

Kotlin


import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

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

模块 Gradle 文件

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

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.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:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

部署并运行应用

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

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

部署并运行应用的步骤如下：

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