阅读 1317

Android paging3 使用和踩坑经验分享

前言

Android 列表分页加载组件 paging3 alpha版本已经出来很久了。目前到了alpha7; 分享一下在项目中使用的经验和坑;不讲原理和源码,纯使用经验分享! (不要问我为啥把alpha版本用在项目中,问就是任性,问就是paging2太难用了)

准备工作

1.依赖:

本文撰写日期:2020-10-21;最新版为3.0.0-alpha07

//java
implementation 'androidx.paging:paging-runtime:3.0.0-alpha07'
//kotlin
implementation 'androidx.paging:paging-runtime-ktx:3.0.0-alpha07'
复制代码

根据语言二选一即可,我使用的是kotlin;

使用:

1.adapter

使用paging3 ,RecyclerView的adapter 必须继承 PagingDataAdapter 因为后续分页的UI和操作都归于 adapter 管理;

adpater 构造必须传参数 DiffUtil.ItemCallback ; 用过 AsyncListDiffer 的小伙伴应该明白它的作用; 不明白的可以参考一下这篇文章:Android AsyncListDiffer-RecyclerView最好的伙伴

DiffUtil.ItemCallback 简单介绍:

DiffUtil.ItemCallback的作用就是取代notifyDataSetChanged粗暴刷新列表的; 毕竟粗暴刷新比较消耗性能;

主要介绍三个方法:

override fun areItemsTheSame(oldItem: T, newItem: T): Boolean {}

override fun areContentsTheSame(oldItem: T, newItem: T): Boolean {}

override fun getChangePayload(oldItem: T, newItem: T): Any? {}
复制代码

paging3的设计理念是不建议对列表数据直接修改;而是对数据源进行操作,数据源的变化会自动更新到列表;
DiffUtil.ItemCallback 就是用来比对数据变化,从而决定更新对应UI;并执行条目动画;

  • areItemsTheSame

比对新旧条目是否是同一个条目; 一般比对条目的唯一标示id即可,谨慎对待,如果条目不同则可能不会更新UI;

  • areContentsTheSame

当上面的方法确定是同一个条目之后,这里比对条目的内容是否一样,不一样则会更新条目UI ;
建议这里的比对把UI展示的数据都写上,写漏了会导致UI不更新对应字段;

  • getChangePayload (可选)

这个方法对应 RcyclerView的 adapter的 第三个参数;用于条目内部的局部刷新;

override fun onBindViewHolder(
        holder: RecyclerView.ViewHolder,
        position: Int,
        payloads: MutableList<Any>
    )
复制代码

2.数据请求处理

这里利用知乎日报的接口作为范例: 没有使用到paging3的数据库缓存方案 remoteMediator;因为参数被注解为
@OptIn(ExperimentalPagingApi::class)还在测试中;这里讲解纯网络请求分页方案;
实际项目中,不可能每个列表接口都做数据库缓存的,工作量太大;

paging3 数据请求主要用到3个类:

  1. Pager
  2. PagingConfig
  3. PagingSource
  • Pager 分页数据的主要入口,这是它的构造:
class Pager<Key : Any, Value : Any>
@JvmOverloads constructor(
    config: PagingConfig,
    initialKey: Key? = null,
    @OptIn(ExperimentalPagingApi::class)
    remoteMediator: RemoteMediator<Key, Value>? = null,
    pagingSourceFactory: () -> PagingSource<Key, Value>
)
复制代码

它的泛型 Key -> 分页标志 ,类似于页码,或者其它告诉后端我要哪一页的参数;
Value -> 列表数据的单个数据类型,就是每个条目的类型;

参数解释: config :分页配置,见下面介绍
initialKey : 初始页的页码 (可选)
remoteMediator :远程数据解调员;网络请求数据后处理的类,可以做数据缓存
pagingSourceFactory:数据源工厂(每次刷新数据都会生产新的数据源)

  • PagingConfig 介绍

Pager的第一个参数:config: PagingConfig 分页逻辑:每页多少条之类的设置;
构造:

