Coil — co to je, klíčové pojmy a ImageLoader v Androidu

Co je Coil?

Coil (Coroutine Image Loader) — je knihovna pro načítání obrázků na Androidu, napsaná výhradně v Kotlinu a využívající korutiny pro asynchronní práci. Poskytuje jednotné API pro načítání bitmapových obrázků ze sítě, zdrojů, souborového systému a Content Provideru s automatickým ukládáním do mezipaměti na více úrovních.

Na rozdíl od Glide a Picasso používá Coil Kotlin Coroutines místo řetězců callbacků, což činí kód lineárnějším a předvídatelnějším. Všechny operace načítání a dekódování jsou prováděny na pozadí přes Dispatchers.IO a výsledek je doručen do hlavního vlákna bez explicitního přepínání.

Coil podporuje transformace (Round, Blur, Grayscale), přechodové animace, SVG a GIF, stejně jako vlastní Target pro nestandardní zobrazení. Podle Google I/O 2023 je Coil doporučován v oficiálních tutoriálech pro Jetpack Compose společně s Glide.

• Velikost APK — kolem 150 KB (oproti 500 KB u Glide)
• Minimální verze Androidu — API 21 (Lollipop)
• Závislost — Kotlin Coroutines (vestavěná)

Jak funguje Coil: ImageLoader a ImageRequest

ImageLoader — hlavní komponenta Coilu odpovědná za provádění požadavků na načtení a správu mezipaměti. Každá instance obsahuje reference na MemoryCache, DiskCache, BitmapPool a fond korutin. Ve výchozím nastavení se používá singleton vytvořený přes Coil.imageLoader(context).

ImageRequest

ImageRequest — objekt popisující jeden požadavek na načtení obrázku: zdroj dat (URL, URI, Int zdroj), cílový ImageView nebo Target, transformace, nastavení mezipaměti a placeholder. ImageRequest se sestavuje pomocí builderu, což zajišťuje flexibilitu a čitelnost.

val request = ImageRequest.Builder(context)
    .data("https://example.com/image.jpg")
    .crossfade(true)
    .size(512, 512)
    .transformations(listOf(RoundedCornersTransformation(12f)))
    .memoryCachePolicy(CachePolicy.ENABLED)
    .diskCachePolicy(CachePolicy.ENABLED)
    .target(imageView)
    .build()

Po sestavení je ImageRequest předán ImageLoaderu přes enqueue nebo execute. Metoda enqueue spouští korutinu a vrací Disposable umožňující zrušení načítání při opuštění obrazovky. Metoda execute je funkce suspend vracející přímo Result.

Tok provedení požadavku

ImageLoader postupně kontroluje MemoryCache, DiskCache a pouze při neúspěchu obou provádí síťový požadavek přes HttpEngine. Po načtení jsou bajty dekódovány do Bitmap s ohledem na cílovou velikost, aplikují se transformace, výsledek je uložen do obou mezipamětí a předán Targetu.

• Memory Cache — kontroluje se jako první, klíč — URL + parametry
• Disk Cache — kontroluje se při absenci v paměti, klíč — MD5 URL
• HttpEngine — ve výchozím nastavení OkHttp, přizpůsobitelný přes komponentu

Hlavní komponenty Coilu

Coil je postaven na komponentové architektuře s možností výměny libovolné části pomocí Dependency Injection. Všechny komponenty jsou registrovány v ImageLoaderFactory a předávány do konstruktoru ImageLoaderu přes builder.

ImageLoader

ImageLoader — vstupní bod pro všechny operace načítání. Každá instance obsahuje fond korutin, BitmapPool, MemoryCache, DiskCache a seznam zachycovačů. Ve výchozím nastavení se vytváří jedna globální instance, ale pro modulární testování lze vytvářet samostatné instance s izolovanou mezipamětí.

MemoryCache

MemoryCache — mezipaměť v paměti založená na LRU (Least Recently Used) ukládající dekódované objekty Bitmap. Výchozí maximální velikost je 25 % dostupné paměti aplikace, ale ne méně než 32 MB. Klíč mezipaměti je tvořen z URL + velikosti + transformací, což vylučuje poskytnutí neaktuálního obrázku.

DiskCache

DiskCache — souborová mezipaměť pro surová data (JPEG, PNG, WebP) a dekódovaná metadata. Nachází se v adresáři mezipaměti aplikace a podporuje automatické čištění při překročení limitu. Práce s diskem se provádí přes DiskCache.Builder s nastavením adresáře a maximální velikosti.

Úrovně ukládání do mezipaměti v Coilu

Coil implementuje víceúrovňovou strategii ukládání do mezipaměti, která minimalizuje síťové požadavky a zrychluje zobrazování obrázků. Každá úroveň má svůj účel a životnost dat.

