适用于 Android 的 Google 地图 Intent

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

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

概览

借助 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 来指定所选操作，以及用于执行该操作的一些数据。

  • 软件包：调用 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 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)

参数

除了用于显示地图的参数之外，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)
搜索旧金山的餐厅
图 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=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 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. 前往 Taronga Zoo 的指示

如果您不想支付过路费或乘坐渡轮，可以请求系统尽量避开这些地点。

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 都必须包含 cbll 或 panoid 参数：

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

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

  • 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 为垂直仰视。

示例

以下是使用街景 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. 街景中的金字塔