适用于 Android 的 Google 地图 Intent

Android 版 Google 地图应用公开了多个 intent，您可以使用这些 intent 以显示模式、搜索模式、导航模式或街景模式 启动 Google 地图。如需在应用中 嵌入地图，请参阅 Maps SDK for Android 快速入门。

对于 Android Automotive OS (AAOS) 平台，有一些特定的注意事项 和额外的 intent 可用。如需了解详情，请参阅 Google 地图 Android Automotive intent 文档。

概览

利用 intent，您可以通过在 Intent 对象中描述您想执行的操作（如“显示地图”或“显示前往 机场的路线”）来启动另一个应用中的 activity。Android 版 Google 地图应用 支持多种不同的 intent，可让您启动 Google 地图应用 并执行以下四项操作之一：

  1. 以指定缩放比例显示指定位置的地图。
  2. 搜索位置或地点，并将它们显示在地图上。
  3. 请求从一个位置到另一个位置的路线。路线可以返回 三种交通方式：驾车、步行、骑自行车。
  4. 在 Google Street View 中显示全景图像。

本页面介绍了可与 Android 版 Google 地图应用搭配使用的 intent。如需详细了解 intent，请参阅 intent 和 intent 过滤器 以及 常见 intent。

Intent 请求

如需使用 intent 启动 Google 地图，您必须先创建一个 Intent 对象，并指定其操作、URI 和软件包。

  • 操作：所有 Google 地图 intent 都作为 View 操作调用 — ACTION_VIEW。
  • URI：Google 地图 intent 使用网址编码的 URI，这些 URI 指定了 所选操作以及执行该操作所需的一些数据。

  • 软件包：调用 setPackage("com.google.android.apps.maps") 可确保 Android 版 Google 地图应用处理该 intent。如果未设置软件包，系统会确定哪些应用可以处理该 Intent。如果有多个 应用可用，系统可能会询问用户想要使用哪个应用。

创建 Intent 后，您可以通过多种方式请求系统启动相关 应用。一种常见的方法是将 Intent 传递给 startActivity() 方法。系统会启动必要的应用 — 在本例中为 Google 地图 — 并启动相应的 Activity。

Java

// Create a Uri from an intent string. Use the result to create an Intent.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

Kotlin

// Create a Uri from an intent string. Use the result to create an Intent.
val gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988")
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps")
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent)

如果系统无法识别可以响应 intent 的应用，您的应用 可能会崩溃。因此，在向用户展示其中一个 intent 之前，请先验证是否已安装接收应用 。

如需验证是否有应用可以接收 intent，请在 Intent 对象上调用 resolveActivity()。如果结果不为 null，则至少有一个应用可以处理该 intent，并且可以安全地调用 startActivity()。如果结果为 null，请不要使用该 intent，并 尽可能停用调用该 intent 的功能。

Java

if (mapIntent.resolveActivity(getPackageManager()) != null) {
    ...
}

Kotlin

mapIntent.resolveActivity(packageManager)?.let {
    ...
}

例如，如需显示旧金山的地图，您可以使用以下代码：

Java

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(mapIntent);
}

Kotlin

val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
mapIntent.resolveActivity(packageManager)?.let {
    startActivity(mapIntent)
}

网址编码的查询字符串

传递给 Google 地图 intent 的所有字符串都必须经过 URI 编码。例如， 字符串 1st & Pike, Seattle 应变为 1st%20%26%20Pike%2C%20Seattle。 字符串中的空格可以使用 %20 进行编码，也可以替换为加号 (+)。

您可以使用 android.net.Uri encode() 方法对字符串进行编码。 例如：

Java

Uri gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

Kotlin

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"))

显示地图

使用 geo: intent 以指定缩放比例显示指定位置的地图。

geo:latitude,longitude?z=zoom

参数

  • latitude 和 longitude 用于设置地图的中心点。
  • z 用于选择性地设置地图的初始缩放级别。可接受的值范围 为 0（整个世界）到 21（单个建筑物）。上限值可能会 因所选位置提供的地图数据而异。

示例

Java

// Creates an Intent that loads a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Creates an Intent that loads a map of San Francisco
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

搜索位置

使用此 intent 可在指定的视口内显示搜索查询。当 查询只有一个结果时，您可以使用此 intent 在 特定地点或地址（例如地标、商家、地理特征 或城镇）显示图钉。

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address
geo:0,0?q=latitude,longitude(label)

参数

除了用于显示地图的参数之外，搜索还支持以下 参数：

  • q 用于定义要在地图上突出显示的地点。q 参数是 所有搜索请求都需要。它接受地点 名称或地址形式的地点。该字符串应采用网址编码，因此 City Hall, New York, NY 等地址应转换为 City+Hall,New+York,NY。

  • label 可让您在地图上标识的地点设置自定义标签。 label 必须指定为字符串。

如果您传递的是一般搜索字词，Google 地图会尝试在 您指定的纬度和经度附近查找符合您条件的地点。如果未指定任何 地点，Google 地图会尝试查找附近的商家信息。例如：