Memory Cache poskytuje okamžitý přístup k již dekódovaným bitmapám. Disk Cache zaručuje fungování aplikace bez sítě (offline-first) po prvním načtení. Http Cache na úrovni OkHttp zpracovává podmíněné požadavky ETag a If-Modified-Since.

Zásady ukládání do mezipaměti se nastavují pro každý požadavek přes CachePolicy se třemi hodnotami: ENABLED, READ_ONLY, WRITE_ONLY, DISABLED. Například pro uživatelské avatary lze nastavit READ_ONLY pro Memory Cache a ENABLED pro Disk Cache.

Příklady použití Coilu v Kotlinu

Coil nabízí několik způsobů integrace v závislosti na architektuře aplikace. Podívejme se na tři klíčové scénáře s funkčními příklady kódu.

Načtení do ImageView přes rozšíření

load — rozšiřující funkce pro ImageView, nejjednodušší způsob načtení obrázku jedním řádkem. Funkce přijímá URL, URI, Int zdroj nebo File a všechny volitelné parametry přes lambda konfigurátor.

imageView.load("https://example.com/photo.jpg") {
    crossfade(true)
    placeholder(R.drawable.placeholder)
    error(R.drawable.error)
    size(300, 300)
    transformations(CircleCropTransformation())
}

Metoda load vrací Disposable, který lze zrušit v onDestroy nebo při opětovném použití View. To zabraňuje únikům paměti a zbytečným síťovým požadavkům při rychlém rolování seznamu.

Použití v Jetpack Compose

AsyncImage — funkce composable pro načítání obrázků v deklarativním UI. Přijímá libovolný zdroj dat a tři volitelné parametry pro stavy: placeholder, error a success.

@Composable
fun NetworkImage(url: String) {
    AsyncImage(
        model = url,
        contentDescription = "obrázek ze sítě",
        placeholder = ColorPainter(Color.Gray),
        error = ColorPainter(Color.Red)
    )
}

SubcomposeAsyncImage — flexibilnější verze umožňující přizpůsobení zobrazení během načítání pomocí content slotu. To je užitečné pro kostry (shimmer) a ukazatele průběhu.

Vlastní Target pro nestandardní výstup

Pokud ImageView nebo AsyncImage nevyhovují, lze implementovat Target s jedinou metodou onSuccess přijímající Bitmap. To se používá pro načítání do Notification, RemoteViews nebo OpenGL textury.

val target = object : BitmapTarget() {
    override fun onSuccess(result: Bitmap) {
        notificationRemoteView.setImageViewBitmap(R.id.icon, result)
    }
}

imageLoader.enqueue(
    ImageRequest.Builder(context)
        .data(url)
        .target(target)
        .build()
)

Srovnání Coilu s jinými knihovnami

Výběr knihovny pro načítání obrázků závisí na požadavcích projektu. Coil konkuruje Glide a Picasso, z nichž každá má své silné stránky. Srovnání hlavních charakteristik je uvedeno v tabulce.

Pro nové projekty v Kotlinu a Jetpack Compose se Coil stává přirozenou volbou díky nulové dodatečné závislosti na korutinách a minimální velikosti. Glide zůstává preferovaný pro složité scénáře s animacemi a náhledy videa. Picasso je oběma funkčně podřadné, ale vítězí jednoduchostí.

Nastavení Coilu v Android projektu

Připojení Coilu k Android projektu se provádí přes závislost Gradle. Po přidání knihovna automaticky registruje ImageLoader přes ContentProvider, takže ruční inicializace v Application není nutná. Při potřebě přizpůsobení se vytvoří vlastní ImageLoader přes builder.

// build.gradle.kts (modul aplikace)
dependencies {
    implementation("io.coil-kt:coil:2.6.0")
    // Dodatečně pro Jetpack Compose:
    implementation("io.coil-kt:coil-compose:2.6.0")
    // Pro podporu SVG:
    implementation("io.coil-kt:coil-svg:2.6.0")
    // Pro podporu GIF:
    implementation("io.coil-kt:coil-gif:2.6.0")
}

Pro přizpůsobení ImageLoaderu se používá ImageLoaderFactory — singleton vytvořený v Application.onCreate. V továrně lze nastavit limity mezipaměti, HTTP klienta, vlastní dekodéry a logování. Ve výchozím nastavení Coil používá OkHttp s připraveným fondem spojení.

class App : Application(), ImageLoaderFactory {
    override fun newImageLoader(): ImageLoader {
        return ImageLoader.Builder(this)
            .memoryCache {
                MemoryCache.Builder()
                    .maxSizePercent(0.25)
                    .build()
            }
            .diskCache {
                DiskCache.Builder()
                    .directory(cacheDir.resolve("coil_cache"))
                    .maxSizeBytes(512 * 1024 * 1024)
                    .build()
            }
            .build()
    }
}