跳到正文
FunCoding

coil-compose

Expert guidance on using Coil for image loading in Jetpack Compose. Use this when asked about loading images from URLs, handling image states, or optimizing image performance in Compose.

Star
974
分类
图像与视频
许可证
Apache-2.0
最近提交
2026年7月28日

.github/skills/ui/coil-compose/SKILL.md

在 GitHub 上查看

Coil for Jetpack Compose

Instructions

When implementing image loading in Jetpack Compose, use Coil (Coroutines Image Loader). It is the recommended library for Compose due to its efficiency and seamless integration.

1. Primary Composable: AsyncImage

Use AsyncImage for most use cases. It handles size resolution automatically and supports standard Image parameters.

AsyncImage(
    model = ImageRequest.Builder(LocalContext.current)
        .data("https://example.com/image.jpg")
        .crossfade(true)
        .build(),
    placeholder = painterResource(R.drawable.placeholder),
    error = painterResource(R.drawable.error),
    contentDescription = stringResource(R.string.description),
    contentScale = ContentScale.Crop,
    modifier = Modifier.clip(CircleShape)
)

2. Low-Level Control: rememberAsyncImagePainter

Use rememberAsyncImagePainter only when you need a Painter instead of a composable (e.g., for Canvas or Icon) or when you need to observe the loading state manually.

Warning

rememberAsyncImagePainter does not detect the size your image is loaded at on screen and always loads the image with its original dimensions by default. Use AsyncImage unless a Painter is strictly required.

val painter = rememberAsyncImagePainter(
    model = ImageRequest.Builder(LocalContext.current)
        .data("https://example.com/image.jpg")
        .size(Size.ORIGINAL) // Explicitly define size if needed
        .build()
)

3. Slot API: SubcomposeAsyncImage

Use SubcomposeAsyncImage when you need a custom slot API for different states (Loading, Success, Error).

Caution

Subcomposition is slower than regular composition. Avoid using SubcomposeAsyncImage in performance-critical areas like LazyColumn or LazyRow.

SubcomposeAsyncImage(
    model = "https://example.com/image.jpg",
    contentDescription = null,
    loading = {
        CircularProgressIndicator()
    },
    error = {
        Icon(Icons.Default.Error, contentDescription = null)
    }
)

4. Performance & Best Practices

  • Singleton ImageLoader: Use a single ImageLoader instance for the entire app to share the disk/memory cache.
  • Main-Safe: Coil executes image requests on a background thread automatically.
  • Crossfade: Always enable crossfade(true) in ImageRequest for a smoother transition from placeholder to success.
  • Sizing: Ensure contentScale is set appropriately to avoid loading larger images than necessary.

5. Checklist for implementation

  • Prefer AsyncImage over other variants.
  • Always provide a meaningful contentDescription or set it to null for decorative images.
  • Use crossfade(true) for better UX.
  • Avoid SubcomposeAsyncImage in lists.
  • Configure ImageRequest for specific needs like transformations (e.g., CircleCropTransformation).

相似的 Skill

blender-motion-state-inspection

AFaffaan-m/ECC278k近 7 天新增 4,046 个 star

官方

slack-gif-creator

ANanthropics/skills181k近 7 天新增 1,119 个 star

精选

algorithmic-art

用 p5.js 生成流场和粒子系统，通过种子随机性创作原创算法艺术。

ANanthropics/skills181k近 7 天新增 1,119 个 star

thinking-out-loud

SHShubhamsaboo/awesome-llm-apps141k近 7 天新增 808 个 star

moneyprinterturbo-video

HAharry0703/MoneyPrinterTurbo130k近 7 天新增 1,722 个 star

complain

PApaperclipai/paperclip101k近 7 天新增 2,948 个 star