您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps Android API

為協助您開始,我們將先引導您使用 Google Developers Console 來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps Android API
  3. 建立適當的金鑰
繼續

街景服務

「Google 街景服務」提供指定道路整個涵蓋區域的 360 度全景檢視。

此影片顯示如何使用「街景服務」服務,讓您的使用者感到如同親身前往地圖上的地址,並提供關於目的地或任何感興趣地點的有意義內容。

透過 Google Maps Android API v2 所取得的涵蓋範圍與 Android 裝置上「Google 地圖」應用程式的涵蓋範圍相同。

您可以在關於街景服務閱讀更多有關「街景服務」的資訊,並在互動式地圖上查看支援的區域。

StreetViewPanorama 類別會在您的應用程式中模擬「街景服務」全景。 在您的 UI 內,全景會以 StreetViewPanoramaFragmentStreetViewPanoramaView 物件代表。

程式碼範例

GitHub 上的 ApiDemos 存放區包括示範「街景服務」用法的範例:

Google Maps Android API 中的街景服務總覽

Google Maps Android API 提供「街景服務」服務,用來取得和操縱「Google 街景服務」中使用的影像。 影像會以全景傳回。

每個「街景服務」全景都是一個或一組影像,可提供單一位置的完整 360 度檢視。 影像遵循等距圓柱 (Plate Carrée) 投影法,包含 360 度的水平檢視(全方位環繞)與 180 度垂直檢視(垂直上下)。

產生的 360 度全景會在球體上定義投影,並將影像包覆至該球體的二維表面上。

StreetViewPanorama 提供一個可將全景轉譯為球體的檢視器,而相機將位於球體的正中間。 您可以操縱 StreetViewPanoramaCamera,控制相機的縮放與方向(傾斜度與方位)。

開始使用

依照入門指南來設定 Google Maps Android API 專案。 接著,新增「街景服務」全景,如下所述。

Google Play Services SDK 用戶端程式庫包括一些「街景服務」範例,您可以匯入專案並當成開發基礎使用。 如需匯入範例的指導方針,請參閱簡介

使用 API

依照下面的指示將「街景服務」全景新增至 Android 片段。 那是將街景服務新增至您應用程式的最簡單方法。 接下來,請深入瞭解片段、檢視及自訂全景。

新增街景服務全景

摘要說明:

  1. 新增片段物件到會處理「街景服務」全景的活動。 最簡單的執行方式是將 <fragment> 元素新增到 Activity 的版面配置檔案。

  2. 實作 OnStreetViewPanoramaReadyCallback 介面並使用 onStreetViewPanoramaReady(StreetViewPanorama) 回呼方法取得 StreetViewPanorama 物件的控制代碼。

  3. 呼叫片段上的 getStreetViewPanoramaAsync() 以註冊回呼。

以下是每個步驟更詳細的資料。

新增片段

新增 <fragment> 元素到 Activity 的版面配置檔案,以定義 Fragment 物件。 在此元素中,將 class 屬性設定為 com.google.android.gms.maps.StreetViewPanoramaFragment (或 SupportStreetViewPanoramaFragment)。

以下是版面配置檔案中的片段範例:

<fragment
    android:name="com.google.android.gms.maps.StreetViewPanoramaFragment"
    android:id="@+id/streetviewpanorama"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

新增街景服務程式碼

如果要使用您的應用程式內的「街景服務」全景,您必須實作 OnStreetViewPanoramaReadyCallback 介面,並針對 StreetViewPanoramaFragmentStreetViewPanoramaView 物件設定回呼的實例。

本教學課程使用的 StreetViewPanoramaFragment,就是將「街景服務」新增至您應用程式的最簡單方法。

第一個步驟是實作回呼介面:

public class MainActivity extends FragmentActivity
    implements OnStreetViewPanoramaReadyCallback {
...
}

ActivityonCreate() 方法中,將版面配置檔案設定為內容檢視。 例如,如果版面配置檔案的名稱是 main.xml,請使用此程式碼:

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    ...
}

