Android 渲染模式

插件支持两种 Android 端地图渲染模式：SurfaceView（Hybrid Composition）和 TextureView（Virtual Display）。不同的渲染模式在性能和兼容性上有差异。

本文档介绍两种模式的区别及选择建议。

---

AndroidViewMode 枚举

TencentMap(
  androidViewMode: AndroidViewMode.auto, // 默认
  ...
)

枚举值	说明
auto	自动选择（默认）：Android 10+ 用 SurfaceView，以下用 TextureView
surfaceView	强制使用 SurfaceView
textureView	强制使用 TextureView

注意：此参数仅影响 Android 端，iOS 端忽略。

---

两种模式对比

特性	SurfaceView (MapView)	TextureView (TextureMapView)
渲染方式	Hybrid Composition	Virtual Display
性能	更好（独立 Surface，直接 GPU 渲染）	略低（额外纹理拷贝）
Flutter 合成	需要主线程同步等待 GPU fence	异步纹理更新

---

auto 模式（推荐）

auto 模式根据系统版本自动选择：

• Android 10+（API 29+）：使用 SurfaceView（性能优先）
• Android 10-：使用 TextureView（兼容性优先）

大多数场景下使用 auto 即可。

---

何时手动指定

强制 TextureView

TencentMap(
  androidViewMode: AndroidViewMode.textureView,
  ...
)

适用场景：

• Android 10 以下设备出现 SurfaceView 闪烁/黑屏
• 需要在地图上叠加 Flutter Widget 且要求精确层级控制

强制 SurfaceView

TencentMap(
  androidViewMode: AndroidViewMode.surfaceView,
  ...
)

适用场景：

• 需要最高渲染性能
• 确认目标设备均为 Android 10+

注意：在 Android 10 以下设备强制使用 SurfaceView 可能出现闪烁、黑屏等渲染问题。