레시피
이 페이지에서는 Coil을 사용할 때 자주 접하는 몇 가지 일반적인 사용 사례를 처리하는 방법을 안내합니다. 실제 요구사항에 맞게 코드를 수정해야 할 수도 있지만, 올바른 방향을 잡는 데 도움이 될 것입니다.
다루지 않은 일반적인 사용 사례가 있나요? 새로운 섹션을 추가하여 언제든지 PR을 제출해 주세요.
Palette
Palette를 사용하면 이미지에서 대표 색상을 추출할 수 있습니다. Palette를 생성하려면 이미지의 Bitmap에 접근해야 합니다. 이는 여러 가지 방법으로 가능합니다.
ImageRequest.Listener를 설정하고 ImageRequest를 큐에 등록(enqueue)하여 이미지의 비트맵에 접근할 수 있습니다:
imageView.load("https://example.com/image.jpg") {
// Palette가 이미지의 픽셀을 읽어야 하므로 하드웨어 비트맵을 비활성화합니다.
allowHardware(false)
listener(
onSuccess = { _, result ->
// 백그라운드 스레드에서 팔레트를 생성합니다.
Palette.Builder(result.image.toBitmap()).generate { palette ->
// 팔레트를 사용합니다.
}
}
)
}메모리 캐시 키를 플레이스홀더로 사용하기
두 이미지가 동일하지만 크기만 다르게 로드되는 경우, 이전 요청의 MemoryCache.Key를 후속 요청의 플레이스홀더로 사용하는 것이 유용할 수 있습니다. 예를 들어 첫 번째 요청에서 이미지를 100x100 크기로 로드하고 두 번째 요청에서 500x500 크기로 로드하는 경우, 첫 번째 이미지를 두 번째 요청의 동기식 플레이스홀더로 사용할 수 있습니다.
샘플 앱에서 이 효과는 다음과 같이 표시됩니다:
시각적 효과를 강조하기 위해 목록의 이미지는 의도적으로 매우 낮은 디테일로 로드되었으며 크로스페이드 속도가 느리게 적용되어 있습니다.
이 효과를 적용하려면 첫 번째 요청의 MemoryCache.Key를 두 번째 요청의 ImageRequest.placeholderMemoryCacheKey로 사용하세요. 예제는 다음과 같습니다:
// 첫 번째 요청
listImageView.load("https://example.com/image.jpg")
// 두 번째 요청 (첫 번째 요청이 완료된 후)
detailImageView.load("https://example.com/image.jpg") {
placeholderMemoryCacheKey((listImageView.result as? SuccessResult)?.memoryCacheKey)
}Compose AnimatedContent
rememberAsyncImagePainter와 AnimatedContent를 사용하여 플레이스홀더와 로드된 이미지 간의 전환 애니메이션을 구현할 수 있습니다:
val sizeResolver = rememberConstraintsSizeResolver()
val painter = rememberAsyncImagePainter(
model = ImageRequest.Builder(LocalPlatformContext.current)
.data("https://example.com/image.jpg")
.size(sizeResolver)
.build(),
)
val state by painter.state.collectAsState()
AnimatedContent(
modifier = Modifier.then(sizeResolver),
targetState = state,
contentKey = { it::class },
transitionSpec = { fadeIn() togetherWith fadeOut() },
) { targetState ->
when (targetState) {
is AsyncImagePainter.State.Empty,
is AsyncImagePainter.State.Loading -> PlaceholderContent()
is AsyncImagePainter.State.Success -> {
// 모델이 변경된 후 애니메이션과 함께 사라지는 동안 이전 이미지를 계속 표시합니다.
Image(
painter = targetState.painter,
contentDescription = stringResource(R.string.description),
)
}
is AsyncImagePainter.State.Error -> ErrorContent()
}
}Image에 targetState.painter를 전달하면 모델이 변경된 후 이전 이미지가 애니메이션과 함께 페이드아웃되는 동안에도 계속 표시됩니다.
로딩이 완료되기 전까지는 최종 이미지 크기를 알 수 없습니다. 공간을 확보하려면 고정 제약 조건(fixed constraints)이나 알려진 가로세로 비율(aspect ratio)을 사용하세요.
rememberAsyncImagePainter는 이미지가 메모리 캐시에 있는 경우에도 State.Empty로 시작합니다. 필요한 경우 state.result.dataSource를 확인하여 메모리에 캐시된 이미지에 대한 애니메이션을 건너뛸 수 있습니다.
참고: AnimatedContent는 페인터 크로스페이드보다 비용이 훨씬 많이 들며, 애니메이션이 끝날 때까지 이전 이미지를 메모리에 유지합니다. 지연 목록(lazy list)이나 단순한 페이드 효과에는 ImageRequest.Builder.crossfade를 사용하는 것이 좋습니다.
공유 요소 전환 (Shared Element Transitions)
공유 요소 전환(Shared element transitions)을 사용하면 Activity와 Fragment 간에 애니메이션을 적용할 수 있습니다. Coil에서 이를 원활하게 동작시키기 위한 몇 가지 권장 사항은 다음과 같습니다:
공유 요소 전환은 하드웨어 비트맵과 호환되지 않습니다. 애니메이션을 시작하는
ImageView와 대상이 되는 뷰 모두에allowHardware(false)를 설정하여 하드웨어 비트맵을 비활성화해야 합니다. 그렇지 않으면 전환 시java.lang.IllegalArgumentException: Software rendering doesn't support hardware bitmaps예외가 발생합니다.시작 이미지의
MemoryCache.Key를 종료 이미지의placeholderMemoryCacheKey로 사용하세요. 이렇게 하면 시작 이미지가 종료 이미지의 플레이스홀더로 사용되어, 이미지가 메모리 캐시에 있을 때 흰색 깜빡임 없이 부드러운 전환 효과를 얻을 수 있습니다.최상의 결과를 얻으려면
ChangeImageTransform과ChangeBounds를 함께 사용하세요.
Compose를 사용 중이신가요? AsyncImage로 공유 요소 전환을 수행하는 방법을 다룬 이 글을 확인해 보세요.
RemoteViews
Coil은 RemoteViews용 Target을 기본으로 제공하지 않지만, 다음과 같이 직접 생성할 수 있습니다:
class RemoteViewsTarget(
private val context: Context,
private val componentName: ComponentName,
private val remoteViews: RemoteViews,
@IdRes private val imageViewResId: Int
) : Target {
override fun onStart(placeholder: Image?) = setImage(placeholder)
override fun onError(error: Image?) = setImage(error)
override fun onSuccess(result: Image) = setImage(result)
private fun setImage(image: Image?) {
remoteViews.setImageViewBitmap(imageViewResId, image?.toBitmap())
AppWidgetManager.getInstance(context).updateAppWidget(componentName, remoteViews)
}
}그런 다음 평소처럼 요청을 enqueue/execute합니다:
val request = ImageRequest.Builder(context)
.data("https://example.com/image.jpg")
.target(RemoteViewsTarget(context, componentName, remoteViews, imageViewResId))
.build()
imageLoader.enqueue(request)Painter 변형하기
AsyncImage와 AsyncImagePainter는 모두 Painter를 인자로 받는 placeholder/error/fallback 매개변수를 지원합니다. Painter는 composable을 사용하는 것보다 유연성은 떨어지지만, Coil이 하위 구성(subcomposition)을 사용할 필요가 없어 더 빠릅니다. 하지만 원하는 UI를 얻기 위해 painter에 인셋(inset)을 주거나 늘리거나(stretch), 틴트(tint)를 주거나 변형해야 할 수 있습니다. 이를 구현하려면 이 Gist를 프로젝트에 복사한 후 다음과 같이 painter를 감싸서 사용하세요:
AsyncImage(
model = "https://example.com/image.jpg",
contentDescription = null,
placeholder = forwardingPainter(
painter = painterResource(R.drawable.placeholder),
colorFilter = ColorFilter(Color.Red),
alpha = 0.5f,
),
)후행 람다(trailing lambda)를 사용하여 onDraw를 재정의할 수도 있습니다:
AsyncImage(
model = "https://example.com/image.jpg",
contentDescription = null,
placeholder = forwardingPainter(painterResource(R.drawable.placeholder)) { info ->
inset(50f, 50f) {
with(info.painter) {
draw(size, info.alpha, info.colorFilter)
}
}
},
)Request 변형하기
이미지를 가져오는 데 사용되는 HTTP 요청을 변형해야 하는 경우가 있을 수 있습니다. 이 예제에서는 Interceptor를 사용하여 요청 URL에 width 및 height 쿼리 파라미터를 추가해 보겠습니다.
class UrlSizeInterceptor : Interceptor {
override suspend fun intercept(chain: Chain): ImageResult {
val request = chain.request
val uri = request.uri
if (uri == null || uri.scheme !in setOf("https", "http")) {
// HTTP 요청이 아닌 경우 무시합니다.
return chain.proceed()
}
val (width, height) = chain.size
return if (width is Pixels && height is Pixels) {
val transformUri = uri.newBuilder()
.query("width=${width.px}&height=${height.px}")
.build()
val transformedRequest = request.newBuilder()
.data(transformUri)
.build()
return chain.withRequest(transformedRequest).proceed()
} else {
// 무한 제약 조건 등으로 인해 너비와 높이를 사용할 수 없습니다.
chain.proceed()
}
}
private val ImageRequest.uri: Uri?
get() = when (val data = data) {
is Uri -> data
is coil3.Uri -> data.toAndroidUri()
is String -> data.toUri()
else -> null
}
}ImageLoader에 인터셉터를 추가하는 것을 잊지 마세요!
ImageLoader.Builder(context)
.components {
add(UrlSizeInterceptor())
}
.build()