class PagingConfig @JvmOverloads constructor(
	val pageSize: Int,
	@IntRange(from = 0)
    val prefetchDistance: Int = pageSize,
	val enablePlaceholders: Boolean = true,
	@IntRange(from = 1)
    val initialLoadSize: Int = pageSize*DEFAULT_INITIAL_PAGE_MULTIPLIER,
	val maxSize: Int = MAX_SIZE_UNBOUNDED,
	val jumpThreshold: Int = COUNT_UNDEFINED
)
复制代码

参数解释: pageSize:每页多少个条目;必填
prefetchDistance :预加载下一页的距离,滑动到倒数第几个条目就加载下一页,无缝加载(可选)默认值是pageSize
enablePlaceholders:是否启用条目占位,当条目总数量确定的时候;列表一次性展示所有条目,但是没有数据;在adapter的 onBindViewHolder里面绑定数据时候,是空数据,判断是空数据展示对应的占位item;可选,默认开启。
initialLoadSize :第一页加载条目数量 ,可选,默认值是 3*pageSize (有时候需要第一页多点数据可用)
maxSize :定义列表最大数量;可选,默认值是:Int.MAX_VALUE
jumpThreshold:暂时还不知道用法,从文档注释上看,是滚动大距离导致加载失效的阈值;可选,默认值是:Int.MIN_VALUE (表示禁用此功能)

  • PagingSource 分页数据源

pagingSourceFactory 工厂生产的产品;

abstract class PagingSource<Key : Any, Value : Any> {
	abstract suspend fun load(params: LoadParams<Key>): LoadResult<Key, Value>
}
复制代码

泛型同 Pager 泛型,要实现的主要方法就一个:比paging2方便了不知道多少倍

参数解释: params :请求列表需要的参数
返回值:
LoadResult :列表数据请求结果,包含下一页要请求的key

用法范例:

val allNews = Pager(PagingConfig(20), initialKey = initialKey) {
            object : PagingSource<Long, News.StoriesBean>() {
                override suspend fun load(params: LoadParams<Long>): LoadResult<Long, News.StoriesBean> {
                    val date = params.key ?: initialKey
                    return try {
                        val data = api.getNews(date).await() //网络请求数据
                        LoadResult.Page(data.stories, null, data.date.toLong())
                    } catch (e: Exception) {
                        LoadResult.Error(e)
                    }
                }
            }
        }
            .flow
            .cachedIn(viewModelScope)
            .asLiveData(viewModelScope.coroutineContext)
复制代码

LoadResult.Page 解释:

constructor(
                data: List<Value>,
                prevKey: Key?,
                nextKey: Key?
            )
复制代码

参数: data :返回的数据列表
prevKey :上一页的key (传 null 表示没有上一页)
nextKey :下一页的key (传 null 表示没有下一页)

paging3 使用 flow 传递数据,不了解的可以搜索一下flow ;
cachedIn 绑定协程生命周期,必须加上,否则可能崩溃;
asLiveData 熟悉livedata的都知道怎么用;

绑定数据给adapter

model.allNews.observe(this@ZhiHuActivity, Observer {
            lifecycleScope.launchWhenCreated {
                adapter.submitData(it)
            }
        })
复制代码

adapter.submitData 是一个协程挂起(suspend)操作,所以要放入协程赋值;
lifecycleScope.launchWhenCreated 和 viewModelScope;
需要依赖协程的生命周期辅助,见下面:

//生命周期辅助ktx
implementation 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.3.0-beta01'
implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.3.0-beta01'
implementation 'androidx.lifecycle:lifecycle-livedata-ktx:2.3.0-beta01'
复制代码

3.UI状态处理和操作

下拉刷新

第一次请求不需要任何操作,订阅数据直接请求;
手动下拉刷新直接调用:

adapter.refresh()
复制代码

就是这么简单,比paging2方便多了

上拉加载

paging3是无缝加载,实际没有手动上拉的操作
但是用户滑动过快的话还是会展示上拉的UI,下面会有UI的处理逻辑

失败重试

adapter.retry()
复制代码

