Sketch Image Loader

翻译：English

Sketch 是专为 Compose Multiplatform 和 Android View 设计的图片加载库，它有以下特点：

多加载源：支持从 http、file、compose resource、android asset/content/resource 等多种来源加载图片
功能强大：支持三级缓存、自动取消请求、自动调整图片尺寸、自动根据 Exif Orientation 旋转图片等
功能丰富：支持动图、SVG 图片、Base64 图片、视频帧
易于扩展：支持对缓存、解码、转换、过渡、占位图等各个环节的扩展
扩展功能：提供蜂窝流量时暂停下载、列表滚动中暂停加载、图片类型徽章、下载进度指示器等实用扩展
现代化：完全基于 Kotlin 和 Kotlin 协程设计

示例 App

Android：请到 Releases 页面下载最新版本的安装包
Web：https://panpf.github.io/sketch/app
桌面：使用 kdoctor 检查运行环境，并按照提示安装需要的软件，然后在项目根目录执行 ./package_desktop.sh 命令打包，安装包位置包含在输出中
iOS：请参考运行示例 App 部分自行编译运行

安装

已发布到 mavenCentral

${LAST_VERSION}: (不包含 'v')

Compose Multiplatform:

Import the required Compose and network modules:

// 提供了 Sketch 的核心功能以及单例和依赖单例实现的扩展函数
implementation("io.github.panpf.sketch4:sketch-compose:${LAST_VERSION}")

// 提供了加载网络图片的能力
implementation("io.github.panpf.sketch4:sketch-http:${LAST_VERSION}")

Important

为提升 compose 的性能请拷贝 sketch-core 模块下的 compose_compiler_config.conf 文件到您的项目中，然后按照 Compose Stability Configuration 文档配置它

Android View:

// 提供了 Sketch 的核心功能以及单例和依赖单例实现的扩展函数
implementation("io.github.panpf.sketch4:sketch-view:${LAST_VERSION}")

// 提供了加载网络图片的能力
implementation("io.github.panpf.sketch4:sketch-http:${LAST_VERSION}")

可选模块

// 使用 Android 或 Skia 内置的解码器解码 gif 动图并播放
implementation("io.github.panpf.sketch4:sketch-animated-gif:${LAST_VERSION}")

// [仅 Android] 使用 android-gif-drawable 库的 GifDrawable 解码 gif 动图并播放
implementation("io.github.panpf.sketch4:sketch-animated-gif-koral:${LAST_VERSION}")

// [仅 Android] Android 或 Skia 内置的解码器解码 heif 动图并播放
implementation("io.github.panpf.sketch4:sketch-animated-heif:${LAST_VERSION}")

// 使用 Android 或 Skia 内置的解码器解码 webp 动图并播放
implementation("io.github.panpf.sketch4:sketch-animated-webp:${LAST_VERSION}")

// 支持通过 uri 或 placeholder、fallback、error 访问 compose resources 资源
implementation("io.github.panpf.sketch4:sketch-compose-resources:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-extensions-compose-resources:${LAST_VERSION}")

// 提供下载进度、图片类型角标、列表滚动中暂停加载、节省蜂窝流量等实用功能
implementation("io.github.panpf.sketch4:sketch-extensions-compose:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-extensions-view:${LAST_VERSION}")

// [仅 Android] 支持通过文件路径加载 apk 文件的图标 
implementation("io.github.panpf.sketch4:sketch-extensions-apkicon:${LAST_VERSION}")

// [仅 Android] 支持通过包名和版本号加载已安装 app 的图标
implementation("io.github.panpf.sketch4:sketch-extensions-appicon:${LAST_VERSION}")

// [仅 JVM] 支持使用 HttpURLConnection 访问网络图片
implementation("io.github.panpf.sketch4:sketch-http-hurl:${LAST_VERSION}")

// [仅 JVM] 支持使用 OkHttp 访问网络图片
implementation("io.github.panpf.sketch4:sketch-http-okhttp:${LAST_VERSION}")

