多媒体技术

// === 创建通知渠道的完整示例 ===
 
// 1. 导入必要的类
import android.app.NotificationChannel
import android.app.NotificationManager
import android.os.Build
import android.content.Context
 
/**
 * 在 Application.onCreate() 或首次需要通知时调用此方法。
 * 建议统一在 App 启动阶段完成所有渠道注册。
 */
fun createNotificationChannels(context: Context) {
    // 2. 渠道 API 仅在 Android 8.0 (API 26) 及以上可用，必须做版本守卫
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
 
        // 3. 定义"聊天消息"渠道 —— 高重要性，会弹出 Heads-Up
        val chatChannel = NotificationChannel(
            "chat_message",               // channelId: 唯一标识，Builder 中会引用
            "聊天消息",                     // channelName: 用户在设置中看到的名称
            NotificationManager.IMPORTANCE_HIGH  // 重要性: 弹出横幅通知
        ).apply {
            description = "接收好友发来的即时消息" // 渠道描述，展示在设置页供用户参考
            enableVibration(true)                 // 允许震动（用户可后续关闭）
            vibrationPattern = longArrayOf(0, 300, 200, 300) // 震动模式：等待0ms→震300ms→停200ms→震300ms
            enableLights(true)                    // 允许呼吸灯（部分设备支持）
            lightColor = 0xFF4CAF50.toInt()       // 呼吸灯颜色：Material Green
        }
 
        // 4. 定义"订单物流"渠道 —— 默认重要性，有声音但不弹横幅
        val logisticsChannel = NotificationChannel(
            "order_logistics",                    // channelId
            "订单物流",                            // channelName
            NotificationManager.IMPORTANCE_DEFAULT // 重要性: 有声音提醒
        ).apply {
            description = "物流状态变更提醒"        // 渠道描述
        }
 
        // 5. 定义"营销推广"渠道 —— 低重要性，静默展示
        val promoChannel = NotificationChannel(
            "promotion",                          // channelId
            "优惠活动",                            // channelName
            NotificationManager.IMPORTANCE_LOW     // 重要性: 无声音无震动
        ).apply {
            description = "促销活动与优惠券推送"
        }
 
        // 6. 获取 NotificationManager 系统服务
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
 
        // 7. 批量注册所有渠道（幂等操作，可安全重复调用）
        manager.createNotificationChannels(
            listOf(chatChannel, logisticsChannel, promoChannel)
        )
    }
}

// === 渠道分组示例 ===
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
 
    // 1. 创建分组（groupId, groupName）
    val workGroup = NotificationChannelGroup("work_account", "工作账号")   // 工作账号分组
    val personalGroup = NotificationChannelGroup("personal_account", "个人账号") // 个人账号分组
 
    // 2. 注册分组
    manager.createNotificationChannelGroups(listOf(workGroup, personalGroup))
 
    // 3. 创建渠道时关联到分组
    val workChat = NotificationChannel("work_chat", "工作聊天", NotificationManager.IMPORTANCE_HIGH).apply {
        group = "work_account"  // 将此渠道归入"工作账号"分组
    }
 
    val personalChat = NotificationChannel("personal_chat", "私人聊天", NotificationManager.IMPORTANCE_HIGH).apply {
        group = "personal_account" // 将此渠道归入"个人账号"分组
    }
 
    // 4. 注册渠道
    manager.createNotificationChannels(listOf(workChat, personalChat))
}

// === 跳转到指定渠道的系统设置页 ===
val intent = Intent(Settings.ACTION_CHANNEL_NOTIFICATION_SETTINGS).apply {
    putExtra(Settings.EXTRA_APP_PACKAGE, context.packageName)  // 指定应用包名
    putExtra(Settings.EXTRA_CHANNEL_ID, "chat_message")         // 指定目标渠道 ID
}
context.startActivity(intent) // 启动系统设置页

// === 构建并发送一条基础通知 ===
 
import androidx.core.app.NotificationCompat
import androidx.core.app.NotificationManagerCompat
 
fun sendBasicNotification(context: Context) {
    // 1. 创建 Builder，必须传入 channelId（API 26+ 生效，低版本忽略）
    val builder = NotificationCompat.Builder(context, "order_logistics")
        // 2. 设置小图标（必须是纯 alpha 通道的矢量图，状态栏中以单色展示）
        .setSmallIcon(R.drawable.ic_notification_logistics)
        // 3. 设置标题（一行，超长会被截断）
        .setContentTitle("包裹已发出")
        // 4. 设置正文（默认单行，超长截断；可通过 setStyle 扩展）
        .setContentText("您的订单 #20250307 已从北京仓库发出，预计3天送达。")
        // 5. 设置通知时间戳（默认为 System.currentTimeMillis()）
        .setWhen(System.currentTimeMillis())
        // 6. 自动取消：用户点击通知后自动从通知栏移除
        .setAutoCancel(true)
        // 7. 设置优先级（兼容 API 26 以下设备，26+ 由 Channel importance 决定）
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
 
    // 8. 获取兼容版 NotificationManager
    val notificationManager = NotificationManagerCompat.from(context)
 
    // 9. 发送通知：第一个参数是通知 ID（同 ID 会覆盖旧通知），第二个是构建好的 Notification
    //    注意：Android 13+ 需要先检查 POST_NOTIFICATIONS 权限
    if (ActivityCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS)
        == PackageManager.PERMISSION_GRANTED
    ) {
        notificationManager.notify(1001, builder.build()) // ID=1001，发送通知
    }
}

// === BigTextStyle 长文本通知 ===
val bigTextStyle = NotificationCompat.BigTextStyle()
    // 设置展开后的完整文本
    .bigText("您的订单 #20250307 已从北京仓库发出，由顺丰速运承运，运单号 SF1234567890。预计3月10日送达杭州市余杭区。如有问题请联系客服 400-xxx-xxxx。")
    // 设置展开后标题（可覆盖 contentTitle）
    .setBigContentTitle("物流详情更新")
    // 设置展开后的摘要行（显示在最底部）
    .setSummaryText("顺丰速运")
 
val notification = NotificationCompat.Builder(context, "order_logistics")
    .setSmallIcon(R.drawable.ic_notification_logistics)
    .setContentTitle("包裹已发出")                       // 折叠状态下的标题
    .setContentText("订单 #20250307 已发出，点击查看详情") // 折叠状态下的正文
    .setStyle(bigTextStyle)                              // 应用长文本样式
    .build()

// === BigPictureStyle 大图通知 ===
val bitmap = BitmapFactory.decodeResource(context.resources, R.drawable.sample_photo) // 加载图片资源
val bigPictureStyle = NotificationCompat.BigPictureStyle()
    .bigPicture(bitmap)          // 展开后显示的大图（Bitmap）
    .bigLargeIcon(null as Bitmap?) // 展开后隐藏大图标（避免重复）
 
val notification = NotificationCompat.Builder(context, "chat_message")
    .setSmallIcon(R.drawable.ic_notification_chat)
    .setContentTitle("Alice")
    .setContentText("[图片消息]")
    .setLargeIcon(bitmap)        // 折叠状态下右侧的大图标缩略图
    .setStyle(bigPictureStyle)   // 应用大图样式
    .build()

// === InboxStyle 多行摘要通知 ===
val inboxStyle = NotificationCompat.InboxStyle()
    .addLine("Alice: 今晚一起吃饭吗？")     // 第1行
    .addLine("Bob: PR 已经合并了")           // 第2行
    .addLine("Carol: 明天会议改到下午3点")    // 第3行
    .setBigContentTitle("3 条新消息")         // 展开后的标题
    .setSummaryText("team@example.com")      // 摘要行
 
val notification = NotificationCompat.Builder(context, "chat_message")
    .setSmallIcon(R.drawable.ic_notification_chat)
    .setContentTitle("3 条新消息")
    .setContentText("Alice, Bob, Carol")
    .setStyle(inboxStyle)                     // 应用收件箱样式
    .setNumber(3)                             // 角标数字（部分启动器支持）
    .build()

