如何使用Coil将本地图片文件直接加载到Jetpack Compose的Image组件中

结论 #

Coil完全支持直接加载本地图片文件到Compose的Image组件，无需提前将文件转换为Bitmap，也不限于仅加载网络URL资源。

前置依赖 #

首先确保你已经在模块级build.gradle中引入了Coil的Compose扩展库，版本可替换为官方最新稳定版：

implementation "io.coil-kt:coil-compose:2.5.0"

加载实现方式 #

Coil的两个常用加载API都支持直接传入本地文件实例：

• 如果你使用Coil 2.x推荐的AsyncImage封装组件，直接把File实例传给model参数即可：

// 替换为你自己的本地图片文件实例
val localImageFile = File("/storage/emulated/0/DCIM/Camera/test.jpg")

AsyncImage(
    model = localImageFile,
    contentDescription = "本地图片",
    modifier = Modifier.size(200.dp),
    // 可选配置项
    placeholder = painterResource(R.drawable.placeholder),
    error = painterResource(R.drawable.load_error)
)

注意：如果你访问的是应用专属目录外的公共存储图片，需要提前申请对应存储权限，Android 12及以下申请READ_EXTERNAL_STORAGE，Android 13及以上仅访问图片媒体库申请READ_MEDIA_IMAGES即可。

• 如果你需要搭配原生Image组件使用，调用rememberAsyncImagePainter传入文件实例即可：

val localImageFile = File(getExternalFilesDir(Environment.DIRECTORY_PICTURES), "my_head.png")
val painter = rememberAsyncImagePainter(model = localImageFile)

Image(
    painter = painter,
    contentDescription = "本地图片",
    modifier = Modifier.fillMaxWidth()
)

其他支持的本地数据源 #

除了File实例外，Coil还支持直接传入以下类型的本地资源作为model参数：

• 应用内drawable资源ID：model = R.drawable.local_default_image
• 系统相册返回的Content Uri实例：model = pickerReturnedUri
• 本地文件绝对路径字符串：model = "/sdcard/test_image.png"（更推荐传File实例，安全性更高）

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