Skip to content

시작하기 ​

Compose UI ​

일반적인 Compose UI 프로젝트에서는 다음을 추가(import)합니다:

kotlin
implementation("io.coil-kt.coil3:coil-compose:3.6.3")
implementation("io.coil-kt.coil3:coil-network-okhttp:3.6.3")

추가한 후에는 AsyncImage를 사용하여 네트워크에서 이미지를 로드할 수 있습니다:

kotlin
AsyncImage(
    model = "https://example.com/image.jpg",
    contentDescription = null,
)

참고

OkHttp는 Android 및 데스크톱 JVM을 지원합니다. iOS나 웹도 타깃으로 하는 공유 네트워킹 코드는 Ktor network engines를 참조하세요.

Android Views ​

Compose UI 대신 Android View를 사용하는 경우 다음을 추가합니다:

kotlin
implementation("io.coil-kt.coil3:coil:3.6.3")
implementation("io.coil-kt.coil3:coil-network-okhttp:3.6.3")

추가한 후에는 ImageView.load 확장 함수를 사용하여 네트워크에서 이미지를 로드할 수 있습니다:

kotlin
imageView.load("https://example.com/image.jpg")

싱글톤 ImageLoader 설정하기 ​

기본적으로 Coil에는 싱글톤 ImageLoader가 포함되어 있습니다. ImageLoader는 가져오기(fetching), 디코딩, 캐싱 및 결과 반환을 통해 전달된 ImageRequest를 실행합니다. ImageLoader를 직접 구성하지 않아도 되며, 별도로 설정하지 않으면 Coil이 기본 구성으로 싱글톤 ImageLoader를 생성합니다.

여러 가지 방법으로 설정할 수 있습니다(한 가지만 선택하세요):

  • 앱의 진입점(앱의 루트 @Composable) 부근에서 setSingletonImageLoaderFactory를 호출합니다. Compose Multiplatform 앱에 가장 적합합니다.
kotlin
setSingletonImageLoaderFactory { context ->
    ImageLoader.Builder(context)
        .crossfade(true)
        .build()
}
  • Android의 Application에서 SingletonImageLoader.Factory를 구현합니다. Android 앱에 가장 적합합니다.
kotlin
class CustomApplication : Application(), SingletonImageLoader.Factory {
    override fun newImageLoader(context: Context): ImageLoader {
        return ImageLoader.Builder(context)
            .crossfade(true)
            .build()
    }
}
  • 앱의 진입점 부근(예: Android의 Application.onCreate)에서 SingletonImageLoader.setSafe를 호출합니다. 가장 유연한 방식입니다.
kotlin
SingletonImageLoader.setSafe { context ->
    ImageLoader.Builder(context)
        .crossfade(true)
        .build()
}

참고

Coil에 의존하는 라이브러리를 작성하는 경우, 싱글톤 ImageLoader를 가져오거나(get) 설정(set)해서는 안 됩니다. 대신 io.coil-kt.coil3:coil-core에 의존하고, 자체 ImageLoader를 생성하여 직접 전달해야 합니다. 라이브러리에서 싱글톤 ImageLoader를 설정하면, 해당 라이브러리를 사용하는 앱 역시 Coil을 사용할 때 앱이 설정한 ImageLoader를 덮어쓸 위험이 있습니다.

이미지 ​

멀티플랫폼 렌더링을 지원하기 위해 Coil 3.x는 커스텀 coil3.Image 클래스를 사용합니다. 이는 Android의 Drawable을 대체하지만 완벽하게 상호 운용(interoperable)됩니다:

kotlin
val drawable = image.asDrawable(resources)
val image = drawable.asImage()

또한 Coil은 coil3.Bitmap 클래스를 정의하고 있으며, 이는 Android에서는 android.graphics.Bitmap, 비 Android 플랫폼에서는 org.jetbrains.skia.Bitmap의 타입 에일리어스(type alias)입니다:

kotlin
val bitmap = image.toBitmap()
val image = bitmap.asImage()

Compose UI의 Painter 클래스와도 상호 운용이 가능합니다. 이 확장 함수를 사용하려면 coil-compose-core 아티팩트를 추가해야 합니다:

kotlin
val painter = image.asPainter(LocalPlatformContext.current)

참고

Painter는 컴포지션 내부에서만 렌더링될 수 있는 반면 Image는 모든 Canvas에서 렌더링될 수 있어야 하므로, Painter를 Image로 변환할 수는 없습니다.

아티팩트 ​

다음은 Coil이 mavenCentral()에 배포한 주요 아티팩트 목록입니다:

  • io.coil-kt.coil3:coil: io.coil-kt.coil3:coil-core에 의존하는 기본 아티팩트입니다. 싱글톤 ImageLoader 및 관련 확장 함수를 포함합니다.
  • io.coil-kt.coil3:coil-core: io.coil-kt.coil3:coil의 서브셋으로, 싱글톤 ImageLoader 및 관련 확장 함수를 포함하지 않습니다.
  • io.coil-kt.coil3:coil-compose: io.coil-kt.coil3:coil 및 io.coil-kt.coil3:coil-compose-core에 의존하는 기본 Compose UI 아티팩트입니다. 싱글톤 ImageLoader를 사용하는 AsyncImage, rememberAsyncImagePainter, SubcomposeAsyncImage 오버로드를 포함합니다.
  • io.coil-kt.coil3:coil-compose-core: io.coil-kt.coil3:coil-compose의 서브셋으로, 싱글톤 ImageLoader에 의존하는 함수를 포함하지 않습니다.
  • io.coil-kt.coil3:coil-network-okhttp: OkHttp를 사용하여 네트워크에서 이미지를 가져오는 지원을 포함합니다.
  • io.coil-kt.coil3:coil-network-ktor2: Ktor 2를 사용하여 네트워크에서 이미지를 가져오는 지원을 포함합니다.
  • io.coil-kt.coil3:coil-network-ktor3: Ktor 3를 사용하여 네트워크에서 이미지를 가져오는 지원을 포함합니다.
  • io.coil-kt.coil3:coil-network-httpengine: Android의 HttpEngine을 사용하여 네트워크에서 이미지를 가져오는 지원을 포함합니다. Android API 34 이상이 필요합니다.
  • io.coil-kt.coil3:coil-network-cache-control: 네트워크에서 이미지를 가져올 때 Cache-Control 헤더를 준수하도록 지원합니다.
  • io.coil-kt.coil3:coil-gif: GIF 디코딩을 지원하는 두 개의 디코더를 포함합니다. 자세한 내용은 GIFs를 참조하세요.
  • io.coil-kt.coil3:coil-svg: SVG 디코딩을 지원하는 디코더를 포함합니다. 자세한 내용은 SVGs를 참조하세요.
  • io.coil-kt.coil3:coil-video: Android에서 지원하는 모든 비디오 포맷에서 프레임을 디코딩할 수 있는 디코더를 포함합니다. 자세한 내용은 videos를 참조하세요.
  • io.coil-kt.coil3:coil-test: 테스트 지원을 위한 클래스를 포함합니다. 자세한 내용은 testing을 참조하세요.
  • io.coil-kt.coil3:coil-bom: BOM(Bill of Materials)을 포함합니다. coil-bom을 가져오면 버전을 명시하지 않고도 다른 Coil 아티팩트에 의존할 수 있습니다.