// === 带 Action 按钮的通知 ===
 
// 1. 创建"标记已读"操作的 PendingIntent（指向 BroadcastReceiver）
val markReadIntent = Intent(context, NotificationActionReceiver::class.java).apply {
    action = "ACTION_MARK_READ"          // 自定义 Action 标识
    putExtra("message_id", 12345)        // 携带业务数据
}
val markReadPending = PendingIntent.getBroadcast(
    context,
    0,                                   // requestCode: 用于区分不同 PendingIntent
    markReadIntent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE // 必须加 IMMUTABLE（API 31+）
)
 
// 2. 创建"回复"操作的 PendingIntent（指向 Activity）
val replyIntent = Intent(context, ChatActivity::class.java).apply {
    putExtra("message_id", 12345)
}
val replyPending = PendingIntent.getActivity(
    context,
    1,                                   // 不同的 requestCode 确保不会复用上面的 PendingIntent
    replyIntent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
)
 
// 3. 将 Action 添加到通知
val notification = NotificationCompat.Builder(context, "chat_message")
    .setSmallIcon(R.drawable.ic_notification_chat)
    .setContentTitle("Alice")
    .setContentText("今晚一起吃饭吗？")
    .addAction(R.drawable.ic_done, "标记已读", markReadPending)  // Action 1
    .addAction(R.drawable.ic_reply, "回复", replyPending)        // Action 2
    .build()

// === 进度条通知 ===
val builder = NotificationCompat.Builder(context, "download")
    .setSmallIcon(R.drawable.ic_download)
    .setContentTitle("正在下载 update.apk")
    .setPriority(NotificationCompat.PRIORITY_LOW)   // 下载通知不需要打扰用户
    .setOngoing(true)                                // 常驻通知，用户无法滑动移除
 
val manager = NotificationManagerCompat.from(context)
 
// 模拟下载进度更新
for (progress in 0..100 step 10) {
    builder.setProgress(100, progress, false)        // (max, current, indeterminate)
    builder.setContentText("已完成 $progress%")       // 更新正文
    manager.notify(2001, builder.build())            // 同 ID 覆盖更新
    Thread.sleep(500)                                 // 模拟延迟（实际应在后台线程）
}
 
// 下载完成：移除进度条，取消常驻
builder.setProgress(0, 0, false)                     // 清除进度条
    .setContentText("下载完成")
    .setOngoing(false)                                // 允许用户滑动移除
manager.notify(2001, builder.build())                // 最终更新

// === FLAG_IMMUTABLE：标准用法（绝大多数场景） ===
val immutablePending = PendingIntent.getActivity(
    context,
    0,
    Intent(context, OrderDetailActivity::class.java),
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE  // 安全：不可被外部篡改
)
 
// === FLAG_MUTABLE：仅用于 Direct Reply 场景 ===
val remoteInput = RemoteInput.Builder("key_reply_text")  // 定义回复输入的 key
    .setLabel("输入回复...")                               // 输入框占位文本
    .build()
 
val replyIntent = Intent(context, ReplyReceiver::class.java)
val mutablePending = PendingIntent.getBroadcast(
    context,
    0,
    replyIntent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE   // 可变：系统需要写入用户输入
)
 
// 将 RemoteInput 绑定到 Action
val replyAction = NotificationCompat.Action.Builder(
    R.drawable.ic_reply, "回复", mutablePending
).addRemoteInput(remoteInput).build()

// === 正确做法：每条通知使用唯一的 requestCode ===
fun buildChatPendingIntent(context: Context, messageId: Int): PendingIntent {
    val intent = Intent(context, ChatActivity::class.java).apply {
        putExtra("message_id", messageId)        // extras 不参与 PendingIntent 匹配
    }
    return PendingIntent.getActivity(
        context,
        messageId,                                // ✅ 使用 messageId 作为 requestCode，确保唯一
        intent,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )
}

// === TaskStackBuilder 构造完整返回栈 ===
val detailIntent = Intent(context, OrderDetailActivity::class.java).apply {
    putExtra("order_id", "20250307")
}
 
val pendingIntent = TaskStackBuilder.create(context)
    // 按层级依次添加父 Activity（需要在 AndroidManifest 中配置 parentActivityName）
    .addNextIntentWithParentStack(detailIntent)  // 自动根据 manifest 解析父级链
    .getPendingIntent(
        0,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )

<!-- AndroidManifest.xml 中声明 Activity 层级关系 -->
<activity
    android:name=".OrderDetailActivity"
    android:parentActivityName=".OrderListActivity">  <!-- 声明父级 Activity -->
    <!-- 兼容 API 15 及以下 -->
    <meta-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value=".OrderListActivity" />
</activity>

// === 直接进入目标页面，不构建返回栈 ===
val intent = Intent(context, OrderDetailActivity::class.java).apply {
    flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK // 清空任务栈后启动
    putExtra("order_id", "20250307")
}
 
val pendingIntent = PendingIntent.getActivity(
    context,
    0,
    intent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
)

// === Application 类中注册渠道 ===
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        createNotificationChannels(this) // 在 App 启动时统一注册所有渠道
    }
}

// === 发送一条完整的聊天通知 ===
fun sendChatNotification(context: Context, senderName: String, message: String, messageId: Int) {
 
    // 1. 构建点击通知后的跳转 PendingIntent（带返回栈）
    val chatIntent = Intent(context, ChatActivity::class.java).apply {
        putExtra("message_id", messageId)    // 携带消息 ID
    }
    val contentPending = TaskStackBuilder.create(context)
        .addNextIntentWithParentStack(chatIntent)  // 自动构建父级返回栈
        .getPendingIntent(
            messageId,                              // 使用 messageId 确保唯一性
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )
 
    // 2. 构建"标记已读" Action 按钮的 PendingIntent
    val markReadIntent = Intent(context, NotificationActionReceiver::class.java).apply {
        action = "ACTION_MARK_READ"
        putExtra("message_id", messageId)
    }
    val markReadPending = PendingIntent.getBroadcast(
        context,
        messageId + 100000,                         // 避免与 contentPending 冲突
        markReadIntent,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )
 
    // 3. 使用 Builder 构建通知
    val notification = NotificationCompat.Builder(context, "chat_message") // 关联渠道 ID
        .setSmallIcon(R.drawable.ic_notification_chat)     // 状态栏小图标
        .setContentTitle(senderName)                        // 标题：发送者昵称
        .setContentText(message)                            // 正文：消息内容
        .setStyle(NotificationCompat.BigTextStyle()         // 长文本样式
            .bigText(message))                              // 展开后显示完整消息
        .setContentIntent(contentPending)                   // 点击通知的跳转
        .setDeleteIntent(markReadPending)                   // 用户滑动删除通知时触发
        .addAction(R.drawable.ic_done, "已读", markReadPending)  // "已读" 按钮
        .setAutoCancel(true)                                // 点击后自动消失
        .setCategory(NotificationCompat.CATEGORY_MESSAGE)   // 分类：消息类
        .setColor(0xFF4CAF50.toInt())                       // 强调色（小图标着色）
        .build()
 
    // 4. 权限检查后发送
    if (ActivityCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS)
        == PackageManager.PERMISSION_GRANTED
    ) {
        NotificationManagerCompat.from(context).notify(messageId, notification)
    }
}

<!-- 在 <application> 标签内注册 FileProvider -->
<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <!-- 指定共享路径的配置文件 -->
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>

<?xml version="1.0" encoding="utf-8"?>
<paths>
    <!-- external-files-path 对应 Context.getExternalFilesDir() -->
    <!-- name 是 URI 路径段的替代名，隐藏了真实目录结构 -->
    <!-- path 是该目录下的子目录，"images/" 表示只共享 images 子目录 -->
    <external-files-path
        name="camera_images"
        path="images/" />