主要用于加载更多的重试。

UI状态处理

adapter.addLoadStateListener :添加状态监听:

adapter.addLoadStateListener {
            when (it.refresh) {
                is LoadState.Loading -> {}
                is LoadState.NotLoading -> {}
                is LoadState.Error -> {}
            }
        }
复制代码

状态返回的参数 CombinedLoadStates,包含了
refresh,prepend,append,source,mediator 五种行为的状态
分别是:
刷新,向前加载更多,向后加载更多,数据源,调解员

每个行为分为3中状态:

  • LoadState.Loading 加载中 (加载数据时候回调)
  • LoadState.NotLoading 没有加载中 (加载数据前和加载数据完成后回调)
  • LoadState.Error 加载失败 (加载数据失败回调)

我们一般业务只关注 刷新和向后加载更多;

以SmartRefreshLayout为例:

下拉刷新状态处理:

//因为刷新前也会调用LoadState.NotLoading,所以用一个外部变量判断是否是刷新后
var hasRefreshing = false
adapter.addLoadStateListener {
    when (it.refresh) {
        is LoadState.Loading -> {
            hasRefreshing = true
            //如果是手动下拉刷新,则不展示loading页
            if (srl_refresh.state != RefreshState.Refreshing) {
                statePager.showLoading()
            }
        }
        is LoadState.NotLoading -> {
            if (hasRefreshing) {
				hasRefreshing= false
				statePager.showContent()
                srl_refresh.finishRefresh(true)
                //如果第一页数据就没有更多了,第一页不会触发append
                if (it.source.append.endOfPaginationReached){
                    //没有更多了(只能用source的append)
                    srl_refresh.finishLoadMoreWithNoMoreData()
                }
            }
        }
        is LoadState.Error -> {
			statePager.showError()
            srl_refresh.finishRefresh(false)
        }
    }
}
复制代码

上拉加载更多状态处理:

//因为刷新前也会调用LoadState.NotLoading,所以用一个外部变量判断是否是加载更多后
var hasLoadingMore = false
adapter.addLoadStateListener {
    when (it.append) {
        is LoadState.Loading -> {
            hasLoadingMore = true
            //重置上拉加载状态,显示加载loading
            srl_refresh.resetNoMoreData()
        }
        is LoadState.NotLoading -> {
            if (hasLoadingMore) {
                hasLoadingMore = false
                if (it.source.append.endOfPaginationReached){
                    //没有更多了(只能用source的append)
                    srl_refresh.finishLoadMoreWithNoMoreData()
                }else{
                    srl_refresh.finishLoadMore(true)
                }
            }
        }
        is LoadState.Error -> {
            srl_refresh.finishLoadMore(false)
        }
    }
}
复制代码

上面代码就是刷新和加载更多状态监听了,有一个问题:
第一页数据如果没有更多了,是不会触发 append 的 LoadState.Loading 状态,所以得在refresh里面判断一下;

刷新失败处理:

直接调用刷新即可

adapter.refresh()
复制代码

加载更多失败处理:

srl_refresh.setOnLoadMoreListener { 
    adapter.retry()
}
复制代码

为什么是重试?
因为paging是无缝加载,所以没有手动上拉加载逻辑
retry()虽然是重试,但是paging已处理,只有失败后会重试,所以这里上拉加载调用重试没问题

关于Header和 Footer

PagingDataAdapter 是支持 添加Header和Footer 的

adapter.withLoadStateHeader(header: LoadStateAdapter<*>)
adapter.withLoadStateFooter(header: LoadStateAdapter<*>)
adapter.withLoadStateHeaderAndFooter(header: LoadStateAdapter<*>,
        footer: LoadStateAdapter<*>)
复制代码

LoadStateAdapter : 也是一个 RecyclerView.Adapter ;
类似于多条目布局,只是分成多个adapter
谷歌出过一个 MergeAdapter,就是把多个RecyclerView.Adapter 合并成一个,
有兴趣的小伙伴可以搜索一下。这里就不介绍了;

本文范例地址:

github