이미지 파이프라인 확장하기
안드로이드는 기본적으로 다양한 이미지 형식을 지원하지만, 지원하지 않는 형식도 많습니다(예: GIF, SVG, MP4 등).
다행히도 ImageLoader는 플러그형 컴포넌트를 지원하므로 새로운 캐시 레이어, 새로운 데이터 타입, 새로운 페치(fetch) 동작, 새로운 이미지 인코딩을 추가하거나 기본 이미지 로딩 동작을 덮어쓸(overwrite) 수 있습니다. Coil의 이미지 파이프라인은 다음 순서로 실행되는 다섯 가지 주요 부분으로 구성됩니다: Interceptors, Mappers, Keyers, Fetchers, Decoders.
커스텀 컴포넌트는 ImageLoader를 구성할 때 ComponentRegistry를 통해 추가해야 합니다:
val imageLoader = ImageLoader.Builder(context)
.components {
add(CustomCacheInterceptor())
add(ItemMapper())
add(HttpUrlKeyer())
add(CronetFetcher.Factory())
add(GifDecoder.Factory())
}
.build()Interceptor
Interceptor를 사용하면 ImageLoader의 이미지 엔진으로 향하는 요청을 관찰(observe), 변환(transform), 조기 반환(short-circuit)하거나 재시도할 수 있습니다. 예를 들어 다음과 같이 커스텀 캐시 레이어를 추가할 수 있습니다:
class CustomCacheInterceptor(
private val context: Context,
private val cache: LruCache<String, Image>,
) : Interceptor {
override suspend fun intercept(chain: Interceptor.Chain): ImageResult {
val value = cache.get(chain.request.data.toString())
if (value != null) {
return SuccessResult(
image = value,
request = chain.request,
dataSource = DataSource.MEMORY_CACHE,
)
}
return chain.proceed()
}
}Interceptor는 ImageLoader의 이미지 파이프라인을 커스텀 로직으로 감쌀 수 있게 해주는 고급 기능입니다. 이 설계는 OkHttp의 Interceptor 인터페이스를 크게 참고하여 만들어졌습니다.
자세한 내용은 Interceptor를 참고하세요.
Mapper
Mapper를 사용하면 커스텀 데이터 타입에 대한 지원을 추가할 수 있습니다. 예를 들어 서버에서 다음과 같은 모델을 받는다고 가정해 보겠습니다:
data class Item(
val id: Int,
val imageUrl: String,
val price: Int,
val weight: Double
)이 모델을 파이프라인의 후속 단계에서 처리될 URL로 매핑하는 커스텀 매퍼를 작성할 수 있습니다:
class ItemMapper : Mapper<Item, String> {
override fun map(data: Item, options: Options) = data.imageUrl
}ImageLoader를 빌드할 때 이를 등록하고 나면(위 내용 참조), 안전하게 Item을 로드할 수 있습니다:
val request = ImageRequest.Builder(context)
.data(item)
.target(imageView)
.build()
imageLoader.enqueue(request)자세한 내용은 Mapper를 참고하세요.
Keyer
Keyer는 데이터를 캐시 키의 일부로 변환합니다. 이 값은 해당 요청의 결과가 MemoryCache에 기록될 때 MemoryCache.Key.key로 사용됩니다.
자세한 내용은 Keyer를 참고하세요.
Fetcher
Fetcher는 데이터(예: URL, URI, File 등)를 ImageSource 또는 Image로 변환합니다. 일반적으로 입력 데이터를 Decoder가 처리할 수 있는 형식으로 변환합니다. 커스텀 페칭 메커니즘(예: Cronet, 커스텀 URI 스킴 등)에 대한 지원을 추가하려면 이 인터페이스를 사용하세요.
자세한 내용은 Fetcher를 참고하세요.
참고
커스텀 데이터 타입을 사용하는 Fetcher를 추가하는 경우, 해당 요청의 결과가 메모리 캐시에 저장될 수 있도록 커스텀 Keyer도 함께 제공해야 합니다. 예를 들어 Fetcher.Factory<MyDataType>에는 Keyer<MyDataType>를 추가해야 합니다.
Decoder
Decoder는 ImageSource를 읽고 Image를 반환합니다. 커스텀 파일 형식(예: GIF, SVG, TIFF 등)에 대한 지원을 추가하려면 이 인터페이스를 사용하세요.
자세한 내용은 Decoder를 참고하세요.
커스텀 ImageLoader 및 ImageRequest 프로퍼티
Coil은 Extras를 통해 ImageRequest와 ImageLoader에 커스텀 데이터를 첨부하는 기능을 지원합니다. Extras는 Extras.Key를 통해 참조되는 추가 프로퍼티의 맵(map)입니다.
예를 들어 각 ImageRequest마다 커스텀 타임아웃을 지원하고 싶다고 가정해 보겠습니다. 다음과 같이 커스텀 확장 함수를 추가할 수 있습니다:
fun ImageRequest.Builder.timeout(timeout: Duration) = apply {
extras[timeoutKey] = timeout
}
fun ImageLoader.Builder.timeout(timeout: Duration) = apply {
extras[timeoutKey] = timeout
}
val ImageRequest.timeout: Duration
get() = getExtra(timeoutKey)
val Options.timeout: Duration
get() = getExtra(timeoutKey)
// 참고: Extras.Key 인스턴스는 인스턴스 동등성(equality)으로 비교되므로 정적(statically)으로 선언해야 합니다.
private val timeoutKey = Extras.Key(default = Duration.INFINITE)그런 다음 ImageLoader에 등록할 커스텀 Interceptor 내부에서 해당 프로퍼티를 읽을 수 있습니다:
class TimeoutInterceptor : Interceptor {
override suspend fun intercept(chain: Interceptor.Chain): ImageResult {
val timeout = chain.request.timeout
if (timeout.isFinite()) {
return withTimeout(timeout) {
chain.proceed()
}
} else {
return chain.proceed()
}
}
}마지막으로 ImageRequest를 생성할 때 해당 프로퍼티를 설정할 수 있습니다:
AsyncImage(
model = ImageRequest.Builder(LocalPlatformContext.current)
.data("https://example.com/image.jpg")
.timeout(10.seconds)
.build(),
contentDescription = null,
)추가로 다음 작업도 가능합니다:
- 정의한
ImageLoader.Builder.timeout확장 함수를 통해 기본 타임아웃 값을 설정할 수 있습니다. - 정의한
Options.timeout확장 함수를 통해Mapper,Fetcher,Decoder내부에서 타임아웃을 읽을 수 있습니다.
Coil 자체에서도 이 패턴을 사용하여 coil-gif 및 기타 확장 라이브러리에서 GIF용 커스텀 요청 프로퍼티를 지원하고 있습니다.
컴포넌트 체이닝
Coil 이미지 로더 컴포넌트의 유용한 특징 중 하나는 내부적으로 체이닝(연결)할 수 있다는 점입니다. 예를 들어 로드할 이미지 URL을 얻기 위해 네트워크 요청을 수행해야 하는 경우가 있습니다.
먼저 전용 fetcher에서만 처리할 커스텀 데이터 타입을 만듭니다:
data class PartialUrl(
val baseUrl: String,
)그런 다음 이미지 URL을 가져와 내부 네트워크 fetcher에 위임하는 커스텀 Fetcher를 작성합니다:
class PartialUrlFetcher(
private val callFactory: Call.Factory,
private val partialUrl: PartialUrl,
private val options: Options,
private val imageLoader: ImageLoader,
) : Fetcher {
override suspend fun fetch(): FetchResult? {
val request = Request.Builder()
.url(partialUrl.baseUrl)
.build()
val response = callFactory.newCall(request).await()
// 이미지 URL을 읽습니다.
val imageUrl: String = readImageUrl(response.body)
// 내부 네트워크 fetcher에 위임합니다.
val data = imageLoader.components.map(imageUrl, options)
val output = imageLoader.components.newFetcher(data, options, imageLoader)
val (fetcher) = checkNotNull(output) { "no supported fetcher" }
return fetcher.fetch()
}
class Factory(
private val callFactory: Call.Factory = OkHttpClient(),
) : Fetcher.Factory<PartialUrl> {
override fun create(data: PartialUrl, options: Options, imageLoader: ImageLoader): Fetcher {
return PartialUrlFetcher(callFactory, data, options, imageLoader)
}
}
}마지막으로 ComponentRegistry에 이 Fetcher를 등록하고 model/data로 PartialUrl을 전달하기만 하면 됩니다:
AsyncImage(
model = PartialUrl("https://example.com/image.jpg"),
contentDescription = null,
)이 패턴은 Mapper, Keyer, Decoder에도 유사하게 적용할 수 있습니다.
