Android 版 Google 地图应用提供了一些 intent,可用于在显示模式、搜索模式、导航模式或街景模式下启动 Google 地图。如果您想在应用中嵌入地图,请参阅 Google Maps Android API 入门指南。
概览
借助 intent,您可以通过描述您想在 Intent
对象中执行的简单操作(如“显示地图”或“显示前往机场的路线”)来启动另一个应用中的 activity。Android 版 Google 地图应用支持多种不同的 intent,可让您启动 Google 地图应用并执行下列四项操作之一:
- 在指定位置以指定的缩放级别显示地图。
- 搜索地点或位置,然后在地图上显示出来。
- 请求从一个地点到另一个地点的路线。可以返回三种交通方式的路线:驾车、步行、骑车。
- 在 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
,但将地址作为查询字符串传递。在搜索非常具体的位置时,无需提供纬度和经度。但是,如果您不知道确切地址,则可以尝试通过指定坐标来自定义调整搜索结果的结果。例如,对“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 街景提供整个覆盖区域内指定位置的全景视图。还可提供用户贡献的照片球和街景特色收藏。
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。Android 应用可通过StreetViewPanoramaLocation
对象获取全景图片 ID。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)