Base RecyclerView Adapter Helper

https://github.com/cymchad/baserecyclerviewadapterhelper
Admin
A powerful and flexible RecyclerView Adapter for Android that simplifies RecyclerView usage,...
Tokens:138,522
Snippets:1,007
Trust Score:7.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Lambda-based usage example

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Shows how to chain the extension functions with lambda callbacks. The example sets drag start/end to call `beginVisual` and `endVisual`, and swipe end to call `deleteRow`.

```kotlin
quickDragAndSwipe
    .setItemDragListener(
        onItemDragStart = { holder, pos -> beginVisual(holder) },
        onItemDragEnd = { holder, pos -> endVisual(holder) }
    )
    .setItemSwipeListener(
        onItemSwiped = { holder, direction, pos -> deleteRow(pos) }
    )
```

--------------------------------

### Driving Pagination State

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example of how to drive pagination state using the trailingLoadState property.

```APIDOC
## Driving Pagination State

### Description
Example of how to drive pagination state using the trailingLoadState property.

### Example

```kotlin
helper.trailingLoadState = LoadState.Loading            // request started
helper.trailingLoadState = LoadState.NotLoading(false)  // more pages remain
helper.trailingLoadState = LoadState.NotLoading(true)   // pagination finished
helper.trailingLoadState = LoadState.Error(e)           // request failed
```
```

--------------------------------

### DiffUtilAdapter constructor example

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example of a differ-backed adapter using the DiffUtil.ItemCallback constructor. Passes a DiffEntityCallback to enable async differ-backed submitList.

```java
public class DiffUtilAdapter extends BaseQuickAdapter<DiffEntity, DiffUtilAdapter.VH> {
    public DiffUtilAdapter() {
        super(new DiffEntityCallback()); // DiffUtil.ItemCallback<T> constructor
    }
}
```

--------------------------------

### onBindViewHolder example from UpFetchAdapter.kt

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example implementation of onBindViewHolder from UpFetchAdapter.kt. Sets different images based on layoutPosition modulo 3.

```kotlin
override fun onBindViewHolder(holder: VH, position: Int, item: Movie?) {
    when (holder.layoutPosition % 3) {
        0 -> holder.viewBinding.iv.setImageResource(R.mipmap.animation_img1)
        1 -> holder.viewBinding.iv.setImageResource(R.mipmap.animation_img2)
        2 -> holder.viewBinding.iv.setImageResource(R.mipmap.animation_img3)
    }
}
```

--------------------------------

### add usage examples

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Shows how to prepend an item at position 0 and append an item. The append variant uses mutableItems.add() for null-safety.

```kotlin
adapter.add(0, newItem)     // prepend
adapter.add(newItem)        // append, null-safety via mutableItems.add()
```

--------------------------------

### removeAdapter usage example

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Adds a FooterAdapter and removes it when clicked, demonstrating self-removal of a footer adapter.

```kotlin
helper.addAfterAdapter(FooterAdapter(true).setOnItemClickListener { adapter, _, _ ->
    helper.removeAdapter(adapter)   // remove this footer when clicked
})
```

--------------------------------

### startItemAnimator

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Open hook to start an item animator. Override to customize animation behavior.

```APIDOC
## startItemAnimator

### Description
Open hook to start an item animator. Override to customize animation behavior.

### Method
`protected open fun startItemAnimator(anim: Animator, holder: RecyclerView.ViewHolder)`

### Parameters
- `anim` (Animator) - Required - The animator to start
- `holder` (RecyclerView.ViewHolder) - Required - The ViewHolder associated with the animation

### Default Behavior
Calls `anim.start()`.
```

--------------------------------

### addBeforeAdapter usage example

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Typical usage from HeaderAndFooterUseActivity.kt: inserts a HeaderAdapter at index 0 and sets a click listener that calls addHeader().

```kotlin
helper.addBeforeAdapter(0, HeaderAdapter().apply {
    setOnItemClickListener { _, _, _ -> addHeader() }
})
```

--------------------------------

### submitList usage example

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Shows how to call submitList with a new list and a commit callback. The callback is invoked after the diff is committed or the list is replaced.

```kotlin
adapter.submitList(newItems) {
    // diff committed / list replaced
}
```

--------------------------------

### submitList usage examples

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Two call variants: one with default clearOpenStates (false) and one with clearOpenStates = true and a commit callback.

```kotlin
adapter.submitList(newRoots)
```

```kotlin
adapter.submitList(newRoots, clearOpenStates = true) { /* committed */ }
```

--------------------------------

### checkDisableLoadMoreIfNotFullPage example

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example usage of checkDisableLoadMoreIfNotFullPage on the trailingLoadStateAdapter. Call after submitting data to the adapter to disable load more if the list does not fill the page.

```kotlin
mAdapter.submitList(data)
helper.trailingLoadStateAdapter?.checkDisableLoadMoreIfNotFullPage()
```

--------------------------------

### Calling asStaggeredGridFullSpan in onViewAttachedToWindow

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example of calling asStaggeredGridFullSpan inside an overridden onViewAttachedToWindow.

```kotlin
holder.asStaggeredGridFullSpan()   // e.g. inside an overridden onViewAttachedToWindow
```

--------------------------------

### startSwipe(holder) / startSwipe(position)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Programmatically starts a swipe operation. Otherwise same semantics as startDrag.

```APIDOC
## startSwipe(holder) / startSwipe(position)

### Description
Programmatically starts a swipe operation. Otherwise same semantics as startDrag.

### Method
startSwipe

### Signature
`open fun startSwipe(...) = apply`

### Parameters
- **holder** (RecyclerView.ViewHolder) - Required - The view holder to start swiping.
- **position** (Int) - Required - The adapter position to start swiping.

### Returns
Returns the QuickDragAndSwipe instance for chaining.
```

--------------------------------

