BigImageViewPager 详解：支持超大图、长图与视频的 Android 图片预览库

在社交、电商、相册类 App 里，点开一张图进入可双指缩放的全屏预览几乎是标配。自己从零实现，要处理长图 OOM、手势缩放、原图下载进度、与图片加载框架衔接等一连串细节。BigImageViewPager（作者 SherlockGougou）把这些打包成一个开箱即用的 Android 预览库，支持超大图、超长图、GIF 甚至视频。本文从依赖、Glide 配置、启动 API 到模块拆分，讲清怎么用。

1、项目概述

典型场景：

- 社交、电商、相册类 App 的图片全屏预览

- 原图查看与下载、加载进度展示

- 图文详情页里的多图左右切换与缩放

- 需要混排图片与视频的媒体浏览页

2、核心特性

它的能力覆盖了图片预览最常见的几个痛点。

功能列表：

- 超大图、超长图、GIF、视频预览

- 双指缩放、双击缩放、平移、左右滑动切换

- 原图查看、下载，以及加载进度监听

- 视频播放策略：仅 WiFi 自动播放、始终自动播放、手动播放

- 数据源动态更新与删除

- 区块复用加载（block-reuse），降低内存、规避 OOM

3、依赖与图片引擎

当前版本 androidx-9.2.2，依赖分为核心库（图片能力）与可选视频插件两部分。图片引擎绑定 Glide（4.16.0），通过 OkHttp 接入加载进度。

// 必选：核心库（图片能力）
implementation "com.gouqinglin:BigImageViewPager:androidx-9.2.2"

// 可选：视频插件（需要视频预览时再加）
implementation "com.gouqinglin:BigImageViewPager-media3:androidx-9.2.2"

// 必选：Glide 及其 OkHttp 集成（用于加载进度）
def glideVersion = "4.16.0"
implementation "com.github.bumptech.glide:glide:$glideVersion"
annotationProcessor "com.github.bumptech.glide:compiler:$glideVersion"
implementation "com.github.bumptech.glide:okhttp3-integration:$glideVersion"

引入要点：

1. 核心库坐标为 com.gouqinglin:BigImageViewPager:androidx-9.2.2

2. 需要视频预览时再加 BigImageViewPager-media3 同版本

3. Glide 4.16.0 与 okhttp3-integration 是必选项，后者用于进度监听

4. Kotlin 工程可把 annotationProcessor 改为 kapt

4、关键配置：GlideModule 与加载进度

想看到"原图加载进度"，必须自定义 GlideModule，把默认 HTTP 加载器换成 ProgressManager 提供的 OkHttp 客户端。否则官方明确警告：原图加载进度可能长期停在 1%。

@GlideModule
public class MyAppGlideModule extends AppGlideModule {
    @Override
    public void registerComponents(Context context, Glide glide, Registry registry) {
        super.registerComponents(context, glide, registry);
        // 替换为 ProgressManager 的 OkHttp，否则原图进度可能长期停在 1%
        registry.replace(GlideUrl.class, InputStream.class,
                new OkHttpUrlLoader.Factory(ProgressManager.getOkHttpClient()));
    }
}

配置要点：

1. 新增一个继承 AppGlideModule 的类，并加上 @GlideModule 注解

2. 在 registerComponents 里 replace GlideUrl 到 InputStream 的 Loader

3. 替换后的 Loader 用 OkHttpUrlLoader.Factory(ProgressManager.getOkHttpClient())

4. 该配置同时让 Glide 统一走 OkHttp 网络栈

5、启动预览：ImagePreview 与视频策略

配置完成后，用 ImagePreview 的一串链式调用即可拉起全屏预览，并能按需设置视频播放策略。

// 基础预览：传入图片 / 视频数据后启动
ImagePreview.getInstance()
        .setContext(MainActivity.this)
        .setMediaInfoList(imageInfoList)
        .start();

// 视频播放策略：仅在 WiFi 下自动播放
ImagePreview.getInstance()
        .setContext(MainActivity.this)
        .setMediaInfoList(imageInfoList)
        .setVideoPlayPolicy(ImagePreview.VideoPlayPolicy.WiFiOnly)
        .start();

启动要点：

1. ImagePreview.getInstance() 取单例，链式设置参数后 start() 启动

2. setContext 传当前 Activity，setMediaInfoList 传图片 / 视频数据集合

3. 三种视频播放策略：WiFiOnly、WiFiAndMobile（默认）、Manual

4. 纯图片场景无需设置视频策略，直接 start() 即可

6、模块拆分与版本演进

自 androidx-9.2.0 起，视频能力被拆成可选插件，核心库回归"只做图片"。

模块划分：

- 核心库 BigImageViewPager：仅图片预览

- 视频插件 BigImageViewPager-media3：基于 Media3 / ExoPlayer

降级策略：

- 未引入视频插件时，视频项优雅降级为"不可用"提示，不影响图片预览

- 引入插件后视频能力自动启用，无需额外初始化

- 关闭预览页会释放视频运行时资源，再次进入重建缓存与播放会话

近期版本要点：

- androidx-9.2.2：新增 VideoPlayPolicy 视频播放策略

- androidx-9.2.1：修复视频 Fragment 回收后只剩声音的 bug

- androidx-9.2.0：把 ExoPlayer / Media3 改为可选依赖

- androidx-8.4.7：支持 32 位 16KB page size；8.4.5 支持自定义请求头

7、使用建议与注意事项

使用建议：

- 务必配置 GlideModule，否则原图加载进度会停在 1%

- 下载 / 保存原图需自备存储权限并刷新相册

- 视频预览按场景选播放策略，省流量优先 WiFiOnly

- 不需要视频就只引核心库，减小包体

注意事项：

- 图片引擎绑定 Glide，非 Glide 项目接入成本相对较高

- 超大 / 超长图仍需留意内存峰值，善用其区块复用机制

- 版本号采用 androidx-X.Y.Z 命名，升级时关注 CHANGELOG

- minSdk 与混淆规则按文档及实际依赖补充

8、总结

BigImageViewPager 是一个开箱即用的 Android 图片 / 视频预览库，支持超大图、超长图、GIF 与视频，提供双指缩放、原图下载进度、视频播放策略与区块复用加载。它绑定 Glide 作为图片引擎，通过自定义 GlideModule 接入加载进度；自 9.2.0 起把视频拆为可选的 Media3 插件，核心库回归纯图片，未启用视频时优雅降级。

对于需要图片预览的 App，引入核心库与 Glide、配置好 GlideModule，用 ImagePreview 一行链式调用拉起预览，并按需启用视频插件与播放策略，同时留意保存权限与大图内存，是快速实现专业级图片预览的必要方案。

BigImageViewPager 详解：支持超大图、长图与视频的 Android 图片预览库