<h1 align="center">Compose 稳定标记</h1> <a href="https://opensource.org/licenses/Apache-2.0"><img alt="许可证" src="https://yellow-cdn.veclightyear.com/87312a0a/59183d33-6b69-4142-a855-1846054ea295.svg"/></a> <a href="https://android-arsenal.com/api?level=21"><img alt="API" src="https://yellow-cdn.veclightyear.com/87312a0a/5ad79e77-c076-436a-9e07-c7dd9823c4e5.svg?style=flat"/></a> <a href="https://github.com/skydoves/compose-stable-marker/actions/workflows/android.yml"><img alt="构建状态" src="https://github.com/skydoves/compose-stable-marker/actions/workflows/android.yml/badge.svg"/></a> <a href="https://github.com/skydoves"><img alt="个人资料" src="https://yellow-cdn.veclightyear.com/87312a0a/03bc01bc-387d-4adf-85ca-6d07ccd5936a.svg"/></a> ✒️ Compose 稳定标记源自 Compose 运行时，它通过向 Compose 编译器传达稳定性和可跳过性保证，从而提高非 Compose 依赖模块的性能。该库支持 Kotlin 多平台。 <img src="https://github.com/skydoves/compose-stable-marker/assets/24237865/9ead142c-3a35-4027-932a-b1d4e1cd13c5" /> ## 目录该库包含一些提取的 Compose 稳定标记，如 [Stable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Stable)、[Immutable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Immutable) 和 [StableMarker](https://developer.android.com/reference/kotlin/androidx/compose/runtime/StableMarker)，用于向 Compose 编译器传达一些保证并将类标记为生成不可变实例。当你想在纯 Kotlin 模块或非 Compose 依赖模块中使用 **Stable** 或 **Immutable** 标记你的属性/类/函数时，可以使用此库。这些标记来自 [compose-runtime](https://developer.android.com/jetpack/androidx/releases/compose-runtime)。因此，如果你不想依赖 `compose-runtime` 库，但仍想通过在多模块结构中将模型标记为稳定来提高 Compose 性能，你可以使用此库。如果你想了解更多关于 **Skippable**、**Stable** 和 **Immutable** 的信息，请查看 [6 条 Jetpack Compose 指南优化你的应用性能](https://medium.com/proandroiddev/6-jetpack-compose-guidelines-to-optimize-your-app-performance-be18533721f9) 和 [Chris Banes 的 Composable 指标](https://chrisbanes.me/posts/composable-metrics/#skippable)。 ## 下载 [![Maven Central](https://yellow-cdn.veclightyear.com/87312a0a/51f16c93-7597-45f7-b052-480499111cc6.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.skydoves%22%20AND%20a:%compose-stable-marker%22) ### Gradle 将以下 `compileOnly` 依赖添加到你的**模块**的 `build.gradle.kts` 文件中： ```gradle dependencies { compileOnly("com.github.skydoves:compose-stable-marker:1.0.5") } ``` 对于 Kotlin 多平台，将以下 `compileOnly` 依赖添加到你的**模块**的 `build.gradle.kts` 文件中： ```gradle sourceSets { val commonMain by getting { dependencies { compileOnly("com.github.skydoves:compose-stable-marker:$version") } } } ``` ## Stable 这些持有可变数据，但在发生变化时会通知 Composition。这使它们变得稳定，因为 Composition 总是被告知状态的任何变化。如果满足以下假设，此注解意味着 Compose 编译器可以进行优化： 1. 对于相同的两个实例，`equals` 的结果将始终返回相同的结果。 2. 当类型的公共属性发生变化时，将通知 Composition。 3. 所有公共属性类型都是稳定的。你可以在纯 Kotlin 模块或非 Compose 依赖模块中像使用普通注解一样使用 [Stable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Stable) 注解。 ### 不使用 Stable 注解（不可跳过且不稳定）假设你有一个没有 `Stable` 注解的普通类： ```kotlin // 数据模块（纯 Kotlin 模块） public data class UnstableUser( public val name: String, public val devices: List<String>, public val createdAt: Instant, )

// 特性模块 @Composable private fun UnstableUserFun(unstableUser: UnstableUser) { Text(text = unstableUser.toString()) }

根据 [Compose 编译器指标](https://github.com/androidx/androidx/blob/androidx-main/compose/compiler/design/compiler-metrics.md)，你将得到以下结果：

restartable scheme("[androidx.compose.ui.UiComposable]") fun UnstableUserFun( unstable unstableUser: UnstableUser )

如上面的指标所示，`UnstableUserFun` Composable 函数是**不可跳过**的，而 `UnstableUser` 类被标记为**不稳定**。  
### 使用 Stable 注解（可跳过且稳定）  
假设你有一个带有 `Stable` 注解的普通类：  
```kotlin
// 数据模块（纯 Kotlin 模块）
@Immutable
public data class StableUser(
    public val name: String,
    public val devices: List<String>,
    public val createdAt: Instant,
)

// 特性模块
@Composable
private fun StableUserFun(stableUser: StableUser) {
    Text(text = stableUser.toString())
}

根据 Compose 编译器指标，你将得到以下结果：

restartable skippable scheme("[androidx.compose.ui.UiComposable]") fun StableUserFun(
    stable stableUser: StableUser
)

如上面的指标所示，StableUserFun Composable 函数是可跳过的，而 StableUser 类被标记为稳定。因此，如果参数自上次调用以来没有变化，你的函数将完全跳过调用，因为所有属性都被标记为稳定。

Immutable

与 Stable 注解的方法相同，你可以像使用普通的 compose-runtime 注解一样使用这个注解。顾名思义，这些持有不可变数据。由于数据永远不会改变，Compose 可以将其视为稳定数据。使用此注解，Composition 可以基于假设从类型读取的值不会改变来启用优化。 
假设你有一个带有 Immutable 注解的普通类：

// 数据模块（纯 Kotlin 模块）
@Immutable
public data class ImmutableUser constructor(
    public val name: String,
    public val devices: List<String>,
    public val createdAt: Instant,
)

// 特性模块
@Composable
private fun ImmutableUserComposable(immutableUser: ImmutableUser) {
    Text(text = immutableUser.toString())
}

根据 Compose 编译器指标，你将得到以下结果：

restartable skippable scheme("[androidx.compose.ui.UiComposable]") fun ImmutableUser(
    stable immutableUser: ImmutableUser
)

StableMarker

标记为 StableMarker 的注解表示一个稳定类型，它遵循以下假设：

对于相同的两个实例，[equals] 的结果将始终返回相同的结果。
当类型的公共属性发生变化时，将通知 Composition。
所有公共属性类型都是稳定的。

许可证

由 skydoves (Jaewoong Eum) 于2023年设计和开发

根据 Apache 许可证 2.0 版（"许可证"）授权；
除非遵守许可证，否则您不得使用此文件。
您可以在以下网址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据许可证分发的软件是基于"按原样"分发的，
不附带任何明示或暗示的担保或条件。
有关许可证下的特定语言管理权限和限制，请参阅许可证。