事件Events

Maps SDK 提供多种方法来监听地图事件 Events。以下列出此 SDK 提供的大多数监听器。不过在其他概述文档中，您也可能偶尔找到与这些 API 不同的其他监听器。

地图单击和长单击事件

单击（点击）事件可以通过 MapboxMap 对象来设置，并在每次发生该事件时调用回调。在这两种情况下，回调都提供地图上发生用户单击的位置的 LatLng。要将 onClick 监听器添加到地图，请将以下代码段插入应用程序的代码中：

mapboxMap.setOnMapClickListener(new MapboxMap.OnMapClickListener() {
  @Override
  public void onMapClick(@NonNull LatLng point) {
    String string = String.format(Locale.US, "User clicked at: %s", point.toString())
    Toast.makeText(MainActivity.this, string, Toast.LENGTH_LONG).show();
  }
});

从屏幕像素转换

开发者如果想知道屏幕上用户手势出现的相应位置时，可以将 LatLng 点转换为屏幕像素。MapboxMap 对象提供地图的Projection，这允许您使用 mapboxMap.getProjection().toScreenLocation(<LatLng>); 在 LatLng 坐标与屏幕像素之间进行转换。您可以将以像素为单位的屏幕位置，转换为相应的 LatLng 对象，也可以进行相反的转换。

在 LatLng 和像素坐标之间转换值的常见用例，是在您希望查询地图层或源的时候，如确定用户是否点击了某 POI。您可以在查询地图要素文档中阅读有关如何执行此操作的更多信息。

Camera 变化事件

地图 Camera 代表地图平面上的俯瞰视图。在几乎所有情况下，您都将与 Camera 交互以调整地图的起始缩放和目标位置。用户还可以通过在地图上做出手势来操纵 Camera，例如捏拉缩放（pinch-to-zoom）、双手指滚动来倾斜地图，以及单指移动来调整位置。

Map SDK 提供一些 Camera 变化监听器，它们可以向您通报任何或特定 Camera 移动。提供不同的 Camera 监听器来确定 Camera 移动是由用户手势、内置 API 动画还是由开发者控制的移动引起。以下代码段显示可用的各种 Camera 监听器：

mapboxMap.setOnCameraMoveStartedistener(new MapboxMap.OnCameraMoveStartedListener() {
 
  private final String[] REASONS = {"REASON_API_GESTURE", "REASON_DEVELOPER_ANIMATION", "REASON_API_ANIMATION"};
 
  @Override
  public void onCameraMoveStarted(int reason) {
    String string = String.format(Locale.US, "OnCameraMoveStarted: %s", REASONS[reason - 1])
    Toast.makeText(MainActivity.this, string, Toast.LENGTH_LONG).show();
  }
});
 
mapboxMap.setOnCameraMoveListener(new MapboxMap.OnCameraMoveListener() {
  @Override
  public void onCameraMove() {  
    Toast.makeText(MainActivity.this, "onCameraMove", Toast.LENGTH_LONG).show();
  }
});
 
mapboxMap.setOnCameraMoveCancelListener(new MapboxMap.OnCameraMoveCanceledListener() {
  @Override
  public void onCameraMoveCanceled() {
    Toast.makeText(MainActivity.this, "onCameraMoveCanceled", Toast.LENGTH_LONG).show();
  }
});
 
mapboxMap.setOnCameraIdleListener(new MapboxMap.OnCameraIdleListener() {
  @Override
  public void onCameraIdle() {
    Toast.makeText(MainActivity.this, "onCameraIdle", Toast.LENGTH_LONG).show();
  }
});

拖拽和滚动事件

除了 Camera 变化监听器，MapboxMap 对象还允许您监听用户何时滚动或拖拽地图。用户在屏幕上拖动单个手指导致 Camera 位置发生变化时，会发生滚动事件。用户的类似操作将导致调用 onFling 回调，但用户以更多动量做出手势。在用户做出特定手势时，仅触发一次这些事件之一。

mapboxMap.setOnScrollListener(new MapboxMap.OnScrollListener() {
  @Override
  public void onScroll() {
    Toast.makeText(MainActivity.this, "onScroll", Toast.LENGTH_LONG).show();
  }
});
 
mapboxMap.setOnFlingListener(new MapboxMap.OnFlingListener() {
  @Override
  public void onFling() {
    Toast.makeText(MainActivity.this, "onFling", Toast.LENGTH_LONG).show();
  }
});

标记 Marker 和信息窗口事件

Maps SDK 提供一个方便的监听器来捕获用户何时点击标记。默认情况下，所有标记都随附一个 onMarkerClick 事件监听器来显示和隐藏信息窗口。您可以覆盖此默认事件监听器，并使用 setOnMarkerClickListener 方法设置自己的事件监听器。

要显示标记标题上发生点击的 toast 消息，请使用 setOnMarkerClickListener 来监听单击事件，最后调用 Toast.makeText()。要防止 toast 消息和信息窗口的同时显示，请在末尾返回 true：

mapboxMap.setOnMarkerClickListener(new MapboxMap.OnMarkerClickListener() {
  @Override
  public boolean onMarkerClick(@NonNull Marker marker) {
    Toast.makeText(MainActivity.this, marker.getTitle(), Toast.LENGTH_LONG).show();
    return true;
  }
});

在类似情况下，信息窗口提供一些监听器，用于在单击信息窗口、长单击或用户关闭窗口时接收通知。

mapboxMap.setOnInfoWindowLongClickListener(OnInfoWindowLongClickListener);
mapboxMap.setOnInfoWindowCloseListener(OnInfoWindowCloseListener);
 
mapboxMap.setOnInfoWindowClickListener(new MapboxMap.OnInfoWindowClickListener() {
  @Override
  public boolean onInfoWindowClick(@NonNull Marker marker) {
    return false;
  }
});

地图更改事件

在构建/更改地图时，地图视图会经历一系列事件。在发生您感兴趣的某个或多个事件时，提供的 OnMapChangedListener 可用于通知您。这包括了解地图何时开始和完成地图样式加载或帧何时完成呈现。

不是通过 MapboxMap 对象添加监听器，而是使用 MapView、MapView addOnMapChangedListener (OnMapChangedListener()); 来添加监听器。发生新的地图更改时，将调用 onMapChanged 回调。这提供常量（整数）作为参数，然后您可以使用该常量来匹配下表中列出的常量之一。

当您不再需要监听地图改变事件时， 可以用mapView. removeOnMapChangedListener(mapChangeListener) 移除监听器。