BaseRecyclerViewAdapterHelper Documentation

File: README.md Copy Chapter

BRVAH

Powerful and flexible RecyclerView Adapter,
Please feel free to use this. (Welcome to Star and Fork)

强大而灵活的RecyclerView Adapter（欢迎 Star 和 Fork）

​
新版4.x.x已发布，完美兼容ConcatAdapter，解决了许多遗留问题，拆分了功能模块，BaseAdapter更加简洁干净。“多类型布局”更加灵活。向上、向下加载得到极大加强。
v4版本已经上传 maven 中央仓库，不需要再引入三方仓库配置了。欢迎尝试。

Of course, you can continue to use the 2.x version.

当然，你也可以继续使用2.x 版本、3.x版本。

Document

• English Writing ...
• 3.0版本 中文
• 4.0版本 中文

(由于各位项目成员工作较为繁忙，请各位同学谅解)

v4 版本 Copy Chapter

wiki

implementation("io.github.cymchad:BaseRecyclerViewAdapterHelper4:4.4.1")

[demo](https://github.com/CymChad/BaseRecyclerViewAdapterHelper/tree/master/demo) Copy Chapter

proguard-rules.pro

此资源库自带混淆规则，并且会自动导入，正常情况下无需手动导入。

The library comes with proguard-rules.pro rules and is automatically imported. Normally no manual import is required.
You can also go here to view proguard-rules

Thanks

JoanZapata / base-adapter-helper

[License](https://github.com/CymChad/BaseRecyclerViewAdapterHelper/blob/master/LICENSE)

File: AGENTS.md Copy Chapter

Repository Guidelines

Project Structure & Module Organization Copy Chapter

This is an Android Gradle project with Kotlin DSL build files. settings.gradle includes two modules:

• library/: the reusable RecyclerView adapter library published as io.github.cymchad:BaseRecyclerViewAdapterHelper4.
• app/: the sample Android application demonstrating library usage.

Main source lives under app/src/main/java and library/src/main/java. Android resources are under each module's src/main/res. Keep public library APIs in the com.chad.library.adapter4 namespace and sample-only code in com.chad.baserecyclerviewadapterhelper.

Build, Test, and Development Commands Copy Chapter

Use the Gradle wrapper from the repository root:

• ./gradlew assembleDebug: builds debug artifacts for all modules.
• ./gradlew :app:assembleDebug: builds the sample app.
• ./gradlew :library:assembleRelease: builds the release AAR for the library.
• ./gradlew clean: removes generated build output.
• ./gradlew test: runs JVM unit tests when test sources exist.
• ./gradlew connectedAndroidTest: runs instrumentation tests on a connected device or emulator when present.

The project targets Java 17 via Gradle toolchains. Dependencies and plugin versions are centralized in gradle/libs.versions.toml.

Coding Style & Naming Conventions Copy Chapter

Use Kotlin for new code unless working in an existing Java file. Follow Android/Kotlin conventions: 4-space indentation, UpperCamelCase classes, lowerCamelCase functions and properties, and package names matching module namespaces. Prefer clear adapter, view holder, and load-state names that match existing patterns such as BaseQuickAdapter, QuickViewHolder, and DefaultTrailingLoadStateAdapter.

Keep resources lowercase with underscores, for example brvah_trailing_load_more.xml. Avoid unrelated formatting churn in mixed Java/Kotlin files.

Testing Guidelines Copy Chapter

No test directories are currently checked in. Add unit tests under module/src/test and Android tests under module/src/androidTest when changing behavior. Name tests after the unit under test and expected behavior, for example BaseDifferAdapterTest. Run ./gradlew test before submitting logic changes, and use connectedAndroidTest for RecyclerView or UI behavior that needs Android runtime coverage.

Commit & Pull Request Guidelines Copy Chapter

Recent history uses Conventional Commit-style messages, often scoped, such as fix(adapter): ..., refactor(loadState): ..., and docs(README): .... Keep commits focused and use scopes that match affected areas.

Pull requests should include a concise description, linked issues when applicable, test results, and screenshots or recordings for sample app UI changes. For library API changes, document migration notes and update README or wiki references when needed.

Security & Configuration Tips Copy Chapter

Do not commit local.properties, signing keys, Sonatype credentials, or generated publishing output. Publishing credentials are loaded from local properties or environment-specific configuration.

File: CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Copy Chapter

BRVAH (BaseRecyclerViewAdapterHelper) — a RecyclerView Adapter helper library for Android (current major version: v4.x, published as io.github.cymchad:BaseRecyclerViewAdapterHelper4). v4 was rewritten to be fully compatible with ConcatAdapter, to split functionality into modules, and to support flexible multi-type layouts plus strengthened up/down load-more.

The repository contains two Gradle modules:

• :library — the published library (namespace com.chad.library.adapter4). This is the artifact.
• :app — the demo application that exercises every library feature (com.chad.baserecyclerviewadapterhelper). demo/ holds a prebuilt APK only.

Build & Toolchain Copy Chapter

Gradle with Kotlin DSL (settings.gradle, build.gradle.kts, gradle/libs.versions.toml). Toolchain and SDK versions are pinned per module:

• JDK 17 toolchain for both modules (CI uses temurin 17).
• :library — compileSdk = 35, minSdk = 19, depends only on androidx.annotation, androidx.recyclerview, and compileOnly databinding-runtime. No AndroidX app deps — it is a pure library.
• :app — compileSdk/targetSdk = 36, minSdk = 23, uses viewBinding + dataBinding, Moshi (KSP codegen). All third-party demo deps live here, never in :library.

Common commands (run from repo root):

./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

There is no test source set — there are no unit or instrumented tests in either module. Verify changes by compiling and/or running the demo app.

Publishing / versioning Copy Section

• Library version lives in library/build.gradle.kts as val versionName (currently 4.4.1). The :app versionName (4.3.2) is independent — update them separately.
• Publishing is configured with maven-publish + signing. Credentials/signing keys are read from local.properties (signing.keyId, signing.password, signing.secretKeyRingFile, ossrhUsername, ossrhPassword). The active publish repository is the local $rootDir/Repo folder (Maven Central upload block is commented out).
• ProGuard consumer rules ship via consumerProguardFiles("proguard-rules.pro") in :library, so consumers auto-import them; the file itself is mostly a placeholder.

Library architecture Copy Chapter

Everything is under com.chad.library.adapter4. The design centers on one abstract base plus adapter composition via ConcatAdapter.

`BaseQuickAdapter` (the base class) Copy Section

BaseQuickAdapter.kt is the foundation for all adapters. Two things define it:

1. Two data modes, decided at construction by whether a DiffUtil.ItemCallback<T>/AsyncDifferConfig<T> is supplied:

   • Diff mode — backs items with AsyncListDiffer (async diffing, no jank). Mutating ops (submitList, add, set, removeAt, swap, move, …) rebuild a mutable list and re-submit.
   • Plain mode (mDiffer == null) — backs items with a plain List<T> and calls the corresponding notifyItem* directly.
     Every mutating method branches on mDiffer == null; when touching one, update both branches.

2. Sealed RecyclerView.Adapter overrides. getItemCount(), getItemViewType(), onCreateViewHolder(), and onBindViewHolder() are final. Subclasses implement the protected variants instead (onCreateViewHolder(context, parent, viewType), onBindViewHolder(holder, position, item[, payloads]), getItemCount(items), getItemViewType(position, list)). Do not try to override the final ones.

Other base-class responsibilities: optional state/empty view (isStateViewEnable + stateView, shown when items is empty via StateLayoutVH), item animations (animationEnable + itemAnimation/setItemAnimation(AnimationType)), and click listeners (item / item-child by view id, stored in a SparseArray). items setter is @Deprecated at ERROR level — use submitList() to replace data.

Adapter variants (all extend `BaseQuickAdapter`) Copy Section

• BaseMultiItemAdapter<T> — multi view-type layouts. Register each type with addItemType(viewType, OnMultiItemAdapterListener) and decide types via onItemViewType { position, list -> }. The listener (or OnMultiItem subclass, which grants adapter/context) provides onCreate/onBind per type.
• BaseNodeAdapter — tree/expandable lists. Subclasses implement getChildNodeList() and isInitialOpen(); open()/close()/openOrClose()/closeAll() drive expansion. Open/closed state is tracked by a custom NodeSet matched through isSameNode() (override for value-based nodes; default is ===). See the bilingual KDoc on isSameNode — it must uniquely identify a node or expand/collapse state leaks across nodes.
• BaseSingleItemAdapter<T, VH> — exactly one item (headers/footers). All list mutation methods throw; use item/setItem() only.
• BaseDifferAdapter — deprecated; BaseQuickAdapter now subsumes it.

Composition: `QuickAdapterHelper` Copy Section

QuickAdapterHelper wraps a content adapter in a ConcatAdapter and exposes helper.adapter to set on the RecyclerView. Layout order: LeadingLoadStateAdapter → before-adapters → content adapter → after-adapters → TrailingLoadStateAdapter. Built via QuickAdapterHelper.Builder(contentAdapter) with optional leading/trailing load-more, then .build() or .attachTo(recyclerView). This is the canonical way to get header/footer and up/down load-more in v4 — header/footer are separate small adapters prepended/appended, not built-in fields of the base adapter.

Load more (`loadState/`) Copy Section

• LoadState — sealed type: None, NotLoading(endOfPaginationReached), Loading, Error.
• LoadStateAdapter<VH> — base for a load-more adapter; toggles its single item on/off via displayLoadStateAsItem().
• TrailingLoadStateAdapter (tail) / LeadingLoadStateAdapter (head), each with a Default… implementation. Trailing supports isAutoLoadMore, preloadSize, and checkDisableLoadMoreIfNotFullPage().

Supporting utilities Copy Section

• viewholder/QuickViewHolder — convenience ViewHolder with cached findViewById and chained setters (setText, setVisible, …).
• layoutmanager/QuickGridLayoutManager — GridLayoutManager that grants full span to adapters implementing FullSpanAdapterType, and to BaseQuickAdapter view types for which isFullSpanItem(type) is true (the empty/state view is full-span by default). Use it (or your own SpanSizeLookup) when an item must span all columns.
• dragswipe/QuickDragAndSwipe + DragSwipeExt.kt — drag-and-swipe on top of ItemTouchHelper.
• animation/* — ItemAnimator implementations (AlphaIn, ScaleIn, SlideIn{Left,Right,Bottom}).
• util/AdapterUtils.kt — ViewGroup.getItemView(layoutResId) and ViewHolder.asStaggeredGridFullSpan().

Internal resource IDs Copy Section

The library declares IDs in library/src/main/res/values/ids.xml (e.g. BaseQuickAdapter_empty_view, BaseQuickAdapter_key_multi) used for internal view tagging and the empty-view viewType. The EMPTY_VIEW companion constant points at R.id.BaseQuickAdapter_empty_view.

Conventions Copy Chapter

• Bilingual KDoc. Public API documentation is written in both Chinese and English (Chinese typically first, then English). Match this style when adding or editing public APIs.
• Builder/apply chaining. Setters in BaseQuickAdapter and QuickAdapterHelper.Builder return apply/the builder for fluent config.
• Keep :library dependency-free of UI libs — it should only depend on AndroidX annotation/recyclerview (plus compileOnly databinding). Put demo-only dependencies in :app.

File: context7.json Copy Chapter

{
"url": "https://context7.com/cymchad/baserecyclerviewadapterhelper",
"public_key": "pk_Gbo1742cAnLeyb0lPCKt3"
}

File: SECURITY.md Copy Chapter

Security Policy

Supported Versions Copy Chapter

Reporting a Vulnerability Copy Chapter

If you discover a security vulnerability, please report it by opening an issue on GitHub Issues.

• Provide a clear description of the vulnerability and steps to reproduce it.
• We will acknowledge your report within 7 business days and keep you updated on the progress.
• Once confirmed, we will release a fix as soon as possible depending on the severity.
• If the report is declined, we will explain the reason.