</paths>

class CameraIntentActivity : AppCompatActivity() {
 
    // 用于存储当前拍照的 URI，拍照完成后从此 URI 读取图片
    private var currentPhotoUri: Uri? = null
 
    // 注册拍照合约：TakePicture 合约接收一个 Uri 作为输入，返回 Boolean 表示是否成功
    // 这里使用更通用的 StartActivityForResult 合约以演示完整流程
    private val takePictureLauncher = registerForActivityResult(
        ActivityResultContracts.StartActivityForResult() // 通用合约，接收 Intent 返回 ActivityResult
    ) { result ->
        // 回调在 Activity 恢复到 STARTED 状态后触发
        if (result.resultCode == RESULT_OK) {
            // 拍照成功，从之前保存的 URI 加载全尺寸图片
            currentPhotoUri?.let { uri ->
                // 使用 ImageDecoder（API 28+）或 BitmapFactory 解码
                val bitmap = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
                    // ImageDecoder 支持更多格式（如 HEIF、动画 GIF/WebP）
                    val source = ImageDecoder.createSource(contentResolver, uri)
                    ImageDecoder.decodeBitmap(source)
                } else {
                    // 低版本回退到传统的流式解码
                    contentResolver.openInputStream(uri)?.use { stream ->
                        BitmapFactory.decodeStream(stream)
                    }
                }
                // 将 Bitmap 显示到 ImageView
                binding.ivPhoto.setImageBitmap(bitmap)
            }
        }
    }
 
    // 创建临时图片文件并返回对应的 content:// URI
    private fun createImageUri(): Uri {
        // 在应用私有外部存储的 images 目录下创建文件
        val imageDir = File(getExternalFilesDir(Environment.DIRECTORY_PICTURES), "images")
        if (!imageDir.exists()) imageDir.mkdirs() // 确保目录存在
 
        // 用时间戳生成唯一文件名，避免覆盖
        val timeStamp = SimpleDateFormat("yyyyMMdd_HHmmss", Locale.getDefault()).format(Date())
        val imageFile = File(imageDir, "IMG_${timeStamp}.jpg")
 
        // 通过 FileProvider 将 File 转换为安全的 content:// URI
        // 第二个参数必须与 Manifest 中注册的 authorities 一致
        return FileProvider.getUriForFile(
            this,
            "${applicationContext.packageName}.fileprovider",
            imageFile
        )
    }
 
    // 启动系统相机拍照
    private fun dispatchTakePicture() {
        // 创建隐式 Intent，Action 为拍照
        val intent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
 
        // 检查设备上是否有能响应此 Intent 的相机应用
        // 在 Android 11+ 需要在 Manifest 中声明 <queries> 才能查询到
        if (intent.resolveActivity(packageManager) != null) {
            // 创建输出 URI 并保存引用
            val photoUri = createImageUri()
            currentPhotoUri = photoUri
 
            // 将输出 URI 放入 Intent，相机应用会将全尺寸照片写入此位置
            intent.putExtra(MediaStore.EXTRA_OUTPUT, photoUri)
 
            // 授予相机应用对该 URI 的写入权限（临时授权）
            intent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION)
 
            // 通过 Launcher 启动
            takePictureLauncher.launch(intent)
        }
    }
}

<manifest>
    <!-- 声明需要查询能处理拍照 Intent 的应用 -->
    <queries>
        <intent>
            <!-- 匹配所有能响应 IMAGE_CAPTURE 的应用 -->
            <action android:name="android.media.action.IMAGE_CAPTURE" />
        </intent>
    </queries>
</manifest>

// 从 URI 读取 EXIF 信息并获取旋转角度
private fun getRotationFromExif(uri: Uri): Float {
    // 通过 ContentResolver 打开输入流
    val inputStream = contentResolver.openInputStream(uri) ?: return 0f
    // ExifInterface 可以直接从流中读取 EXIF 数据
    val exif = ExifInterface(inputStream)
    // 获取方向标签，默认为 ORIENTATION_NORMAL（无旋转）
    val orientation = exif.getAttributeInt(
        ExifInterface.TAG_ORIENTATION,
        ExifInterface.ORIENTATION_NORMAL
    )
    inputStream.close()
    // 将 EXIF 方向常量映射为旋转角度
    return when (orientation) {
        ExifInterface.ORIENTATION_ROTATE_90 -> 90f   // 顺时针旋转 90 度
        ExifInterface.ORIENTATION_ROTATE_180 -> 180f // 旋转 180 度
        ExifInterface.ORIENTATION_ROTATE_270 -> 270f // 顺时针旋转 270 度
        else -> 0f                                    // 正常方向无需旋转
    }
}
 
// 根据角度旋转 Bitmap
private fun rotateBitmap(bitmap: Bitmap, degrees: Float): Bitmap {
    if (degrees == 0f) return bitmap // 无需旋转直接返回
    val matrix = Matrix()            // 创建变换矩阵
    matrix.postRotate(degrees)       // 设置旋转角度
    // 创建旋转后的新 Bitmap（原 Bitmap 可回收）
    return Bitmap.createBitmap(bitmap, 0, 0, bitmap.width, bitmap.height, matrix, true)
}

// build.gradle.kts (Module level)
dependencies {
    // CameraX 核心库，包含用例基类和 CameraProvider
    val cameraxVersion = "1.3.4"
    implementation("androidx.camera:camera-core:$cameraxVersion")
 
    // Camera2 实现后端，CameraX 通过此模块与 Camera2 API 交互
    implementation("androidx.camera:camera-camera2:$cameraxVersion")
 
    // Lifecycle 集成模块，提供 ProcessCameraProvider
    implementation("androidx.camera:camera-lifecycle:$cameraxVersion")
 
    // CameraX View 模块，提供 PreviewView 控件
    implementation("androidx.camera:camera-view:$cameraxVersion")
}

// 选择后置摄像头（默认选择）
val backCamera = CameraSelector.DEFAULT_BACK_CAMERA
 
// 选择前置摄像头
val frontCamera = CameraSelector.DEFAULT_FRONT_CAMERA
 
// 自定义选择逻辑（例如选择广角镜头）
val customSelector = CameraSelector.Builder()
    .requireLensFacing(CameraSelector.LENS_FACING_BACK) // 要求后置镜头
    .build()

<!-- activity_camera.xml -->
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
 
    <!-- PreviewView 填满整个父容器，作为相机预览区域 -->
    <androidx.camera.view.PreviewView
        android:id="@+id/previewView"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />
 
    <!-- 拍照按钮，居底部水平居中 -->
    <ImageButton
        android:id="@+id/btnCapture"
        android:layout_width="72dp"
        android:layout_height="72dp"
        android:layout_marginBottom="32dp"
        android:src="@drawable/ic_camera_shutter"
        android:background="@drawable/circle_button_bg"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />
 
</androidx.constraintlayout.widget.ConstraintLayout>

class CameraActivity : AppCompatActivity() {
 
