地图显示与配置

TencentMap Widget 是插件的核心入口，通过其构造参数可以配置地图类型、UI 控件、手势开关、显示范围等。

本文档介绍 TencentMap Widget 的全部配置参数及其使用方法。

---

TencentMap Widget 参数总览

参数	类型	默认值	说明
initialCameraPosition	CameraPosition	必填	初始相机位置（中心点 + 缩放级别）
apiKey	TencentMapApiKey?	null	API Key，不传则从平台配置读取
mapType	MapType	normal	地图类型：普通 / 卫星 / 暗色 / 3D沉浸式
compassEnabled	bool	false	是否显示指南针
scaleEnabled	bool	true	是否显示比例尺
trafficEnabled	bool	false	是否显示路况
buildingsEnabled	bool	true	是否显示 3D 建筑
labelsEnabled	bool	true	是否显示 POI 标注
rotateGesturesEnabled	bool	true	是否允许旋转手势
scrollGesturesEnabled	bool	true	是否允许平移手势
zoomGesturesEnabled	bool	true	是否允许缩放手势
tiltGesturesEnabled	bool	true	是否允许倾斜手势
touchPoiEnabled	bool	true	是否允许点击 POI
myLocationStyleOptions	MyLocationStyleOptions?	null	定位图层配置
minMaxZoomPreference	MinMaxZoomPreference?	null	缩放范围限制
limitBounds	LatLngBounds?	null	显示范围限制
logoPositionOptions	LogoPositionOptions?	null	Logo 位置配置
customStyleOptions	CustomStyleOptions?	null	个性化地图样式
polygons	Set<Polygon>	{}	多边形覆盖物
circles	Set<Circle>	{}	圆形覆盖物
arcs	Set<Arc>	{}	弧线覆盖物
polylines	Set<Polyline>	{}	折线覆盖物
markers	Set<Marker>	{}	点标记覆盖物
androidViewMode	AndroidViewMode	auto	Android 渲染模式
gestureRecognizers	Set<Factory<...>>	{}	手势冲突处理

---

地图类型

TencentMap(
  mapType: MapType.normal,    // 普通地图（默认）
  // mapType: MapType.satellite, // 卫星地图
  // mapType: MapType.dark,      // 暗色模式
  // mapType: MapType.immersive3D, // 3D 沉浸式
  ...
)

枚举值	说明
MapType.normal	普通矢量地图，显示道路、建筑、POI 等
MapType.satellite	卫星影像地图
MapType.dark	暗色模式地图
MapType.immersive3D	3D 沉浸式地图

---

UI 控件

指南针

TencentMap(
  compassEnabled: true, // 显示指南针（默认 false）
  ...
)

指南针在地图旋转后出现，点击可恢复正北朝向。

比例尺

TencentMap(
  scaleEnabled: true, // 显示比例尺（默认 true）
  ...
)

Logo 位置

TencentMap(
  logoPositionOptions: LogoPositionOptions(
    anchor: LogoAnchor.bottomRight, // 默认右下角
    offset: const Offset(10, 10),   // 距边缘偏移（逻辑像素）
  ),
  ...
)

LogoAnchor 枚举	说明	Android	iOS
bottomLeft	左下角	✅	✅
bottomRight	右下角（默认）	✅	✅
topLeft	左上角	✅	✅
topRight	右上角	✅	✅

---

地图开关

TencentMap(
  trafficEnabled: true,    // 开启路况
  buildingsEnabled: false, // 关闭 3D 建筑
  labelsEnabled: false,    // 关闭 POI 标注
  ...
)

参数	说明	默认值
trafficEnabled	路况图层（红/黄/绿表示拥堵程度）	false
buildingsEnabled	3D 建筑物渲染	true
labelsEnabled	POI 标注（地名、店铺等）	true

---

手势开关

TencentMap(
  rotateGesturesEnabled: false, // 禁用旋转
  scrollGesturesEnabled: true,  // 允许平移
  zoomGesturesEnabled: true,    // 允许缩放
  tiltGesturesEnabled: false,   // 禁用倾斜
  ...
)

---

缩放范围限制

TencentMap(
  minMaxZoomPreference: const MinMaxZoomPreference(5, 18), // 限制 5~18 级
  ...
)

参数	类型	说明
minZoom	double	最小缩放级别（默认 3）
maxZoom	double	最大缩放级别（默认 20）

---

显示范围限制

TencentMap(
  limitBounds: LatLngBounds(
    southwest: const LatLng(39.8, 116.3), // 西南角
    northeast: const LatLng(40.0, 116.5), // 东北角
  ),
  ...
)

取消限制时传 null：

// 取消范围限制
limitBounds: null,

注意：取消限制必须传 null。

---

运行时更新配置

以上所有配置参数均支持声明式更新。修改 TencentMap Widget 的参数后，插件会自动 diff 并将变化推送到原生层，无需手动调用 setter。

// 切换为卫星地图 + 开启路况
setState(() {
  // 直接修改 Widget 参数即可
});