SmoothRefreshLayout

简介:一个较为强大的下拉刷新加载库,支持多种模式。
更多:作者   提 Bug   
标签:
下拉刷新-加载更多-越界回弹-Nested Scroll-自定义View-加载-上拉加载-SwipeRefreshLayout-

English | 中文

一个高效的 Android 刷新库,理论上支持所有的视图,比官方的 SwipeRefreshLayout 更强大且使用方便.
本开源库的部分代码来自android-Ultra-Pull-To-Refresh.
非常感谢他提供的这么棒的开源项目!

特性:

  • 理论上支持所有的视图,且可根据具体需求高效适配.
  • 支持嵌套滑动,完整实现了 NestedScrollingChild,NestedScrollingParent 接口,玩转 CoordinatorLayout.
  • 直接继承自 ViewGroup,拥有卓越的性能,支持类 FameLayout 的特性(Gravity、Margin).
  • 支持自动刷新、自动上拉加载、到底自动加载更多(不推荐,建议使用 Adapter 实现,可自定义到底判断逻辑回调实现预加载更多).
  • 支持越界回弹.
  • 支持刷新视图自定样式,STYLE_DEFAULT(默认不改变大小)、STYLE_SCALE(动态改变大小,一直会重测量并布局,所以性能会有损失)、STYLE_PIN(不会改变视图大小,固定在顶部或者底部)、STYLE_FOLLOW_SCALE(先纵向跟随移动并且不改变视图大小,大于视图高度后动态改变视图大小且性能会有损失)、STYLE_FOLLOW_PIN(不会改变视图大小,先纵向跟随移动,大于视图高度后固定)、STYLE_FOLLOW_CENTER(不会改变视图大小,先纵向跟随移动,大于视图高度后让视图保持在移动的距离中心点).
  • 支持二级刷新事件(TwoLevelSmoothRefreshLayout),PS:淘宝二楼、京东活动.
  • 支持 ListView,GridView,RecyclerView 加载更多的平滑滚动.
  • 支持多状态视图,STATE_CONTENT(默认状态)、STATE_ERROR(异常状态),STATE_EMPTY(空状态),STATE_CUSTOM(自定义状态).
  • 丰富的回调接口和调试信息,可利用现有 Api 实现丰富的效果.

演示程序

下载 Demo.apk

更新日志

老版本升级务必查看

更新日志

快照

  • 测试 QQ 浏览器样式

  • 测试 QQ 活动样式

  • 测试 2 级刷新

  • 包含 FrameLayout

  • 包含 TextView

  • 包含 ListView

  • 包含 GridView

  • 包含 RecyclerView

  • 包含 ViewPager

  • 包含 WebView

  • CoordinatorLayout

  • 越界回弹模式

  • 测试嵌套滑动

使用

Gradle

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

dependencies {  
    compile 'com.github.dkzwm:SmoothRefreshLayout:1.4.8'
}

在 Xml 中配置

自 v1.4.1 版本后
<?xml version="1.0" encoding="utf-8"?>
<me.dkzwm.widget.srl.SmoothRefreshLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/smoothRefreshLayout"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>
</me.dkzwm.widget.srl.SmoothRefreshLayout>
v1.4.1 之前的版本
<?xml version="1.0" encoding="utf-8"?>
<me.dkzwm.smoothrefreshlayout.SmoothRefreshLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/smoothRefreshLayout"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>
</me.dkzwm.smoothrefreshlayout.SmoothRefreshLayout>

Java 代码配置

SmoothRefreshLayout refreshLayout = (SmoothRefreshLayout)findViewById(R.id.smoothRefreshLayout);
refreshLayout.setHeaderView(new ClassicHeader(this));
refreshLayout.setOnRefreshListener(new RefreshingListenerAdapter() {
    @Override
    public void onRefreshBegin(boolean isRefresh) {
        mHandler.postDelayed(new Runnable() {
            @Override
            public void run() {
                refreshLayout.refreshComplete();
            }
        }, 4000);
    }
});

自定义刷新视图

接口定义
public interface IRefreshView <T extends IIndicator> {    

    byte TYPE_HEADER = 0;
    byte TYPE_FOOTER = 1;

    byte STYLE_DEFAULT = 0;
    byte STYLE_SCALE = 1;

    /**
     * 返回是头部视图还是尾部视图;
     */
    int getType();

    /**
     * 一般情况都是 View 实现本接口,所以返回 this;
     */
    View getView();