// 支持使用 2.x 版本的 ktor 访问网络图片
implementation("io.github.panpf.sketch4:sketch-http-ktor2:${LAST_VERSION}")

// 支持使用 3.x 版本的 ktor 访问网络图片
implementation("io.github.panpf.sketch4:sketch-http-ktor3:${LAST_VERSION}")

// 支持 SVG 图片
implementation("io.github.panpf.sketch4:sketch-svg:${LAST_VERSION}")

// [仅 Android] 使用 Android 内置的 MediaMetadataRetriever 类实现解码视频帧
implementation("io.github.panpf.sketch4:sketch-video:${LAST_VERSION}")

// [仅 Android] 使用 wseemann 的 FFmpegMediaMetadataRetriever 库实现解码视频帧
implementation("io.github.panpf.sketch4:sketch-video-ffmpeg:${LAST_VERSION}")

Tip

sketch-compose、sketch-view 模块都依赖 sketch-singleton > 模块提供的单例，如果你不需要单例则可以直接依赖他们的 *-core 版本
sketch-http 模块在 jvm 平台上依赖 sketch-http-hurl，在非 jvm 平台上依赖 sketch-http-ktor3

注册组件

Sketch 支持自动发现并注册 Fetcher 和 Decoder 组件，在 jvm 平台通过 ServiceLoader 实现，在非 jvm 平台通过 @EagerInitialization 注解实现。

自带模块全部支持自动注册，如果你想禁用自动注册，采用手动注册的方式请参考文档：《注册组件》

R8 / Proguard

Sketch 自己不需要配置任何混淆规则，但你可能需要为间接依赖的 Kotlin Coroutines, OkHttp, Okio 添加混淆配置

快速上手

Compose Multiplatform：

// val imageUri = "/Users/my/Downloads/image.jpg"
// val imageUri = file:///compose_resource/composeResources/com.github.panpf.sketch.sample.resources/files/sample.png
val imageUri = "https://www.sample.com/image.jpg"

AsyncImage(
    uri = imageUri,
    contentDescription = "photo"
)

AsyncImage(
    uri = imageUri,
    state = rememberAsyncImageState(ComposableImageOptions {
        placeholder(Res.drawable.placeholder)
        error(Res.drawable.error)
        crossfade()
        // There is a lot more...
    }),
    contentDescription = "photo"
)

AsyncImage(
    rqeuest = ComposableImageRequest(imageUri) {
        placeholder(Res.drawable.placeholder)
        error(Res.drawable.error)
        crossfade()
        // There is a lot more...
    },
    contentDescription = "photo"
)

Image(
    painter = rememberAsyncImagePainter(
        request = ComposableImageRequest(imageUri) {
            placeholder(Res.drawable.placeholder)
            error(Res.drawable.error)
            crossfade()
            // There is a lot more...
        }
    ),
    contentDescription = "photo"
)

Tip

placeholder(Res.drawable.placeholder) 需要导入 sketch-compose-resources 模块

Android View：

// val imageUri = "/sdcard/download/image.jpg"
// val imageUri = "file:///android_asset/image.jpg"
// val imageUri = "content://media/external/images/media/88484"
val imageUri = "https://www.sample.com/image.jpg"

imageView.loadImage(imageUri)

imageView.loadImage(imageUri) {
    placeholder(R.drawable.placeholder)
    error(R.drawable.error)
    crossfade()
    // There is a lot more...
}

val request = ImageRequest(context, imageUri) {
    placeholder(R.drawable.placeholder)
    error(R.drawable.error)
    crossfade()
    target(imageView)
    // There is a lot more...
}
context.sketch.enqueue(request)

文档

基础功能：

