Skip to content

레시피 ​

이 페이지에서는 Coil을 사용할 때 자주 접하는 몇 가지 일반적인 사용 사례를 처리하는 방법을 안내합니다. 실제 요구사항에 맞게 코드를 수정해야 할 수도 있지만, 올바른 방향을 잡는 데 도움이 될 것입니다.

다루지 않은 일반적인 사용 사례가 있나요? 새로운 섹션을 추가하여 언제든지 PR을 제출해 주세요.

Palette ​

Palette를 사용하면 이미지에서 대표 색상을 추출할 수 있습니다. Palette를 생성하려면 이미지의 Bitmap에 접근해야 합니다. 이는 여러 가지 방법으로 가능합니다.

ImageRequest.Listener를 설정하고 ImageRequest를 큐에 등록(enqueue)하여 이미지의 비트맵에 접근할 수 있습니다:

kotlin
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로 사용하세요. 예제는 다음과 같습니다:

kotlin
// 첫 번째 요청
listImageView.load("https://example.com/image.jpg")

// 두 번째 요청 (첫 번째 요청이 완료된 후)
detailImageView.load("https://example.com/image.jpg") {
    placeholderMemoryCacheKey((listImageView.result as? SuccessResult)?.memoryCacheKey)
}

Compose AnimatedContent ​

rememberAsyncImagePainter와 AnimatedContent를 사용하여 플레이스홀더와 로드된 이미지 간의 전환 애니메이션을 구현할 수 있습니다:

kotlin
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을 기본으로 제공하지 않지만, 다음과 같이 직접 생성할 수 있습니다:

kotlin
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합니다:

kotlin
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를 감싸서 사용하세요:

kotlin
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를 재정의할 수도 있습니다:

kotlin
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 쿼리 파라미터를 추가해 보겠습니다.

kotlin
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에 인터셉터를 추가하는 것을 잊지 마세요!

kotlin
ImageLoader.Builder(context)
    .components {
        add(UrlSizeInterceptor())
    }
    .build()