    private lateinit var binding: ActivityCameraBinding
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityCameraBinding.inflate(layoutInflater)
        setContentView(binding.root)
        // 启动相机
        startCamera()
    }
 
    private fun startCamera() {
        // 获取 ProcessCameraProvider 的 ListenableFuture
        // ProcessCameraProvider 是单例，管理整个应用的相机生命周期
        val cameraProviderFuture = ProcessCameraProvider.getInstance(this)
 
        // 添加监听器，在 CameraProvider 准备好后执行
        // 第二个参数是执行回调的 Executor，这里用主线程 Executor
        cameraProviderFuture.addListener({
            // 获取 CameraProvider 实例
            val cameraProvider: ProcessCameraProvider = cameraProviderFuture.get()
 
            // 构建 Preview 用例
            val preview = Preview.Builder()
                .setTargetAspectRatio(AspectRatio.RATIO_16_9) // 目标宽高比 16:9
                .build()
                .also { previewUseCase ->
                    // 将 Preview 用例的输出连接到 PreviewView
                    // setSurfaceProvider 是关键：它告诉 Preview 用例"把画面渲染到哪里"
                    previewUseCase.setSurfaceProvider(binding.previewView.surfaceProvider)
                }
 
            // 选择后置摄像头
            val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
 
            try {
                // 解绑之前的所有用例，防止重复绑定
                cameraProvider.unbindAll()
 
                // 核心调用：将生命周期、相机选择器和用例绑定在一起
                // 返回的 Camera 对象可用于控制闪光灯、对焦、缩放等
                val camera = cameraProvider.bindToLifecycle(
                    this,               // LifecycleOwner（当前 Activity）
                    cameraSelector,      // 使用哪个摄像头
                    preview              // 绑定的用例（可同时绑定多个）
                )
            } catch (e: Exception) {
                // 绑定失败（例如设备不支持所选配置）
                Log.e("CameraX", "Use case binding failed", e)
            }
        }, ContextCompat.getMainExecutor(this)) // 在主线程执行回调
    }
}

// 构建拍照用例
val imageCapture = ImageCapture.Builder()
    // 拍照模式：最大化质量（启用 HDR、多帧合成等设备特有优化）
    .setCaptureMode(ImageCapture.CAPTURE_MODE_MAXIMIZE_QUALITY)
    // 目标宽高比 4:3，这是大多数手机传感器的原生宽高比，拍照分辨率最高
    .setTargetAspectRatio(AspectRatio.RATIO_4_3)
    // 闪光灯模式：自动（根据环境亮度决定是否开闪光灯）
    .setFlashMode(ImageCapture.FLASH_MODE_AUTO)
    // JPEG 质量（0-100），默认 95，值越高文件越大
    .setJpegQuality(95)
    .build()

private lateinit var imageCapture: ImageCapture
 
private fun startCamera() {
    val cameraProviderFuture = ProcessCameraProvider.getInstance(this)
 
    cameraProviderFuture.addListener({
        val cameraProvider = cameraProviderFuture.get()
 
        // 构建预览用例
        val preview = Preview.Builder()
            .setTargetAspectRatio(AspectRatio.RATIO_4_3) // 与拍照保持一致的宽高比
            .build()
            .also { it.setSurfaceProvider(binding.previewView.surfaceProvider) }
 
        // 构建拍照用例并保存引用（后续拍照时需要用到）
        imageCapture = ImageCapture.Builder()
            .setCaptureMode(ImageCapture.CAPTURE_MODE_MAXIMIZE_QUALITY)
            .setTargetAspectRatio(AspectRatio.RATIO_4_3)
            .setFlashMode(ImageCapture.FLASH_MODE_AUTO)
            .build()
 
        // 选择后置摄像头
        val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
 
        try {
            cameraProvider.unbindAll() // 先解绑所有旧用例
 
            // 同时绑定 Preview 和 ImageCapture 两个用例
            cameraProvider.bindToLifecycle(
                this,
                cameraSelector,
                preview,
                imageCapture  // 与 preview 一起绑定
            )
        } catch (e: Exception) {
            Log.e("CameraX", "Bindind failed", e)
        }
    }, ContextCompat.getMainExecutor(this))
}

private fun takePhoto() {
    // 确保 imageCapture 已初始化（已绑定到生命周期）
    val imageCapture = imageCapture ?: return
 
    // 使用时间戳创建唯一文件名
    val name = SimpleDateFormat("yyyyMMdd_HHmmss", Locale.getDefault())
        .format(System.currentTimeMillis())
 
    // 配置 MediaStore 的 ContentValues（元数据）
    val contentValues = ContentValues().apply {
        put(MediaStore.MediaColumns.DISPLAY_NAME, name)        // 文件显示名
        put(MediaStore.MediaColumns.MIME_TYPE, "image/jpeg")   // MIME 类型
        // Android 10+ 使用相对路径代替绝对路径（Scoped Storage）
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/MyApp") // 保存到 Pictures/MyApp
        }
    }
 
    // 构建输出选项：指定保存到 MediaStore 的 Images 表
    val outputOptions = ImageCapture.OutputFileOptions.Builder(
        contentResolver,                          // ContentResolver
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI, // 目标 URI（图片媒体集合）
        contentValues                              // 文件元数据
    ).build()
 
    // 触发拍照
    imageCapture.takePicture(
        outputOptions,                              // 输出配置
        ContextCompat.getMainExecutor(this),        // 回调执行线程
        object : ImageCapture.OnImageSavedCallback { // 结果回调
 
            override fun onImageSaved(output: ImageCapture.OutputFileResults) {
                // 拍照成功，output.savedUri 是保存位置的 content:// URI
                val savedUri = output.savedUri
                Log.d("CameraX", "Photo saved: $savedUri")
                // 可以用 savedUri 显示图片、上传服务器等
                Toast.makeText(
                    this@CameraActivity,
                    "拍照成功",
                    Toast.LENGTH_SHORT
                ).show()
            }
 
            override fun onError(exception: ImageCaptureException) {
                // 拍照失败，ImageCaptureException 包含错误码和原因
                Log.e("CameraX", "Photo capture failed: ${exception.message}", exception)
            }
        }
    )
}

private fun takePhotoToPrivateDir() {
    val imageCapture = imageCapture ?: return
 
    // 在应用私有外部存储中创建文件
    val photoFile = File(
        getExternalFilesDir(Environment.DIRECTORY_PICTURES), // 私有 Pictures 目录
        "IMG_${System.currentTimeMillis()}.jpg"               // 唯一文件名
    )
 
    // 使用 File 构建输出选项
    val outputOptions = ImageCapture.OutputFileOptions.Builder(photoFile).build()
 
    imageCapture.takePicture(
        outputOptions,
        ContextCompat.getMainExecutor(this),
        object : ImageCapture.OnImageSavedCallback {
            override fun onImageSaved(output: ImageCapture.OutputFileResults) {
                // savedUri 为 file:// URI（私有目录不需要 content:// URI）
                Log.d("CameraX", "Photo saved to: ${photoFile.absolutePath}")
            }
            override fun onError(e: ImageCaptureException) {
                Log.e("CameraX", "Capture failed", e)
            }
        }
    )
}

private fun captureToMemory() {
    val imageCapture = imageCapture ?: return
 
    imageCapture.takePicture(
        ContextCompat.getMainExecutor(this), // 回调 Executor
        object : ImageCapture.OnImageCapturedCallback() {
 
            override fun onCaptureSuccess(image: ImageProxy) {
                // ImageProxy 包装了底层的 android.media.Image
                // 获取图像的旋转角度（CameraX 已计算好，考虑了传感器方向和设备旋转）
                val rotationDegrees = image.imageInfo.rotationDegrees
 
                // 获取图像数据平面（JPEG 格式只有一个平面）
                val buffer = image.planes[0].buffer   // ByteBuffer
                val bytes = ByteArray(buffer.remaining()) // 创建字节数组
                buffer.get(bytes)                          // 复制数据到数组
 
                // 可以在这里做自定义处理：
                // - BitmapFactory.decodeByteArray() 解码为 Bitmap
                // - 添加水印、压缩、上传等
                val bitmap = BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
 
                // ⚠️ 必须关闭 ImageProxy，否则会阻塞后续拍照！
                // ImageProxy 底层对应一个 ImageReader buffer slot，
                // 不释放就无法接收新的图像
                image.close()
            }
 
            override fun onError(exception: ImageCaptureException) {
                Log.e("CameraX", "Capture failed", exception)
            }
        }
    )
}

