panpf/zoomimage
panpf/zoomimage has 659 GitHub stars and 38 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 23:45 UTC. Last push 2026-09-28.
实测星标增长
- 24小时
- 0
- 7天
- 更新延迟
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Image zoom library specially designed for Compose Multiplatform and Android View. Supported scale, pan, locate, rotation, and super-large image subsampling.
开发工具README.zh.md
原文
ZoomImage
翻译:English
ZoomImage 是一个专为 Compose Multiplatform 和 Android View 设计的手势缩放查看图片的库,它有以下特点和功能:
Compose Multiplatform. 支持 Android、iOS、macOS Native、JVM 桌面端和 Web 等平台功能齐全. 支持双击缩放、双指缩放、单指缩放、鼠标滚轮缩放、键盘缩放、单指拖动、惯性滑动、键盘拖动等基础功能定位. 支持定位到图片的任意位置并保持在屏幕中央旋转. 支持 0°, 90°, 180°, 270°, 360° 旋转图片子采样. 支持对超大图进行子采样显示,避免 OOM,碎片支持动画以及清晰度渐变动态缩放比例. 根据图片尺寸和容器尺寸自动计算出最合适的双击缩放比例缩放阻尼. 手动缩放超过最大或最小缩放比例后会有带阻尼感的橡皮筋效果滚动条. 支持显示水平和垂直滚动条,明确当前滚动位置阅读模式. 阅读模式下显示长图时初始状态会自动充满屏幕,用户可立即开始阅读图片内容,省去用户双击放大的操作Exif. 支持读取 Exif Orientation 信息并自动旋转图片图片加载器. 提供对 sketch、coil、glide、picasso 等图片加载器的支持,也可以自定义支持更多图片加载器
https://github.com/panpf/zoomimage/assets/3250512/f067bed9-24e4-4ab8-a839-0731e155f4ef
多平台支持
| 功能/平台 | Android | iOS | macOS Native | JVM | Web |
|---|---|---|---|---|---|
| 缩放 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 子采样 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Exif Orientation | ✅ | ✅ | ✅ | ✅ | ✅ |
| 集成 Sketch | ✅ | ✅ | ✅ | ✅ | ✅ |
| 集成 Coil | ✅ | ✅ | ✅ | ✅ | ✅ |
| 集成 Glide | ✅ | ❌ | ❌ | ❌ | ❌ |
| 集成 Picasso | ✅ | ❌ | ❌ | ❌ | ❌ |
示例 App
- Android、iOS、桌面版、Web 可部署包请到 Releases 页面下载最新版本
- Web 示例:https://panpf.github.io/zoomimage/app
下载
已发布到 mavenCentral
Compose multiplatform:
// 集成 Sketch v4+ 单例模式,提供 SketchZoomAsyncImage 组件(推荐使用)
implementation("io.github.panpf.zoomimage:zoomimage-compose-sketch4:${LAST_VERSION}")
// 集成 Sketch v4+ koin 模式,提供 SketchZoomAsyncImage 组件(推荐使用)
implementation("io.github.panpf.zoomimage:zoomimage-compose-sketch4-koin:${LAST_VERSION}")
// 集成 Sketch v4+ core,提供 SketchZoomAsyncImage 组件(推荐使用)
implementation("io.github.panpf.zoomimage:zoomimage-compose-sketch4-core:${LAST_VERSION}")
// 集成 Sketch v3 单例模式,提供 SketchZoomAsyncImage 组件
implementation("io.github.panpf.zoomimage:zoomimage-compose-sketch3:${LAST_VERSION}")
// 集成 Sketch v3 core,提供 SketchZoomAsyncImage 组件
implementation("io.github.panpf.zoomimage:zoomimage-compose-sketch3-core:${LAST_VERSION}")
// 集成 Coil v3+ 单例模式,提供 CoilZoomAsyncImage 组件
implementation("io.github.panpf.zoomimage:zoomimage-compose-coil3:${LAST_VERSION}")
// 集成 Coil v3+ core,提供 CoilZoomAsyncImage 组件
implementation("io.github.panpf.zoomimage:zoomimage-compose-coil3-core:${LAST_VERSION}")
// 集成 Coil v2 单例模式,提供 CoilZoomAsyncImage 组件
implementation("io.github.panpf.zoomimage:zoomimage-compose-coil2:${LAST_VERSION}")
// 集成 Coil v2 core,提供 CoilZoomAsyncImage 组件
implementation("io.github.panpf.zoomimage:zoomimage-compose-coil2-core:${LAST_VERSION}")
// 提供基础的 ZoomImage 组件,不支持网络图片
implementation("io.github.panpf.zoomimage:zoomimage-compose:${LAST_VERSION}")
// 支持从 composeResources 文件夹下加载图片
implementation("io.github.panpf.zoomimage:zoomimage-compose-resources:${LAST_VERSION}")
[!TIP] 根据你用的图片加载器或需求任选其一即可
Only android compose:
// 集成 Glide,提供 GlideZoomAsyncImage 组件
implementation("io.github.panpf.zoomimage:zoomimage-compose-glide:${LAST_VERSION}")
[!TIP] 为什么没有 picasso 版本的 compose ZoomImage 组件?因为 Picasso 官方已经说明不会提供对 compose 的支持(原文在此)
Android view:
// 集成 Sketch v4+ 单例模式,提供 SketchZoomImageView 组件(推荐使用)
implementation("io.github.panpf.zoomimage:zoomimage-view-sketch4:${LAST_VERSION}")
// 集成 Sketch v4+ koin 模式,提供 SketchZoomImageView 组件(推荐使用)
implementation("io.github.panpf.zoomimage:zoomimage-view-sketch4-koin:${LAST_VERSION}")
// 集成 Sketch v4+ core,提供 SketchZoomImageView 组件(推荐使用)
implementation("io.github.panpf.zoomimage:zoomimage-view-sketch4-core:${LAST_VERSION}")
// 集成 Sketch v3 单例模式,提供 SketchZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-sketch3:${LAST_VERSION}")
// 集成 Sketch v3 core,提供 SketchZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-sketch3-core:${LAST_VERSION}")
// 集成 Coil v3+ 单例模式,提供 CoilZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-coil3:${LAST_VERSION}")
// 集成 Coil v3+ core,提供 CoilZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-coil3-core:${LAST_VERSION}")
// 集成 Coil v2 单例模式,提供 CoilZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-coil2:${LAST_VERSION}")
// 集成 Coil v2 core,提供 CoilZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-coil2-core:${LAST_VERSION}")
// 集成 Glide,提供 GlideZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-glide:${LAST_VERSION}")
// 集成 Picasso,提供 PicassoZoomImageView 组件
implementation("io.github.panpf.zoomimage:zoomimage-view-picasso:${LAST_VERSION}")
// 提供基础的 ZoomImageView 组件,不支持网络图片
implementation("io.github.panpf.zoomimage:zoomimage-view:${LAST_VERSION}")
[!TIP] 根据你用的图片加载器或需求任选其一即可
R8 / Proguard
ZoomImage 自己的混淆已经包含在了 aar 中,但你可能还需要为间接依赖的其它库添加混淆配置
快速上手
Compose multiplatform:
// 使用基础的 ZoomImage 组件
val zoomState: ZoomState by rememberZoomState()
val imageSource = remember {
val resUri = Res.getUri("files/huge_world.jpeg")
ImageSource.fromComposeResource(resUri)
}
zoomState.setSubsamplingImage(imageSource)
ZoomImage(
painter = painterResource(Res.drawable.huge_world_thumbnail),
contentDescription = "view image",
modifier = Modifier.fillMaxSize(),
zoomState = zoomState,
)
// 使用 SketchZoomAsyncImage 组件
SketchZoomAsyncImage(
uri = "https://sample.com/sample.jpeg",
contentDescription = "view image",
modifier = Modifier.fillMaxSize(),
)
// 使用 CoilZoomAsyncImage 组件
CoilZoomAsyncImage(
model = "https://sample.com/sample.jpeg",
contentDescription = "view image",
modifier = Modifier.fillMaxSize(),
)
[!TIP] SketchZoomAsyncImage 和 CoilZoomAsyncImage 的用法和它们原本的 AsyncImage 一样,只是多了一个
zoomState: ZoomState参数
Only android compose:
// 使用 GlideZoomAsyncImage 组件
GlideZoomAsyncImage(
model = "https://sample.com/sample.jpeg",
contentDescription = "view image",
modifier = Modifier.fillMaxSize(),
)
[!TIP] GlideZoomAsyncImage 的用法和它原本的 GlideImage 一样,只是多了一个
zoomState: ZoomState参数
Android view:
// 使用基础的 ZoomImageView 组件
val zoomImageView = ZoomImageView(context)
zoomImageView.setImageResource(R.drawable.huge_world_thumbnail)
zoomImageView.setSubsamplingImage(ImageSource.fromResource(R.raw.huge_world))
// 使用 SketchZoomAsyncImage 组件
val sketchZoomImageView = SketchZoomImageView(context)
sketchZoomImageView.loadImage("https://sample.com/sample.jpeg")
// 使用 CoilZoomImageView 组件
val coilZoomImageView = CoilZoomImageView(context)
sketchZoomImageView.loadImage("https://sample.com/sample.jpeg")
// 使用 GlideZoomImageView 组件
val glideZoomImageView = GlideZoomImageView(context)
Glide.with(this@GlideZoomImageViewFragment)
.load("https://sample.com/sample.jpeg")
.into(glideZoomImageView)
// 使用 PicassoZoomImageView 组件
val picassoZoomImageView = PicassoZoomImageView(context)
picassoZoomImageView.loadImage("https://sample.com/sample.jpeg")
文档
- 开始使用
- Scale: 缩放图片以查看更清晰的细节
- Offset: 移动图片以查看容器之外的内容
- Rotate: 旋转图片以不同角度查看内容
- Locate: 定位到图片的任意位置
- Keep Transform: 切换图像时保持变换状态
- Read Mode: 长图初始时充满屏幕方便阅读
- Click: 接收点击事件
- Subsampling: 通过子采样的方式显示大图避免 OOM
- Scroll Bar: 显示水平和垂直滚动条
- Log: 修改日志等级以及输出管道
- Modifier.zoom()
示例
你可以在 examples 目录下找到示例代码,也可以到 release 页面下载 App 体验
更新日志
请查看 CHANGELOG 文件
测试平台
- Android: Emulator; Arm64; API 21-34
- JVM: macOS 26; JDK 17
- iOS: iPhone 16 Simulator; iOS 18.1
- macOS Native: Apple Silicon; macOS 26
- Web: Chrome; 130
运行示例 App
准备环境:
- Android Studio: Norwhal+ (2025.1.1+)
- JDK: 17+
- 使用 kdoctor 检查运行环境,并按照提示安装需要的软件
- Android Studio 安装
Kotlin Multiplatform插件
运行示例 App:
- 克隆项目并使用 Android Studio 打开
- 同步完成后
Kotlin Multiplatform插件会自动为各个平台创建运行配置 - 选择对应平台的运行配置,然后点击运行即可
我的项目
以下是我的其它开源项目,感兴趣的可以了解一下:
- sketch:Sketch 是一个为 Compose Multiplatform 和 Android View 设计的图像加载库。它功能强大且丰富,除了基本功能外,还支持GIF、SVG、视频缩略图、Exif Orientation 等。
- assembly-adapter:Android 上的一个为各种 Adapter 提供多类型 Item 实现的库。还顺带为 RecyclerView 提供了最强大的 divider。
- sticky-item-decoration:RecyclerView 黏性 item 实现
License
Apache 2.0. 有关详细信息,请参阅 LICENSE 文件.