BigImageViewPager

Introduction: 🔥🔥🔥 BigImage ImageView ViewPager 支持超长图、超大图的图片浏览器,优化内存,支持手势放大、下拉关闭、查看原图、加载百分比、保存图片等功能。现已支持 androidx。
More: Author   ReportBugs   OfficialWebsite   
Tags:

BigImage + ImageView + ViewPager = BigImageViewPager

一个图片浏览器,支持超大图、超长图、支持手势放大、支持查看原图、下载、加载百分比进度显示。采用区块复用加载,优化内存占用,有效避免 OOM。支持手势下拉退出。

注意:本框架支持网络图片、本地图片、支持 gif 动图、支持 Android 12。

后续可能会仅维护 androidx 版本,support 请尽快迁移到 androidx。参考官方迁移文档:https://developer.android.google.cn/jetpack/androidx/migrate

框架特性

  • 支持网络图片、本地图片;
  • 支持 https 图片;
  • 支持缩放比例、缩放动画时间的设置;
  • 支持手势下拉关闭;
  • 支持多种加载策略:(仅普清、仅原图、手动模式、网络自适应)
  • 支持多种类型图片(超大图、超长图、超宽图、小图、gif 动图)
  • 支持查看原图,支持查看原图时百分比进度的展示;
  • 看图体验优化:长图拉到屏幕宽度显示、宽图双击放大到屏幕高度显示、gif 图放大到屏幕宽度显示;
  • 自动根据 Exif 信息旋转图片进行显示;
  • 支持图片的下载,可设置保存到的路径(默认在存储根目录新建文件夹)
  • 支持多种界面的自定义(具体可查看 Demo)
  • 支持加载失败时占位图的设置;
  • 针对保存图片进行优化,文件扩展名使用文件头部 Mime 信息进行设置,不用担心 gif 保存成 jpeg;
  • 支持自定义查看原图时的百分比 View;
  • 支持 BMP 格式的图片;
  • 支持 Android 12;
  • 支持自定义预览界面;
  • 支持平板等横屏设备显示;

用法

一、添加依赖

Step 1. 在你 project 层级的 build.gradle 中,添加仓库地址:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Step 2. 在你主 module 的 build.gradle 中添加依赖:

此处显示的是本框架的最新版本号:
⚠️注意:glide v3 版本不再维护,最终版本为 v3_4.0.2。建议使用 androidx 版本。
androidx 用户  :   使用  androidx-7.0.4
对于 glide4.x  :   使用        v4_6.1.3
dependencies {

  // ① 针对 androidx 用户,需要添加以下依赖:

  // glide
  implementation 'com.github.bumptech.glide:glide:4.11.0'
  annotationProcessor 'com.github.bumptech.glide:compiler:4.11.0'
  implementation 'com.github.bumptech.glide:okhttp3-integration:4.11.0'
  // BigImageViewPager https://github.com/SherlockGougou/BigImageViewPager
  implementation 'com.github.SherlockGougou:BigImageViewPager:androidx-7.0.4'

================================分割线==================================

  // ② 针对 glide v4 版本【建议项目尽快迁移到 androix,后续此库的 support 版本会停更】,需要添加以下依赖:

  // glide
  implementation 'com.github.bumptech.glide:glide:4.9.0'
  annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
  implementation 'com.github.bumptech.glide:okhttp3-integration:4.9.0'
  // BigImageViewPager https://github.com/SherlockGougou/BigImageViewPager
  implementation 'com.github.SherlockGougou:BigImageViewPager:v4_6.1.3'

================================分割线==================================
}

Step 3. 在你的主 module 里,添加自定义 AppGlideModule。你需要继承 AppGlideModule 并添加以下代码到对应的重载方法中,例如:

@GlideModule
public class MyAppGlideModule extends AppGlideModule {
  @Override
  public void registerComponents(@NonNull Context context, @NonNull Glide glide, @NonNull Registry registry) {
    super.registerComponents(context, glide, registry);

    // 替换底层网络框架为 okhttp3,这步很重要!如果不添加会无法正常显示原图的加载百分比,或者卡在 1%
    // 如果你的 app 中已经存在了自定义的 GlideModule,你只需要把这一行代码,添加到对应的重载方法中即可。
    registry.replace(GlideUrl.class, InputStream.class, new OkHttpUrlLoader.Factory(ProgressManager.getOkHttpClient()));
  }
}

Step 4. 以上操作完成后,请点击顶部按钮:Build->Rebuild Project,等待重建完成,至此,框架添加完成。如遇到任何问题,请附带截图提 issues,我会及时回复,或添加底部 QQ 群,进行交流。

二、调用方式

1:生成图片源:(如果你有缩略图和原图两种路径,请使用下面的方式,进行图片 List 的生成;如果你是本地图片或者没有原图缩略图之分,可以跳过这一步)

        ImageInfo imageInfo;
        final List<ImageInfo> imageInfoList = new ArrayList<>();
        for (String image : images) {
            imageInfo = new ImageInfo();
            imageInfo.setOriginUrl(url);// 原图 url
            imageInfo.setThumbnailUrl(thumbUrl);// 缩略图 url
            imageInfoList.add(imageInfo);
        }