private fun setupCameraControls(camera: Camera) {
    val cameraControl = camera.cameraControl // 获取控制接口
    val cameraInfo = camera.cameraInfo       // 获取信息查询接口
 
    // === 点击对焦（Tap to Focus）===
    binding.previewView.setOnTouchListener { _, event ->
        if (event.action == MotionEvent.ACTION_UP) {
            // 将触摸点转换为 MeteringPoint（归一化坐标）
            val factory = binding.previewView.meteringPointFactory
            val point = factory.createPoint(event.x, event.y)
 
            // 构建对焦/测光动作：同时对焦和测光
            val action = FocusMeteringAction.Builder(point)
                .setAutoCancelDuration(3, TimeUnit.SECONDS) // 3 秒后自动取消（恢复连续对焦）
                .build()
 
            // 执行对焦，返回 ListenableFuture<FocusMeteringResult>
            cameraControl.startFocusAndMetering(action)
        }
        true // 消费触摸事件
    }
 
    // === 双指缩放（Pinch to Zoom）===
    val scaleGestureDetector = ScaleGestureDetector(this,
        object : ScaleGestureDetector.SimpleOnScaleGestureListener() {
            override fun onScale(detector: ScaleGestureDetector): Boolean {
                // 获取当前缩放比例
                val currentZoomRatio = cameraInfo.zoomState.value?.zoomRatio ?: 1f
                // 乘以手势缩放因子
                val newZoomRatio = currentZoomRatio * detector.scaleFactor
                // 设置新的缩放比例（CameraX 会自动限制在合法范围内）
                cameraControl.setZoomRatio(newZoomRatio)
                return true
            }
        }
    )
 
    // === 切换闪光灯模式 ===
    // 运行时动态修改闪光灯模式（无需重新绑定用例）
    imageCapture.flashMode = ImageCapture.FLASH_MODE_ON  // 强制开启
    // 或
    imageCapture.flashMode = ImageCapture.FLASH_MODE_OFF // 关闭
}

// 定义要查询的目标 URI —— 外部存储中的图片表
// MediaStore.Images.Media.EXTERNAL_CONTENT_URI = content://media/external/images/media
val collection: Uri = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    // Android 10+ 推荐使用带 Volume 的方法，VOLUME_EXTERNAL 包含所有外部存储卷
    MediaStore.Images.Media.getContentUri(MediaStore.VOLUME_EXTERNAL)
} else {
    // Android 9 及以下使用经典常量
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI
}
 
// 定义 projection —— 只查询需要的列，避免 SELECT * 带来的性能浪费
val projection = arrayOf(
    MediaStore.Images.Media._ID,            // 每条记录的唯一 ID（long 类型）
    MediaStore.Images.Media.DISPLAY_NAME,   // 文件显示名，如 "photo_001.jpg"
    MediaStore.Images.Media.SIZE,           // 文件大小（字节）
    MediaStore.Images.Media.DATE_ADDED,     // 添加到 MediaStore 的时间戳（秒）
    MediaStore.Images.Media.WIDTH,          // 图片宽度（像素）
    MediaStore.Images.Media.HEIGHT          // 图片高度（像素）
)
 
// 定义 selection —— WHERE 子句，筛选 MIME 类型为 JPEG 的图片
val selection = "${MediaStore.Images.Media.MIME_TYPE} = ?"
 
// 定义 selectionArgs —— 绑定参数，防止 SQL 注入攻击
val selectionArgs = arrayOf("image/jpeg")
 
// 定义 sortOrder —— 按添加时间降序排列，最新的图片排在最前面
val sortOrder = "${MediaStore.Images.Media.DATE_ADDED} DESC"
 
// 用于存储查询结果的列表
data class ImageItem(val id: Long, val name: String, val size: Long, val uri: Uri)
val imageList = mutableListOf<ImageItem>()
 
// 执行查询 —— use {} 确保 Cursor 在代码块结束后自动关闭
contentResolver.query(
    collection,     // 目标 URI
    projection,     // 需要的列
    selection,      // WHERE 子句
    selectionArgs,  // WHERE 参数
    sortOrder       // 排序规则
)?.use { cursor ->
    // 预先获取各列的索引（在循环外调用，避免重复查找列索引的开销）
    val idColumn = cursor.getColumnIndexOrThrow(MediaStore.Images.Media._ID)
    val nameColumn = cursor.getColumnIndexOrThrow(MediaStore.Images.Media.DISPLAY_NAME)
    val sizeColumn = cursor.getColumnIndexOrThrow(MediaStore.Images.Media.SIZE)
 
    // 逐行遍历 Cursor，moveToNext() 返回 false 表示已无更多数据
    while (cursor.moveToNext()) {
        // 从当前行读取各列的值
        val id = cursor.getLong(idColumn)          // 读取 _ID 列
        val name = cursor.getString(nameColumn)    // 读取 DISPLAY_NAME 列
        val size = cursor.getLong(sizeColumn)       // 读取 SIZE 列
 
        // 通过 ContentUris 工具类将 _ID 拼接到 collection URI 后面
        // 生成形如 content://media/external/images/media/42 的单条记录 URI
        val contentUri = ContentUris.withAppendedId(collection, id)
 
        // 将解析结果存入列表
        imageList.add(ImageItem(id, name, size, contentUri))
    }
}
 
// 此时 imageList 中已包含所有符合条件的 JPEG 图片信息
Log.d("MediaStore", "找到 ${imageList.size} 张 JPEG 图片")

// 构建查询参数 Bundle
val queryArgs = Bundle().apply {
    // 等价于 WHERE mime_type = 'image/jpeg'
    // QUERY_ARG_SQL_SELECTION 定义 WHERE 子句
    putString(ContentResolver.QUERY_ARG_SQL_SELECTION, "${MediaStore.Images.Media.MIME_TYPE} = ?")
    // QUERY_ARG_SQL_SELECTION_ARGS 定义 WHERE 参数
    putStringArray(ContentResolver.QUERY_ARG_SQL_SELECTION_ARGS, arrayOf("image/jpeg"))
    // QUERY_ARG_SQL_SORT_ORDER 定义排序规则
    putString(ContentResolver.QUERY_ARG_SQL_SORT_ORDER, "${MediaStore.Images.Media.DATE_ADDED} DESC")
    // QUERY_ARG_LIMIT 定义分页大小 —— 传统 query() 无法原生支持 LIMIT
    putInt(ContentResolver.QUERY_ARG_LIMIT, 50)
    // QUERY_ARG_OFFSET 定义分页偏移量
    putInt(ContentResolver.QUERY_ARG_OFFSET, 0)
}
 
// 使用 Bundle 版 query() 执行查询
contentResolver.query(
    collection,     // 目标 URI（与之前相同）
    projection,     // 需要的列（与之前相同）
    queryArgs,      // Bundle 形式的查询参数（替代 selection/selectionArgs/sortOrder）
    null            // CancellationSignal，可用于取消长时间查询
)?.use { cursor ->
    // Cursor 遍历逻辑与之前完全相同
    // ...
}

