Google Maps Platform 推出 15 周年 - 查看最新资讯和公告

事件

利用 Maps SDK for Android,您可以监听地图上的事件。

代码示例

GitHub 上的 ApiDemos 代码库包含展示事件和监听器的相关示例:

地图点击/长按事件

如果您想对用户点按地图上某一点的操作作出响应,可以使用 OnMapClickListener(可通过调用 GoogleMap.setOnMapClickListener(OnMapClickListener) 在地图上进行设置)。当用户在地图上点击(点按)某个位置时,您会收到一个 onMapClick(LatLng) 事件,指示用户在地图上点击的位置。请注意,如果您需要屏幕上的对应位置(以像素表示),可以从地图中获取 Projection,后者可在纬度/经度坐标与屏幕像素坐标之间进行转换。

您还可以使用 OnMapLongClickListener(可通过调用 GoogleMap.setOnMapLongClickListener(OnMapLongClickListener) 在地图上进行设置)监听长按事件。该监听器的行为与点击监听器的行为类似,系统会使用 onMapLongClick(LatLng) 回调将长按事件告知该监听器。

在精简模式下停用点击事件

要在精简模式下停用地图上的点击事件,请对包含 MapViewMapFragment 的视图调用 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();
    }
}

以下相机监听器可供使用:

  • 当相机开始移动时,系统会调用 OnCameraMoveStartedListeneronCameraMoveStarted() 回调。此回调方法将收到相机移动的 reason。原因可能为下列之一:

    • REASON_GESTURE 表示相机移动是为了响应用户在地图上做出的手势,如平移、倾斜、通过双指张合进行缩放或旋转地图。
    • REASON_API_ANIMATION 表示 API 移动相机是为了响应用户的非手势操作,如点按缩放按钮、点按“我的位置”按钮或点击标记。
    • REASON_DEVELOPER_ANIMATION 表示您的应用发起了相机移动。
  • 当相机正在移动或用户正与触摸屏互动时,系统将多次调用 OnCameraMoveListeneronCameraMove() 回调。API 针对每个帧调用一次回调,知道这一点有助于确定调用回调的频率。但请注意,此回调是异步调用的,因此,它与屏幕上显示的内容不同步。另请注意,在一次 onCameraMove() 回调和下一次回调之间相机位置可以保持不变。

  • 当相机停止移动且用户已停止与地图互动时,系统将调用 OnCameraIdleListenerOnCameraIdle() 回调。

  • 在当前相机移动已中断时,系统将调用 OnCameraMoveCanceledListenerOnCameraMoveCanceled() 回调。调用 OnCameraMoveCanceled() 回调之后,系统会立即使用新的 reason 调用 onCameraMoveStarted() 回调。

    如果您的应用明确调用 GoogleMap.stopAnimation(),则系统将调用 OnCameraMoveCanceled() 回调,但不会调用 onCameraMoveStarted() 回调。

要在地图上设置监听器,请调用相关的设置监听器方法。例如,要从 OnCameraMoveStartedListener 请求回调,请调用 GoogleMap.setOnCameraMoveStartedListener()

您可以从 CameraPosition 获取相机的目标(纬度/经度)、缩放级别、方位及倾斜度。如需详细了解这些属性,请参阅有关相机位置的指南。

商家和其他地图注点上的事件

默认情况下,地图注点 (POI) 将与对应的图标一起显示在基本地图上。地图注点包括公园、学校、政府大楼,以及商店、餐馆和酒店等商家地图注点。

您可以响应地图注点上的点击事件。请参阅有关商家和其他地图注点的指南。

室内地图事件

您可以利用事件来查找和自定义室内地图的活动楼层。使用 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 对象上设置相应的监听器来监听和响应标记事件,包括标记点击和拖动事件。请参阅有关标记事件的指南。

您还可以监听信息窗口上的事件。

形状和叠加层事件

您可以监听和响应多段线多边形圆形地面叠加层上的点击事件。

位置事件

您的应用可以响应以下与“我的位置”图层相关的事件:

如需了解详情,请参阅有关“我的位置”图层的指南。