3. 拍照功能实现：配置 ImageCapture 用例、拍照回调、保存图片到相册

3.1 本章概述

拍照是相机应用最核心的功能之一。CameraX 通过 ImageCapture 用例提供标准化拍照能力，开发者只需完成“配置用例 → 绑定生命周期 → 触发拍照 → 处理回调 → 保存图片”五个步骤。本章从原理出发，逐步拆解每一环节的 API 调用、参数配置、回调处理以及保存策略，同时覆盖调试方法与常见陷阱。

3.2 原理：ImageCapture 用例工作模型

ImageCapture 内部封装了 Camera2 的 CaptureRequest 与 CaptureCallback 的复杂交互。其核心处理链路如下：

• 触发拍照：调用 takePicture() 方法，CameraX 内部创建一个单次捕获请求。
• 图像捕获：底层 Camera2 返回 JPEG 或 YUV_420_888 格式的原始帧。
• 回调分发：数据进入 OnImageCapturedCallback（内存模式）或 OnImageSavedCallback（文件模式）。
• 后处理：Exif 写入（方向、GPS）、缩略图生成、存储到 MediaStore。

3.3 配置 ImageCapture 用例

通过 ImageCapture.Builder 设置输出格式、分辨率、闪关灯模式等参数，再通过 bindToLifecycle 注册到 CameraX 会话。

3.3.1 核心配置参数

// 典型配置示例
val imageCapture = ImageCapture.Builder()
    .setCaptureMode(ImageCapture.CAPTURE_MODE_MAXIMIZE_QUALITY)
    .setFlashMode(ImageCapture.FLASH_MODE_AUTO)
    .setTargetResolution(Size(1920, 1080))
    .setTargetRotation(Surface.ROTATION_0)
    .setJpegQuality(95)
    .build()

3.3.2 绑定到生命周期

val cameraProviderFuture = ProcessCameraProvider.getInstance(context)
cameraProviderFuture.addListener({
    val cameraProvider = cameraProviderFuture.get()
    val preview = Preview.Builder().build()
    val imageCapture = ImageCapture.Builder().build()
    val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
    val camera = cameraProvider.bindToLifecycle(
        lifecycleOwner,
        cameraSelector,
        preview,
        imageCapture
    )
}, ContextCompat.getMainExecutor(context))

3.4 拍照回调：两种模式对比

3.4.1 内存模式回调

imageCapture.takePicture(
    ContextCompat.getMainExecutor(context),
    object : ImageCapture.OnImageCapturedCallback() {
        override fun onCaptureSuccess(imageProxy: ImageProxy) {
            // imageProxy.image 可获取 ByteBuffer
            // 注意：必须调用 imageProxy.close() 释放帧
            imageProxy.close()
        }

        override fun onError(exception: ImageCaptureException) {
            Log.e("CameraX", "拍照失败: ${exception.message}")
        }
    }
)

3.4.2 文件模式回调

val photoFile = File(
    context.getExternalFilesDir(Environment.DIRECTORY_PICTURES),
    "IMG_${System.currentTimeMillis()}.jpg"
)
val outputOptions = ImageCapture.OutputFileOptions.Builder(photoFile).build()

imageCapture.takePicture(
    outputOptions,
    ContextCompat.getMainExecutor(context),
    object : ImageCapture.OnImageSavedCallback() {
        override fun onImageSaved(outputFileResults: ImageCapture.OutputFileResults) {
            Log.d("CameraX", "图片已保存: ${photoFile.absolutePath}")
        }

        override fun onError(exception: ImageCaptureException) {
            Log.e("CameraX", "保存失败: ${exception.message}")
        }
    }
)

3.5 保存图片到相册

Android 10（API 29）之后推荐使用 MediaStore 保存在系统相册，应用卸载后图片仍保留。Android 10 以下使用 Environment.getExternalStoragePublicDirectory() 并扫描 MediaScanner。

3.5.1 MediaStore 保存（API 29+）