### Implement FullSpanAdapterType in adapter

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Recommended setup: implement the marker interface or isFullSpanItem, and assign QuickGridLayoutManager. The first adapter shows a header adapter; the second shows a full-span item adapter.

```kotlin
class HeaderAdapter : BaseQuickAdapter<Status, QuickViewHolder>() {
    override fun onCreateViewHolder(context: Context, parent: ViewGroup, viewType: Int): QuickViewHolder =
        QuickViewHolder(R.layout.head_view, parent)

    override fun onBindViewHolder(holder: QuickViewHolder, position: Int, item: Status?) { /* ... */ }
}

// marker interface -> every item of this adapter spans full width:
class FullSpanItemAdapter : BaseQuickAdapter<Item, VH>(), FullSpanAdapterType { /* ... */ }
```

--------------------------------

### ScaleInAnimation

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Constructor for the ScaleInAnimation class. Configures a scale-in animation with optional duration and start scale.

```APIDOC
## ScaleInAnimation

### Description
Constructor for the ScaleInAnimation class. Configures a scale-in animation with optional duration and start scale.

### Parameters
#### Constructor Parameters
- `duration` (Long) - Optional - Scale duration (ms). Default: `300`
- `mFrom` (Float) - Optional - Start scale. Default: `0.5f`

### Notes
- All constructors are `@JvmOverloads`.
- Interpolator: default for ScaleIn.
```

--------------------------------

### AlphaInAnimation

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Constructor for the AlphaInAnimation class. Configures a fade-in animation with optional duration and start alpha.

```APIDOC
## AlphaInAnimation

### Description
Constructor for the AlphaInAnimation class. Configures a fade-in animation with optional duration and start alpha.

### Parameters
#### Constructor Parameters
- `duration` (Long) - Optional - Fade duration (ms). Default: `300`
- `mFrom` (Float) - Optional - Start alpha. Default: `0f`

### Notes
- All constructors are `@JvmOverloads`.
- Interpolator: `LinearInterpolator`.
```

--------------------------------

### items

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Gets the current adapter data. The setter is deprecated and writing to it is a compile error; use submitList() instead.

```APIDOC
## items

### Description
Gets the current adapter data. The setter is deprecated and writing to it is a compile error; use submitList() instead.

### Property
`items`

### Type
`List<T>`

### Default
—

### Accessor
Getter returns `mDiffer?.currentList ?: _items`. From Java the accessor is `getItems()`.

### Deprecation
Setter is `@Deprecated(level = DeprecationLevel.ERROR)` — writing it is a **compile error**; use `submitList()` instead.
```

--------------------------------

### Using getItemView inside a custom adapter

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example usage of getItemView to inflate an item layout and create a ViewHolder.

```kotlin
// inside a custom adapter:
val itemView = parent.getItemView(R.layout.my_item)
return VH(itemView)
```

--------------------------------

### removeAt usage example

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Shows how to catch IndexOutOfBoundsException when removing a non-existent position. The comment notes that position 99 does not exist because items.size is less than 99.

```kotlin
try {
    adapter.removeAt(99)
} catch (e: IndexOutOfBoundsException) {
    // position 99 does not exist; items.size < 99
}
```

--------------------------------

### DataBindingAdapter usage with DataBindingHolder

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example adapter extending BaseQuickAdapter with DataBindingHolder. onCreateViewHolder creates a holder from a layout resource; onBindViewHolder sets the movie item and executes pending bindings.

```java
public class DataBindingAdapter extends BaseQuickAdapter<Movie, DataBindingHolder<ItemMovieBinding>> {
    @Override
    protected DataBindingHolder<ItemMovieBinding> onCreateViewHolder(@NonNull Context context, @NonNull ViewGroup parent, int viewType) {
        return new DataBindingHolder<>(R.layout.item_movie, parent);
    }

    @Override
    protected void onBindViewHolder(@NonNull DataBindingHolder<ItemMovieBinding> holder, int position, Movie item) {
        holder.getBinding().setMovie(item).executePendingBindings();
    }
}
```

--------------------------------

### QuickAdapterHelper.Builder.build()

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Creates the QuickAdapterHelper instance.

```APIDOC
## build()

### Description
Creates the QuickAdapterHelper instance.

### Method
build

### Returns
QuickAdapterHelper - The built helper.
```

--------------------------------

### DragAndSwipeAdapter using QuickViewHolder

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example adapter from DragAndSwipeAdapter.java. Overrides onCreateViewHolder to create QuickViewHolder from a layout resource and onBindViewHolder to set image resources and text based on layout position.

```java
public class DragAndSwipeAdapter extends BaseQuickAdapter<String, QuickViewHolder> {
    @Override
    protected QuickViewHolder onCreateViewHolder(@NonNull Context context, @NonNull ViewGroup parent, int viewType) {
        return new QuickViewHolder(R.layout.item_draggable_view, parent);
    }

    @Override
    protected void onBindViewHolder(@NonNull QuickViewHolder holder, int position, String item) {
        switch (holder.getLayoutPosition() % 3) {
            case 0 -> holder.setImageResource(R.id.iv_head, R.mipmap.head_img0);
            case 1 -> holder.setImageResource(R.id.iv_head, R.mipmap.head_img1);
            case 2 -> holder.setImageResource(R.id.iv_head, R.mipmap.head_img2);
        }
        holder.setText(R.id.tv, item);
    }
}
```

--------------------------------

### Typical wiring with QuickAdapterHelper and LoadState

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Builds a QuickAdapterHelper with a trailing load state adapter, assigns its adapter to a RecyclerView, and drives pagination by setting trailingLoadState to Loading, NotLoading(false) for more pages, NotLoading(true) for end, or Error(e) for failure.

