StateLayout A library for showing different st @codeKK AndroidOpen Source Website

StateLayout

Introduction: A library for showing different state of views - Content,Empty,Loading,Error.

Tags:

状态部局-状态切换-

StateLayout is a small Android View container that displays one of four mutually exclusive states: content, empty, error, or loading. It is intended for projects that use Android XML layouts and the classic View system.

Maintenance status: maintained. Version 1.1.0 is available from GitHub Releases. Maven Central publication is still pending; the historical 1.0.3 Bintray/JCenter artifact should not be used for new builds.

StateLayout sample

Why StateLayout?

One predictable container for four common UI states.
Configure views in XML or supply them programmatically.
Preserve the selected state across Android view recreation.
Java API that is straightforward to call from both Java and Kotlin.
No runtime dependency on AppCompat or a networking/state-management framework.

Requirements

Component	Requirement
Library runtime	Android API 8+
Build from source	JDK 17 and Android SDK Platform 36
Sample target	Android API 36

Installation

GitHub Release

Download statelayout-1.1.0.aar from the v1.1.0 release, place it in your app's libs directory, and add:

dependencies {
    implementation files('libs/statelayout-1.1.0.aar')
}

You can also include this repository as source and depend on its library module:

dependencies {
    implementation project(':statelayout')
}

The planned Maven Central coordinate is io.github.wangyuyan666:statelayout:1.1.0. Do not use that coordinate until this README links to a verified Maven Central artifact. See the release procedure for the remaining Central Portal work.

XML configuration

Assign the state views and initial state directly from XML:

<com.objectlife.statelayout.StateLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/state_layout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:sl_contentView="@id/content"
    app:sl_emptyView="@id/empty"
    app:sl_errorView="@id/error"
    app:sl_loadingView="@id/loading"
    app:sl_initialState="loading">

    <include android:id="@+id/content" layout="@layout/view_content" />
    <include android:id="@+id/empty" layout="@layout/view_empty" />
    <include android:id="@+id/error" layout="@layout/view_error" />
    <include android:id="@+id/loading" layout="@layout/view_loading" />
</com.objectlife.statelayout.StateLayout>

Switch state from Kotlin:

val stateLayout = findViewById<StateLayout>(R.id.state_layout)
stateLayout.setState(StateLayout.VIEW_CONTENT)

Or Java:

StateLayout stateLayout = findViewById(R.id.state_layout);
stateLayout.setState(StateLayout.VIEW_ERROR);

Programmatic configuration

Views with no parent are added to the container automatically:

val stateLayout = findViewById<StateLayout>(R.id.state_layout)
val inflater = LayoutInflater.from(this)

stateLayout
    .setContentView(inflater.inflate(R.layout.view_content, stateLayout, false))
    .setEmptyView(inflater.inflate(R.layout.view_empty, stateLayout, false))
    .setErrorView(inflater.inflate(R.layout.view_error, stateLayout, false))
    .setLoadingView(inflater.inflate(R.layout.view_loading, stateLayout, false))
    .initWithState(StateLayout.VIEW_LOADING)

For existing descendants, the original ID-based API remains available:

stateLayout.setContentViewResId(R.id.content)
        .setEmptyViewResId(R.id.empty)
        .setErrorViewResId(R.id.error)
        .setLoadingViewResId(R.id.loading)
        .initWithState(StateLayout.VIEW_LOADING);

An invalid state or a missing ID passed through the programmatic API fails immediately with an IllegalArgumentException. Missing XML references fail during inflation with an IllegalStateException. State references declared in XML are resolved after child inflation.

Build and verify

./gradlew testDebugUnitTest lintDebug assembleDebug assembleRelease

To verify the library's AAR, sources, documentation, and POM locally:

./gradlew publishReleasePublicationToMavenLocal

Project scope

StateLayout deliberately remains a focused View-system primitive. Networking, pagination, retry policy, and application state ownership belong in higher-level application code. Compose applications generally do not need a wrapper around conditional composition; a future Compose sample may demonstrate interoperability without replacing this library's View API.