Android 版 Google 地图 Intent

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

概览

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

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

本页面介绍了可用于 Android 版 Google 地图应用的 intent。如需详细了解 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。

如需验证应用是否可用于接收 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 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

参数

  • latitude 和 longitude 可设置地图的中心点。
  • 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 参数。它接受以地点名称或地址作为营业地点。该字符串应经过网址编码，因此“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 的纬度/经度，但将地址作为查询字符串传递。搜索非常具体的营业地点时，无需提供纬度和经度。不过，如果您不知道确切地址，则可以通过尝试指定坐标来尝试调整搜索结果。例如，对“主街”执行地址搜索将返回太多结果。

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 将请求前往澳大利亚悉尼的 Taronga 动物园的精细导航：

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 街景提供整个覆盖区域内指定位置的全景视图。您也可以使用用户提交的全景照片和街景特惠照片集。

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) 的纬度和经度。应用将显示离该位置最近拍摄的全景图片。由于街景图像会定期刷新，并且每次拍摄的照片可能略有不同，因此当图像更新时，您的位置信息可能会与不同的全景图片同步。

  • panoid 是特定的全景图片 ID。如果同时指定了 panoid 和 cbll，Google 地图将使用全景图片 ID。全景图片 ID 可通过 StreetViewPanoramaLocation 对象提供给 Android 应用。

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

    • bearing：表示相机的罗盘方向，以与北方所呈顺时针角度表示。正北方为 0，东方为 90，南方为 180，西方为 270。传递给方位的值将环绕；即，0°、360° 和 720°。方向角由五个逗号分隔值中的第二个定义。
    • zoom：设置相机的缩放级别。默认缩放级别设置为 0。缩放级别 1 表示放大倍率。缩放级别将限制在 0 与当前全景图像的最大缩放级别之间。这意味着，任何超出此范围的值都将设为该范围内最接近的极端值。例如，值 -1 将设置为 0。“Zoom”是五个逗号分隔值中的第四个。
    • 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)

街景中的金字塔