```kotlin
val helper = QuickAdapterHelper.Builder(contentAdapter)
    .setTrailingLoadStateAdapter(object : OnTrailingListener {
        override fun onLoad() { loadNextPage() }
        override fun onFailRetry() { loadNextPage() }
    })
    .build()
recyclerView.adapter = helper.adapter

helper.trailingLoadState = LoadState.Loading
helper.trailingLoadState = LoadState.NotLoading(false)   // more pages
helper.trailingLoadState = LoadState.NotLoading(true)    // end
helper.trailingLoadState = LoadState.Error(e)            // failure
```

--------------------------------

### startItemAnimator(anim, holder)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Overrides the start hook for item animations. Allows custom behavior when an item animation starts, such as blocking taps during animation.

```APIDOC
## startItemAnimator(anim, holder)

### Description
Overrides the start hook for item animations. Allows custom behavior when an item animation starts, such as blocking taps during animation.

### Method
startItemAnimator

### Parameters
- **anim** (Animator) - Required - The animator to start.
- **holder** (RecyclerView.ViewHolder) - Required - The view holder for the item being animated.

### Example
```kotlin
override fun startItemAnimator(anim: Animator, holder: RecyclerView.ViewHolder) {
    anim.addListener(object : AnimatorListenerAdapter() {
        override fun onAnimationStart(animation: Animator) {
            holder.itemView.isEnabled = false   // block taps while animating
        }
        override fun onAnimationEnd(animation: Animator) {
            holder.itemView.isEnabled = true
        }
    })
    anim.start()
}
```
```

--------------------------------

### Basic build with trailing load state adapter

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Builds a QuickAdapterHelper with a trailing load state adapter for load more, sets preload size to 0 and auto load more enabled, then attaches to RecyclerView.

```kotlin
helper = QuickAdapterHelper.Builder(mAdapter)
    .setTrailingLoadStateAdapter(object : OnTrailingListener {
        override fun onLoad() { request() }
        override fun onFailRetry() { request() }
        override fun isAllowLoading(): Boolean = !viewBinding.refreshLayout.isRefreshing
    })
    .setTrailPreloadSize(0)          // preload distance from the tail (default 0)
    .isTrailAutoLoadMore(true)       // auto load more (default true)
    .build()
viewBinding.rvList.adapter = helper.adapter
```

--------------------------------

### Observing load state transitions

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example of adding a load state listener to react to Loading and Error states. The listener receives the previous and current LoadState and can show a spinner or error message.

```kotlin
adapter.addLoadStateListener { previous, current ->
    when (current) {
        is LoadState.Loading -> showSpinner()
        is LoadState.Error -> showError(current.error)
        else -> {}
    }
}
```

--------------------------------

### 配置自定义加载更多适配器

Source: https://github.com/cymchad/baserecyclerviewadapterhelper/wiki/尾部加载更多（向下加载更多）

实例化自定义的加载更多类，设置 OnTrailingListener 监听器，并通过 QuickAdapterHelper.Builder 将其应用到适配器中。

```kotlin
// 实例化自定义"加载更多"的类
val loadMoreAdapter = CustomLoadMoreAdapter()
loadMoreAdapter.setOnLoadMoreListener(object : OnTrailingListener {
    override fun onLoad() {
        // 执行加载更多的操作，通常都是网络请求
    }

    override fun onFailRetry() {
        // 加载失败后，点击重试的操作，通常都是网络请求
    }

    override fun isAllowLoading(): Boolean {
        // 是否允许触发“加载更多”，通常情况下，下拉刷新的时候不允许进行加载更多
        return !viewBinding.refreshLayout.isRefreshing
    }
})

helper = QuickAdapterHelper.Builder(mAdapter)
    .setTrailingLoadStateAdapter(loadMoreAdapter) // 传递自定义的“加载跟多”
    .build()

...
```

--------------------------------

### OnItemSwipeListener interface (Java)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Defines callbacks for swipe operations: start, end, swiped, and moving. The onItemSwipeEnd KDoc notes that if you change the view on start, you should reset it here, regardless of whether the item was swiped; if swiped, pos will be negative.

```java
public interface OnItemSwipeListener {
    void onItemSwipeStart(@Nullable RecyclerView.ViewHolder viewHolder, int bindingAdapterPosition);
    void onItemSwipeEnd(@NonNull RecyclerView.ViewHolder viewHolder, int bindingAdapterPosition);
    void onItemSwiped(@NonNull RecyclerView.ViewHolder viewHolder, int direction, int bindingAdapterPosition);
    void onItemSwipeMoving(@NonNull Canvas canvas, @NonNull RecyclerView.ViewHolder viewHolder,
                           float dX, float dY, boolean isCurrentlyActive);
}
```

--------------------------------

### AlphaInAnimation constructor

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Built-in animation that fades in by animating alpha from a configurable start to 1f. Uses LinearInterpolator, default duration 300 ms, default start alpha 0f. Constructor is @JvmOverloads so Java sees one-argument and no-argument forms.

```kotlin
class AlphaInAnimation @JvmOverloads constructor(
    private val duration: Long = 300,
    private val mFrom: Float = DEFAULT_ALPHA_FROM   // 0f
) : ItemAnimator
```

--------------------------------

### Up-fetch build with leading load state adapter

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Builds a QuickAdapterHelper with a leading load state adapter for up-fetch, sets preload size to 0, then attaches to RecyclerView.

```kotlin
helper = QuickAdapterHelper.Builder(mAdapter)
    .setLeadingLoadStateAdapter(object : OnLeadingListener {
        override fun onLoad() { requestUoFetch() }
        override fun isAllowLoading(): Boolean = true
    })
    .setLeadPreloadSize(0)
    .build()
viewBinding.rv.adapter = helper.adapter
```

--------------------------------

### context

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Gets the context from the attached RecyclerView.

