Camera

翻译：郭文密

Maps SDK 的 Camera 是用户在地图上的视区。可以通过屏幕上的手势（例如捏合或使用预先编写的代码）倾斜(tilted)，旋转(rotated)，缩放(zoomed)和/或移动(moved)相机。重要的是，在没有对此行为的直接影响的情况下，Camera 不会对地图中的标记(marker)，图层(layer)，源(sources)或其他标注(annotation)进行任何更改。

Maps SDK 中提供了一些 Camera 事件侦听器来监听各种通知，例如 Camera 何时被调整。可以在事件页面中了解有关这些侦听器的更多信息。

Camera 位置

Maps SDK 包含一个 CameraPosition类，该类包括 Camera 的目标(target)、角度(angle)、缩放(zoom)、倾斜(tilt)和填充(padding)。Camera 的这些选项可以塑造用户对地图切片(tile)的透视图。

目标 Target

目标 Target 是 Camera 中心所在的经纬度坐标。改变 Camera 的目标 Target 将会移动 Camera 到该输入的坐标。目标 Target 是LatLng 对象。目标 Target 坐标始终处于整个视区的中心。

用手指拖拽地图会平移地图，从而平移 Camera 的目标 Target。

倾斜 Tilt

倾斜度是 Camera 与最低点（直接面对地球）之间的角度，它使用度作为单位。 Camera 的最小（默认）倾斜是0度，最大倾斜是60度。倾斜度精确到六位小数，这样能够极其准确地限制/设置/锁定地图的方位。

还可以通过将两个指尖放在地图上并同时平行地上下移动两个手指，来调整地图 Camera 的倾斜度。

方位 Bearing

方位 Bearing 是 Camera 指向的方向，并从北向顺时针方向以度为度量单位。

Camera 的默认方位为0度（即“正北”），此时地图罗盘将会被隐藏，直到 Camera 方位变为非零值时，罗盘将会再次显示。 mapbox_uiCompass 布尔XML属性允许调整罗盘的可见性。方位使用六位小数精度，这使您能够极其精确地限制/设置/锁定地图的方位。除了以编程方式外，用户还可以将两个指尖放在地图上并旋转手指调整Camera方位。

缩放 Zoom

缩放 Zoom 控制地图的比例，并采用 0 到 22 之间的任何值。缩放级别为 0 时，当前视区显示大洲和其他世界特征。当为中间值 11 时，将显示城市级别的细节，而在更高的缩放水平下，地图将开始显示建筑物和兴趣点。 Camera 可以通过以下方式缩放：

捏合两根手指以放大和缩小。
一根手指在地图上快速点按两次放大。
在地图上用一根手指快速点击两次，第二次点击后手指按在屏幕上，然后向上向下滑动手指可以缩放。

为确保您的地图样式在正确的Camera位置显示正确的数据，参阅关于地图的艺术/科学和视觉信息的文章：为移动设备设计地图。

获取 Camera 当前位置

MapboxMap类的getCameraPosition()方法可用来了解地图Camera的当前发生的情况以及用户的视区。一旦地图被成功初始化，可通过MapboxMap对象检索地图的CameraPosition。各种Camera值位于CameraPosition对象中。

·`java CameraPosition currentCameraPosition = mapboxMap.getCameraPosition(); double currentZoom = currentCameraPosition.zoom; double currentTilt = currentCameraPosition.tilt;

```kotlin
val currentCameraPosition = mapboxMap.cameraPosition
val currentZoom = currentCameraPosition.zoom
val currentTilt = currentCameraPosition.tilt

更新 Camera 位置

Animate the map camera

example

Change the camera target, bearing, zoom, and tilt by animating the camera.

