Skip to content
项目

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

原文

logo_image ZoomImage

Platform Platform2 API License version_icon

翻译: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

下载

已发布到 mavenCentral

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

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")

文档

示例

你可以在 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

准备环境:

  1. Android Studio: Norwhal+ (2025.1.1+)
  2. JDK: 17+
  3. 使用 kdoctor 检查运行环境,并按照提示安装需要的软件
  4. Android Studio 安装 Kotlin Multiplatform 插件

运行示例 App:

  1. 克隆项目并使用 Android Studio 打开
  2. 同步完成后 Kotlin Multiplatform 插件会自动为各个平台创建运行配置
  3. 选择对应平台的运行配置,然后点击运行即可

我的项目

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

  • 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 文件.