```APIDOC
## context

### Description
Gets the context from the attached RecyclerView.

### Property
`context`

### Type
`Context`

### Default
—

### Value
`recyclerView.context`
```

--------------------------------

### QuickDragAndSwipe.dataCallback

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Gets the data callback. Throws IllegalStateException if not set.

```APIDOC
## QuickDragAndSwipe.dataCallback

### Description
Gets the data callback. Throws IllegalStateException if not set.

### Method
dataCallback

### Returns
- **DragAndSwipeDataCallback** - The data callback.

### Exceptions
- **IllegalStateException** - If the data callback has not been set.

### Example
```kotlin
try {
    val cb = quickDragAndSwipe.dataCallback
} catch (e: IllegalStateException) {
    // "Please set _adapterImpl" — call setDataCallback(...) first
}
```
```

--------------------------------

### 基础使用：创建 Adapter 和配置尾部加载更多

Source: https://github.com/cymchad/baserecyclerviewadapterhelper/wiki/尾部加载更多（向下加载更多）

第一步创建 adapter，第二步通过 QuickAdapterHelper.Builder 设置默认样式的尾部加载更多，并实现 OnTrailingListener 的三个方法：onLoad 执行加载更多的操作（通常是网络请求），onFailRetry 在加载失败后点击重试执行操作，isAllowLoading 控制是否允许触发加载更多（例如下拉刷新时不允许）。第三步需将 helper.adapter（ConcatAdapter）设置给 RecyclerView，而非 mAdapter。

```kotlin
// 第一步，创建 adapter
val mAdapter = RecyclerViewAdapter()


// 第二部，使用 Builder 创建 QuickAdapterHelper 对象，这里需要传入你的 mAdapter
val helper = QuickAdapterHelper.Builder(mAdapter)
    // 使用默认样式的尾部"加载更多"
    .setTrailingLoadStateAdapter(object : OnTrailingListener {
        override fun onLoad() {
            // 执行加载更多的操作，通常都是网络请求
            request()
        }

        override fun onFailRetry() {
            // 加载失败后，点击重试的操作，通常都是网络请求
            request()
        }

        override fun isAllowLoading(): Boolean {
            // 是否允许触发“加载更多”，通常情况下，下拉刷新的时候不允许进行加载更多
            return !viewBinding.refreshLayout.isRefreshing
        }
}).build()

/**
* 第三步，给 RecyclerView 设置 Adapter，
* 注意：这个adapter不是前面创建的 mAdapter，而是 helper 所提供的 adapter（ConcatAdapter）
*/
recyclerView.adapter = helper.adapter
```

```kotlin
if (isFirstPage) {
    // 如果是加载的第一页数据，用 submitList()
    // If it is the first page of data loaded, use submitList().
    mAdapter.submitList(list)
} else {
    //不是第一页，则用add
    mAdapter.addAll(list)
}

if(page >= MAX_PAGE) {
    // 没有分页数据了
    /*
    Set the status to not loaded, and there is no paging data.
    设置状态为未加载，并且没有分页数据了
    */
    helper.trailingLoadState = LoadState.NotLoading(true)
    Tips.show("no more data")
} else {
    // 后续还有分页数据
    /*
    Set the state to not loaded, and there is also paginated data
    设置状态为未加载，并且还有分页数据
    */
    helper.trailingLoadState = LoadState.NotLoading(false)
}
```

--------------------------------

### ScaleInAnimation constructor

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Built-in animation that scales scaleX and scaleY from a configurable start to 1f in parallel (AnimatorSet.play(scaleX).with(scaleY)). Uses DecelerateInterpolator, default duration 300 ms, default start scale 0.5f. Constructor is @JvmOverloads so Java sees one-argument and no-argument forms.

```kotlin
class ScaleInAnimation @JvmOverloads constructor(
    private val duration: Long = 300,
    private val mFrom: Float = DEFAULT_SCALE_FROM   // .5f
) : ItemAnimator
```

--------------------------------

### QuickAdapterHelper.Builder.attachTo(recyclerView)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Builds the helper and assigns recyclerView.adapter = helper.adapter.

```APIDOC
## attachTo(recyclerView)

### Description
Builds the helper and assigns recyclerView.adapter = helper.adapter.

### Method
attachTo

### Parameters
- **recyclerView** (RecyclerView) - Required - The RecyclerView to attach the adapter to.

### Returns
QuickAdapterHelper - The built helper.
```

--------------------------------

### Set trailing load state for pagination

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Use these assignments to drive pagination state through the helper's trailingLoadState property. Each line corresponds to a different state: loading, more pages available, pagination finished, or an error.

```kotlin
helper.trailingLoadState = LoadState.Loading            // request started
helper.trailingLoadState = LoadState.NotLoading(false)  // more pages remain
helper.trailingLoadState = LoadState.NotLoading(true)   // pagination finished
helper.trailingLoadState = LoadState.Error(e)           // request failed
```

--------------------------------

### recyclerView

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Gets the attached RecyclerView. Throws IllegalStateException if accessed before onAttachedToRecyclerView.

```APIDOC
## recyclerView

### Description
Gets the attached RecyclerView. Throws IllegalStateException if accessed before onAttachedToRecyclerView.

### Property
`recyclerView`

### Type
`RecyclerView`

### Default
—

### Exceptions
Throws `IllegalStateException` with message `"Please get it after onAttachedToRecyclerView()"` if accessed before `onAttachedToRecyclerView`.
```

--------------------------------

### BaseQuickAdapter Constructor

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Creates a BaseQuickAdapter with an initial data set and optional async differ configuration. The primary constructor accepts a list of items and an optional AsyncDifferConfig; when no differ is configured, submitList and mutators operate directly on the backing list.

