Maps SDK for Android 快速入门

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

本快速入门适用于熟悉如何使用 Java 或 Kotlin 进行基本 Android 开发的开发者。

设置开发环境

  1. 必须使用 Android Studio。如果您尚未安装,请下载安装

  2. Google Play 服务 SDK 添加到 Android Studio。Maps SDK for Android 是作为 Google Play 服务 SDK 的一部分进行分发的,您可以通过 SDK 管理器添加该 SDK。

设置 Android 设备

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

创建 Google 地图项目

  1. 打开 Android Studio,然后在 Welcome to Android Studio 窗口中点击 Create New Project

  2. New Project 窗口的 Phone and Tablet 类别下,选择 Google Maps Activity,然后点击 Next

  3. 填写 Google Maps Activity 表单:

    • Language 设置为 Java 或 Kotlin。这两种语言都完全受 Maps SDK for Android 支持。如需详细了解 Kotlin,请参阅使用 Kotlin 开发 Android 应用

    • Minimum SDK 设置为您的测试设备支持的 Android SDK 版本。

  4. 点击 Finish

当您完成项目的创建后,Android Studio 将启动 Gradle 并构建该项目。此过程可能需要一段时间。构建完成后,Android Studio 将打开 google_maps_api.xmlMapsActivity 文件。您的 activity 可能具有不同的名称,但它应是您在设置期间配置的名称。

如需详细了解如何创建项目,请参阅创建 Android 项目

google_maps_api.xml 文件包含有关如何获取 Google Maps API 密钥并将其添加到该文件的说明。请勿将您的 API 密钥添加到该文件。这样做会降低 API 密钥的存储安全性。相反,请按照下一部分中的说明操作。

在 Cloud Console 中设置

依次点击以下标签页,完成所需的 Cloud Console 设置步骤:

第 1 步

控制台

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

    转到项目选择器页面

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

    Google Cloud 会提供 300 美元的免费试用赠金,Google Maps Platform 则是每月定期提供 200 美元的赠金。如需了解详情,请参阅结算帐号赠金结算

Cloud SDK

gcloud projects create "PROJECT"

详细了解 Google Cloud SDKCloud 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 SDKCloud SDK 安装和以下命令:

第 3 步

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

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

如需创建 API 密钥,请执行以下操作:

控制台

  1. 依次转到 Google Maps Platform > 凭据页面。

    转到“凭据”页面

  2. 凭据页面上,依次点击创建凭据 > API 密钥
    已创建的 API 密钥对话框会显示您新创建的 API 密钥。
  3. 点击关闭
    新的 API 密钥位于凭据页面的 API 密钥下。
    (请务必在实际使用之前限制 API 密钥。)

Cloud SDK

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

详细了解 Google Cloud SDKCloud SDK 安装和以下命令:

向您的应用添加 API 密钥

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

为了简化此任务,您可以使用 Android 版 Secrets Gradle 插件

如需安装此插件并存储您的 API 密钥,请执行以下操作:

  1. 在 Android Studio 中,打开根级 build.gradle 文件,并将以下代码添加到 buildscript 下的 dependencies 元素中。
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
        }
    }
        
  2. 接下来,打开应用级 build.gradle 文件,并将以下代码添加到 plugins 元素中。
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. 保存文件并将项目与 Gradle 同步
  4. 在项目级目录中打开 local.properties,然后添加以下代码。将 YOUR_API_KEY 替换为您的 API 密钥。
    MAPS_API_KEY=YOUR_API_KEY
        
  5. 保存文件并将项目与 Gradle 同步。
  6. 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 的主类。地图对象指南更详细地介绍了 SupportMapFragmentGoogleMap 对象。

  • moveCamera 函数,可将地图中心设置为澳大利亚悉尼的 LatLng 坐标。添加地图时首先要配置的设置通常是地图位置和相机设置,如视角、地图方向和缩放级别。如需了解详情,请参阅相机和视图指南。

  • addMarker 函数,可向悉尼的坐标添加一个标记。如需了解详情,请参阅标记指南。

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

Java


// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

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;

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


// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.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
import com.google.maps.example.R

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.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: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" />

部署并运行应用

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

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

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

  1. 在 Android Studio 中,点击 Run 菜单选项(或 play 按钮图标),以运行您的应用。
  2. 当系统提示您选择设备时,选择以下选项之一:
    • 选择与您的计算机相连的 Android 设备。
    • 此外,还可以选择 Launch emulator 单选按钮,然后选择您设置过的虚拟设备。
  3. 点击 OK。Android Studio 将启动 Gradle 来构建您的应用,然后在设备或模拟器上显示结果。应用可能需要几分钟的时间才能启动。

后续步骤

  • 设置地图:本主题介绍了如何设置地图的初始设置和运行时设置,例如相机位置、地图类型、界面组件和手势。

  • 将地图添加到您的 Android 应用 (Kotlin):此 Codelab 将引导您构建一款应用,从而演示 Maps SDK for Android 的一些其他功能。