    /**
     * 获取视图样式,自 1.4.8 版本后支持 6 种样式,STYLE_DEFAULT、STYLE_SCALE、STYLE_PIN、STYLE_FOLLOW_SCALE、STYLE_FOLLOW_PIN、STYLE_FOLLOW_CENTER;
     */
    int getStyle();

    /**
     * 获取视图的自定义高度,当视图样式为 STYLE_SCALE 和 STYLE_FOLLOW_SCALE 时,必须返回一个确切且大于 0 的值;
     */
    int getCustomHeight();

    /**
     * 手指离开屏幕;
     */
    void onFingerUp(SmoothRefreshLayout layout, T indicator);

    /**
     * 重置视图;
     */
    void onReset(SmoothRefreshLayout layout);

    /**
     * 重新配置视图,准备刷新;
     */
    void onRefreshPrepare(SmoothRefreshLayout layout);

    /**
     * 开始刷新;
     */
    void onRefreshBegin(SmoothRefreshLayout layout, T indicator);

    /**
     * 刷新完成;
     */
    void onRefreshComplete(SmoothRefreshLayout layout,boolean isSuccessful);

    /**
     * 当头部或者尾部视图发生位置变化;
     */
    void onRefreshPositionChanged(SmoothRefreshLayout layout, byte status, T indicator);

    /**
     * 当头部或者尾部视图仍然处于处理事务中,这时候移动其他刷新视图则会调用该方法;
     * 在 1.4.6 版本新加入;
     */
    void onPureScrollPositionChanged(SmoothRefreshLayout layout, byte status, T indicator);
}
添加自定义刷新视图
  • 全局静态代码构造
    ```

      SmoothRefreshLayout.setDefaultCreator(new IRefreshViewCreator() {
          @Override
          public void createHeader(SmoothRefreshLayout layout) {
              ClassicHeader header = new ClassicHeader(layout.getContext());
              layout.setHeaderView(header);
          }
    
          @Override
          public void createFooter(SmoothRefreshLayout layout) {
              ClassicFooter footer = new ClassicFooter(layout.getContext());
              layout.setFooterView(footer);
          }
      });
    

- 动态代码添加
setHeaderView(@NonNull IRefreshView header);
setFooterView(@NonNull IRefreshView footer);

```

  • 请直接写入 Xml 文件,SmoothRefreshLayout 会根据添加的 View 是否是实现了 IRefreshView 接口进行判断

Xml 属性