```APIDOC
## BaseQuickAdapter Constructor

### Description
Creates a BaseQuickAdapter with an initial data set and optional async differ configuration.

### Parameters
- `items` (List<T>) - Optional - Initial data set. Default: `emptyList()`
- `config` (AsyncDifferConfig<T>?) - Optional - Differ config; non-null enables async diffing for `submitList`. Default: `null`
- `diffCallback` (DiffUtil.ItemCallback<T>) - Optional - Convenience: wraps in `AsyncDifferConfig.Builder(diffCallback).build()`

### Example
```kotlin
implementation("io.github.cymchad:BaseRecyclerViewAdapterHelper4:4.4.2")
```
```

--------------------------------

### Both debounced helpers in ItemClickActivity

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example usage of both setOnDebouncedItemClick and addOnDebouncedChildClick together, as shown in ItemClickActivity.kt.

```kotlin
adapter.setOnDebouncedItemClick { adapter, view, position ->
    Tips.show("onItemClick $position")
}
adapter.addOnDebouncedChildClick(R.id.btn) { adapter, view, position ->
    Tips.show("onItemChildClick: $position")
}
```

--------------------------------

### Layout produced by QuickAdapterHelper

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

ASCII diagram showing the ConcatAdapter layout with leading load state adapter or before adapter, content adapter, and trailing load state adapter or after adapter.

```text
                          ConcatAdapter
|-----------------------------------------------------------------|
|        leadingLoadStateAdapter 或者 BeforeAdapter               |
|-----------------------------------------------------------------|
|                        contentAdapter（内容）                    |
|-----------------------------------------------------------------|
|        trailingLoadStateAdapter 或者 AfterAdapter               |
|-----------------------------------------------------------------|
```

--------------------------------

### ScaleInAnimation

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Scales an item from a configurable start scale to 1f. Use through BaseQuickAdapter.itemAnimation.

```APIDOC
## ScaleInAnimation

### Description
Scales an item from a configurable start scale to 1f. Use through BaseQuickAdapter.itemAnimation.

### Constructor
```kotlin
class ScaleInAnimation @JvmOverloads constructor(
    private val duration: Long = 300,
    private val mFrom: Float = DEFAULT_SCALE_FROM   // .5f
) : ItemAnimator
```

### Parameters
- **duration** (Long) - Optional - Animation duration in milliseconds. Default 300.
- **mFrom** (Float) - Optional - Starting scale value. Default 0.5f.

### Behavior
- Interpolator: DecelerateInterpolator
- Default duration: 300 ms
- Default start scale: 0.5f
```

--------------------------------

### QuickAdapterHelper class declaration

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Private constructor for QuickAdapterHelper, taking content adapter, leading and trailing load state adapters, and a ConcatAdapter config. Instances are created only through Builder.

```kotlin
class QuickAdapterHelper private constructor(
    val contentAdapter: BaseQuickAdapter<*, *>,
    val leadingLoadStateAdapter: LeadingLoadStateAdapter<*>?,
    val trailingLoadStateAdapter: TrailingLoadStateAdapter<*>?,
    config: ConcatAdapter.Config
)
```

--------------------------------

### QuickAdapterHelper.Builder Options

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Configuration options for the QuickAdapterHelper.Builder, which is used to set up a RecyclerView adapter with load state adapters and preload sizes.

```APIDOC
## QuickAdapterHelper.Builder Options

### Description
Configuration options for the QuickAdapterHelper.Builder, which is used to set up a RecyclerView adapter with load state adapters and preload sizes.

### Constructor
- **contentAdapter** (BaseQuickAdapter<*, *>) - Required - The content adapter for the RecyclerView.

### Methods
#### setTrailingLoadStateAdapter
- **Signature**: `(loadStateAdapter: TrailingLoadStateAdapter<*>?)` / `(loadMoreListener: OnTrailingListener?)`
- **Description**: Tail load adapter or its listener (default adapter used for listener form).

#### setTrailPreloadSize
- **Signature**: `(size: Int)`
- **Description**: Tail preload distance; default `0`.

#### isTrailAutoLoadMore
- **Signature**: `(enable: Boolean)`
- **Description**: Auto load more; default `true`.

#### setLeadingLoadStateAdapter
- **Signature**: `(loadStateAdapter: LeadingLoadStateAdapter<*>?)` / `(loadListener: OnLeadingListener?)`
- **Description**: Head load adapter or its listener.

#### setLeadPreloadSize
- **Signature**: `(size: Int)`
- **Description**: Head preload distance; default `0`.

#### setConfig
- **Signature**: `(config: ConcatAdapter.Config)`
- **Description**: `ConcatAdapter.Config`; default `ConcatAdapter.Config.DEFAULT`.

#### build
- **Signature**: `()`
- **Description**: Returns `QuickAdapterHelper`.

#### attachTo
- **Signature**: `(recyclerView: RecyclerView)`
- **Description**: Builds and sets `recyclerView.adapter`.
```

--------------------------------

### itemAnimation

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Gets or sets a custom animation. Setting it also forces animationEnable = true.

```APIDOC
## itemAnimation

### Description
Gets or sets a custom animation. Setting it also forces animationEnable = true.

### Property
`itemAnimation`

### Type
`ItemAnimator?`

### Default
`null`
```

--------------------------------

### Using setOnDebouncedItemClick with custom time

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example of setting a debounced item click with a 300 ms interval.

```kotlin
adapter.setOnDebouncedItemClick(time = 300) { adapter, view, position ->
    viewModel.open(position)
}
```

--------------------------------

### BaseQuickAdapter constructor

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Creates a BaseQuickAdapter instance. The primary constructor takes a list of items and an optional AsyncDifferConfig; when config is non-null, submitList is backed by an AsyncListDiffer. Additional convenience constructors accept a DiffUtil.ItemCallback or no arguments.

