Android 版 Google 地图 Intent

Android 版 Google 地图应用提供了多个 intent，您可以使用这些 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。

// 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);

// 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 的功能。

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

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

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

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);
}

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() 方法对字符串进行编码。例如：

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

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（个别建筑物）之间。上限可能会有所不同，具体取决于所选位置的可用地图数据。

示例

// 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);

// 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 地图将尝试查找附近的商家信息。例如：

// 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);

// 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 为 10 的缩放级别将尝试在城市一级（而不是在附近）查找餐馆。

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);

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)

位置搜索

搜索特定地址时，将在该位置处显示一个图钉。

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);

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，但以查询字符串的形式传递了地址。在搜索非常具体的位置时，无需提供纬度和经度。不过，如果您不知道确切地址，则可以尝试通过指定坐标来影响搜索结果。例如，对“主街”执行地址搜索将返回过多结果。

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

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

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

// 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);

// 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 时，标签才可用。

// 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);

// 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 Codes 在已知位置显示图钉。

// 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

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

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);

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)

如果您不想支付通行费或乘坐轮渡，可以请求尽量避开这些交通工具的路线。

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);

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)

如果您想做一些练习，可以改为请求骑车路线。

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);

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 会返回一条印度的路线。

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);

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。缩放级别是五个逗号分隔值中的第四个值。
  • tilt：指定相机的向上或向下角度。范围是 -90 至 0 至 90，90 为垂直俯视，0 为水平居中，-90 为垂直仰视。

示例

以下是一些使用街景 intent 的示例。

// 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);

// 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)