您可以使用适用于 Android Studio 的 Google 地图景观模板来开发能显示地图的 Android 应用。如要设置现有的 Android Studio 项目,请参阅设置 Android Studio 项目。
本快速入门指南面向熟悉 Kotlin 或 Java,能够使用它们进行基本 Android 开发的开发者。
关于开发环境
本快速入门指南演示的是使用 Android Studio Hedgehog 和 Android Gradle 插件 8.2 版的开发环境。
设置 Android 设备
若要运行使用 Maps SDK for Android 的应用,您必须将其部署到 Android 设备或 Android 基于 Android 5.0 或更高版本且包含以下内容的模拟器 Google API。
- 如要使用 Android 设备,请按照在硬件设备上运行应用一文中的说明操作。
- 如要使用 Android 模拟器,您可以使用 Android Studio 随附的 Android 虚拟设备 (AVD) 管理器来创建虚拟设备并安装模拟器。
在 Android Studio 中创建 Google 地图项目
在 Flamingo 及更高版本的 Android Studio 中,创建 Google 地图项目的步骤有所更改。
打开 Android Studio,然后在 Welcome to Android Studio 窗口。
在 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 19.0.x 版、 即 Android API 级别 21(“Lollipop”;Android 5.0)或更高版本。 如需了解有关 SDK 版本要求的最新信息,请参阅版本说明。
将 Build configuration language 设置为“Kotlin DSL”或“Groovy DSL”。这两种 build 配置语言的代码段如以下步骤所示。
点击 Finish。
Android Studio 会启动 Gradle 并构建此项目。此过程可能需要一段时间。
添加 Google Maps Views Activity:
- 右键点击您项目中的
app
文件夹。 依次点击 New > Google > Google Maps Views Activity。
在 New Android Activity 对话框中,选中 Launcher Activity 复选框。
选择 Finish。
如需了解详情,请参阅基于模板添加代码
- 右键点击您项目中的
构建完成后,Android Studio 会打开
AndroidManifest.xml
和MapsActivity
文件。您的 activity 名称可能与示例中显示的不同,但会是您在设置过程中配置的名称。
设置 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 安装和以下命令:
第 2 步
如要使用 Google Maps Platform,您必须启用计划用于项目的 API 或 SDK。
控制台
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 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 插件,请执行以下操作:
-
在 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" } }
-
打开模块级
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' }
- 在模块级
build.gradle.kts
或build.gradle
文件中,确保targetSdk
和compileSdk
已设置 到 34。 - 保存文件并将项目与 Gradle 同步。
-
在顶级目录中打开
secrets.properties
文件,然后添加以下代码。将YOUR_API_KEY
替换为您的 API 密钥。secrets.properties
不会签入版本控制系统,因此请将您的密钥存储在此文件中。MAPS_API_KEY=YOUR_API_KEY
- 保存文件。
-
在顶级目录(即
secrets.properties
文件所在的文件夹)中创建local.defaults.properties
文件,然后添加以下代码。MAPS_API_KEY=DEFAULT_API_KEY
此文件的作用是为 API 密钥提供备用位置,以免在找不到
secrets.properties
文件的情况下构建失败。如果您是从省略secrets.properties
的版本控制系统中克隆应用,而您还没有在本地创建secrets.properties
文件来提供 API 密钥,就可能会出现构建失败。 - 保存文件。
-
在
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}" />
注意: 建议使用
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 中,打开模块级
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 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
坐标。添加地图时,首先要配置的设置通常是地图位置和镜头设置,如视角、地图方向和缩放级别。如需了解详情,请参阅镜头和视图指南。
模块 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" />
部署并运行应用
应用成功运行后,将会显示一个以澳大利亚悉尼为中心的地图,且在该城市上会带有一个标记,如以下屏幕截图所示。
如需部署并运行应用,请按以下步骤操作:
- 在 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 语言功能。