```APIDOC
## BaseQuickAdapter

### Description
Creates a BaseQuickAdapter instance. The primary constructor takes a list of items and an optional AsyncDifferConfig; when config is non-null, submitList is backed by an AsyncListDiffer. Additional convenience constructors accept a DiffUtil.ItemCallback or no arguments.

### Constructors
- `BaseQuickAdapter(items: List<T>, config: AsyncDifferConfig<T>?)` - Primary constructor. `config != null` enables async differ-backed `submitList`
- `BaseQuickAdapter(diffCallback: DiffUtil.ItemCallback<T>)` - `this(emptyList(), AsyncDifferConfig.Builder(diffCallback).build())`
- `BaseQuickAdapter(items: List<T>, diffCallback: DiffUtil.ItemCallback<T>)` - `this(items, AsyncDifferConfig.Builder(diffCallback).build())`
- `BaseQuickAdapter(config: AsyncDifferConfig<T>?)` - `this(emptyList(), config)`
- `BaseQuickAdapter(items: List<T>)` - `this(items, null)`
- `BaseQuickAdapter()` - `this(emptyList(), null)`

### Request Example
```java
public class DiffUtilAdapter extends BaseQuickAdapter<DiffEntity, DiffUtilAdapter.VH> {
    public DiffUtilAdapter() {
        super(new DiffEntityCallback()); // DiffUtil.ItemCallback<T> constructor
    }
}
```
```

--------------------------------

### AlphaInAnimation

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Fades in an item by animating alpha from a configurable start to 1f. Use through BaseQuickAdapter.itemAnimation.

```APIDOC
## AlphaInAnimation

### Description
Fades in an item by animating alpha from a configurable start to 1f. Use through BaseQuickAdapter.itemAnimation.

### Constructor
```kotlin
class AlphaInAnimation @JvmOverloads constructor(
    private val duration: Long = 300,
    private val mFrom: Float = DEFAULT_ALPHA_FROM   // 0f
) : ItemAnimator
```

### Parameters
- **duration** (Long) - Optional - Animation duration in milliseconds. Default 300.
- **mFrom** (Float) - Optional - Starting alpha value. Default 0f.

### Behavior
- Interpolator: LinearInterpolator
- Default duration: 300 ms
- Default start alpha: 0f
```

--------------------------------

### QuickAdapterHelper.Builder.setLeadingLoadStateAdapter(listener)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Uses a default leading adapter and sets its OnLeadingListener. The default adapter is lazily instantiated.

```APIDOC
## setLeadingLoadStateAdapter(listener)

### Description
Uses a default leading adapter and sets its OnLeadingListener. The default adapter is lazily instantiated.

### Method
setLeadingLoadStateAdapter

### Parameters
- **listener** (LeadingLoadStateAdapter.OnLeadingListener?) - Required - The listener for load events.

### Returns
Builder (this builder for chaining)
```

--------------------------------

### QuickDragAndSwipe.setItemDragListener

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Sets a listener for drag events. The listener receives callbacks for drag start, moving, and end.

```APIDOC
## QuickDragAndSwipe.setItemDragListener

### Description
Sets a listener for drag events. The listener receives callbacks for drag start, moving, and end.

### Method
setItemDragListener

### Parameters
- **listener** (OnItemDragListener) - Required - The listener for drag events.

### Example
```kotlin
quickDragAndSwipe.setItemDragListener(object : OnItemDragListener {
    override fun onItemDragStart(viewHolder: RecyclerView.ViewHolder?, pos: Int) { /* ... */ }
    override fun onItemDragMoving(source: RecyclerView.ViewHolder, from: Int, target: RecyclerView.ViewHolder, to: Int) { /* ... */ }
    override fun onItemDragEnd(viewHolder: RecyclerView.ViewHolder, pos: Int) { /* ... */ }
})
```
```

--------------------------------

### Using addOnDebouncedChildClick with custom time

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example of adding a debounced child click listener for a button with a 500 ms interval.

```kotlin
adapter.addOnDebouncedChildClick(R.id.btn, time = 500) { adapter, view, position ->
    adapter.removeAt(position)
}
```

--------------------------------

### add

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Adds an item at a specific position or appends it to the end. Handles empty-view transitions.

```APIDOC
## add

### Description
Adds an item at a specific position or appends it to the end. Handles empty-view transitions.

### Method
Function

### Signature
```kotlin
@JvmOverloads
open fun add(@IntRange(from = 0) position: Int, data: T, commitCallback: Runnable? = null)
@JvmOverloads
open fun add(data: T, commitCallback: Runnable? = null)
```

### Parameters
- `position` (Int) - Required for indexed variant - Position to insert at (must be in range)
- `data` (T) - Required - The item to add
- `commitCallback` (Runnable?) - Optional - Callback after commit

### Exceptions
- Indexed variant throws `IndexOutOfBoundsException("position: ${position}. size:${items.size}")` when `position > items.size || position < 0`

### Usage Example
```kotlin
adapter.add(0, newItem)     // prepend
adapter.add(newItem)        // append, null-safety via mutableItems.add()
```
```

--------------------------------

### Common Gradle Build Commands

Source: https://github.com/cymchad/baserecyclerviewadapterhelper/blob/master/CLAUDE.md

Commands to compile the library, assemble the AAR, build the demo APK, or clean the project, executed from the repository root.

```bash
./gradlew :library:compileDebugKotlin        # what CI runs — fastest library sanity check
./gradlew :library:assembleRelease           # build the AAR
./gradlew :app:assembleDebug                 # build the demo APK
./gradlew clean
```

--------------------------------

### Error consumption in fail callback

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example from AutoLoadMoreRefreshUseActivity.kt showing how to set trailingLoadState to LoadState.Error when a load fails.

```kotlin
override fun fail(e: Exception) {
    helper.trailingLoadState = LoadState.Error(e)
}
```

--------------------------------

