相机控制

相机（Camera）控制地图的视角，包括中心点位置、缩放级别、旋转角度和倾斜角度。插件提供 CameraPosition 描述相机状态，通过 CameraUpdate 执行相机移动。

本文档介绍相机位置的设置、移动动画、以及相机变化事件的监听。

---

CameraPosition

CameraPosition 描述相机的完整状态：

参数	类型	说明
target	LatLng	地图中心点经纬度
zoom	double	缩放级别（3~20，值越大越放大）
bearing	double	旋转角度（0~360，正北为 0，顺时针增加）
tilt	double	倾斜角度（0~45，0 为俯视）

const CameraPosition(
  target: LatLng(39.9087, 116.3975),
  zoom: 12,
  bearing: 0,
  tilt: 0,
)

---

CameraUpdate 工厂方法

CameraUpdate 提供了 8 种工厂方法用于不同场景的相机移动：

方法	说明
CameraUpdate.newCameraPosition(pos)	移动到完整的 CameraPosition
CameraUpdate.newLatLng(latLng)	移动中心点到指定坐标，保持当前缩放
CameraUpdate.newLatLngZoom(latLng, zoom)	移动中心点并设置缩放级别
CameraUpdate.newLatLngBounds(bounds, [padding])	自动调整视角以显示整个 bounds 区域，padding 可为 double（四边相同）或 EdgeInsets（四边独立）
CameraUpdate.zoomIn()	放大一级
CameraUpdate.zoomOut()	缩小一级
CameraUpdate.zoomTo(zoom)	缩放到指定级别
CameraUpdate.scrollBy(dx, dy)	按屏幕像素偏移平移地图

---

moveCamera

通过 TencentMapController 调用相机移动：

// 同步移动（无动画）
controller.moveCamera(CameraUpdate.newLatLng(LatLng(39.9, 116.4)), animated: false);

// 动画移动（默认 250ms）
controller.moveCamera(CameraUpdate.newLatLng(LatLng(39.9, 116.4)));

// 动画移动（自定义时长）
controller.moveCamera(
  CameraUpdate.newLatLng(LatLng(39.9, 116.4)),
  animated: true,
  duration: 500,
);

参数	类型	默认值	说明
cameraUpdate	CameraUpdate	必填	相机更新指令
animated	bool	true	是否使用动画过渡
duration	int?	null	动画时长（毫秒），仅 animated: true 时生效

---

使用示例

移动到指定坐标并缩放

controller.moveCamera(
  CameraUpdate.newLatLngZoom(
    const LatLng(31.2304, 121.4737), // 上海
    14,
  ),
  duration: 500,
);

显示一个区域

controller.moveCamera(
  CameraUpdate.newLatLngBounds(
    LatLngBounds(
      southwest: const LatLng(39.8, 116.3),
      northeast: const LatLng(40.0, 116.5),
    ),
    100, // padding（逻辑像素）
  ),
);

平移地图

// 向右下平移 100 像素
controller.moveCamera(CameraUpdate.scrollBy(100, 100));

---

相机事件回调

TencentMap Widget 提供三个相机事件回调：

TencentMap(
  onCameraMoveStarted: (position) {
    print('相机开始移动: ${position.target}');
  },
  onCameraMove: (position) {
    // 移动过程中持续回调（高频）
    print('缩放级别: ${position.zoom}');
  },
  onCameraMoveEnd: (position) {
    print('相机移动结束: ${position.target}, zoom=${position.zoom}');
  },
  ...
)

回调	触发时机	频率
onCameraMoveStarted	相机开始移动（手势或 API 调用）	一次
onCameraMove	相机移动过程中	高频（每帧）
onCameraMoveEnd	相机移动结束	一次

注意：onCameraMoveStarted 仅在 SDK ≥ 6.7.0（Android）/ 对应 iOS 版本上触发。低版本 SDK 会 fallback 为 onCameraMove + onCameraMoveEnd 两个事件。

---

注意事项

• newLatLngBounds 的 bounds 合法性：southwest 必须在 northeast 的西南方（纬度更低、经度更小）。
• moveCamera 的 duration 仅在 animated: true 时生效。
• 地图旋转/倾斜后，onCameraMove 回调的 position.bearing 和 position.tilt 会反映当前角度。