适用于 Android 的 Google 地图 Intent

通过 Android 版 Google 地图应用 提供了多个 intent,可用于在显示屏上启动 Google 地图, 搜索、导航或街景模式。如果您想 在应用中嵌入地图,请参阅 Google Maps Android API 入门指南

概览

利用 intent,您可以通过描述简单操作,在另一个应用中启动 activity 您想要执行的操作(例如“显示地图”或“显示前往 机场”) Intent 对象。通过 Android 版 Google 地图应用 支持多种不同的 Intent,让您可以启动 Google 地图应用 然后执行以下四种操作之一:

  1. 在指定位置以指定的缩放级别显示地图。
  2. 搜索地点或位置,然后在地图上显示出来。
  3. 请求从一个地点到另一个地点的路线。可返回路线 3 种交通方式:驾车、步行、骑车。
  4. 在 Google 街景中显示全景图像。

本页面介绍了可与 Google 地图应用搭配使用的 intent, Android。如需详细了解 Intent 和 Intent, 过滤器Android 通用的 intent 平台,请参阅 Android 开发者文档。

intent 请求

为了通过 intent 启动 Google 地图,您必须先创建一个 Intent 对象来指定其操作、URI 和软件包。

  • 操作:所有 Google 地图 intent 都称为“查看”操作 - ACTION_VIEW
  • URI:Google 地图 Intent 使用网址编码,以指定期望的 以及用于执行操作的一些数据。
  • 软件包:调用 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,请调用 resolveActivity()(在您的 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 &西雅图派克”应变为 1st%20%26%20Pike%2C%20Seattle。 字符串中的空格可使用 %20 编码或替换为加号 (+)。

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

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

参数

  • latitudelongitude 用于设置地图的中心点。
  • z(可选)设置地图的初始缩放级别。接受的值范围 范围为 0(全世界)到 21(单个建筑物)。上限 因所选位置提供的地图数据而异。

示例

Java

// Creates an Intent that will load 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 will load 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)

参数

除了用于显示地图的参数外,Google 搜索还支持 以下参数:

  • q,用于定义要在地图上突出显示的地点。q 参数为 所有 Search 请求所需要。它接受位置作为地点 姓名或地址该字符串应进行网址编码, 因此地址,如“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)

搜索旧金山的餐馆

您可以进一步自定义调整搜索结果的范围,只需指定沿途的缩放参数即可 替换为查询字符串。在以下示例中,系统将尝试添加 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' will return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

Kotlin

// Searching for 'Main Street' will return 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=Google+Sydney@-33.8666,151.1957");
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 examples above

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 examples above

启动精细导航

使用此 Intent 可启动含精细路线的 Google 地图导航 传递给指定的地址或坐标。始终从 用户的当前位置。

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

参数

  • q:设置导航搜索的终点。该值可以是 纬度、经度坐标或查询格式的地址。如果是查询 返回多个结果的字符串,那么第一个结果将是 已选择。

  • mode 设置交通方式。模式是可选的,可设置为 以下之一:

    • d 表示驾车(默认)
    • b(骑车)
    • l(双轮机动车)
    • 步行需要 w
  • 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)

前往塔龙加动物园的路线

如果您不想支付通行费或搭乘渡轮,可以请求 会尽量避免这些行为

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 街景。Google 街景 提供从指定位置的全景视图, 覆盖范围用户提供的 360 度全景照片, 和 街景集锦

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

参数

所有 google.streetview URI 都必须包含 cbllpanoid 参数。

  • cbll 接受以英文逗号分隔值的纬度和经度 (46.414382,10.013988)。应用将显示拍摄的全景图片 离此位置最近的地点。由于街景图像会定期 刷新后,系统可能会从略微不同的位置拍摄照片 那么每次定位时,您所在的位置都可能会 。

  • panoid 是特定的全景图片 ID。如果存在以下情况,Google 地图将使用全景图片 ID: 同时指定了 panoidcbll。全景图片 ID 可用于 Android 应用 StreetViewPanoramaLocation 对象。

  • cbp 是一个可选参数,用于调整 摄像头。cbp 参数接受 5 个以英文逗号分隔的值,均以 都是选填的最重要的值是第二、第四和第五个值 用于分别设置方位、缩放级别和倾斜度。第一个和第三个 值不受支持,因此应设为 0

    • bearing:指示相机的罗盘方向,以顺时针度数表示 来自北方正北方为 0,东方为 90,南方为 180,西方为 270。值 传递到轴承的物体会封装;即 0°、360°和 720° 都指向同一个方向方位的定义为五个中的第二个 逗号分隔值。
    • zoom:设置相机的缩放级别。设置默认缩放级别 为 0。缩放级别为 1 时,放大率会加倍。缩放比例为固定值 介于 0 和当前全景的最大缩放级别之间。 也就是说,任何超出此范围的值都会被设为 该范围内最接近的极值。例如,值 -1 将设置为 0。缩放级别是五个逗号分隔值中的第四个值。
    • tilt:指定镜头的向上或向下角度。范围是 -90 0 到 90,90 为垂直俯视,0 为地平线, 和-90 竖直向上看

示例

以下是一些使用街景 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 will angle 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 will angle 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)

街景中的金字塔