### addAfterAdapter method signatures

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Appends or inserts a footer adapter into the after-list. The indexed variant throws IndexOutOfBoundsException with message 'Index must be between 0 and ${mAfterList.size}. Given:${index}'. The non-indexed variant inserts before the trailing load-state adapter or appends when none exists.

```kotlin
fun addAfterAdapter(adapter: BaseQuickAdapter<*, *>) = apply
fun addAfterAdapter(index: Int, adapter: BaseQuickAdapter<*, *>) = apply
```

--------------------------------

### QuickDragAndSwipe.setItemSwipeListener

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Sets a listener for swipe events. The listener receives callbacks for swipe start, end, swiped, and moving.

```APIDOC
## QuickDragAndSwipe.setItemSwipeListener

### Description
Sets a listener for swipe events. The listener receives callbacks for swipe start, end, swiped, and moving.

### Method
setItemSwipeListener

### Parameters
- **listener** (OnItemSwipeListener) - Required - The listener for swipe events.

### Example
```kotlin
quickDragAndSwipe.setItemSwipeListener(object : OnItemSwipeListener {
    override fun onItemSwipeStart(viewHolder: RecyclerView.ViewHolder?, bindingAdapterPosition: Int) { /* ... */ }
    override fun onItemSwipeEnd(viewHolder: RecyclerView.ViewHolder, bindingAdapterPosition: Int) { /* ... */ }
    override fun onItemSwiped(viewHolder: RecyclerView.ViewHolder, direction: Int, bindingAdapterPosition: Int) { /* ... */ }
    override fun onItemSwipeMoving(canvas: Canvas, viewHolder: RecyclerView.ViewHolder, dX: Float, dY: Float, isCurrentlyActive: Boolean) { /* ... */ }
})
```
```

--------------------------------

### addBeforeAdapter

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Adds a header adapter to the beginning of the list. The indexed variant inserts at a specific position relative to the before-list.

```APIDOC
## addBeforeAdapter

### Description
Adds a header adapter to the beginning of the list. The indexed variant inserts at a specific position relative to the before-list.

### Method
Kotlin function

### Signature
```kotlin
fun addBeforeAdapter(adapter: BaseQuickAdapter<*, *>) = apply
fun addBeforeAdapter(index: Int, adapter: BaseQuickAdapter<*, *>) = apply
```

### Parameters
- `index` (Int) - Required - Index relative to the before-list; bounds `0..mBeforeList.size`
- `adapter` (BaseQuickAdapter<*, *>) - Required - The header adapter

### Exceptions
- `IndexOutOfBoundsException` - If index is out of bounds, message: "Index must be between 0 and ${mBeforeList.size}. Given:${index}"

### Request Example
```kotlin
helper.addBeforeAdapter(0, HeaderAdapter().apply {
    setOnItemClickListener { _, _, _ -> addHeader() }
})
```
```

--------------------------------

### OnItemDragListener

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Interface for receiving drag events on RecyclerView items. Implement this to handle drag start, moving, and end callbacks.

```APIDOC
## OnItemDragListener

### Description
Interface for receiving drag events on RecyclerView items. Implement this to handle drag start, moving, and end callbacks.

### Methods

#### onItemDragStart
- **Parameters**: `viewHolder` (RecyclerView.ViewHolder, nullable) - The view holder being dragged; `pos` (int) - The position of the item.

#### onItemDragMoving
- **Parameters**: `source` (RecyclerView.ViewHolder, non-null) - The source view holder; `from` (int) - The original position; `target` (RecyclerView.ViewHolder, non-null) - The target view holder; `to` (int) - The new position.

#### onItemDragEnd
- **Parameters**: `viewHolder` (RecyclerView.ViewHolder, non-null) - The view holder being dragged; `pos` (int) - The final position.

### Source Code
```java
public interface OnItemDragListener {
    void onItemDragStart(@Nullable RecyclerView.ViewHolder viewHolder, int pos);
    void onItemDragMoving(@NonNull RecyclerView.ViewHolder source, int from,
                          @NonNull RecyclerView.ViewHolder target, int to);
    void onItemDragEnd(@NonNull RecyclerView.ViewHolder viewHolder, int pos);
}
```
```

--------------------------------

### addBeforeAdapter method signatures

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Appends or inserts a header adapter into the before-list. The indexed variant throws IndexOutOfBoundsException with message 'Index must be between 0 and ${mBeforeList.size}. Given:${index}' when out of bounds.

```kotlin
fun addBeforeAdapter(adapter: BaseQuickAdapter<*, *>) = apply            // appends to the head list
fun addBeforeAdapter(index: Int, adapter: BaseQuickAdapter<*, *>) = apply
```

--------------------------------

### OnItemDragListener interface (Java)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Defines callbacks for drag operations: start, moving, and end. Use with RecyclerView drag-and-swipe adapters.

```java
public interface OnItemDragListener {
    void onItemDragStart(@Nullable RecyclerView.ViewHolder viewHolder, int pos);
    void onItemDragMoving(@NonNull RecyclerView.ViewHolder source, int from,
                          @NonNull RecyclerView.ViewHolder target, int to);
    void onItemDragEnd(@NonNull RecyclerView.ViewHolder viewHolder, int pos);
}
```

--------------------------------

### Package layout of com.chad.library.adapter4

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Shows the directory structure of the adapter4 package, listing key Kotlin files and subdirectories for core adapters, animations, drag/swipe, fullspan, layoutmanager, loadState, util, and viewholder.