透過呼叫 FragmentManager.findFragmentById(),再將 <fragment> 元素的資源 ID 傳遞給它,以取得片段的控制代碼。

請注意,當您建置版面配置檔案時,資源 ID R.id.streetviewpanorama 會自動新增到 Android 專案。

接著,使用 getStreetViewPanoramaAsync() 在片段上設定回呼。

StreetViewPanoramaFragment streetViewPanoramaFragment =
    (StreetViewPanoramaFragment) getFragmentManager()
        .findFragmentById(R.id.streetviewpanorama);
streetViewPanoramaFragment.getStreetViewPanoramaAsync(this);

注意:getStreetViewPanoramaAsync() 必須從主要執行緒呼叫,然後回呼才會在主要執行緒中執行。 如果使用者的裝置上未安裝 Google Play 服務,在使用者安裝 Play 服務之前,都不會觸發回呼。

使用 onStreetViewPanoramaReady(StreetViewPanorama) 回呼方法來擷取準備使用的非 Null StreetViewPanorama 實例。

@Override
public void onStreetViewPanoramaReady(StreetViewPanorama panorama) {
    panorama.setPosition(new LatLng(-33.87365, 151.20689));
}

深入瞭解如何設定初始狀態

和地圖不一樣的是,您無法透過 XML 設定「街景服務」全景的初始狀態。 然而,您可以透過傳遞包含您所指定選項的 StreetViewPanoramaOptions 物件,以程式設計方式來設定全景。

mSvpView = new StreetViewPanoramaView(this,
    new StreetViewPanoramaOptions().position(SAN_FRAN));

深入瞭解 StreetViewPanoramaFragment

StreetViewPanoramaFragmentAndroid Fragment 類別的子類別,並允許您在 Android 片段中放置「街景服務」全景。

StreetViewPanoramaFragment 物件可以當成全景的容器,並提供對 StreetViewPanorama 物件的存取。

注意:Google Maps Android API 需要 API 層級 12 或更高版本,才能支援 StreetViewPanoramaFragment 物件。 如果您以 API 層級 21 以前的應用程式為目標,您可以透過 SupportStreetViewPanoramaFragment 類別存取相同的功能。

您也必須包括 Android 支援程式庫

注意:Google Maps Android API 不支援單一活動中有多個 StreetViewPanoramaFragment 物件。

StreetViewPanoramaView

StreetViewPanoramaView 是 Android View 類別的子類別,允許您在 Android View 中放置「街景服務」全景。

View 代表畫面的矩形區域,而且是 Android 應用程式與小工具的基礎建置區塊。

StreetViewPanoramaView 很像 StreetViewPanoramaFragment,可以當成全景的容器,透過 StreetViewPanorama 物件公開核心功能。

此類別的使用者必須將所有活動生命週期方法(例如 onCreate()onDestroy()onResume()onPause())) 轉送給 StreetViewPanoramaView 類別中的對應方法。

注意:Google Maps Android API 不支援單一活動中有多個 StreetViewPanoramaView 物件。

自訂由使用者控制的功能

根據預設,檢視「街景服務」全景時,使用者能使用下列功能:平移、縮放及移動到鄰近全景。

您可以透過 StreetViewPanorama 上的方法,啟用和停用由使用者控制的手勢。 在停用手勢的情況下,仍然可以透過程式設計方法進行變更。

setPanningGesturesEnabled()
決定使用者是否能透過拖曳來重新調整相機的方位。
      mSvp.setPanningGesturesEnabled(false);
setUserNavigationEnabled()
決定使用者是否能移至不同的全景。 使用者可以點選一次瀏覽連結,或是點選兩次檢視來移至新的全景。
      mSvp.setUserNavigationEnabled(false);
setZoomGesturesEnabled()
決定使用者是否能透過捏合來縮放。
      mSvp.setZoomGesturesEnabled(false);

此外,您可以決定使用者是否會看到街道名稱:

setStreetNamesEnabled()
決定使用者是否能看到地面上顯示的街道名稱。
      mSvp.setStreetNamesEnabled(false);

設定全景的位置