val contentValues = ContentValues().apply {
    put(MediaStore.Images.Media.DISPLAY_NAME, "IMG_${System.currentTimeMillis()}.jpg")
    put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg")
    put(MediaStore.Images.Media.RELATIVE_PATH, Environment.DIRECTORY_PICTURES + "/CameraXDemo")
}

val uri = context.contentResolver.insert(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    contentValues
)

// 将文件模式输出指向 MediaStore URI
val outputOptions = ImageCapture.OutputFileOptions.Builder(
    context.contentResolver,
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    contentValues
).build()

3.5.2 传统文件保存（兼容旧版本）

val photoFile = File(
    Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES),
    "CameraXDemo/IMG_${System.currentTimeMillis()}.jpg"
)
photoFile.parentFile?.mkdirs()

// 写文件后再通知 MediaScanner
val outputOptions = ImageCapture.OutputFileOptions.Builder(photoFile).build()
MediaScannerConnection.scanFile(context, arrayOf(photoFile.absolutePath), null, null)

3.6 完整代码示例：拍照并保存到相册

class CameraCaptureFragment : Fragment() {
    private var imageCapture: ImageCapture? = null

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        val preview = Preview.Builder().build()
        imageCapture = ImageCapture.Builder()
            .setCaptureMode(ImageCapture.CAPTURE_MODE_MAXIMIZE_QUALITY)
            .setFlashMode(ImageCapture.FLASH_MODE_AUTO)
            .build()

        val cameraProviderFuture = ProcessCameraProvider.getInstance(requireContext())
        cameraProviderFuture.addListener({
            val cameraProvider = cameraProviderFuture.get()
            cameraProvider.bindToLifecycle(
                viewLifecycleOwner,
                CameraSelector.DEFAULT_BACK_CAMERA,
                preview,
                imageCapture
            )
        }, ContextCompat.getMainExecutor(requireContext()))

        // 拍照按钮点击
        view.findViewById<Button>(R.id.btn_capture).setOnClickListener {
            takePhoto()
        }
    }

    private fun takePhoto() {
        val imageCapture = imageCapture ?: return
        val contentValues = ContentValues().apply {
            put(MediaStore.Images.Media.DISPLAY_NAME, "IMG_${System.currentTimeMillis()}.jpg")
            put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg")
            put(MediaStore.Images.Media.RELATIVE_PATH, Environment.DIRECTORY_PICTURES + "/CameraXDemo")
        }
        val outputOptions = ImageCapture.OutputFileOptions.Builder(
            requireContext().contentResolver,
            MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
            contentValues
        ).build()

        imageCapture.takePicture(
            outputOptions,
            ContextCompat.getMainExecutor(requireContext()),
            object : ImageCapture.OnImageSavedCallback() {
                override fun onImageSaved(outputFileResults: ImageCapture.OutputFileResults) {
                    Toast.makeText(requireContext(), "拍照成功", Toast.LENGTH_SHORT).show()
                }

                override fun onError(exception: ImageCaptureException) {
                    Toast.makeText(requireContext(), "拍照失败: ${exception.message}", Toast.LENGTH_LONG).show()
                }
            }
        )
    }
}

3.7 调试与常见错误

3.8 稳定性与优化建议

• 释放 ImageProxy：内存模式下务必在 onCaptureSuccess 中调用 imageProxy.close()，否则 CameraX 无法推送下一帧，导致拍照卡死。
• 避免拍照抖动：设置 setTargetRotation 为当前显示屏旋转角度，避免图片方向错误导致后期旋转开销。
• 节约存储：setJpegQuality(85) 可以在肉眼无损前提下减少 30%~50% 文件大小。
• 异常捕获：在 onError 中区分 ImageCaptureException 的错误码（如 ERROR_CAMERA_CLOSED、ERROR_FILE_IO），针对性恢复。
• 后台处理：文件模式的保存路径使用 ContentResolver 配合 MediaStore 时，大文件写入可能会触发 ANR。建议在 takePicture 后切换到后台协程做 Exif 写入或缩略图生成。