事件

您可以使用 Maps SDK for Android 監聽地圖上的事件。

程式碼範例

GitHub 上的 ApiDemos 存放區包含說明事件和事件監聽器的範例：

地圖點擊/長按事件

如果您想要回應輕觸了地圖上某個地點的使用者，可以使用 OnMapClickListener；只要呼叫 GoogleMap.setOnMapClickListener(OnMapClickListener)，即可在地圖上進行設定。當使用者點擊 (輕觸) 地圖上的某個位置時，您會收到一個 onMapClick(LatLng) 事件，指出使用者在地圖上點擊的位置。請注意，如果您需要在螢幕上顯示對應的位置 (以像素為單位)，可以從地圖取得 Projection，這樣就能在經緯度座標和螢幕像素座標之間進行轉換。

您也可以透過 OnMapLongClickListener 監聽長按點擊事件；只要呼叫 GoogleMap.setOnMapLongClickListener(OnMapLongClickListener)，即可在地圖上進行設定。 這個事件監聽器的運作方式與點擊事件監聽器類似，當出現長按點擊事件時，就會收到 onMapLongClick(LatLng) 回呼通知。

在精簡模式中停用點擊事件

如要在精簡模式中停用地圖上的點擊事件，請在包含 MapView 或 MapFragment 的檢視畫面中呼叫 setClickable()。舉例來說，在清單檢視中顯示一或多張地圖時，或是您希望點擊事件叫用與地圖無關的動作時，這項功能就很實用。

停用點擊事件的選項僅適用於精簡模式。停用點擊事件也會使標記無法點擊，但不影響地圖上的其他控制項。

對於 MapView：

MapView view;
...
view.setClickable(false);

對於 MapFragment：

MapFragment fragment;
...
fragment.getView().setClickable(false);

攝影機變更事件

地圖檢視是模擬向下俯瞰平面的攝影機。您可以變更攝影機的屬性，調整地圖的縮放等級、可視區域和視角。請參閱攝影機指南。使用者也可以透過手勢來調整攝影機。

使用攝影機變更事件監聽器，您就可以追蹤攝影機的動作。您的應用程式可接收攝影機動作開始、進行中和結束事件的通知。您也可以查看促使攝影機移動的「原因」，例如使用者手勢、內建 API 動畫或由開發人員控制的動作。

以下範例說明所有可用的攝影機事件監聽器：