```text
com.chad.library.adapter4
├── BaseQuickAdapter.kt            # core adapter
├── BaseMultiItemAdapter.kt        # multi layout adapter
├── BaseNodeAdapter.kt             # tree node adapter
├── BaseSingleItemAdapter.kt       # single item adapter
├── BaseDifferAdapter.kt           # deprecated differ base
├── QuickAdapterHelper.kt          # ConcatAdapter helper + Builder
├── animation/                     # ItemAnimator + 5 built-ins
├── dragswipe/                     # QuickDragAndSwipe, DragSwipeExt, listeners
├── fullspan/                      # FullSpanAdapterType
├── layoutmanager/                 # QuickGridLayoutManager
├── loadState/                     # LoadState, LoadStateAdapter, leading/, trailing/
├── util/                          # AdapterUtils, ItemClickUtils
└── viewholder/                    # QuickViewHolder, DataBindingHolder, StateLayoutVH(internal)
```

--------------------------------

### 配置加载更多功能属性

Source: https://github.com/cymchad/baserecyclerviewadapterhelper/wiki/尾部加载更多（向下加载更多）

定义了控制加载更多行为的布尔值和预加载设置，需在初始化时配置。

```kotlin
/**
 * Whether to display "Loading end" after all data is loaded.
 *
 * 所有数据加载完毕后，是否显示"加载结束"，必须初始化时传递，中途无法修改参数。
*/
val isLoadEndDisplay: Boolean = true

/**
 * Whether to turn on autoload more.
 *
 * 是否打开自动加载更多
 */
var isAutoLoadMore = true

/**
 * Preload, the number of items from the tail.
 *
 * 预加载，距离尾部 item 的个数
 */
var preloadSize = 0

/**
 * Call this method, Check disable load more if not full page.
 * 调用此方法，当数据不满足一屏幕的时候，暂停加载更多
 */
fun checkDisableLoadMoreIfNotFullPage()
```

--------------------------------

### QuickAdapterHelper.Builder.setLeadPreloadSize(size)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Sets the leading adapter's preloadSize.

```APIDOC
## setLeadPreloadSize(size)

### Description
Sets the leading adapter's preloadSize.

### Method
setLeadPreloadSize

### Parameters
- **size** (Int) - Required - The preload size.

### Returns
Builder (this builder for chaining)
```

--------------------------------

### QuickAdapterHelper.Builder.setConfig(config)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Sets the ConcatAdapter configuration. Defaults to ConcatAdapter.Config.DEFAULT.

```APIDOC
## setConfig(config)

### Description
Sets the ConcatAdapter configuration. Defaults to ConcatAdapter.Config.DEFAULT.

### Method
setConfig

### Parameters
- **config** (ConcatAdapter.Config) - Required - The ConcatAdapter configuration.

### Returns
Builder (this builder for chaining)
```

--------------------------------

### Override onBindViewHolder with null handling

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Example override that handles null items by rendering an empty state and returning early.

```kotlin
override fun onBindViewHolder(holder: VH, item: T?) {
    if (item == null) { /* render empty state */ return }
    holder.text = item.name
}
```

--------------------------------

### isInitialOpen abstract method

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Return true to expand the item by default when data is submitted. Called multiple times for roots and children; position is the position in the list being constructed.

```kotlin
abstract fun isInitialOpen(position: Int, item: Any): Boolean
```

--------------------------------

### QuickAdapterHelper.Builder.isTrailAutoLoadMore(enable)

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Enables or disables automatic load more on the default trailing adapter.

```APIDOC
## isTrailAutoLoadMore(enable)

### Description
Enables or disables automatic load more on the default trailing adapter.

### Method
isTrailAutoLoadMore

### Parameters
- **enable** (Boolean) - Required - Whether to enable auto load more.

### Returns
Builder (this builder for chaining)
```

--------------------------------

### OnItemSwipeListener

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Java interface for listening to swipe events on RecyclerView items. Implement this to receive callbacks when swipe starts, ends, or moves.

```APIDOC
## OnItemSwipeListener

### Description
Java interface for listening to swipe events on RecyclerView items. Implement this to receive callbacks when swipe starts, ends, or moves.

### Methods
- `onItemSwipeStart(@Nullable RecyclerView.ViewHolder viewHolder, int bindingAdapterPosition)`: void - Required - Called when swipe starts
- `onItemSwipeEnd(@NonNull RecyclerView.ViewHolder viewHolder, int bindingAdapterPosition)`: void - Required - Called when swipe ends
- `onItemSwiped(@NonNull RecyclerView.ViewHolder viewHolder, int direction, int bindingAdapterPosition)`: void - Required - Called when item is swiped
- `onItemSwipeMoving(@NonNull Canvas canvas, @NonNull RecyclerView.ViewHolder viewHolder, float dX, float dY, boolean isCurrentlyActive)`: void - Required - Called while swiping

### Usage
Used by `QuickDragAndSwipe.setItemSwipeListener`, `DragSwipeExt.setItemSwipeListener`.
```

--------------------------------

### OnItemDragListener

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Java interface for listening to drag events on RecyclerView items. Implement this to receive callbacks when drag starts, moves, or ends.

```APIDOC
## OnItemDragListener

### Description
Java interface for listening to drag events on RecyclerView items. Implement this to receive callbacks when drag starts, moves, or ends.

### Methods
- `onItemDragStart(@Nullable RecyclerView.ViewHolder viewHolder, int pos)`: void - Required - Called when drag starts
- `onItemDragMoving(@NonNull RecyclerView.ViewHolder source, int from, @NonNull RecyclerView.ViewHolder target, int to)`: void - Required - Called while dragging
- `onItemDragEnd(@NonNull RecyclerView.ViewHolder viewHolder, int pos)`: void - Required - Called when drag ends

### Usage
Used by `QuickDragAndSwipe.setItemDragListener`, `DragSwipeExt.setItemDragListener`.
```

--------------------------------

### QuickAdapterHelper.Builder class declaration

Source: https://github.com/cymchad/baserecyclerviewadapterhelper

Builder class that takes a content adapter and provides methods to configure the helper.

```kotlin
class Builder(private val contentAdapter: BaseQuickAdapter<*, *>)
```
Tokens:
Raw