SmoothRefreshLayout 自身配置
名称 类型 描述
sr_content reference 指定内容视图的资源 ID
sr_resistance float 移动刷新视图时候的移动阻尼(默认:1.65f
sr_resistance_of_footer float 移动 Footer 视图时候的移动阻尼(默认:1.65f
sr_resistance_of_header float 移动 Header 视图时候的移动阻尼(默认:1.65f
sr_ratio_of_refresh_height_to_refresh float 触发刷新时位置占刷新视图的高度比(默认:1.1f
sr_ratio_of_header_height_to_refresh float 触发刷新时位置占 Header 视图的高度比(默认:1.1f
sr_ratio_of_footer_height_to_refresh float 触发加载更多时位置占 Footer 视图的高度比(默认:1.1f
sr_offset_ratio_to_keep_refresh_while_Loading float 刷新中保持视图位置占刷新视图的高度比(默认:1f),该属性的值必须小于等于触发刷新高度比才会有效果
sr_offset_ratio_to_keep_header_while_Loading float 刷新中保持视图位置占 Header 视图的高度比(默认:1f),该属性的值必须小于等于触发刷新高度比才会有效果
sr_offset_ratio_to_keep_footer_while_Loading float 刷新中保持视图位置占 Footer 视图的高度比(默认:1f),该属性的值必须小于等于触发刷新高度比才会有效果
sr_can_move_the_max_ratio_of_refresh_height float 最大移动距离占刷新视图的高度比(默认:0f,表示不会触发)
sr_can_move_the_max_ratio_of_header_height float 最大移动距离占 Header 视图的高度比(默认:0f,表示不会触发)
sr_can_move_the_max_ratio_of_footer_height float 最大移动距离占 Footer 视图的高度比(默认:0f,表示不会触发)
sr_duration_to_close_of_refresh integer 指定收缩刷新视图到起始位置的时长(默认:500
sr_duration_to_close_of_header integer 指定收缩 Header 视图到起始位置的时长(默认:500
sr_duration_to_close_of_footer integer 指定收缩 Footer 视图到起始位置的时长(默认:500
sr_duration_of_back_to_keep_refresh_pos integer 设置回滚到保持刷新视图位置的时间(默认:200
sr_duration_of_back_to_keep_header_pos integer 设置回滚到保持 Header 视图位置的时间(默认:200
sr_duration_of_back_to_keep_header_pos integer 设置回滚到保持 Footer 视图位置的时间(默认:200
sr_enable_pin_content boolean 固定内容视图(默认:false
sr_enable_keep_refresh_view boolean 刷新中保持视图停留在所设置的应该停留的位置(默认:true
sr_enable_pull_to_refresh boolean 拉动刷新,下拉或者上拉到触发刷新位置即立即触发刷新(默认:false
sr_enable_over_scroll boolean 越界回弹(默认:true),使用者需要自己设置内容视图的 overScrollModenever 才能达到最优效果
sr_empty_layout reference 指定空状态下对应的布局资源 ID
sr_error_layout reference 指定异常状态下对应的布局资源 ID
sr_custom_layout reference 指定自定义状态下对应的布局资源 ID
sr_state enum 状态设置 (默认:STATE_CONTENT
sr_enable_refresh boolean 设置是否启用下拉刷新(默认:ture
sr_enable_load_more boolean 设置是否启用加载更多(默认:false
TwoLevelSmoothRefreshLayout 自身配置
v1.4.5 之后的版本
名称 类型 描述
sr_enable_two_level_refresh boolean 设置是否启用二级刷新(默认:true
v1.4.5 之前的版本
名称 类型 描述
sr_enable_two_level_pull_to_refresh boolean 设置是否启用二级刷新(默认:true
SmoothRefreshLayout 包裹内部其他 View 支持配置
名称 类型 描述
layout_gravity flag 指定其它被包裹视图的对齐属性(非 targetView、非 refreshView)

SmoothRefreshLayout java 属性设置方法

名称 参数 描述
setHeaderView IRefreshView 配置头部视图
setFooterView IRefreshView 配置尾部视图
setContentView int,View 配置内容视图,参数 1:设置内容视图对应的状态,参数 2:状态对应的内容视图
setState int 配置当前状态
setState int,boolean 配置当前状态,参数 1:当前状态,参数 2:是否使用渐变动画过渡
setDisableWhenHorizontalMove boolean 内部视图含有横向滑动视图(例如 ViewPager)时需设置该属性为 ture(默认:false
setEnableNextPtrAtOnce boolean 刷新完成即可再次刷新
setOverScrollDurationRatio float 越界回弹时间比,当触发越界时得到的移动时长乘以该比例得到真实移动时长,该时长最大不超过mMaxOverScrollDuration的值(默认:0.5f).
setMaxOverScrollDuration int 设置越界回弹动画最长时间(默认:500
setMinOverScrollDuration int 设置越界回弹动画最短时间(默认:150
setResistance float 移动刷新视图时候的移动阻尼(默认:1.65f
setResistanceOfFooter float 移动 Footer 视图时候的移动阻尼(默认:1.65f
setResistanceOfHeader float 移动 Header 视图时候的移动阻尼(默认:1.65f
setRatioOfRefreshViewHeightToRefresh float 触发刷新时位置占刷新视图的高度比(默认:1.1f
setRatioOfHeaderHeightToRefresh float 触发刷新时位置占 Header 视图的高度比(默认:1.1f
setRatioOfFooterHeightToRefresh float 触发加载更多时位置占 Footer 视图的高度比(默认:1.1f
setOffsetRatioToKeepRefreshViewWhileLoading float 刷新中保持视图位置占刷新视图的高度比(默认:1f),该属性的值必须小于等于触发刷新高度比才会有效果
setOffsetRatioToKeepHeaderWhileLoading float 刷新中保持视图位置占 Header 视图的高度比(默认:1f),该属性的值必须小于等于触发刷新高度比才会有效果
setOffsetRatioToKeepFooterWhileLoading float 刷新中保持视图位置占 Footer 视图的高度比(默认:1f),该属性的值必须小于等于触发刷新高度比才会有效果
setCanMoveTheMaxRatioOfRefreshViewHeight float 最大移动距离占刷新视图的高度比(默认:0f,表示不会触发)
setCanMoveTheMaxRatioOfHeaderHeight float 最大移动距离占 Header 视图的高度比(默认:0f,表示不会触发)
setCanMoveTheMaxRatioOfFooterHeight float 最大移动距离占 Footer 视图的高度比(默认:0f,表示不会触发)
setDurationToClose int 指定收缩刷新视图到起始位置的时长(默认:500
setDurationToCloseHeader int 指定收缩 Header 视图到起始位置的时长(默认:500
setDurationToCloseFooter int 指定收缩 Footer 视图到起始位置的时长(默认:500
setDurationOfBackToKeepRefreshViewPosition integer 设置回滚到保持刷新视图位置的时间(默认:200
setDurationOfBackToKeepHeaderPosition integer 设置回滚到保持 Header 视图位置的时间(默认:200
setDurationOfBackToKeepFooterPosition integer 设置回滚到保持 Footer 视图位置的时间(默认:200
setEnablePinContentView boolean 固定内容视图(默认:false
setEnabledPullToRefresh boolean 拉动刷新,下拉或者上拉到触发刷新位置即立即触发刷新(默认:false
setEnableOverScroll boolean 越界回弹(默认:true),使用者需要自己设置内容视图的 overScrollModenever 才能达到最优效果
setEnabledInterceptEventWhileLoading boolean 刷新中拦截不响应触摸操作(默认:false
setEnableHeaderDrawerStyle boolean Header 抽屉样式,即 Header 视图在内容视图下面(默认:false
setEnableFooterDrawerStyle boolean Footer 抽屉样式,即 Footer 视图在内容视图下面(默认:false
setDisablePerformRefresh boolean 关闭触发 Header 刷新(默认:false
setDisablePerformLoadMore boolean 关闭触发 Footer 刷新(默认:false
setEnableLoadMoreNoMoreData boolean 设置 Footer 没有更多数据,该选项设置true时在 Frame 层等同setDisablePerformLoadMore设置为true,只是自定义视图可以根据该标志位改变视图样式,ClassicFooter默认实现了对该属性的支持(默认:false
setDisableRefresh boolean 禁用 Header 刷新(默认:false
setDisableLoadMore boolean 禁用 Footer 刷新(默认:false
setEnableKeepRefreshView boolean 刷新中保持视图停留在所设置的应该停留的位置(默认:true
setEnableScrollToBottomAutoLoadMore boolean 到底部自动加载(默认:false
setEnablePinRefreshViewWhileLoading boolean 固定刷新视图在所设置的应该停留的位置,并且不响应移动,即 Material 样式(默认:false),设置前提是开启了setEnablePinContentViewsetEnableKeepRefreshView2 个选项,否则运行时会抛出异常
setSpringInterpolator Interpolator 设置默认的滚动插值器
setOverScrollInterpolator Interpolator 设置越界回弹时的滚动插值器
setEnableCheckFingerInsideHorView boolean 设置是否开启检查手指按下点是否位于水平滚动视图内,该属性起作用必须满足开启setDisableWhenHorizontalMove

SmoothRefreshLayout 回调

名称 参数 描述
setOnRefreshListener T extends OnRefreshListener 设置刷新事件监听回调
setOnStateChangedListener OnStateChangedListener 设置状态改变回调
setChangeStateAnimatorCreator IChangeStateAnimatorCreator 设置改变状态时使用的动画创建者
addOnUIPositionChangedListener OnUIPositionChangedListener 添加视图位置变化的监听回调
removeOnUIPositionChangedListener OnUIPositionChangedListener 移除视图位置变化的监听回调
setOnLoadMoreScrollCallback OnLoadMoreScrollCallback 设置 Footer 完成刷新后进行平滑滚动的回调
setOnPerformAutoLoadMoreCallBack OnPerformAutoLoadMoreCallBack 设置触发自动加载更多的条件回调,如果回调的canAutoLoadMore()方法返回true则会立即触发加载更多
setOnChildScrollUpCallback OnChildScrollUpCallback 设置检查内容视图是否在顶部的重载回调(SmoothRefreshLayout 内部canChildScrollUp()方法)
setOnChildScrollDownCallback OnChildScrollDownCallback 设置检查内容视图是否在底部的重载回调(SmoothRefreshLayout 内部canChildScrollDown()方法)
setOnHookHeaderRefreshCompleteCallback OnHookUIRefreshCompleteCallBack 设置 Header 刷新完成的 Hook 回调,可实现延迟完成刷新
setOnHookFooterRefreshCompleteCallback OnHookUIRefreshCompleteCallBack 设置 Footer 刷新完成的 Hook 回调,可实现延迟完成刷新
setOnFingerInsideHorViewCallback OnFingerInsideHorViewCallback 设置检查手指按下点是否位于水平滚动视图内的重载回调,可自定义判断逻辑,提高判断效率

SmoothRefreshLayout 其它

名称 参数 描述
debug(静态方法) boolean Debug 开关
setDefaultCreator(静态方法) IRefreshViewCreator 设置刷新视图创建者,如果没有特殊指定刷新视图且设置的模式需要刷新视图则会调用创建者构建刷新视图
refreshComplete 无参 刷新完成,且设置最后一次刷新状态为成功
refreshComplete boolean 刷新完成,参数:设置最后一次刷新是否刷新成功
refreshComplete boolean,long 刷新完成,参数 1:设置最后一次刷新是否刷新成功,参数 2:设置延迟重置刷新状态的时间(会先触发刷新视图的刷新完成回调,但在延迟的时间内库实际上状态仍是刷新状态)
refreshComplete long 刷新完成,且设置最后一次刷新状态为成功,参数:设置延迟重置刷新状态的时间(会先触发刷新视图的刷新完成回调,但在延迟的时间内库实际上状态仍是刷新状态)
setLoadingMinTime long 设置开始刷新到结束刷新的最小时间差(默认:500),参数:时间差
autoRefresh 无参 自动触发 Header 刷新,立即触发刷新事件并滚动到触发 Header 刷新位置
autoRefresh boolean 自动触发 Header 刷新,参数:是否立即触发刷新事件,会滚动到触发 Header 刷新位置
autoRefresh boolean,boolean 自动触发 Header 刷新,参数 1:是否立即触发刷新事件,参数 2:是否滚动到触发 Header 刷新位置
autoLoadMore 无参 自动触发 Footer 刷新,立即触发刷新事件并滚动到触发 Footer 刷新位置
autoLoadMore boolean 自动触发 Footer 刷新,参数:是否立即触发刷新事件,会滚动到触发 Footer 刷新位置
autoLoadMore boolean,boolean 自动触发 Footer 刷新,参数 1:是否立即触发刷新事件,参数 2:是否滚动到触发 Footer 刷新位置
setLoadMoreScrollTargetView View 设置 Footer 移动时,响应移动事件的内容视图,例如在 SmoothRefreshLayout 中有一个 CoordinatorLayout,CoordinatorLayout 中有 AppbarLayout、RecyclerView 等,加载更多时希望被移动的视图为 RecyclerView 而不是 CoordinatorLayout,那么设置 RecyclerView 为 TargetView 即可

TwoLevelSmoothRefreshLayout java 属性设置方法

名称 参数 描述
setRatioOfHeaderHeightToHintTwoLevelRefresh float 设置触发二级刷新提示时的位置占 Header 视图的高度比
setRatioOfHeaderHeightToTwoLevelRefresh float 设置触发二级刷新时的位置占 Header 视图的高度比
setOffsetRatioToKeepTwoLevelHeaderWhileLoading float 二级刷新中保持视图位置占 Header 视图的高度比(默认:1f
setDisableTwoLevelRefresh boolean 设置是否关闭二级刷新(默认:false
setDurationOfBackToKeepTwoLevelHeaderViewPosition int 设置回滚到保持二级刷新 Header 视图位置的时间(默认:500
setDurationToCloseTwoLevelHeader int 设置二级刷新 Header 刷新完成回滚到起始位置的时间(默认:500

TwoLevelSmoothRefreshLayout 其它

名称 参数 描述
autoTwoLevelRefreshHint 无参 自动触发二级刷新提示并滚动到触发提示位置后回滚回起始位置
autoTwoLevelRefreshHint int 自动触发二级刷新提示并滚动到触发提示位置后停留指定时长,参数:停留多长时间
autoTwoLevelRefreshHint boolean 自动触发二级刷新提示是否滚动到触发提示位置后回滚回起始位置,参数:是否滚到到触发位置
autoTwoLevelRefreshHint boolean,int 自动触发二级刷新提示,参数 1:是否滚动到触发位置,参数 2:停留多长时间
autoTwoLevelRefreshHint boolean,int,boolean 自动触发二级刷新提示,参数 1:是否滚动到触发位置,参数 2:停留多长时间,参数 3:是否可以被触摸打断,即触发提示动作过程中拦截触摸事件,直到回滚到起始位置并重置为默认状态

Thanks

License

MIT License

Copyright (c) 2017 dkzwm
Copyright (c) 2015 liaohuqiu.net

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Android 开发经验分享
C 轮融资近 30 亿元理财推荐
Android 开发经验分享
C 轮融资近 30 亿元理财推荐