Flutter AndroidView渲染CameraX时原生控件遮挡组件问题

问题根因 #

• 这个问题不是Flutter Stack组件写法错误，核心是Android平台原生视图的渲染机制差异：CameraX 自带的PreviewView默认采用SurfaceView作为渲染载体，SurfaceView会单独创建独立的渲染窗口，Z轴层级默认高于Flutter自身的UI渲染画布，不管你在Flutter层怎么调整组件顺序，这个独立窗口都会盖在所有Flutter组件上方，覆盖debug banner就是典型表现。

解决方案（按改造成本从低到高排序） #

方案1：修改CameraX PreviewView渲染模式（推荐） #

• 改原生侧一行配置即可解决，将PreviewView的默认渲染实现从SurfaceView切换为TextureView，TextureView不会创建独立渲染窗口，会和Flutter UI处于同一个层级合成栈，可正常和Flutter组件叠加、被覆盖。
• 原生侧修改代码示例：

// 在AndroidView对应的原生View工厂初始化PreviewView时添加配置
val previewView = PreviewView(context).apply {
    // 关键配置：切到兼容模式，底层使用TextureView渲染
    implementationMode = PreviewView.ImplementationMode.COMPATIBLE
    layoutParams = FrameLayout.LayoutParams(
        ViewGroup.LayoutParams.MATCH_PARENT,
        ViewGroup.LayoutParams.MATCH_PARENT
    )
}
// 后续绑定CameraX生命周期、Preview用例的逻辑不需要改动

• 注意：该模式相比默认SurfaceView模式性能损耗在10%以内，绝大多数业务场景无感知。

方案2：开启Flutter 混合合成模式 #

• 如果不想修改CameraX侧配置，可在Flutter侧嵌入AndroidView时显式开启Hybrid Composition合成模式，让Flutter接管原生视图的层级调度，代码示例：

AndroidView(
  viewType: '你注册的CameraX原生视图标识',
  // 传入StandardMessageCodec即可触发3.0+版本默认的混合合成逻辑
  creationParamsCodec: const StandardMessageCodec(),
)

• 补充：Flutter 3.0以下版本需要手动使用PlatformViewLink组件显式声明混合合成模式，否则默认使用的虚拟显示模式依然会存在层级问题。

方案3：上层UI全部用原生实现 #

• 如果对相机预览性能要求极高，不想承担TextureView或混合合成的性能损耗，可以把需要叠加在预览上层的UI（拍照按钮、扫码框、功能栏等）全部在原生Android侧实现，和PreviewView放在同一个原生布局中，通过MethodChannel和Flutter侧做数据交互。该方案性能最优，但双端逻辑维护成本最高。

避坑提示 #

• 不要尝试在Flutter侧通过Stack调整顺序、Clip裁剪、透明度修改等操作处理原生视图层级，只要底层还是独立Surface窗口渲染，这类Flutter层操作全部无效。
• 切换为TextureView后如果出现预览拉伸，把PreviewView的缩放类型设置为PreviewView.ScaleType.FILL_CENTER，和Flutter侧组件的宽高比对齐即可。
• 部分国产定制ROM存在TextureView硬件加速兼容问题，若遇到黑屏、花屏，可在对应Activity的清单配置中添加android:hardwareAccelerated="false"，但会小幅降低渲染性能。

内容的提问来源于stack exchange，提问作者Confidence