Android 版 Google 地圖應用程式提供了數種意圖,可讓您在顯示、搜尋、導航或街景服務模式中啟動 Google 地圖。如果您想在應用程式中嵌入地圖,請參閱 Google Maps Android API 入門指南。
總覽
您可以透過意圖在 Intent
物件中描述您要執行的簡單動作 (例如「顯示地圖」或「顯示前往機場的路線」),以便在其他應用程式中啟動活動。Android 版 Google 地圖應用程式支援數種不同的意圖,可讓您啟動 Google 地圖應用程式並執行以下四種操作之一:
- Display a map at a specified location and zoom level.
- Search for locations or places, and display them on a map.
- Request directions from one location to another. 系統可以傳回三種交通方式的路線:開車、步行、單車。
- 在 Google 街景服務中顯示全景圖像。
本頁說明可用於 Android 版 Google 地圖應用程式的意圖。如要進一步瞭解「意圖和意圖篩選器」或「Android 平台常見的意圖」,請參閱 Android 開發人員說明文件。
意圖要求
如要使用意圖啟動 Google 地圖,您必須先建立 Intent
物件,並指定其動作、URI 和套件。
- 動作:所有 Google 地圖意圖都稱為 View 動作 —
ACTION_VIEW
。 - URI:Google 地圖意圖用來指定所需動作的網址編碼,以及要執行動作的部分資料。
- 套件:呼叫
setPackage("com.google.android.apps.maps")
可確保 Android 版 Google 地圖應用程式會處理該意圖。如未設定套件,系統會決定哪些應用程式可以處理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
物件上呼叫 resolveActivity()
。如果結果不是空值,則至少有一個應用程式可以處理意圖且呼叫 startActivity()
也無妨。如果結果是 null
,則不應使用該意圖,請盡可能停用叫用意圖的功能。
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 地圖意圖的所有字串都必須採用 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:
意圖,在指定位置和縮放等級顯示地圖。
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)
搜尋位置
請使用這項意圖,在特定可視區域中顯示搜尋查詢。如果查詢有一筆結果,您可以使用這項意圖,顯示特定地點或地址 (例如地標、商家、地理地圖項目或城鎮) 的圖釘。
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
的 lat/lng 設為查詢字串,但把地址做為查詢字串傳送。搜尋特定位置時,就不需要提供經緯度。不過,如果不知道確切的地址,則可以指定座標,調整搜尋的結果。舉例來說,執行地址搜尋「中山路」時,會傳回太多結果。
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")
在意圖 URI 中加入 lat/lng 可將結果自訂調整至特定區域:
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
啟動即時路線導航
使用此意圖即可啟動 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
意圖啟動 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 為垂直向上。
例子
以下舉例說明使用街景服務意圖。
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)