本頁面由 Cloud Translation API 翻譯而成。

Android 版 Google 地圖意圖

Google 地圖應用程式 Android 版提供多個意圖，您可以使用這些意圖在顯示、搜尋、導航或街景服務模式中啟動 Google 地圖。如要在應用程式中嵌入地圖，請參閱 Google Maps Android API 入門指南。

總覽

意圖可讓您在 Intent 物件中說明要執行的簡單動作 (例如「顯示地圖」或「顯示機場的路線」)，在其他應用程式中啟動活動。Google 地圖應用程式 Android 版支援多種不同的意圖，讓您啟動 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 地圖意圖稱為「瀏覽動作」。ACTION_VIEW。
URI：Google 地圖意圖採用網址編碼功能指定需要的動作，以及部分要執行動作的資料。
套件：呼叫 setPackage("com.google.android.apps.maps") 可確保 Google 地圖應用程式 Android 版會處理意圖。如未設定套件，系統會判斷哪些應用程式可處理 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 的經緯度，但將地址做為查詢字串傳遞。搜尋非常明確的位置時，就不需要經緯度。不過，如果您不知道確切的地址，可以指定座標，以嘗試縮小搜尋結果。舉例來說，執行「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")

將 lat/lng 新增至意圖 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)

除了街道地址或緯度/經度以外，您也可以使用加號圖示，在已知位置顯示圖釘。

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。Zoom 是五個半形逗號分隔的值的第四個。
- tilt：指定相機的角度。範圍介於 -90 到 0 和 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)

街景服務中的金字塔

Android 版 Google 地圖意圖

總覽

意圖要求

Java

Kotlin

Java

Kotlin

Java

Kotlin

網址編碼查詢字串

Java

Kotlin

顯示地圖

Java

Kotlin

搜尋地點

類別搜尋

Java

Kotlin

Java

Kotlin

位置搜尋

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

推出即時路線導航

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

顯示街景服務全景

Java

Kotlin