开始使用
注册组件
Compose
Http：加载网络图片
AnimatedImage：GIF、WEBP、HEIF
Resize：修改图片尺寸
Transformation：转换图片
Transition：用炫酷的过渡方式显示图片
StateImage：占位图和错误图
Listener：监听请求状态和下载进度
DownloadCache：了解下载缓存，避免重复下载
ResultCache：了解结果缓存，避免重复转换
MemoryCache：了解内存缓存，避免重复加载
Fetcher：了解 Fetcher 及扩展新的 URI 类型
Decoder：了解 Sketch 的解码过程
Target：将加载结果应用到目标上
SVG：解码 SVG 静态图片
VideoFrames：解码视频帧
ExifOrientation：纠正图片方向
ImageOptions：统一管理图片配置
RequestInterceptor：拦截 ImageRequest
DecodeInterceptor：拦截解码过程
预加载图片到内存中
下载图片
Lifecycle
日志
迁移

特色功能：

SketchImageView：通过 XML 属性配置请求
提高长图在网格列表中的清晰度
显示下载进度
显示图片类型角标
蜂窝数据网络下暂停下载图片节省流量
列表滑动中暂停加载图片
显示 APK 文件或已安装 APP 的图标

更新日志

请查看 CHANGELOG.md 文件

测试平台

Android: Emulator; Arm64; API 21-34
Desktop: macOS; 14.6.1; JDK 17
iOS: iphone 16 simulator; iOS 18.1
Web: Chrome; 130

运行示例 App

准备环境：

Android Studio: Koala+ (2024.1.1+)
JDK: 17+
使用 kdoctor 检查运行环境，并按照提示安装需要的软件
Android Studio 安装 Kotlin Multiplatform 和 Compose Multiplatform IDE Support 插件

运行示例 App：

克隆项目并使用 Android Studio 打开
.run 目录下已经添加了各个平台的运行配置，同步完成后直接在 Android Studio 顶部运行配置下拉框中选择对应平台的运行配置然后点击运行即可
ios 平台的运行配置需要你根据模版手动创建，如下：
1. 拷贝 .run/iosSample.run.template.xml 文件，并去掉 .template 后缀，.ignore 文件中已经配置了忽略 iosSample.run.xml
2. 在顶部运行配置下拉框点击 Edit Configurations 选择 iosSample 然后配置 Execute target 即可

关于 4.0 版本

maven groupId 升级为 io.github.panpf.sketch4，因此 2.*、3.* 版本不会提示升级
4.0 版本专为 Compose Multiplatform 打造，所以 API 有很多破坏性改动，请谨慎升级
4.0 版本做了大量的简化，比 3.0 版本简单很多，详情请查看更新日志
Android 最低 API 升到了 API 21
Kotlin 版本升级到了 2.0.0

特别感谢

coil-kt/coil: Sketch 使用了来自 Coil 的部分代码，包括 framework、compose 以及 sketch-animated 的 movie 部分
koral--/android-gif-drawable: sketch-animated-koralgif
wseemann/FFmpegMediaMetadataRetriever: sketch-video-ffmpeg
BigBadaboom/androidsvg: sketch-svg

我的项目

以下是我的其它开源项目，感兴趣的可以了解一下：

zoomimage：用于缩放图片的库，支持 Compose Multiplatform 和 Android View；支持双击缩放、单指或双指手势缩放、单指拖动、惯性滑动、定位、旋转、超大图子采样等功能。
assembly-adapter：Android 上的一个为各种 Adapter 提供多类型 Item 实现的库。还顺带为 RecyclerView 提供了最强大的 divider。
sticky-item-decoration：RecyclerView 黏性 item 实现

License

Apache 2.0. 有关详细信息，请参阅 LICENSE 文件.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README_zh.md

README_zh.md

Sketch Image Loader

示例 App

安装

Compose Multiplatform:

Android View:

可选模块

注册组件

R8 / Proguard

快速上手

Compose Multiplatform：

Android View：

文档

更新日志

测试平台

运行示例 App

关于 4.0 版本

特别感谢

我的项目

License

Files

README_zh.md

Latest commit

History

README_zh.md

File metadata and controls

Sketch Image Loader

示例 App

安装

Compose Multiplatform:

Android View:

可选模块

注册组件

R8 / Proguard

快速上手

Compose Multiplatform：

Android View：

文档

更新日志

测试平台

运行示例 App

关于 4.0 版本

特别感谢

我的项目

License