시작하기

Compose UI

일반적인 Compose UI 프로젝트에서는 다음을 임포트합니다:

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

임포트가 완료되면 AsyncImage를 사용하여 네트워크에서 이미지를 로드할 수 있습니다:

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

::: Note Compose Multiplatform을 사용하는 경우 OkHttp 대신 Ktor를 사용해야 합니다. 자세한 방법은 여기를 참고하세요.

:::

Android View

Compose UI 대신 Android View를 사용한다면 다음을 임포트하세요:

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

임포트가 완료되면 ImageView.load 확장 함수를 사용하여 네트워크에서 이미지를 로드할 수 있습니다:

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

싱글톤 ImageLoader 설정하기

기본적으로 Coil은 싱글톤 ImageLoader를 포함하고 있습니다. ImageLoader는 들어오는 ImageRequest를 가져오기(fetching), 디코딩(decoding), 캐싱(caching)하여 그 결과를 반환하는 방식으로 실행합니다. ImageLoader를 직접 설정할 필요는 없습니다. 별도로 설정하지 않으면 Coil이 기본 설정으로 싱글톤 ImageLoader를 생성합니다.

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

• 앱의 진입점(앱의 루트 @Composable) 근처에서 setSingletonImageLoaderFactory를 호출하세요. 이 방법은 Compose Multiplatform 앱에 가장 적합합니다.

setSingletonImageLoaderFactory { context ->
    ImageLoader.Builder(context)
        .crossfade(true)
        .build()
}

• Android의 Application에서 SingletonImageLoader.Factory를 구현하세요. 이 방법은 Android 앱에 가장 적합합니다.

class CustomApplication : Application(), SingletonImageLoader.Factory {
    override fun newImageLoader(context: Context): ImageLoader {
        return ImageLoader.Builder(context)
            .crossfade(true)
            .build()
    }
}

• 앱의 진입점(예: Android의 Application.onCreate) 근처에서 SingletonImageLoader.setSafe를 호출하세요. 이 방법이 가장 유연합니다.

SingletonImageLoader.setSafe { context ->
    ImageLoader.Builder(context)
        .crossfade(true)
        .build()
}

::: Note Coil에 의존하는 라이브러리를 작성 중이라면 싱글톤 ImageLoader를 가져오거나 설정해서는 안 됩니다. 대신 io.coil-kt.coil3:coil-core에 의존하고, 자체 ImageLoader를 만들어 직접 전달해야 합니다. 라이브러리에서 싱글톤 ImageLoader를 설정하면, 해당 라이브러리를 사용하는 앱에서도 Coil을 사용할 경우 앱이 설정한 ImageLoader를 덮어씌울 위험이 있습니다.

:::

이미지

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

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

또한 Coil은 coil3.Bitmap 클래스를 정의하고 있는데, 이는 Android에서는 android.graphics.Bitmap, Android 이외의 플랫폼에서는 org.jetbrains.skia.Bitmap에 대한 타입 별칭(type alias)입니다:

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

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

val painter = image.asPainter()

::: Note Painter는 컴포지션(composition) 내부에서만 렌더링될 수 있는 반면, 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: 기본 Compose UI 아티팩트로 io.coil-kt.coil3:coil 및 io.coil-kt.coil3:coil-compose-core에 의존합니다. 싱글톤 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-cache-control: 네트워크에서 이미지를 가져올 때 Cache-Control 헤더를 준수하도록 지원합니다.
• io.coil-kt.coil3:coil-gif: GIF 디코딩을 지원하기 위한 두 개의 디코더를 포함합니다. 자세한 내용은 GIF를 참고하세요.
• io.coil-kt.coil3:coil-svg: SVG 디코딩을 지원하기 위한 디코더를 포함합니다. 자세한 내용은 SVG를 참고하세요.
• io.coil-kt.coil3:coil-video: Android에서 지원하는 모든 비디오 형식의 프레임 디코딩을 지원하기 위한 디코더를 포함합니다. 자세한 내용은 비디오를 참고하세요.
• io.coil-kt.coil3:coil-test: 테스트 지원을 위한 클래스들을 포함합니다. 자세한 내용은 테스트를 참고하세요.
• io.coil-kt.coil3:coil-bom: BOM(Bill of Materials)을 포함합니다. coil-bom을 임포트하면 버전을 지정하지 않고도 다른 Coil 아티팩트들에 의존할 수 있습니다.