// 封装一个通用的图片查询方法，支持自定义过滤条件
fun queryImages(
    contentResolver: ContentResolver,
    mimeType: String? = null,        // 可选的 MIME 类型过滤
    minSize: Long = 0L,              // 最小文件大小（过滤缩略图等小文件）
    limit: Int = 100                 // 分页大小
): List<ImageItem> {
    // 确定集合 URI —— 兼容 Android 10 以下与以上版本
    val collection = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Images.Media.getContentUri(MediaStore.VOLUME_EXTERNAL)
    } else {
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI
    }
 
    // 只查询必要的列
    val projection = arrayOf(
        MediaStore.Images.Media._ID,
        MediaStore.Images.Media.DISPLAY_NAME,
        MediaStore.Images.Media.DATE_ADDED,
        MediaStore.Images.Media.SIZE
    )
 
    // 动态构建 WHERE 子句 —— 用 StringBuilder 拼接多个条件
    val conditions = mutableListOf<String>()  // 存储各个条件表达式
    val args = mutableListOf<String>()        // 存储各条件对应的参数值
 
    // 如果指定了 MIME 类型，添加 MIME 过滤条件
    if (mimeType != null) {
        conditions.add("${MediaStore.Images.Media.MIME_TYPE} = ?")
        args.add(mimeType)
    }
 
    // 添加最小文件大小过滤（排除极小的缩略图或损坏文件）
    if (minSize > 0) {
        conditions.add("${MediaStore.Images.Media.SIZE} >= ?")
        args.add(minSize.toString())
    }
 
    // 将条件用 AND 连接；若无条件则 selection 为 null（查询全部）
    val selection = if (conditions.isNotEmpty()) conditions.joinToString(" AND ") else null
    val selectionArgs = if (args.isNotEmpty()) args.toTypedArray() else null
 
    val result = mutableListOf<ImageItem>()
 
    // 执行查询并遍历结果
    contentResolver.query(
        collection,
        projection,
        selection,
        selectionArgs,
        "${MediaStore.Images.Media.DATE_ADDED} DESC"  // 最新在前
    )?.use { cursor ->
        val idCol = cursor.getColumnIndexOrThrow(MediaStore.Images.Media._ID)
        val nameCol = cursor.getColumnIndexOrThrow(MediaStore.Images.Media.DISPLAY_NAME)
        val sizeCol = cursor.getColumnIndexOrThrow(MediaStore.Images.Media.SIZE)
 
        var count = 0  // 手动计数实现 LIMIT（兼容旧版 API）
        while (cursor.moveToNext() && count < limit) {
            val id = cursor.getLong(idCol)
            val name = cursor.getString(nameCol)
            val size = cursor.getLong(sizeCol)
            // 拼接单条记录的 content URI
            val uri = ContentUris.withAppendedId(collection, id)
            result.add(ImageItem(id, name, size, uri))
            count++
        }
    }
    return result
}

fun queryVideos(contentResolver: ContentResolver): List<VideoItem> {
    // 视频集合 URI
    val collection = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Video.Media.getContentUri(MediaStore.VOLUME_EXTERNAL)
    } else {
        MediaStore.Video.Media.EXTERNAL_CONTENT_URI
    }
 
    // 视频特有的列：DURATION 表示时长（毫秒）
    val projection = arrayOf(
        MediaStore.Video.Media._ID,
        MediaStore.Video.Media.DISPLAY_NAME,
        MediaStore.Video.Media.DURATION,      // 视频时长（毫秒），图片表中无此列
        MediaStore.Video.Media.SIZE,
        MediaStore.Video.Media.DATE_ADDED
    )
 
    // 过滤条件：只查询时长大于 1 秒的视频（排除损坏或极短的片段）
    val selection = "${MediaStore.Video.Media.DURATION} >= ?"
    val selectionArgs = arrayOf("1000")  // 1000 毫秒 = 1 秒
 
    val result = mutableListOf<VideoItem>()
 
    contentResolver.query(
        collection,
        projection,
        selection,
        selectionArgs,
        "${MediaStore.Video.Media.DATE_ADDED} DESC"
    )?.use { cursor ->
        val idCol = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID)
        val nameCol = cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DISPLAY_NAME)
        val durationCol = cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DURATION)
        val sizeCol = cursor.getColumnIndexOrThrow(MediaStore.Video.Media.SIZE)
 
        while (cursor.moveToNext()) {
            val id = cursor.getLong(idCol)
            val name = cursor.getString(nameCol)
            val duration = cursor.getLong(durationCol)       // 时长（毫秒）
            val size = cursor.getLong(sizeCol)
            val uri = ContentUris.withAppendedId(collection, id)
 
            result.add(VideoItem(id, name, duration, size, uri))
        }
    }
    return result
}

fun queryAudioFiles(contentResolver: ContentResolver): List<AudioItem> {
    // 音频集合 URI
    val collection = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Audio.Media.getContentUri(MediaStore.VOLUME_EXTERNAL)
    } else {
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI
    }
 
    // 音频特有的列：ARTIST（艺术家）、ALBUM（专辑）、ALBUM_ID（专辑封面关联）
    val projection = arrayOf(
        MediaStore.Audio.Media._ID,
        MediaStore.Audio.Media.DISPLAY_NAME,    // 文件名
        MediaStore.Audio.Media.TITLE,           // 歌曲标题（从 ID3 Tag 读取）
        MediaStore.Audio.Media.ARTIST,          // 艺术家名
        MediaStore.Audio.Media.ALBUM,           // 专辑名
        MediaStore.Audio.Media.ALBUM_ID,        // 专辑 ID（用于查询封面）
        MediaStore.Audio.Media.DURATION,        // 时长（毫秒）
        MediaStore.Audio.Media.IS_MUSIC         // 是否为音乐（区分铃声/通知音等）
    )
 
    // 只查询音乐文件，排除铃声、通知音、闹钟等
    val selection = "${MediaStore.Audio.Media.IS_MUSIC} != 0"
 
    val result = mutableListOf<AudioItem>()
 
    contentResolver.query(
        collection,
        projection,
        selection,
        null,  // IS_MUSIC != 0 不需要参数
        "${MediaStore.Audio.Media.TITLE} ASC"  // 按歌曲标题升序排列
    )?.use { cursor ->
        val idCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media._ID)
        val titleCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.TITLE)
        val artistCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.ARTIST)
        val albumCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.ALBUM)
        val albumIdCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.ALBUM_ID)
        val durationCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.DURATION)
 
        while (cursor.moveToNext()) {
            val id = cursor.getLong(idCol)
            val title = cursor.getString(titleCol)
            val artist = cursor.getString(artistCol)
            val album = cursor.getString(albumCol)
            val albumId = cursor.getLong(albumIdCol)
            val duration = cursor.getLong(durationCol)
 
            // 音频文件的 content URI
            val contentUri = ContentUris.withAppendedId(collection, id)
 
            // 专辑封面的 content URI —— 通过 albumId 拼接到专辑封面 URI 上
            val albumArtUri = ContentUris.withAppendedId(
                Uri.parse("content://media/external/audio/albumart"),
                albumId
            )
 
            result.add(AudioItem(id, title, artist, album, contentUri, albumArtUri, duration))
        }
    }
    return result
}

// 获取指定 content URI 的缩略图 Bitmap
// imageUri 为查询得到的 content://media/external/images/media/42 这样的 URI
fun loadThumbnail(
    contentResolver: ContentResolver,
    mediaUri: Uri,
    width: Int = 256,           // 缩略图目标宽度
    height: Int = 256           // 缩略图目标高度
): Bitmap? {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        // Android 10+ 推荐方式：loadThumbnail() 由系统根据尺寸自动选择最优的缩略图源
        try {
            contentResolver.loadThumbnail(
                mediaUri,                       // 媒体文件的 content URI
                Size(width, height),            // 期望的缩略图尺寸
                null                            // CancellationSignal（可选，用于取消）
            )
        } catch (e: IOException) {
            // 文件可能已被删除，或无权限访问
            null
        }
    } else {
        // Android 9 及以下：使用 MediaStore.Images.Thumbnails（已 Deprecated）
        // 或手动 BitmapFactory.decodeStream() + inSampleSize 降采样
        MediaStore.Images.Thumbnails.getThumbnail(
            contentResolver,
            ContentUris.parseId(mediaUri),   // 提取 URI 末尾的数字 ID
            MediaStore.Images.Thumbnails.MINI_KIND,  // 缩略图类型：MINI 或 MICRO
            null                              // BitmapFactory.Options（可选）
        )
    }
}

/**
 * 将 Bitmap 保存到系统图片库（适配 Android 10 Scoped Storage）
 * @param bitmap 要保存的位图
 * @param displayName 文件显示名（不含扩展名）
 * @param mimeType MIME 类型，如 "image/jpeg"
 * @return 保存成功则返回 content URI，失败返回 null
 */