Maps SDK 中的MapboxMap 类有多种更改相机位置的方法。每个 Camera 移动 API 都包含一个CameraUpdate 对象。应该使用CameraUpdateFactory类提供新的 Camera 位置信息。 CameraUpdateFactory 可以构建多个不同的CameraUpdate 对象，包括newLatLngZoom()，zoomBy()，newLatLngBounds() 等。 CameraUpdate 中有一个直接创建CameraPosition的方法newCameraPosition() 。

CameraPosition 对象可以更改相机对象的单个属性（例如缩放），也可以同时更改多个属性。例如，可以同时更改 Camera 的目标，缩小和倾斜：

CameraPosition position = new CameraPosition.Builder()
    .target(new LatLng(51.50550, -0.07520))
    .zoom(10)
    .tilt(20)
    .build();

val position = CameraPosition.Builder()
    .target(LatLng(51.50550, -0.07520))
    .zoom(10.0)
    .tilt(20.0)
    .build()

阅读所有有关MapView XML 属性的内容，以了解如何使用XML而不是通过Java或Kotlin来设置Camera的初始位置。您应该使用XML或通过MapboxMapOptions来设置Camera的初始位置，去避免不必要的而且会耗尽用户数据的地图图块的下载。

mapboxMap.animateCamera(CameraUpdateFactory.newCameraPosition(position), millisecondSpeed);

mapboxMap.animateCamera(CameraUpdateFactory.newCameraPosition(position), millisecondSpeed)

除了使用CameraUpdate对象外，还可以添加可取消的回调，以了解动画何时结束或用户是否通过在地图上执行手势来取消Camera移动。 easeCamera()或animateCamera()方法具有一个可选的持续时间参数（以毫秒为单位），它可以控制Camera移动到地图上新位置的速度。

Method	Description
`moveCamera()`	瞬间根据`CameraUpdate`对象参数中定义的说明重新定位Camera。`moveCamera()` 会快速移动Camera，这可能会给用户带来视觉冲击。强烈推荐改用不那么突兀的`easeCamera()`或`animateCamera()`方法。
`easeCamera()`	根据`CameraUpdate`对象参数中定义的说明逐渐移动 Camera。 Camera 使用默认持续时间进行移动，但是可以将以毫秒为单位的自定义持续时间设置为第二个参数。除非在`CameraUpdate`对象中指定，否则 Camera 的缩放级别不会受到影响。如果您当前正在使用此方法让地图 Camera 随着设备位置的变化而跟踪用户，请使用`LocationComponent`的`CameraMode.TRACKING`模式，而不是自己移动相机。 `easeCamera()`的另一个可选参数是一个布尔值，用于设置是否使用动画插值器。禁用插值器会导致线性地动画移动到新位置。 Java SDK Isochrone API 示例使用了动画插值。
`animateCamera()`	使用动画将 Camera 移动到“ CameraUpdate”对象中定义的新位置。预定义的Camera动画会唤起动力飞行。一个使用此方法的示例。

在地图区域内居中 Camera

Center the camera

example

Adjust the camera position to fit a bounding box within the viewport.

Camera 还可以在地图区域内居中，例如如何将 Camera 限制在某个区域内（请参阅下文）。首先，需要定义一个至少包含两个坐标的LatLngBounds对象。然后，可以使用可用的newLatLngBounds()方法来更新 Camera 位置，该方法将使用边界框并调整视区，以使指定区域位于视区内。除了将边界框传递到CameraUpdateFactory之外，还需要提供一个定义屏幕边缘与实际边界区域之间的填充的int值。同样的，还可以为边界框的每一边提供不同的填充值。

LatLngBounds latLngBounds = new LatLngBounds.Builder()
                    .include(first marker position)
                    .include(second marker position)
                    .build();
 
mapboxMap.animateCamera(CameraUpdateFactory.newLatLngBounds(latLngBounds, 10));

val latLngBounds = LatLngBounds.Builder()
                .include(first marker position)
                .include(second marker position)
                .build()
mapboxMap.animateCamera(CameraUpdateFactory.newLatLngBounds(latLngBounds, 10));