第四章 创建CameraX预览用例

4.1 原理概述

CameraX 预览（Preview）用例是连接相机硬件与屏幕显示的桥梁。其核心原理包含三个要素：

• Preview.Builder – 负责配置预览参数（分辨率、帧率、目标旋转等），生成 Preview 实例。
• SurfaceProvider – 提供显示表面（Surface），CameraX 将相机帧渲染到该表面，通常由 PreviewView 或 Compose 的 AndroidView 包装的 SurfaceView/TextureView 提供。
• ProcessCameraProvider – 绑定生命周期，将 Preview 用例与 Activity 或 Fragment 的生命周期关联，自动启动/停止相机。

绑定生命周期后，CameraX 内部会为 Preview 用例分配一个 CameraSession，当 SurfaceProvider 就绪时，相机帧开始流向 Surface，用户即可在屏幕上看到实时预览画面。

4.2 实现流程

4.3 代码实现（Compose 环境）

以下示例展示如何在 Compose 中创建一个全屏相机预览界面，使用 PreviewView 作为 SurfaceProvider。

@Composable
fun CameraPreviewScreen() {
    val context = LocalContext.current
    val lifecycleOwner = LocalLifecycleOwner.current

    // PreviewView 暴露的 SurfaceProvider
    val previewView = remember { PreviewView(context) }

    DisposableEffect(lifecycleOwner) {
        val cameraProviderFuture = ProcessCameraProvider.getInstance(context)
        cameraProviderFuture.addListener({
            val cameraProvider = cameraProviderFuture.get()

            // 配置 Preview 用例
            val preview = Preview.Builder()
                .setTargetResolution(Size(1920, 1080))  // 目标分辨率
                .setTargetRotation(Surface.ROTATION_0)   // 主轴旋转
                .build()

            // 设置 SurfaceProvider 为 PreviewView 提供的
            preview.setSurfaceProvider(previewView.surfaceProvider)

            // 选择后置摄像头
            val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA

            // 绑定生命周期（自动管理相机）
            try {
                cameraProvider.unbindAll()
                cameraProvider.bindToLifecycle(
                    lifecycleOwner,
                    cameraSelector,
                    preview
                )
            } catch (e: Exception) {
                Log.e("CameraPreview", "绑定失败", e)
            }
        }, ContextCompat.getMainExecutor(context))

        onDispose {
            // 生命周期结束时不需要手动释放，CameraX 自动处理
        }
    }

    // 将 PreviewView 放入 Compose 树
    AndroidView(
        factory = { previewView },
        modifier = Modifier.fillMaxSize()
    )
}

4.4 SurfaceProvider 的多种获取方式

4.5 调试与部署

• 检查预览画面：确保 Activity 或 Fragment 的布局中包含了 PreviewView 并占据可见区域。
• 日志输出：监听 CameraX 内部日志（通过 CameraXConfig 设置最低日志级别）或使用 android.util.Log 输出步骤信息。
• 权限验证：AndroidManifest.xml 中必须声明 CAMERA 权限，且在运行时要动态请求。
• 模拟器问题：Android 模拟器需要支持 Camera 模拟（AVD 配置中勾选 Camera 支持），否则预览黑屏。

4.6 性能与稳定性优化

4.7 预览用例创建流程

下面这张流程图总结了从初始化到预览画面显示的核心步骤：

4.8 常见错误与排查

4.9 部署到真机/模拟器

• 在 AndroidManifest.xml 中添加 <uses-permission android:name="android.permission.CAMERA" /> 及 <uses-feature android:name="android.hardware.camera" />。
• 动态权限请求建议使用 Compose 的 rememberLauncherForActivityResult 封装，或第三方库（如 Accompanist Permissions）。
• 模拟器预览时，请确保 AVD 的 Camera 设置为 “Webcam” 或 “Emulated”。部分模拟器不支持所有分辨率，建议先使用 Preview.Builder.setTargetResolution(Size(640,480)) 调试。

至此，你已经完成 CameraX 预览用例的创建、配置、绑定与显示。下一阶段将学习如何切换前后摄像头，以及对预览画面进行实时滤镜处理。