fun saveBitmapToGallery(
    context: Context,
    bitmap: Bitmap,
    displayName: String,
    mimeType: String = "image/jpeg"
): Uri? {
    val resolver = context.contentResolver
 
    // ① 构建元数据 ContentValues —— 类似于数据库的 INSERT 语句的列值对
    val contentValues = ContentValues().apply {
        // DISPLAY_NAME：文件显示名（系统会自动添加扩展名）
        put(MediaStore.Images.Media.DISPLAY_NAME, displayName)
        // MIME_TYPE：文件的 MIME 类型，系统据此决定存储目录和文件扩展名
        put(MediaStore.Images.Media.MIME_TYPE, mimeType)
        // DATE_ADDED：添加时间戳（秒），System.currentTimeMillis() 返回毫秒需除以 1000
        put(MediaStore.Images.Media.DATE_ADDED, System.currentTimeMillis() / 1000)
 
        // Android 10+ 的 Scoped Storage 特有字段
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            // RELATIVE_PATH：相对存储路径，文件将保存到 Pictures/MyApp/ 目录下
            put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/MyApp")
            // IS_PENDING = 1：将文件标记为"写入中"
            // 处于 pending 状态的文件对其他应用不可见，避免其他应用读取到不完整的文件
            put(MediaStore.Images.Media.IS_PENDING, 1)
        }
    }
 
    // ② 插入元数据记录，获取该记录的 content URI
    // insert() 返回形如 content://media/external/images/media/123 的 URI
    // 此时数据库中已有该记录，但物理文件尚未写入
    val imageUri = resolver.insert(
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI,  // 插入到外部存储图片表
        contentValues                                   // 列值对
    ) ?: return null  // insert 失败（如存储空间不足）返回 null
 
    // ③ 通过返回的 URI 打开输出流，写入 Bitmap 数据
    // openOutputStream() 返回一个指向实际文件的 OutputStream
    // use {} 确保流在写入完成后自动关闭
    resolver.openOutputStream(imageUri)?.use { outputStream ->
        // 根据 MIME 类型选择压缩格式
        val format = if (mimeType == "image/png") {
            Bitmap.CompressFormat.PNG     // PNG 无损压缩
        } else {
            Bitmap.CompressFormat.JPEG    // JPEG 有损压缩
        }
        // compress() 将 Bitmap 压缩并写入输出流
        // 参数：压缩格式、质量（0-100，仅 JPEG 有效）、输出流
        val success = bitmap.compress(format, 90, outputStream)
        if (!success) {
            // 压缩失败，删除已创建的空记录
            resolver.delete(imageUri, null, null)
            return null
        }
    } ?: run {
        // 无法打开输出流（URI 可能已失效），清理空记录
        resolver.delete(imageUri, null, null)
        return null
    }
 
    // ④ 清除 IS_PENDING 标记，使文件对其他应用可见
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        val updateValues = ContentValues().apply {
            // 将 IS_PENDING 设为 0，标记文件写入完成
            put(MediaStore.Images.Media.IS_PENDING, 0)
        }
        // update() 更新指定 URI 的记录
        resolver.update(imageUri, updateValues, null, null)
    }
 
    // 返回保存成功的 content URI
    return imageUri
}

/**
 * 重命名 MediaStore 中的媒体文件
 * @param mediaUri 要修改的记录的 content URI
 * @param newName 新的显示名（不含扩展名）
 */
fun renameMedia(contentResolver: ContentResolver, mediaUri: Uri, newName: String) {
    // 构建要更新的列值对
    val updateValues = ContentValues().apply {
        // 只修改 DISPLAY_NAME 列
        put(MediaStore.Images.Media.DISPLAY_NAME, newName)
    }
    // update() 的参数与 query() 类似：URI、新值、WHERE 条件
    // 这里直接使用单条记录的 URI，所以不需要 WHERE 条件
    val rowsUpdated = contentResolver.update(
        mediaUri,       // 目标记录的 URI（如 content://media/external/images/media/42）
        updateValues,   // 要更新的列值对
        null,           // selection（对单条 URI 无需条件）
        null            // selectionArgs
    )
    Log.d("MediaStore", "更新了 $rowsUpdated 行")
}

/**
 * 将编辑后的 Bitmap 覆盖写回原文件
 * 注意：在 Android 10+ 上，如果文件不是本应用创建的，
 * 系统会抛出 RecoverableSecurityException，需要请求用户授权
 */
fun overwriteImage(
    context: Context,
    mediaUri: Uri,
    editedBitmap: Bitmap
) {
    val resolver = context.contentResolver
 
    try {
        // Android 10+：先将文件设为 pending 状态，防止其他应用读取到半成品
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            val pendingValues = ContentValues().apply {
                put(MediaStore.Images.Media.IS_PENDING, 1)  // 标记为写入中
            }
            resolver.update(mediaUri, pendingValues, null, null)
        }
 
        // 以 "w" 模式打开输出流（覆盖写入，而非追加）
        // "w" = write/truncate，会清空文件原有内容
        resolver.openOutputStream(mediaUri, "w")?.use { outputStream ->
            editedBitmap.compress(Bitmap.CompressFormat.JPEG, 95, outputStream)
        }
 
        // 清除 pending 标记
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            val doneValues = ContentValues().apply {
                put(MediaStore.Images.Media.IS_PENDING, 0)  // 标记为完成
            }
            resolver.update(mediaUri, doneValues, null, null)
        }
 
    } catch (securityException: SecurityException) {
        // Android 10+ 操作非本应用创建的文件时会抛出此异常
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            val recoverableException = securityException as? RecoverableSecurityException
            // 获取用户授权的 IntentSender，弹出系统授权对话框
            recoverableException?.userAction?.actionIntent?.intentSender?.let { sender ->
                // 需要通过 Activity.startIntentSenderForResult() 请求用户确认
                // 用户同意后，在 onActivityResult 中重试 overwriteImage()
                Log.w("MediaStore", "需要用户授权才能修改此文件")
            }
        }
    }
}

/**
 * 删除单条媒体记录（及其物理文件）
 * Android 10+ 删除非本应用创建的文件需要用户确认
 */
fun deleteMedia(context: Context, mediaUri: Uri): Boolean {
    return try {
        // delete() 返回被删除的行数（0 或 1）
        val deletedRows = context.contentResolver.delete(
            mediaUri,   // 要删除的记录 URI
            null,       // 额外 WHERE 条件（单条 URI 无需）
            null        // WHERE 参数
        )
        deletedRows > 0  // 删除成功返回 true
    } catch (securityException: SecurityException) {
        // 与 update 相同，需要处理 RecoverableSecurityException
        false
    }
}
 
/**
 * Android 11+ 批量删除请求 —— 系统弹出统一的确认对话框
 * 需要在 Activity 中通过 ActivityResultLauncher 处理结果
 */
fun createBatchDeleteRequest(
    context: Context,
    urisToDelete: List<Uri>
): IntentSender? {
    // Android 11+ 可用 createDeleteRequest() 批量请求删除权限
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        // 返回 PendingIntent，调用方通过 launcher.launch(intentSender) 弹出系统确认框
        MediaStore.createDeleteRequest(
            context.contentResolver,
            urisToDelete  // 要删除的 URI 列表
        ).intentSender
    } else {
        null  // Android 10 及以下需逐个处理 RecoverableSecurityException
    }
}

// 注册一个 ContentObserver 监听图片表的变化
val imageObserver = object : ContentObserver(Handler(Looper.getMainLooper())) {
    // 当监听的 URI 对应的数据发生变化时，系统回调此方法
    override fun onChange(selfChange: Boolean, uri: Uri?) {
        super.onChange(selfChange, uri)
        // selfChange = true 表示变更是本应用触发的
        // uri 为发生变更的具体 URI（可能为 null）
        Log.d("MediaStore", "图片库发生变化: selfChange=$selfChange, uri=$uri")
        // 在此触发 UI 刷新，如重新查询图片列表
        refreshImageList()
    }
}
 