2:最简单的调用方式:

        // 最简单的调用,即可实现大部分需求,如需定制,可参考下一步的自定义代码:

        ImagePreview
            .getInstance()
            // 上下文,必须是 activity,不需要担心内存泄漏,本框架已经处理好;
            .setContext(MainActivity.this)

            // 设置从第几张开始看(索引从 0 开始)
            .setIndex(0)

            //=================================================================================================
            // 有三种设置数据集合的方式,根据自己的需求进行三选一:
            // 1:第一步生成的 imageInfo List
            .setImageInfoList(imageInfoList)

            // 2:直接传 url List
            //.setImageList(List<String> imageList)

            // 3:只有一张图片的情况,可以直接传入这张图片的 url
            //.setImage(String image)
            //=================================================================================================

            // 开启预览
            .start();

            // 默认配置为:
            //      显示顶部进度指示器、
            //      显示右侧下载按钮、
            //      隐藏关闭按钮、
            //      开启点击图片关闭、
            //      开启下拉图片关闭、
            //      加载策略为全自动
接口说明:
方法名 功能 说明
setBigImageClickListener 设置图片点击事件 默认 null
setBigImageLongClickListener 设置图片长按事件 默认 null
setBigImagePageChangeListener 设置页面切换监听 默认 null
setDownloadClickListener 设置点击下载监听 默认 null,可选是否拦截下载行为
setCloseIconResId 设置关闭按钮的 Drawable 资源 id 默认内置 R.drawable.ic_action_close
setContext 设置上下文 不允许为空
setDownIconResId 设置下载按钮的 Drawable 资源 id R.drawable.icon_download_new
setEnableClickClose 设置是否开启点击图片退出 默认 true
setEnableDragClose 设置是否开启下拉图片退出 默认 true
setEnableUpDragClose 设置是否开启上拉图片退出 默认 false
setEnableDragCloseIgnoreScale 是否忽略缩放启用拉动关闭 默认 true
setErrorPlaceHolder 设置加载失败的占位图资源 id 默认内置 R.drawable.load_failed
setFolderName 设置下载到的文件夹名称 默认保存 Picture 文件夹中
setImage 设置单张图片地址 三选一
setImageInfoList 设置图片 Bean 集合 三选一
setImageList 设置图片地址集合 三选一
setIndex 设置开始的索引 从 0 开始
setLoadStrategy 设置加载策略 详见加载策略说明
setOnOriginProgressListener 设置原图加载进度回调 加载原图的百分比进度
setProgressLayoutId 自定义百分比布局 详细见 demo
setShowCloseButton 设置是否显示关闭按钮 默认 false,不显示
setShowDownButton 设置是否显示下载按钮 默认 true,显示
setShowIndicator 设置是否显示顶部的进度指示器 默认 true,显示
setIndicatorShapeResId 设置顶部指示器背景 shape 默认自带灰色圆角 shape,设置为 0 时不显示背景
setShowErrorToast 设置是否显示加载失败的 Toast 默认 false,不显示
setZoomTransitionDuration 设置图片缩放动画时长 默认 200ms
setPreviewLayoutResId 设置自定义的预览页面布局 id 默认 R.layout.sh_layout_preview
start 开启看图 最后调用
3:自定义多种配置:

请参考 Demo:https://github.com/SherlockGougou/BigImageViewPager/blob/androidx/sample/src/main/java/cc/shinichi/bigimageviewpager/MainActivity.java#L289

4:加载策略介绍
  public enum LoadStrategy {
    /**
     * 仅加载原图;会强制隐藏查看原图按钮
     */
    AlwaysOrigin,

    /**
     * 仅加载普清;会强制隐藏查看原图按钮
     */
    AlwaysThumb,

    /**
     * 根据网络自适应加载,WiFi 原图,流量普清;会强制隐藏查看原图按钮
     */
    NetworkAuto,

    /**
     * 手动模式:默认普清,点击按钮再加载原图;会根据原图、缩略图 url 是否一样来判断是否显示查看原图按钮
     */
    Default

    /**
     * 全自动模式:WiFi 原图,流量下默认普清,可点击按钮查看原图
     */
    Auto
  }

  注:以上所有方式,如果原图缓存存在的情况,会默认加载原图缓存保证清晰度;且原图缓存只要存在,就不会显示查看原图按钮。
5:自定义百分比 View

详细操作请参考 Demo:https://raw.githubusercontent.com/SherlockGougou/BigImageViewPager/master/sample/src/main/java/cc/shinichi/bigimageviewpager/MainActivity.java#L291

6:Q&A

1.查看原图卡在 1%? 答:请仔细查看以上第三步的操作。

推荐扫描二维码进行安装体验:

GitHub 源码

https://github.com/SherlockGougou/BigImageViewPager

致谢

Bug 反馈、增加需求,加 QQ 交流群

LICENSE

Copyright (C) 2018 SherlockGougou qinglingou@gmail.com

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Apps
About Me
GitHub: Trinea
Facebook: Dev Tools