本页面介绍了如何在不使用快速入门中详细介绍的 Google 地图模板的情况下,将 Android Studio 项目配置为使用 Maps SDK for Android。
Google 地图模板会自动配置基本地图,并将此类地图添加到新的 Android Studio 项目。不过,您也可以向使用其他 Android Studio 模板的 Android 项目添加地图。为此,您需要先手动配置项目,然后再添加地图。
第 1 步:设置 Android Studio
本文档介绍的是使用 Android Studio Hedgehog 和 Android Gradle 插件 8.2 版的开发环境。
第 2 步:设置 SDK
您可以通过 Google 的 Maven 制品库获取 Maps SDK for Android 库。要将 SDK 添加到您的应用中,请执行以下操作:
- 在顶级
settings.gradle
文件的pluginManagement
代码块下,添加 Gradle 插件门户、Google 的 Maven 制品库和 Maven 中央存储库。pluginManagement
代码块必须位于脚本中的任何其他语句之前。pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- 在顶级
settings.gradle
文件的dependencyResolutionManagement
代码块下,添加 Google 的 Maven 制品库和 Maven 中央存储库:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- 在模块级
build.gradle
文件中,为 Maps SDK for Android 添加 Google Play 服务依赖项。Groovy
dependencies { // Maps SDK for Android implementation 'com.google.android.gms:play-services-maps:19.0.0' }
Kotlin
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:18.2.0") }
- 在模块级
build.gradle
文件中,设置compileSdk
并将minSdk
更改为以下值:Groovy
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
- 在模块级
build.gradle
文件的buildFeatures
部分中,添加BuildConfig
类;您可以使用该类访问此过程中稍后定义的元数据值:Groovy
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
第 3 步:将您的 API 密钥添加到项目中
本部分介绍了如何存储 API 密钥,以便您的应用可以安全引用该密钥。您不应将 API 密钥签入版本控制系统,建议将其存储在项目根目录下的 secrets.properties
文件中。如需详细了解 secrets.properties
文件,请参阅 Gradle 属性文件。
为了简化此任务,建议您使用 Android 版 Secret Gradle 插件。
如需在 Google 地图项目中安装 Android 版 Secret Gradle 插件,请执行以下操作:
-
在 Android Studio 中,打开顶级
build.gradle
或build.gradle.kts
文件,并将以下代码添加到buildscript
下的dependencies
元素中。Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
-
打开模块级
build.gradle
文件,并将以下代码添加到plugins
元素中。Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- 在模块级
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}" />
Note:
com.google.android.geo.API_KEY
is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY
. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. -
In Android Studio, open your module-level
build.gradle
orbuild.gradle.kts
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Groovy
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" 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.*" }
Kotlin
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" 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.*" }
第 4 步:更新应用清单
本部分介绍了要添加到
AndroidManifest.xml
文件中的设置。Google Play 服务版本号
在
application
元素中添加以下声明。该操作会嵌入编译应用时所用 Google Play 服务的版本。<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
位置信息权限
如果您的应用需要访问用户的位置信息,那么您就需要在
AndroidManifest.xml
文件中请求位置信息权限。您可以选择请求ACCESS_FINE_LOCATION
(可提供精确的设备位置信息),也可以选择请求ACCESS_COARSE_LOCATION
(提供的位置信息不太精确)。如需了解详情,请参阅位置数据指南。如要请求
ACCESS_FINE_LOCATION
权限,请将以下代码添加到manifest
元素中:<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
外部存储权限
如果您的目标平台是 8.3 版或更高版本的 Google Play 服务 SDK,则您不需要
WRITE_EXTERNAL_STORAGE
权限。如果目标平台是较低版本的 Google Play 服务 SDK,则必须在manifest
元素中请求 WRITE_EXTERNAL_STORAGE 权限。<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
Apache HTTP 旧版库
如果您使用的是
com.google.android.gms:play-services-maps:16.0.0
或更低版本,并且您的应用以 API 级别 28 (Android 9.0) 或更高级别为目标平台,那么您必须在AndroidManifest.xml
的<application>
元素中添加以下声明。否则,请跳过添加声明这一步。<uses-library android:name="org.apache.http.legacy" android:required="false" />
第 5 步:设置 Android 设备
若要运行使用 Maps SDK for Android 的应用,您必须将其部署到 Android 设备或 Android 基于 Android 5.0 或更高版本且包含以下内容的模拟器 Google API。
- 如要使用 Android 设备,请按照在硬件设备上运行应用一文中的说明操作。
- 如要使用 Android 模拟器,您可以使用 Android Studio 随附的 Android 虚拟设备 (AVD) 管理器来创建虚拟设备并安装模拟器。
第 6 步:(可选)检查是否已安装 Play 服务
若要使用 Maps SDK for Android,您部署应用的设备上必须已安装 Google Play 服务。您可以在应用中调用 Google 提供的一种方法,对此进行检查。 如需了解详情,请参阅检查是否已安装 Google Play 服务。
后续步骤
配置完项目后,您就可以添加地图了。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2024-08-16。
[] [] { "last_modified": "最后更新时间 (UTC):2024-08-16。", "state": "" }