// 注册监听 —— 第二个参数 notifyForDescendants = true 表示监听该 URI 下所有子路径的变化
contentResolver.registerContentObserver(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,  // 监听整个图片表
    true,                                           // 包含子路径
    imageObserver                                    // 观察者实例
)
 
// 在 onDestroy() 或不再需要监听时取消注册，避免内存泄漏
contentResolver.unregisterContentObserver(imageObserver)

// 使用示例：为不同业务场景选择合适的磁盘缓存策略
Glide.with(this)                              // 绑定生命周期
    .load("https://example.com/photo.jpg")    // 指定图片 URL
    .diskCacheStrategy(DiskCacheStrategy.ALL)  // 同时缓存原始数据与变换后资源
    .into(imageView)                          // 目标 ImageView
 
// 验证码场景：禁用所有缓存，确保每次都获取最新图片
Glide.with(this)                              // 绑定生命周期
    .load("https://example.com/captcha")      // 验证码 URL，每次返回不同图片
    .diskCacheStrategy(DiskCacheStrategy.NONE) // 禁用磁盘缓存
    .skipMemoryCache(true)                    // 同时禁用内存缓存
    .into(captchaImageView)                   // 目标验证码 ImageView

// LinkedHashMap 内部结构示意（伪代码）
// 每个 Entry 除了 HashMap 的 hash/key/value/next 外
// 还有 before 和 after 指针形成双向链表

╔═══════════════════════════════════════════════════════════╗
║             LinkedHashMap (accessOrder = true)            ║
║                                                           ║
║   ┌──────────────────── 双向链表 ────────────────────┐    ║
║   │                                                   │    ║
║   │  HEAD(最旧)                        TAIL(最新)     │    ║
║   │  ┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐       │    ║
║   │  │Key:C│◄──►│Key:A│◄──►│Key:D│◄──►│Key:B│       │    ║
║   │  │Val:3│    │Val:1│    │Val:4│    │Val:2│       │    ║
║   │  └─────┘    └─────┘    └─────┘    └─────┘       │    ║
║   │  ↑ 淘汰优先                    最近访问 ↑        │    ║
║   └──────────────────────────────────────────────────┘    ║
║                                                           ║
║   底层 HashMap 桶数组(提供 O(1) 查找):                     ║
║   [0]→null  [1]→KeyA  [2]→KeyB  [3]→KeyC  [4]→KeyD      ║
╚═══════════════════════════════════════════════════════════╝

// 创建一个用于缓存 Bitmap 的 LruCache
class BitmapLruCache : LruCache<String, Bitmap>(calculateMaxSize()) {
 
    companion object {
        fun calculateMaxSize(): Int {
            // 获取应用可用的最大内存（单位：字节）
            val maxMemory = Runtime.getRuntime().maxMemory().toInt()
            // 取最大内存的 1/8 作为图片缓存上限
            // 例如 256MB 可用内存 → 32MB 图片缓存
            return maxMemory / 8
        }
    }
 
    // 必须重写 sizeOf，告诉 LruCache 每个条目占多少"单位"
    // 这里的"单位"与构造函数的 maxSize 保持一致（字节）
    override fun sizeOf(key: String, value: Bitmap): Int {
        // allocationByteCount 返回 Bitmap 实际分配的内存字节数
        // 对于复用的 Bitmap，它可能大于 byteCount
        return value.allocationByteCount
    }
 
    // 可选：当条目被淘汰时的回调
    // 可以在此处回收 Bitmap 或将其放入复用池
    override fun entryRemoved(
        evicted: Boolean,       // true = 因容量淘汰; false = 被 put/remove 替换
        key: String,            // 被移除条目的 Key
        oldValue: Bitmap,       // 被移除的 Bitmap
        newValue: Bitmap?       // 替换者（淘汰时为 null）
    ) {
        if (evicted) {
            // 被 LRU 淘汰，可以将 Bitmap 放入 BitmapPool 以供复用
            // bitmapPool.put(oldValue)
        }
    }
}

/data/data/com.example.app/cache/image_cache/
├── journal              ← 操作日志文件（核心）
├── journal.bkp          ← journal 的备份
├── a1b2c3d4e5f6.0       ← 缓存数据文件（Key 的 MD5 + 索引）
├── f6e5d4c3b2a1.0       ← 另一个缓存数据文件
└── ...

libcore.io.DiskLruCache         ← 魔数（Magic Number），标识文件格式
1                               ← 磁盘缓存版本号
100                             ← App 版本号
2                               ← 每个 Key 对应的值数量（valueCount）
                                ← 空行分隔
DIRTY a1b2c3d4e5f6              ← 开始编辑 Key=a1b2c3d4e5f6
CLEAN a1b2c3d4e5f6 1024 512    ← 编辑完成，两个文件大小分别为 1024 和 512 字节
READ a1b2c3d4e5f6               ← 读取操作
DIRTY f6e5d4c3b2a1              ← 开始编辑另一个 Key
CLEAN f6e5d4c3b2a1 2048 0      ← 编辑完成
REMOVE a1b2c3d4e5f6             ← 删除 Key=a1b2c3d4e5f6

// 自定义 AppGlideModule 配置磁盘缓存
@GlideModule
class MyAppGlideModule : AppGlideModule() {
 
    // 应用 Glide 选项（全局生效，仅初始化时调用一次）
    override fun applyOptions(context: Context, builder: GlideBuilder) {
        // 设置磁盘缓存为内部存储，大小 500MB
        builder.setDiskCache(
            InternalCacheDiskCacheFactory(
                context,           // 应用上下文
                "glide_cache",     // 缓存目录名称
                500L * 1024 * 1024 // 500MB 上限
            )
        )
 
        // 同时可以自定义内存缓存大小
        builder.setMemoryCache(
            LruResourceCache(
                50L * 1024 * 1024  // 50MB 内存缓存上限
            )
        )
    }
 
    // 是否启用清单（Manifest）解析
    // 返回 false 可以提升初始化速度（推荐）
    override fun isManifestParsingEnabled(): Boolean = false
}

// 演示 inBitmap 的基本用法
val options = BitmapFactory.Options()
 
// 第一步：先解码一张图片
options.inPreferredConfig = Bitmap.Config.ARGB_8888  // 指定像素格式
val firstBitmap = BitmapFactory.decodeFile(           // 从文件解码
    "/sdcard/photo1.jpg",                             // 图片路径
    options                                           // 解码选项
)
 
// 第二步：用 firstBitmap 的内存块来解码第二张图片
options.inMutable = true       // 必须！inBitmap 要求 Bitmap 是可变的（mutable）
options.inBitmap = firstBitmap // 核心：指定要复用的 Bitmap
val secondBitmap = BitmapFactory.decodeFile(          // 解码第二张图片
    "/sdcard/photo2.jpg",                             // 不同的图片路径
    options                                           // 同一个 options，含 inBitmap
)
// secondBitmap 复用了 firstBitmap 的底层内存
// firstBitmap 此时已不可用（像素数据已被覆盖）

// 预热 BitmapPool 的示例
fun prewarmBitmapPool(glide: Glide, count: Int = 6) {
    val pool = glide.bitmapPool                    // 获取 Glide 的 BitmapPool 实例
    for (i in 0 until count) {                     // 预创建 count 个 Bitmap
        val bitmap = Bitmap.createBitmap(           // 创建空白 Bitmap
            300,                                   // 宽度（像素），覆盖常见缩略图尺寸
            300,                                   // 高度（像素）
            Bitmap.Config.ARGB_8888                // 默认像素格式
        )
        pool.put(bitmap)                           // 放入 BitmapPool 等待被复用
    }
}