public class MyCameraActivity extends FragmentActivity implements
        OnCameraMoveStartedListener,
        OnCameraMoveListener,
        OnCameraMoveCanceledListener,
        OnCameraIdleListener,
        OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_my_camera);

        SupportMapFragment mapFragment =
            (SupportMapFragment) getSupportFragmentManager()
                    .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        mMap.setOnCameraIdleListener(this);
        mMap.setOnCameraMoveStartedListener(this);
        mMap.setOnCameraMoveListener(this);
        mMap.setOnCameraMoveCanceledListener(this);

        // Show Sydney on the map.
        mMap.moveCamera(CameraUpdateFactory
                .newLatLngZoom(new LatLng(-33.87365, 151.20689), 10));
    }

    @Override
    public void onCameraMoveStarted(int reason) {

        if (reason == OnCameraMoveStartedListener.REASON_GESTURE) {
            Toast.makeText(this, "The user gestured on the map.",
                           Toast.LENGTH_SHORT).show();
        } else if (reason == OnCameraMoveStartedListener
                                .REASON_API_ANIMATION) {
            Toast.makeText(this, "The user tapped something on the map.",
                           Toast.LENGTH_SHORT).show();
        } else if (reason == OnCameraMoveStartedListener
                                .REASON_DEVELOPER_ANIMATION) {
            Toast.makeText(this, "The app moved the camera.",
                           Toast.LENGTH_SHORT).show();
        }
    }

    @Override
    public void onCameraMove() {
        Toast.makeText(this, "The camera is moving.",
                       Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onCameraMoveCanceled() {
        Toast.makeText(this, "Camera movement canceled.",
                       Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onCameraIdle() {
        Toast.makeText(this, "The camera has stopped moving.",
                       Toast.LENGTH_SHORT).show();
    }
}

您可以使用下列攝影機事件監聽器：

  • 攝影機開始移動時，系統會叫用 OnCameraMoveStartedListener 的 onCameraMoveStarted() 回呼，回呼方法則會接收攝影機動作的 reason。原因可能是下列其中一項：

    • REASON_GESTURE 表示攝影機是為了回應使用者地圖上的手勢 (例如平移、傾斜、雙指撥動以縮放或是旋轉地圖) 而移動。
    • REASON_API_ANIMATION 表示 API 為了回應使用者的非手勢動作 (例如輕觸縮放按鈕、輕觸 [我的位置] 按鈕或點選標記) 而移動攝影機。
    • REASON_DEVELOPER_ANIMATION 表示您的應用程式啟動了攝影機動作。

  • 使用者與觸控螢幕進行互動或攝影機移動時，系統會多次叫用 OnCameraMoveListener 的 onCameraMove() 回呼。API 會在每個頁框叫用回呼一次，瞭解這一點能幫助您掌握系統叫用回呼的頻率。不過請注意，這個回呼是以非同步方式叫用，因此會與螢幕上顯示的內容不同步。此外也請注意，在一個 onCameraMove() 回呼和下一個回呼之間，攝影機位置可能會維持不變。

  • 當攝影機停止移動且使用者停止與地圖互動時，系統會叫用 OnCameraIdleListener 的 OnCameraIdle() 回呼。

  • 目前的攝影機動作中斷時，系統會叫用 OnCameraMoveCanceledListener 的 OnCameraMoveCanceled() 回呼。在 OnCameraMoveCanceled() 回呼之後，系統會立即使用新的 reason 叫用 onCameraMoveStarted() 回呼。

    如果您的應用程式明確呼叫 GoogleMap.stopAnimation()，系統會叫用 OnCameraMoveCanceled() 回呼，但不會叫用 onCameraMoveStarted() 回呼。

如要在地圖上設定事件監聽器，請呼叫相關的事件監聽器設定方法。 舉例來說，如要向 OnCameraMoveStartedListener 要求回呼，請呼叫 GoogleMap.setOnCameraMoveStartedListener()。

您可以從 CameraPosition 取得攝影機的目標 (緯度/經度)、縮放、方位和傾斜。如要進一步瞭解這些屬性，請參閱攝影機位置指南。

商家和其他搜尋點的事件

根據預設，搜尋點會與其對應的圖示一併顯示在基本地圖上。搜尋點包括公園、學校、政府大樓等，以及像是商店、餐廳和飯店等商家搜尋點。

您可以回應搜尋點上的點擊事件。請參閱商家和其他搜尋點指南。

室內地圖事件

您可以使用事件來尋找及自訂室內地圖的顯示樓層。如要在對焦新的建築物或啟用建築物的其他樓層時呼叫事件監聽器，可以使用 OnIndoorStateChangeListener 介面設定事件監聽器。

呼叫 GoogleMap.getFocusedBuilding() 可存取目前對焦的建築物。 將地圖置於特定經緯度的中心位置時，通常會顯示該經緯度的建築物 (但不保證會如此)。

接著，您可以呼叫 IndoorBuilding.getActiveLevelIndex() 來尋找顯示樓層。

IndoorBuilding building = mMap.getFocusedBuilding();
if (building == null) {
  return null;
}
return building.getLevels().get(building.getActiveLevelIndex());

如果您想要展現顯示樓層的自訂標記 (例如標記、區域疊加層、圖塊疊加層、多邊形、折線和其他形狀)，這項做法就很實用。

提示：如要返回街景，請透過 IndoorBuilding.getDefaultLevelIndex() 取得預設樓層，並透過 IndoorLevel.activate() 將其設為顯示樓層。

標記和資訊視窗事件

您可以針對標記所屬的 GoogleMap 物件設定對應的事件監聽器，藉此監聽並回應標記事件 (包括標記點擊和拖曳事件)。請參閱標記事件指南。

您也可以在資訊視窗上監聽事件。

形狀和疊加層事件

您可以監聽並回應折線、多邊形、圓形和區域疊加層上的點擊事件。

位置事件

您的應用程式可以回應下列與「我的位置」圖層相關的事件：

詳情請參閱我的位置圖層指南。