Java

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Search for restaurants in San Francisco.
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Search for restaurants nearby.
val gmmIntentUri = Uri.parse("geo:0,0?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Search for restaurants in San Francisco.
val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
搜索 San Francisco 的餐厅
图 1.在旧金山搜索餐厅

您可以通过指定缩放参数以及 查询字符串来进一步偏向搜索结果。在以下示例中，添加缩放级别 10 会尝试 在城市级别查找餐厅，而不是在附近查找。

Java

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

搜索特定地址会在该位置显示图钉。

Java

Uri gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

前面的示例设置了纬度和经度 0、0，但传递了一个 地址作为查询字符串。搜索特定位置时，不需要纬度 和经度。不过，如果您不知道确切的地址，您 可以尝试通过指定坐标来偏向搜索结果。例如，对“Main Street”执行地址搜索可能会返回太多 结果。

Java

// Searching for 'Main Street' returns too many results.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

Kotlin

// Searching for 'Main Street' returns too many results.
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

向 intent URI 添加纬度和经度会使结果偏向特定区域：

Java

// Searches for 'Main Street' near San Francisco.
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Searches for 'Main Street' near San Francisco.
val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?q=101+main+street")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

当您知道搜索会返回单个值时，您可能需要传递一个 可选标签。标签必须指定为字符串，并显示在 地图标记下方。请注意，只有在将 q 指定为 纬度和经度坐标时，标签才可用。

Java

// Display a label at the location of Google's Sydney office.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Display a label at the location of Google's Sydney office.
val gmmIntentUri =
    Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

除了街道地址或纬度和经度之外，您还可以 使用 Plus Code 在已知位置显示图钉。

Java

// Display the location of Google, San Francisco using a global plus code.
Uri gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX");
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco");
// Construct and use the Intent as in the preceding examples.

Kotlin

// Display the location of Google, San Francisco using a global plus code.
var gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX")
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco")
// Construct and use the Intent as in the preceding examples.

启动精细导航

使用此 intent URI 可启动 Google 地图导航，并提供前往指定地址或坐标的精细路线 。路线始终从用户的当前位置开始。

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude

参数

  • q：设置导航搜索的端点。此值可以是纬度 和经度坐标，也可以是查询格式的地址。如果它是返回多个结果的查询 字符串，则会选择第一个结果。

  • mode 用于设置交通方式。mode 是可选的，可以设置为以下值之一：

    • d 表示驾车（默认）
    • b 表示骑自行车
    • l 表示两轮车
    • w 表示步行

  • avoid 用于设置路线应尽量避开的功能。avoid 是可选的， 可以设置为以下一个或多个值：

    • t 表示收费站
    • h 表示高速公路
    • f 表示渡轮

示例

以下 Intent 请求提供前往澳大利亚悉尼塔龙加动物园的精细导航：

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
前往塔朗加动物园的路线
图 2.前往塔龙加 动物园
的路线

如果您不想支付过路费或乘坐渡轮，可以请求路线 尽量避开这些功能。

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

如果您想做一些运动，可以改为请求骑自行车路线。

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

如果您想乘坐机动两轮车，可以请求路线包含汽车无法行驶的狭窄道路和小路。以下 intent 会返回印度的一条路线。

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

显示街景全景图片

使用 google.streetview intent 启动 Google Street View。Google Street View 提供整个 覆盖 区域内以指定位置为中心的 360 度全景视图。用户贡献的球形全景照片和Street View 特别 系列也可用。

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

参数

所有 google.streetview URI 都必须包含 cbll 或 panoid 参数：

  • cbll 接受以英文逗号分隔的纬度和经度值 (46.414382,10.013988)。应用会显示最靠近此位置的全景照片。由于 Street View 图像会定期 刷新，并且每次拍摄的照片位置可能会略有不同 ，因此当图像更新时，您的位置可能会切换到不同的 全景照片。

  • panoid 是一个特定的全景照片 ID。如果同时指定了 panoid 和 cbll，Google 地图会使用全景照片 ID。Android 应用可以从 StreetViewPanoramaLocation 对象获取全景照片 ID。

  • cbp 是一个可选参数，用于调整 摄像头的初始方向。cbp 参数接受 5 个以英文逗号分隔的值，所有这些值 都是可选的。最重要的值是第二个、第四个和第五个值 ，它们分别用于设置方位、缩放级别和倾斜度。第一个和第三个 值不受支持，应设置为 0。

    • bearing：表示摄像头相对于正北方向的顺时针罗盘方位角（以度为单位）。正北为 0，正东为 90，正南为 180，正西为
      1. 传递给方位角的值会换行；也就是说，0°、360° 和 720° 都指向同一方向。方位角定义为五个以英文逗号分隔的值中的第二个值 。
    • zoom：设置摄像头的缩放级别。默认缩放级别设置为 0。缩放级别为 1 时，放大倍数会翻倍。缩放级别介于 0 和当前全景照片的最大缩放级别之间。 这意味着 任何超出此范围的值都会设置为该范围内最接近的极值 。例如，值 -1 会设置为 0。 缩放级别是五个以英文逗号分隔的值中的第四个值。
    • tilt：指定摄像头的向上或向下角度。范围是 -90 至 0 至 90，90 为垂直俯视，0 为水平居中，-90 为垂直仰视。

示例

以下是一些使用 Street View intent 的示例。

Java

// Displays an image of the Swiss Alps.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
Uri gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Displays an image of the Swiss Alps.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=46.414382,10.013988")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
val gmmIntentUri =
    Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
街景中的金字塔
图 3.街景中的金字塔