如果要設定「街景服務」全景的位置,您可以呼叫 StreetViewPanorama.setPosition(),並傳遞 LatLng

您也可以將 radius 當成選擇性參數傳遞。 半徑在您想要擴大或縮小供「街景服務」尋找相符全景的區域時非常實用。 半徑為 0 表示全景必須確實連結至指定的 LatLng

預設半徑為 50。如果符合的區域中有多個全景,API 將會傳回最符合的全景。

private static final LatLng SAN_FRAN = new LatLng(37.765927, -122.449972);
mSvp.setPosition(SAN_FRAN);

或者,您也可以透過將 panoId 傳遞給 StreetViewPanorama.setPosition(),以根據全景 ID 設定位置。

如果要擷取鄰近全景的全景 ID,請先使用 getLocation() 來擷取 StreetViewPanoramaLocation

此物件包含目前全景的 ID 與 StreetViewPanoramaLink 物件陣列,而每個物件都包含連至目前全景的全景 ID。

StreetViewPanoramaLocation location = mSvp.getLocation();
if (location != null && location.links != null) {
    mSvp.setPosition(location.links[0].panoId);
}

放大和縮小

您可以透過設定 StreetViewPanoramaCamera.zoom,以程式設計方法來變更縮放層級。

將縮放層級設定為 1.0,會將影像放大 2 倍。

下列片段使用 StreetViewPanoramaCamera.Builder() 以現有相機的傾斜度與方位來建構新的相機,同時將縮放層級增加 50%。

private static final float ZOOM_BY = 0.5f;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(mSvp.getPanoramaCamera().zoom + ZOOM_BY)
    .tilt(mSvp.getPanoramaCamera().tilt)
    .bearing(mSvp.getPanoramaCamera().bearing)
    .build();

設定相機方向(視角)

您可以透過針對 StreetViewPanoramaCamera 設定方位與傾斜度,以決定「街景服務」相機的方向。

bearing
相機所指的方向(以從正北開始計算相機焦點順時針旋轉的度數指定)。 正北方是 0、東方是 90、南方是 180、西方是 270。
tilt
Y 軸朝上或朝下傾斜。 範圍是從 -90 到 0 至 90 之間,-90 為筆直往下俯視,0 為水平置中,90 為筆直往上仰視。 從相機的初始預設傾斜度測量變化,通常是(但不一定是)完全水平。 例如,在山丘上拍到的影像可能有未呈現水平的預設傾斜度。

下列程式碼片段使用 StreetViewPanoramaCamera.Builder() 以現有相機的縮放層級與傾斜度來建構新的相機,同時將方位變成左轉 30 度。

private static final int PAN_BY = 30;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(mSvp.getPanoramaCamera().zoom)
    .tilt(mSvp.getPanoramaCamera().tilt)
    .bearing(mSvp.getPanoramaCamera().bearing - PAN_BY)
    .build();

下列程式碼片段會讓相機朝上傾斜 30 度。

float tilt = mSvp.getPanoramaCamera().tilt + 30;
tilt = (tilt > 90) ? 90 : tilt;

StreetViewPanoramaCamera previous = mSvp.getPanoramaCamera();

StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder(previous)
    .tilt(tilt)
    .build();

動畫處理相機移動方向

如果要動畫處理相機移動方向,請呼叫 StreetViewPanorama.animateTo()

動畫將會在目前的相機屬性和新的相機屬性之間進行內插計算。 如果您不要進行動畫處理,想要直接跳到相機,可以將時間長度設定為 0。

// Set the tilt to zero, keeping the zoom and bearing at current values.
// Animate over a duration of 500 milliseconds.
long duration = 500;
float tilt = 0;
StreetViewPanoramaCamera camera = new StreetViewPanoramaCamera.Builder()
    .zoom(mSvp.getPanoramaCamera().zoom)
    .bearing(mSvp.getPanoramaCamera().bearing)
    .tilt(tilt)
    .build();

mSvp.animateTo(camera, duration);

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps Android API
Google Maps Android API
需要協助嗎?請前往我們的支援網頁