官宣 Landscapist Core：专为 Android 与 Compose 多平台打造的全新图片加载库
图片加载一直是移动端和跨平台开发中的核心挑战。多年来，Android 开发者一直依赖 Glide、Coil 和 Fresco 这些久经考验的库。然而，随着 Kotlin 多平台的兴起，一个空白出现了：如何在不重复代码或不依赖平台特定解决方案的情况下，在 Android、iOS、桌面端和 Wasm 上一致地加载图片？这正是 Landscapist Core 要解决的问题。
在本文中，你将探索 Landscapist Core（一个独立的 Kotlin 多平台图片加载引擎）及其 Compose 多平台 UI 伴侣 Landscapist Image 背后的架构。你将了解使这个库异常轻量化的设计决策，理解它如何实现跨平台一致性，并学习将其集成到应用中的实用模式。无论你是在构建一个消费级应用，还是一个需要最小化体积的库/SDK，理解 Landscapist 的方法都将为你提供关于现代图片加载架构的宝贵见解。
如果你想深入探索 Kotlin 背后的“如何”与“为何”，从核心语言基础、内部机制到 API 设计，可以查看作者的新书 Practical Kotlin Deep Dive。
现有解决方案的问题
在深入了解 Landscapist Core 之前，值得思考一下为什么在已有成熟解决方案的情况下，还需要一个新的图片加载库。
当 Compose 多平台作为一个严肃的跨平台 UI 框架出现时，图片加载的故事仍然是碎片化的。开发者们拼凑解决方案：在 Android 上用 Glide/Coil，在其他地方用平台特定的加载器，或者重复造轮子。这自 2020 年 Landscapist 库 首次发布以来，就一直是我待办事项清单上的一个长期项目。随着时间的推移，我发现自己一直在寻找：
- 统一的解决方案：在所有 Compose 多平台目标上保持一致的 API 和行为。
- 极致轻量：我一直在处理大量的第三方解决方案，比如库和 SDK，所以我希望一切都尽可能轻量，只专注于核心能力，如网络获取、内存和磁盘缓存、解码与降采样以及渐进式加载。
- 为 Jetpack Compose 极致优化的性能。
对于 SDK 开发者来说，每一 KB 都至关重要。当你发布一个包含图片加载功能的库时，你的用户就继承了你的依赖。大约 312 KB 的 Landscapist Core 与 Coil3（~460 KB，大 47%）、Glide（~689 KB，大 121%）和 Fresco（~1 MB，大 228%）相比，显得非常小巧。这并非偶然，而是专注于核心功能、保持设计简洁的深思熟虑的架构选择的结果。
那么，Landscapist 是每个场景下的最佳选择吗？不，由于其成熟度，Coil3 在许多情况下可能是一个非常安全的选择。Landscapist Core 的主要价值在于：
- 为 Compose 高度优化，减少不必要的重组，并通过 Baseline Profiles 改善启动时间。
- 为需要节省每一 KB 的 SDK/库开发者。
- 除了核心引擎，Landscapist 还提供了一个丰富的插件生态系统，包括占位符动画（闪烁、淡入淡出、共振）、图片变换（模糊）、过渡动画（交叉淡入淡出、圆形揭示）、调色板提取，以及针对高分辨率图片的带子采样功能的高级缩放支持。
- 已经使用 Landscapist 插件生态系统的项目。
那么，让我们更深入地探索一下 Landscapist。
Landscapist Core：基石
Landscapist Core 是一个从一开始就为 Kotlin 多平台设计的、完整的、独立的图片加载引擎。它提供了获取、缓存、解码和交付图片所需的一切，没有任何 UI 依赖。
核心架构
该架构遵循管道模式，图片流经不同的阶段：从网络或源，经过获取、解码、转换、缓存，最后到达结果。每个阶段都是可插拔的，允许在不修改核心行为的情况下进行定制。这种设计实现了几个重要特性：阶段可以在适当的时候被跳过（缓存命中则绕过获取），任何阶段的失败都能清晰地传播，并且整个管道都是可挂起的，以便与协程高效集成。
在 Android 上，你可以使用构建器模式配合 Context 来创建实例：
val imageLoader = ImageLoader.Builder(context)
.memoryCache {
MemoryCache.Builder()
.maxSizePercent(0.25)
.build()
}
.diskCache {
DiskCache.Builder()
.directory(context.cacheDir.resolve("landscapist_cache"))
.maxSizeBytes(512L *1024*1024) //512 MB
.build()
}
.build()
这种方法会自动在应用的缓存目录中配置磁盘缓存，并启用 Android 特定的图片源，如 Uri、Drawable 资源和内容提供者。
或者，你可以使用无上下文的构建器和 getInstance()，这在包括 Android 在内的所有平台上都有效：
val imageLoader = ImageLoader.Builder()
.memoryCache {
MemoryCache.Builder()
.maxSizePercent(0.25)
.build()
}
.diskCache {
DiskCache.Builder()
.maxSizeBytes(512L *1024*1024) //512 MB
.build()
}
.build()
使用 Flow 加载图片
图片加载本质上是异步的，Landscapist 拥抱 Kotlin 的 Flow 来交付结果：
imageLoader.execute(
ImageRequest.builder()
.data("https://example.com/image.jpg")
.size(400, 400)
.build()
).collect { result ->
when (result) {
is ImageResult.Loading -> {
// 显示占位符
}
is ImageResult.Success -> {
// 使用 result.imageBitmap 或 result.imageDrawable
}
is ImageResult.Failure -> {
// 处理错误
}
}
}
基于 Flow 的 API 相比基于回调的替代方案有几个优点。状态变化按顺序传递，并且可以被多次收集。加载状态是显式的而非隐式的。当收集协程被取消时，加载会自动取消。
内存和磁盘缓存策略
缓存是图片加载器花费大部分复杂性的地方，Landscapist 的方法在简单性和有效性之间取得了平衡。
双层缓存架构
缓存策略使用两层：一个快速的内存 LRU 缓存和一个持久的磁盘缓存。
内存缓存使用最近最少使用淘汰策略，当缓存超过其大小限制时自动移除最旧的条目。weakReferencesEnabled 选项特别巧妙：当条目从 LRU 缓存中被淘汰时，它们会被保留为弱引用。如果位图在被重新请求时尚未被垃圾回收，它将被提升回 LRU 缓存，而无需任何 I/O 操作。
不同的图片有不同的缓存需求。用户的个人资料图片应该被积极缓存。一次性的验证图片可能完全跳过缓存。Landscapist 通过缓存策略提供细粒度控制：
ImageRequest.builder()
.data("https://example.com/image.jpg")
.memoryCachePolicy(CachePolicy.ENABLED)
.diskCachePolicy(CachePolicy.ENABLED)
.build()
自动降采样
大图片是 OutOfMemoryErrors 的常见来源。Landscapist 根据请求中指定的目标尺寸自动对图片进行降采样：
ImageRequest.builder()
.data("https://example.com/large-image.jpg")
.size(400, 400) // 目标尺寸
.build()
解码器使用目标尺寸来计算适当的采样大小，加载一个约 400x400 的位图，而不是完整的 4000x4000 图片。这一项优化通常决定了是流畅滚动的列表，还是在内存压力下崩溃的应用。
Landscapist Image：Compose 多平台集成
Landscapist Core 处理图片加载管道，而 Landscapist Image 则提供 Compose 多平台 UI 集成。它构建在核心模块之上，并与 Compose 的组合和布局系统无缝集成。
基本用法
最简单的用法只需要一个图片模型和一个尺寸：
LandscapistImage(
imageModel = { "https://example.com/image.jpg" },
modifier = Modifier.size(200.dp)
)
在这个简单的 API 背后，有几件事会自动发生：在组合期间测量来自修饰符的尺寸约束，检查适当的缓存，如果需要则获取图片，在目标分辨率下解码，然后渲染。
加载状态可组合项
真实应用需要优雅地处理加载和错误状态。Landscapist Image 为每种状态提供了可组合项插槽：
LandscapistImage(
imageModel = { "https://example.com/image.jpg" },
modifier = Modifier.size(200.dp),
loading = {
// 显示加载指示器
CircularProgressIndicator()
},
success = { state, painter ->// state: LandscapistImageState.Success
// painter: Painter
Image(
painter = painter,
contentDescription = null
)
},
failure = { state ->// state: LandscapistImageState.Failure
// 显示错误 UI
Text("Failed to load image")
}
)
可组合项插槽接收相关的状态信息。成功插槽提供 LandscapistImageState.Success（包含数据源、原始尺寸等元数据）和一个准备渲染的 Painter。失败插槽提供包含导致失败的异常的 LandscapistImageState.Failure。
状态变化回调
为了进行分析、日志记录或协调 UI 状态，你可以观察状态变化：
LandscapistImage(
imageModel = { "https://example.com/image.jpg" },
onImageStateChanged = { state ->
when (state) {
is LandscapistImageState.Loading -> {
// 开始加载
}
is LandscapistImageState.Success -> {
// 加载成功
}
is LandscapistImageState.Failure -> {
// 加载失败
}
}
}
)
插件生态系统
Landscapist 最优雅的特性之一是其插件架构。插件是模块化、可组合的组件，可以在不修改核心行为的情况下扩展功能。
插件通过 DSL 使用 component 参数添加：
val component = rememberImageComponent {
+ShimmerPlugin(
baseColor = Color.LightGray,
highlightColor = Color.White
)
+CrossfadePlugin(duration =300)
}
LandscapistImage(
imageModel = { "https://example.com/image.jpg" },
component = component
)
+ 操作符将插件添加到组件中。插件按顺序应用，允许你叠加效果。rememberImageComponent 确保组件配置在重组中得以保留。
该生态系统包含几个可用于生产的插件：
- ShimmerPlugin：在加载期间显示动画闪烁效果，提供内容正在加载的视觉反馈，可自定义颜色、持续时间和动画参数。
- CrossfadePlugin：在占位符和加载的图片之间平滑交叉淡入淡出，对于打造精致的用户体验至关重要。
- CircularRevealPlugin：以从中心扩展的圆形动画揭示图片。
- BlurTransformationPlugin：对加载的图片应用模糊效果。
- PalettePlugin：从加载的图片中提取主色调，用于创建响应图片内容的动态 UI。
- ZoomablePlugin：在图片上启用捏合缩放和平移手势，并且你可以为 Kotlin 多平台应用子采样。
插件可以组合使用以创建复杂的加载体验：
val component = rememberImageComponent {
+ShimmerPlugin()
+CrossfadePlugin()
+PalettePlugin { palette ->// 使用提取的调色板
}
}
你甚至可以使用 ImageComponent 和 ImagePlugin 创建自己的插件，这一切都让你的 Jetpack Compose 项目更加灵活。
性能特性
Landscapist 的性能并非事后才考虑，而是从一开始就针对特定性能目标进行设计的。
与成熟库的性能测试对比显示出了有竞争力的结果。LandscapistImage 的平均加载时间为 1,245 毫秒，内存使用量为 4,520 KB，而 GlideImage 为 1,312 毫秒（+5%）和 5,124 KB（+13%），CoilImage 为 1,389 毫秒（+12%）和 4,876 KB（+8%），FrescoImage 为 1,467 毫秒（+18%）和 5,342 KB（+18%）。这些数字来自标准化的基准测试条件：在相同的硬件上从网络加载同一组图片。实际性能会因网络条件、缓存状态和图片特性而异。
测试方法：性能数据是在 Android 16 模拟器上进行的 5 轮仪器化测试的平均值。每个测试从网络（GitHub CDN，无缓存）加载一个新鲜的 200KB JPEG 图片，尺寸为 300dp。每次运行之间清除所有缓存。测量从 setContent 到完全解码位图的时间。你可以查看 ComprehensivePerformanceTest.kt 获取完整实现。
Landscapist 的可组合函数被设计为符合 Compose 编译器指标的 Restartable 和 Skippable。Restartable 意味着函数可以在状态变化时重新进入，而无需重新执行整个函数体。Skippable 意味着如果输入没有改变，函数可以在重组期间被完全跳过。这些特性显著减少了列表和复杂 UI（其中图片很常见）中的重组开销。
该库还包含 Baseline Profiles，可在应用安装期间预编译关键代码路径。这减少了冷启动延迟并提高了整体响应能力，在低端设备上尤其明显。
跨平台考量
编写真正的跨平台代码需要理解平台之间的差异，并设计隐藏这些差异的抽象。
Landscapist 使用 Kotlin 的 expect/actual 机制来提供平台特定的实现：
// 通用代码
expect classPlatformContext// Android
actual typealias PlatformContext = Context
// iOS
actual classPlatformContext// 通用代码与抽象一起工作；平台提供具体实现。
不同的平台支持不同的图片源。Android 支持网络 URL、内容 URI、文件路径、Drawable 资源、位图和字节数组。iOS 和桌面端支持网络 URL 和文件路径。Web 仅支持网络 URL。ImageRequest.builder().model() 接受 Any?，平台特定的获取器会解析适当的加载策略。
Ktor 提供了跨平台的 HTTP 客户端，并根据平台自动选择引擎：Android 上用 OkHttp，iOS/macOS 上用 Darwin，桌面端用 CIO，Web 上用 JS。Ktor 引擎会根据你的目标平台自动打包，因此你无需手动添加 Ktor 依赖。
从现有 Landscapist 库迁移
从现有的 Landscapist 库迁移到 Landscapist Core 被设计为简单直接的。如果你已经在使用 Landscapist 的其他组件（GlideImage、CoilImage、FrescoImage），迁移几乎是直接替换：
// 之前
GlideImage(
imageModel = { "https://example.com/image.jpg" },
modifier = Modifier.size(200.dp)
)
// 之后
LandscapistImage(
imageModel = { "https://example.com/image.jpg" },
modifier = Modifier.size(200.dp)
)
API 被有意设计得相似。相同的插件两者都适用。主要区别在于 LandscapistImage 使用独立的核心引擎，而不是委托给 Glide、Coil 或 Fresco。
其他 Compose 图片加载解决方案的概念也能很好地映射过来。
何时选择 Landscapist
Landscapist Core 和 Landscapist Image 特别适合特定场景。如果你正在构建一个需要图片加载功能的 SDK，Landscapist 的最小体积非常有吸引力。大约 312 KB，它为你用户的 APK 增加了最小的负担。与捆绑 Glide（~689 KB）或 Fresco（~1 MB）相比，这种差异在你的 SDK 安装基数上会成倍放大。
对于针对 Android、iOS、桌面端或 Wasm 的 Compose 多平台应用程序，Landscapist 提供了一个统一的解决方案。在通用源代码集中编写一次图片加载代码，它就能在所有平台上完全相同地工作。如果你正在启动一个新项目，并且不需要特定库的功能（Glide 的资源管理、Coil 的扩展生态系统、Fresco 的流式架构），Landscapist 提供了一个更简单的思维模型，需要学习的概念更少。
在以下情况下，Landscapist 可能不是最佳选择：
- 你需要 Glide 广泛的变换库或资源生命周期集成。
- 你深度依赖 Coil 的拦截器和扩展生态系统。
- 你需要 Fresco 针对超大图片的渐进式流式加载。
- 你的项目仅针对 Android，并且你需要经过验证的特定库优化。
因此，这很大程度上取决于你的选择，我们无法说“A”在每种情况下都是最好的。
结论
Landscapist Core 代表了在 Kotlin 多平台时代对图片加载问题的一种深思熟虑的
原文链接：https://proandroiddev.com/announcing-landscapist-core-a-new-image-loading-library-for-android-compose-multiplatform-6a4f408cba00
