地图事件

TencentMap Widget 提供丰富的事件回调，用于监听用户的交互操作和地图状态变化。

本文档介绍各类地图事件的回调接口及其使用方法。

---

事件总览

事件	回调参数	说明
onMapCreated	TencentMapController	地图创建完成
onMapLoaded	无	地图瓦片加载完成
onTap	LatLng	点击地图空白处
onLongPress	LatLng	长按地图
onPoiTouched	TencentMapPoi	点击 POI 标注
onCameraMoveStarted	CameraPosition	相机开始移动
onCameraMove	CameraPosition	相机移动中
onCameraMoveEnd	CameraPosition	相机移动结束

---

地图创建与加载

TencentMap(
  onMapCreated: (controller) {
    // 地图 PlatformView 创建完成，可在此获取 controller
    // 此时地图可能尚未渲染瓦片
    _controller = controller;
  },
  onMapLoaded: () {
    // 地图瓦片加载完成，可安全进行相机操作
    print('地图加载完成');
  },
  ...
)

注意：onMapCreated 和 onMapLoaded 的区别——onMapCreated 是 PlatformView 创建完成的回调，此时地图引擎已就绪但瓦片可能还在下载；onMapLoaded 是瓦片渲染完成的回调。相机操作（如 moveCamera）建议在 onMapLoaded 后执行。

---

地图点击

TencentMap(
  onTap: (latLng) {
    print('点击位置: ${latLng.latitude}, ${latLng.longitude}');
  },
  onLongPress: (latLng) {
    print('长按位置: ${latLng.latitude}, ${latLng.longitude}');
  },
  ...
)

事件	触发条件	返回值
onTap	单击地图空白区域	点击位置的 LatLng
onLongPress	长按地图	长按位置的 LatLng

注意：点击 Marker、Polygon 等覆盖物时不会触发 onTap，覆盖物有自己的点击回调。

---

POI 点击

TencentMap(
  onPoiTouched: (poi) {
    print('POI 名称: ${poi.name}');
    print('POI ID: ${poi.id}');
    print('POI 位置: ${poi.latLng.latitude}, ${poi.latLng.longitude}');
  },
  ...
)

TencentMapPoi 结构：

字段	类型	说明
id	String	POI 唯一标识
name	String	POI 名称
latLng	LatLng?	POI 经纬度位置

注意：可通过 touchPoiEnabled: false 禁用 POI 点击事件。

---

相机事件

TencentMap(
  onCameraMoveStarted: (position) {
    print('开始移动，目标: ${position.target}');
  },
  onCameraMove: (position) {
    // 高频回调，适合实时更新 UI
    print('当前缩放: ${position.zoom.toStringAsFixed(1)}');
  },
  onCameraMoveEnd: (position) {
    print('移动结束: ${position.target}, zoom=${position.zoom}');
  },
  ...
)

详细说明请参考相机控制文档。

---

完整示例

TencentMap(
  initialCameraPosition: const CameraPosition(
    target: LatLng(39.9087, 116.3975),
    zoom: 12,
  ),
  onMapCreated: (controller) => _controller = controller,
  onMapLoaded: () => print('地图加载完成'),
  onTap: (latLng) => print('点击: $latLng'),
  onLongPress: (latLng) => print('长按: $latLng'),
  onPoiTouched: (poi) => print('POI: ${poi.name}'),
  onCameraMoveStarted: (pos) => print('相机开始移动'),
  onCameraMove: (pos) => print('缩放: ${pos.zoom.toStringAsFixed(1)}'),
  onCameraMoveEnd: (pos) => print('相机移动结束'),
)