androidx.compose.runtime

在本页面中,您可以找到有关 androidx.compose.runtime 软件包中提供的类型、属性和函数的文档。例如:

如需相关指导,请查看以下 Compose 指南:

接口

Applier

Applier 负责应用会在组合期间发出的基于树的操作。

CMN
ComposeNodeLifecycleCallback

观察 ReusableContentHostReusableContent 内使用 ReusableComposeNodeComposeNode 发出的节点的生命周期。

CMN
Composer

Composer 是 Compose Kotlin 编译器插件的目标接口,供代码生成帮助程序使用。

CMN
Composition

组合对象通常会为您构建,并通过用于最初编写界面的 API 返回。

CMN
CompositionLocalMap

CompositionLocals 的只读、不可变快照,在组合层次结构中的特定位置设置。

CMN
CompositionServiceKey

用于使用 CompositionServices 接口定位服务的密钥(可选由 Composition 的实现实现)。

CMN
CompositionServices

允许从运行时查找合成服务。

CMN
CompositionTracer

内部跟踪 API。

CMN
ControlledComposition

受控的合成是指可以直接由调用方控制的 Composition

CMN
DisposableEffectResult
CMN
DoubleState

Composable 函数执行期间读取 doubleValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
FloatState

Composable 函数执行期间读取 floatValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
IntState

Composable 函数执行期间读取 intValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
LongState

Composable 函数执行期间读取 longValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
MonotonicFrameClock

提供显示帧的时间源以及对下一帧执行操作的功能。

CMN
MutableDoubleState

Composable 函数执行期间读取 doubleValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
MutableFloatState

Composable 函数执行期间读取 floatValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
MutableIntState

Composable 函数执行期间读取 intValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
MutableLongState

Composable 函数执行期间读取 longValue 属性的值容器会导致当前 RecomposeScope 订阅该值的更改。

CMN
MutableState

一个可变值容器,在 Composable 函数执行期间读取 value 属性,当前的 RecomposeScope 将订阅该值的更改。

CMN
ProduceStateScope

produceState 搭配使用的接收器范围。

CMN
RecomposeScope

表示组合层次结构的可重组范围或部分。

CMN
RecomposerInfo

有关 Recomposer 的只读信息。

CMN
RememberObserver

当实现此接口的对象最初在组合中使用以及不再使用时,系统会通知它们。

CMN
ReusableComposition

ReusableComposition 是一个可以重复用于不同可组合项内容的 Composition

CMN
ScopeUpdateScope

内部 Compose 编译器插件 API,用于更新 Composer 为重组重组作用域而调用的函数。

CMN
SnapshotMutationPolicy

此政策用于控制 mutableStateOf 的结果如何报告以及将更改合并到状态对象的方式。

CMN
State

一个值容器,在 Composable 函数执行期间读取 value 属性,当前的 RecomposeScope 将订阅该值的更改。

CMN

AbstractApplier

抽象 Applier 实现。

CMN
AtomicReference
CMN
BroadcastFrameClock

简单的帧时钟。

CMN
CompositionContext

CompositionContext 是一种不透明类型,用于在逻辑上将两个组合“关联”在一起。

CMN
CompositionLocal

Compose 通过组合树通过形参显式将数据传递给可组合函数。

CMN
CompositionLocalContext

存储 CompositionLocal 及其值。

CMN
DisposableEffectScope

DisposableEffect 的接收器范围,提供 onDispose 子句,该子句应该是对 DisposableEffect 的任何调用中的最后一个语句。

CMN
MovableContent

Compose 编译器插件 API。

CMN
MovableContentState

Compose 编译器插件 API。

CMN
MovableContentStateReference

Compose 编译器插件 API。

CMN
PausableMonotonicFrameClock

可以执行 pause 操作和 resume 操作的 MonotonicFrameClock 封装容器。

CMN
ProvidableCompositionLocal

可以在 CompositionLocalProvider 中使用 ProvidableCompositionLocal 来提供值。

CMN
ProvidedValue

用于保存 CompositionLocalProvider 提供的值的实例,由固定的 ProvidableCompositionLocal.provides 运算符创建。

CMN
Recomposer

用于执行重组并向一个或多个 Composition 应用更新的调度器。

CMN
SkippableUpdater
CMN
Updater

辅助接收器作用域类,供 ComposeNode 用于帮助编写代码以初始化和更新节点。

CMN

对象

注解

CheckResult
CMN
Android
Composable

Composable 函数是使用 Compose 构建的应用的基本构建块。

CMN
ComposableInferredTarget

由 Compose 编译器插件生成的注解。

CMN
ComposableOpenTarget

Composable 声明不需要使用特定 Applier。

CMN
ComposableTarget

Composable 函数已声明为使用名称为 applier 的 Applier。

CMN
ComposableTargetMarker

此注解用于将使用 ComposableTarget 并将已标记注解的完全限定名称作为 applier 值来将某个注解标记为等效。

CMN
ComposeCompilerApi
CMN
DisallowComposableCalls

这样可防止可组合调用在它所适用的函数内部进行。

CMN
ExperimentalComposeApi
CMN
ExperimentalComposeRuntimeApi
CMN
ExplicitGroupsComposable

此注解可以应用于 Composable 函数,这样在其添加了注解的函数正文中就不会生成组。

CMN
Immutable

Immutable 可用于将类标记为生成不可变实例。

CMN
InternalComposeApi
CMN
InternalComposeTracingApi
CMN
NoLiveLiterals

此注解用于指示 Compose Compiler 不要尝试在对其所应用的声明作用域内生成实时字面量,即使已开启实时字面量代码生成功能也是如此。

CMN
NonRestartableComposable

可以将此注解应用于 Composable 函数,以防止生成代码,从而跳过或重新开始此函数的执行。

CMN
ReadOnlyComposable

此注解可应用于 Composable 函数,这样就不会在其注解的函数正文周围生成任何组。

CMN
Stable

稳定版用于向 Compose 编译器传达关于特定类型或函数的行为方式的一些保证。

CMN
StableMarker

StableMarker 用于将注解标记为“类型稳定”。

CMN
TestOnly
CMN

枚举

Recomposer.State

Recomposer 的有效操作状态。

CMN

顶级函数摘要

inline Unit
@Composable
<T : Any, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit
)

T 类型的组合发出一个节点。

CMN
inline Unit
@Composable
<T : Any?, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    content: @Composable () -> Unit
)

T 类型的组合发出一个节点。

CMN
inline Unit
@Composable
@ExplicitGroupsComposable
<T : Any?, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit,
    content: @Composable () -> Unit
)

T 类型的组合发出一个节点。

CMN
Composition
Composition(applier: Applier<*>, parent: CompositionContext)

此方法用于启动组合。

CMN
Composition
@ExperimentalComposeApi
Composition(
    applier: Applier<*>,
    parent: CompositionContext,
    recomposeCoroutineContext: CoroutineContext
)

使用 applier 创建一个 Composition 来管理组合,将其作为 parent 的子级。

CMN
Unit
@Composable
CompositionLocalProvider(
    context: CompositionLocalContext,
    content: @Composable () -> Unit
)

CompositionLocalProvider 将值绑定到 context 提供的 CompositionLocal

CMN
Unit
@Composable
CompositionLocalProvider(
    value: ProvidedValue<*>,
    content: @Composable () -> Unit
)

CompositionLocalProvider 将值绑定到 ProvidableCompositionLocal 键。

CMN
Unit
@Composable
CompositionLocalProvider(
    vararg values: ProvidedValue<*>,
    content: @Composable () -> Unit
)

CompositionLocalProvider 会将值绑定到 ProvidableCompositionLocal 键。

CMN
ControlledComposition

此方法用于启动组合。

CMN
ControlledComposition
@TestOnly
@ExperimentalComposeApi
ControlledComposition(
    applier: Applier<*>,
    parent: CompositionContext,
    recomposeCoroutineContext: CoroutineContext
)
CMN
Unit

此函数已废弃。DisposableEffect 必须提供一个或多个“key”参数,以定义 DisposableEffect 的标识并确定应何时处理其先前的效果以及为新键启动新效果。

CMN
Unit

组合的附带效应:必须针对 key1 的任何新唯一值运行,并且在 key1 发生变化或 DisposableEffect 退出组合时必须反转或清理。

CMN
Unit

组合的附带效应:必须针对 keys 的任何新唯一值运行,并且如有任何 keys 发生变化或 DisposableEffect 退出组合,则必须反转或清理。

CMN
Unit

组合的附带效应:必须针对 key1key2 的任何新唯一值运行,并且在 key1key2 发生变化或 DisposableEffect 退出组合时必须反转或清理。

CMN
Unit
@Composable
@NonRestartableComposable
DisposableEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    effect: DisposableEffectScope.() -> DisposableEffectResult
)

组合的附带效应:必须针对 key1key2key3 的任何新唯一值运行,并且在 key1key2key3 发生变化或 DisposableEffect 退出组合时必须反转或清理。

CMN
Unit

此函数已废弃。LaunchedEffect 必须提供一个或多个“key”参数,用于定义 LaunchedEffect 的身份并确定何时应取消其先前的效果协程并为新键启动新效果。

CMN
Unit

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block

CMN
Unit
@Composable
@NonRestartableComposable
LaunchedEffect(vararg keys: Any?, block: suspend CoroutineScope.() -> Unit)

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block

CMN
Unit
@Composable
@NonRestartableComposable
LaunchedEffect(key1: Any?, key2: Any?, block: suspend CoroutineScope.() -> Unit)

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block

CMN
Unit
@Composable
@NonRestartableComposable
LaunchedEffect(key1: Any?, key2: Any?, key3: Any?, block: suspend CoroutineScope.() -> Unit)

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block

CMN
inline Unit
@Composable
<T : Any, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit
)

将可回收节点发送到 T 类型的组合中。

CMN
inline Unit
@Composable
<T : Any?, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    content: @Composable () -> Unit
)

将可回收节点发送到 T 类型的组合中。

CMN
inline Unit
@Composable
@ExplicitGroupsComposable
<T : Any?, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit,
    content: @Composable () -> Unit
)

将可回收节点发送到 T 类型的组合中。

CMN
ReusableComposition

此方法用于启动可重复使用的组合。

CMN
inline Unit
@Composable
ReusableContent(key: Any?, content: @Composable () -> Unit)

用于将组合标记为支持回收的实用函数。

CMN
inline Unit
@Composable
@ExplicitGroupsComposable
ReusableContentHost(
    active: Boolean,
    crossinline content: @Composable () -> Unit
)

托管 ReusableContent 时使用的可选实用函数。

CMN
Unit

effect 调度到当前组合成功完成并应用更改时运行。

CMN
ProvidableCompositionLocal<T>
<T : Any?> compositionLocalOf(
    policy: SnapshotMutationPolicy<T>,
    defaultFactory: () -> T
)

创建可使用 CompositionLocalProvider 提供的 CompositionLocal 键。

CMN
State<T>
@StateFactoryMarker
<T : Any?> derivedStateOf(calculation: () -> T)

创建一个 State 对象,其 State.valuecalculation 的结果。

CMN
State<T>
@StateFactoryMarker
<T : Any?> derivedStateOf(
    policy: SnapshotMutationPolicy<T>,
    calculation: () -> T
)

创建一个 State 对象,其 State.valuecalculation 的结果。

CMN
Boolean

内部跟踪 API。

CMN
inline T
@Composable
<T : Any?> key(vararg keys: Any?, block: @Composable () -> T)

key 是一个实用程序可组合项,用于对组合中的执行块进行“分组”或“设置键”。

CMN
@Composable () -> Unit
movableContentOf(content: @Composable () -> Unit)

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable (P) -> Unit
<P : Any?> movableContentOf(content: @Composable (P) -> Unit)

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable (P1, P2) -> Unit
<P1 : Any?, P2 : Any?> movableContentOf(content: @Composable (P1, P2) -> Unit)

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable (P1, P2, P3) -> Unit
<P1 : Any?, P2 : Any?, P3 : Any?> movableContentOf(
    content: @Composable (P1, P2, P3) -> Unit
)

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable (P1, P2, P3, P4) -> Unit
<P1 : Any?, P2 : Any?, P3 : Any?, P4 : Any?> movableContentOf(
    content: @Composable (P1, P2, P3, P4) -> Unit
)

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable R.() -> Unit
<R : Any?> movableContentWithReceiverOf(content: @Composable R.() -> Unit)

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable R.(P) -> Unit
<R : Any?, P : Any?> movableContentWithReceiverOf(content: @Composable R.(P) -> Unit)

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable R.(P1, P2) -> Unit
<R : Any?, P1 : Any?, P2 : Any?> movableContentWithReceiverOf(
    content: @Composable R.(P1, P2) -> Unit
)

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
@Composable R.(P1, P2, P3) -> Unit
<R : Any?, P1 : Any?, P2 : Any?, P3 : Any?> movableContentWithReceiverOf(
    content: @Composable R.(P1, P2, P3) -> Unit
)

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

CMN
MutableDoubleState

返回使用传入的 value 初始化的新 MutableDoubleState

CMN
MutableFloatState

返回使用传入的 value 初始化的新 MutableFloatState

CMN
MutableIntState

返回使用传入的 value 初始化的新 MutableIntState

CMN
MutableLongState

返回使用传入的 value 初始化的新 MutableLongState

CMN
SnapshotStateList<T>

创建一个可观察且可截取快照的 MutableList 实例。

CMN
SnapshotStateList<T>
@StateFactoryMarker
<T : Any?> mutableStateListOf(vararg elements: T)

创建一个可观察且可截取快照的 MutableList 实例。

CMN
SnapshotStateMap<K, V>

创建一个可观察且可截取快照的 MutableMap<k, v=""> 实例。</k,>

CMN
SnapshotStateMap<K, V>
@StateFactoryMarker
<K : Any?, V : Any?> mutableStateMapOf(vararg pairs: Pair<K, V>)

创建一个可观察且可截取快照的 MutableMap<k, v=""> 实例。</k,>

CMN
MutableState<T>

返回使用传入的 value 初始化的新 MutableState

CMN
SnapshotMutationPolicy<T>

政策绝不会将 MutableState 的值视为等效值。

CMN
State<T>
@Composable
<T : Any?> produceState(initialValue: T, producer: suspend ProduceStateScope<T>.() -> Unit)

返回一个可观察的 snapshot State,它会在没有定义数据源的情况下随时间生成值。

CMN
State<T>
@Composable
<T : Any?> produceState(initialValue: T, key1: Any?, producer: suspend ProduceStateScope<T>.() -> Unit)

返回一个可观察的 snapshot State,它会根据 key1 随时间生成值。

CMN
State<T>
@Composable
<T : Any?> produceState(
    initialValue: T,
    vararg keys: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
)

返回一个可观察的 snapshot State,它会根据 keys 随时间生成值。

CMN
State<T>
@Composable
<T : Any?> produceState(
    initialValue: T,
    key1: Any?,
    key2: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
)

返回一个可观察的 snapshot State,它会根据 key1key2 随时间生成值。

CMN
State<T>
@Composable
<T : Any?> produceState(
    initialValue: T,
    key1: Any?,
    key2: Any?,
    key3: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
)

返回一个可观察的 snapshot State,它会根据 key1key2key3 随时间生成值。

CMN
SnapshotMutationPolicy<T>

一项政策,如果 MutableState 的值引用 (===) 相等,则将它们视为等效值。

CMN
inline T
@Composable
<T : Any?> remember(crossinline calculation: @DisallowComposableCalls () -> T)

记住 calculation 生成的值。

CMN
inline T
@Composable
<T : Any?> remember(
    key1: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
)

如果 key1 等于前一个组合,请记住 calculation 返回的值,否则通过调用 calculation 生成并记住新值。

CMN
inline T
@Composable
<T : Any?> remember(
    vararg keys: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
)

如果 keys 的所有值都等于前一个组合,请记住 calculation 返回的值,否则通过调用 calculation 生成并记住新值。

CMN
inline T
@Composable
<T : Any?> remember(
    key1: Any?,
    key2: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
)

如果 key1key2 等于前一个组合,请记住 calculation 返回的值;否则,通过调用 calculation 生成并记住新值。

CMN
inline T
@Composable
<T : Any?> remember(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
)

如果 key1key2key3 等于前一个组合,请记住 calculation 返回的值;否则,通过调用 calculation 生成并记住新值。

CMN
CompositionContext

用于在当前合成点构建 CompositionContext 的效果。

CMN
inline CoroutineScope

使用 getContext 提供的可选 CoroutineContext 返回绑定到组合中此位置的 CoroutineScope

CMN
State<T>
@Composable
<T : Any?> rememberUpdatedState(newValue: T)

mutableStateOf 执行 remember 操作,并在每次重组 rememberUpdatedState 调用时将其值更新为 newValue

CMN
Flow<T>
<T : Any?> snapshotFlow(block: () -> T)

根据可观察的 Snapshot 状态创建 Flow

CMN
Unit
@ComposeCompilerApi
sourceInformation(composer: Composer, sourceInformation: String)

Compose 内部函数。

CMN
Unit

Compose 内部函数。

CMN
Unit
@ComposeCompilerApi
sourceInformationMarkerStart(
    composer: Composer,
    key: Int,
    sourceInformation: String
)

Compose 内部函数。

CMN
ProvidableCompositionLocal<T>
<T : Any?> staticCompositionLocalOf(defaultFactory: () -> T)

创建可使用 CompositionLocalProvider 提供的 CompositionLocal 键。

CMN
SnapshotMutationPolicy<T>

此政策旨在将 MutableState 的值在结构 (==) 相等的情况下视为等效值。

CMN
Unit

内部跟踪 API。

CMN
Unit
@ComposeCompilerApi
traceEventStart(key: Int, dirty1: Int, dirty2: Int, info: String)

内部跟踪 API。

CMN
suspend R
<R : Any?> withFrameMillis(onFrame: (frameTimeMillis: Long) -> R)

挂起,直到请求新帧为止,在帧的调用上下文中立即使用帧时间(以毫秒为单位)调用 onFrame,然后恢复并返回 onFrame 的结果。

CMN
suspend R
<R : Any?> withFrameNanos(onFrame: (frameTimeNanos: Long) -> R)

挂起,直到请求新帧为止,在帧调度的调用上下文中立即使用帧时间(以纳秒为单位)调用 onFrame,然后恢复为 onFrame 的结果。

CMN
suspend R
<R : Any?> withRunningRecomposer(block: suspend CoroutineScope.(recomposer: Recomposer) -> R)

使用新的活跃 Recomposer 运行 block,并在调用 CoroutineContext 中应用更改。

CMN

扩展函数摘要

DoubleState

State<Double>(例如,由盒装 Double 组成的 State)转换为由基元支持的 Double

CMN
FloatState

State<Float>(例如,由盒装 Float 组成的 State)转换为由基元支持的 Float

CMN
IntState

State<Int>(例如,由盒装 Int 组成的 State)转换为由基元支持的 IntState

CMN
LongState

State<Long>(例如,由盒装 Long 组成的 State)转换为由基元支持的 LongState

CMN
inline T
@ComposeCompilerApi
<T : Any?> Composer.cache(
    invalid: Boolean,
    block: @DisallowComposableCalls () -> T
)

Compose 编译器插件 API。

CMN
State<T>

从此 StateFlow 收集值,并通过 State 表示其最新值。

CMN
State<R>
@Composable
<T : R, R : Any?> Flow<T>.collectAsState(initial: R, context: CoroutineContext)

从此 Flow 收集值,并通过 State 表示其最新值。

CMN
inline operator Double
DoubleState.getValue(thisObj: Any?, property: KProperty<*>)

允许使用 DoubleStatebyval 进行属性委托。

CMN
inline operator Float
FloatState.getValue(thisObj: Any?, property: KProperty<*>)

允许使用 FloatStatebyval 进行属性委托。

CMN
inline operator Int
IntState.getValue(thisObj: Any?, property: KProperty<*>)

允许使用 IntStatebyval 进行属性委托。

CMN
inline operator Long
LongState.getValue(thisObj: Any?, property: KProperty<*>)

允许使用 LongStatebyval 进行属性委托。

CMN
inline operator T
<T : Any?> State<T>.getValue(thisObj: Any?, property: KProperty<*>)

允许使用 Statebyval 进行属性委托。

CMN
inline operator Unit
MutableDoubleState.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: Double
)

允许使用 MutableDoubleStatebyvar 进行属性委托。

CMN
inline operator Unit
MutableFloatState.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: Float
)

允许使用 MutableFloatStatebyvar 进行属性委托。

CMN
inline operator Unit
MutableIntState.setValue(thisObj: Any?, property: KProperty<*>, value: Int)

允许使用 MutableIntStatebyvar 进行属性委托。

CMN
inline operator Unit
MutableLongState.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: Long
)

允许使用 MutableLongStatebyvar 进行属性委托。

CMN
inline operator Unit
<T : Any?> MutableState<T>.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: T
)

允许使用 MutableStatebyvar 进行属性委托。

CMN
SnapshotStateList<T>

从可观察且可截取快照的集合中创建 MutableList 的实例。

CMN
SnapshotStateMap<K, V>
<K : Any?, V : Any?> Iterable<Pair<K, V>>.toMutableStateMap()

从一组可观察且可截取快照的对中创建一个 MutableMap<k, v=""> 实例。</k,>

CMN
suspend inline R
<R : Any?> MonotonicFrameClock.withFrameMillis(
    crossinline onFrame: (frameTimeMillis: Long) -> R
)

挂起,直到请求新帧为止,在帧的调用上下文中立即使用帧时间(以毫秒为单位)调用 onFrame,然后恢复并返回 onFrame 的结果。

CMN

顶级属性摘要

MonotonicFrameClock

此属性已弃用。MonotonicFrameClock 并非适用于所有平台。

CMN
Android
Composer

TODO(lmr):提供文档

CMN
Int

这是一个哈希值,用于将外部存储的状态映射到组合。

CMN
CompositionLocalContext

返回当前的 CompositionLocalContext,其中包含当前组合中的所有 CompositionLocal 及其由 CompositionLocalProvider 提供的值。

CMN
RecomposeScope

返回一个对象,该对象可用于在组合的这一时间点使当前作用域失效。

CMN

扩展属性摘要

顶级函数

ComposeNode

@Composable
inline fun <T : Any, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit
): Unit

T 类型的组合发出一个节点。

如果 E 不是 currentComposer 的 applier 的子类型,则此函数将抛出运行时异常。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
noinline factory: () -> T

一个用于创建 T 新实例的函数。不保证此函数会就地调用。

update: @DisallowComposableCalls Updater<T>.() -> Unit

用于在节点上执行更新的函数。每次执行 emit 时,此代码都会运行。此函数会就地调用并被内嵌。

另请参阅
Updater
Applier
Composition

ComposeNode

@Composable
inline fun <T : Any?, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

T 类型的组合发出一个节点。content 内发出的节点将成为已发出的节点的子节点。

如果 E 不是 currentComposer 的 applier 的子类型,则此函数将抛出运行时异常。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
noinline factory: () -> T

一个用于创建 T 新实例的函数。不保证此函数会就地调用。

update: @DisallowComposableCalls Updater<T>.() -> Unit

用于在节点上执行更新的函数。每次执行 emit 时,此代码都会运行。此函数会就地调用并被内嵌。

content: @Composable () -> Unit

将发出此节点“子项”的可组合项内容。

另请参阅
Updater
Applier
Composition

ComposeNode

@Composable
@ExplicitGroupsComposable
inline fun <T : Any?, E : Applier<*>> ComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

T 类型的组合发出一个节点。content 内发出的节点将成为已发出的节点的子节点。

如果 E 不是 currentComposer 的 applier 的子类型,则此函数将抛出运行时异常。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
noinline factory: () -> T

一个用于创建 T 新实例的函数。不保证此函数会就地调用。

update: @DisallowComposableCalls Updater<T>.() -> Unit

用于在节点上执行更新的函数。每次执行 emit 时,此代码都会运行。此函数会就地调用并被内嵌。

noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit

用于在节点上执行更新的函数。与 update 不同,此函数是可组合函数,因此会被跳过,除非它已通过某种其他机制失效。如果要执行成本高昂的计算来更新节点,则随着时间的推移,这些计算可能会具有相同输入,因此可以跳过函数的执行。

content: @Composable () -> Unit

将发出此节点“子项”的可组合项内容。

合成

fun Composition(applier: Applier<*>, parent: CompositionContext): Composition

此方法用于启动组合。parent 可以是

  • 以使组合行为作为父级的子组合。如果组合

  • 没有父级,则应提供 Recomposer 实例。

当不再需要组合时,必须调用 Composition.dispose 才能释放资源。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
applier: Applier<*>

要在组合中使用的 Applier 实例。

parent: CompositionContext

父级 CompositionContext

合成

@ExperimentalComposeApi
fun Composition(
    applier: Applier<*>,
    parent: CompositionContext,
    recomposeCoroutineContext: CoroutineContext
): Composition

使用 applier 创建一个 Composition 来管理组合,将其作为 parent 的子级。

在支持并发重组的配置中使用时,会提示环境应该使用 recomposeCoroutineContext 执行重组。重组将启动到

CompositionLocalProvider

@Composable
fun CompositionLocalProvider(
    context: CompositionLocalContext,
    content: @Composable () -> Unit
): Unit

CompositionLocalProvider 将值绑定到 context 提供的 CompositionLocal。使用 CompositionLocal.current 读取 CompositionLocal 时,系统会针对在 content lambda 中直接或间接调用的所有可组合函数,返回存储在 context 内的值中提供的值。

import androidx.compose.runtime.CompositionLocalProvider

@Composable
fun App(user: User) {
    CompositionLocalProvider(ActiveUser provides user) {
        SomeScreen()
    }
}

CompositionLocalProvider

@Composable
fun CompositionLocalProvider(
    value: ProvidedValue<*>,
    content: @Composable () -> Unit
): Unit

CompositionLocalProvider 将值绑定到 ProvidableCompositionLocal 键。使用 CompositionLocal.current 读取 CompositionLocal 时,系统会针对在 content lambda 中直接或间接调用的所有可组合函数,返回 CompositionLocalProvidervalue 形参中提供的值。

import androidx.compose.runtime.CompositionLocalProvider

@Composable
fun App(user: User) {
    CompositionLocalProvider(ActiveUser provides user) {
        SomeScreen()
    }
}

CompositionLocalProvider

@Composable
fun CompositionLocalProvider(
    vararg values: ProvidedValue<*>,
    content: @Composable () -> Unit
): Unit

CompositionLocalProvider 会将值绑定到 ProvidableCompositionLocal 键。使用 CompositionLocal.current 读取 CompositionLocal 时,系统会针对在 content lambda 中直接或间接调用的所有可组合函数,返回 CompositionLocalProvidervalues 形参中提供的值。

import androidx.compose.runtime.CompositionLocalProvider

@Composable
fun App(user: User) {
    CompositionLocalProvider(ActiveUser provides user) {
        SomeScreen()
    }
}

控制组合

@TestOnly
fun ControlledComposition(applier: Applier<*>, parent: CompositionContext): ControlledComposition

此方法用于启动组合。或者,可以提供 parent,以使组合行为作为父级的子组合,也可以提供 Recomposer

借助受控组合,您可以直接控制组合,而不是由传递到根组合的 Recomposer 进行控制。

必须调用 Composition.dispose 才能释放资源,不再需要此合成器。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
applier: Applier<*>

要在组合中使用的 Applier 实例。

parent: CompositionContext

父级 CompositionContext

控制组合

@TestOnly
@ExperimentalComposeApi
fun ControlledComposition(
    applier: Applier<*>,
    parent: CompositionContext,
    recomposeCoroutineContext: CoroutineContext
): ControlledComposition

DisposableEffect

@Composable
@NonRestartableComposable
fun DisposableEffect(effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

组合的附带效应,如果 DisposableEffect 退出组合,必须反转或清理它。

在缺少至少一个 key 参数的情况下调用 DisposableEffect 是错误的。

DisposableEffect

@Composable
@NonRestartableComposable
fun DisposableEffect(key1: Any?, effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

组合的附带效应:必须针对 key1 的任何新唯一值运行,并且在 key1 发生变化或 DisposableEffect 退出组合时必须反转或清理。

DisposableEffect 的键是一个值,用于定义 DisposableEffect 的身份。如果某个按键发生更改,DisposableEffect 必须 dispose 其当前 effect,并通过再次调用 effect 进行重置。键的示例包括:

  • 效果订阅的可观察对象

  • 操作的唯一请求参数,如果这些参数发生更改,必须取消并重试

DisposableEffect 可用于初始化或订阅密钥,并在提供其他密钥时重新初始化,在初始化新密钥之前对旧操作执行清理操作。例如:

import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

DisposableEffect 必须在其 effect 块中包含一个 onDispose 子句作为最后一个语句。如果您的操作不需要处置,则可能是 SideEffect;如果操作启动了应由组合管理的协程,则可能是 LaunchedEffect

保证每次调用 effect 时都会对 dispose 进行一次调用。effectdispose 将始终在组合的应用调度程序上运行,且永远不会与自身并发运行、将更改应用到组合树或运行 RememberObserver 事件回调。

DisposableEffect

@Composable
@NonRestartableComposable
fun DisposableEffect(vararg keys: Any?, effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

组合的附带效应:必须针对 keys 的任何新唯一值运行,并且如有任何 keys 发生变化或 DisposableEffect 退出组合,则必须反转或清理。

DisposableEffect 的键是一个值,用于定义 DisposableEffect 的身份。如果某个按键发生更改,DisposableEffect 必须 dispose 其当前 effect,并通过再次调用 effect 进行重置。键的示例包括:

  • 效果订阅的可观察对象

  • 操作的唯一请求参数,如果这些参数发生更改,必须取消并重试

DisposableEffect 可用于初始化或订阅密钥,并在提供其他密钥时重新初始化,在初始化新密钥之前对旧操作执行清理操作。例如:

import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

DisposableEffect 必须在其 effect 块中包含一个 onDispose 子句作为最后一个语句。如果您的操作不需要处置,则可能是 SideEffect;如果操作启动了应由组合管理的协程,则可能是 LaunchedEffect

保证每次调用 effect 时都会对 dispose 进行一次调用。effectdispose 将始终在组合的应用调度程序上运行,且永远不会与自身并发运行、将更改应用到组合树或运行 RememberObserver 事件回调。

DisposableEffect

@Composable
@NonRestartableComposable
fun DisposableEffect(key1: Any?, key2: Any?, effect: DisposableEffectScope.() -> DisposableEffectResult): Unit

组合的附带效应:必须针对 key1key2 的任何新唯一值运行,并且在 key1key2 发生变化或 DisposableEffect 退出组合时必须反转或清理。

DisposableEffect 的键是一个值,用于定义 DisposableEffect 的身份。如果某个按键发生更改,DisposableEffect 必须 dispose 其当前 effect,并通过再次调用 effect 进行重置。键的示例包括:

  • 效果订阅的可观察对象

  • 操作的唯一请求参数,如果这些参数发生更改,必须取消并重试

DisposableEffect 可用于初始化或订阅密钥,并在提供其他密钥时重新初始化,在初始化新密钥之前对旧操作执行清理操作。例如:

import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

DisposableEffect 必须在其 effect 块中包含一个 onDispose 子句作为最后一个语句。如果您的操作不需要处置,则可能是 SideEffect;如果操作启动了应由组合管理的协程,则可能是 LaunchedEffect

保证每次调用 effect 时都会对 dispose 进行一次调用。effectdispose 将始终在组合的应用调度程序上运行,且永远不会与自身并发运行、将更改应用到组合树或运行 RememberObserver 事件回调。

DisposableEffect

@Composable
@NonRestartableComposable
fun DisposableEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    effect: DisposableEffectScope.() -> DisposableEffectResult
): Unit

组合的附带效应:必须针对 key1key2key3 的任何新唯一值运行,并且在 key1key2key3 发生变化或 DisposableEffect 退出组合时必须反转或清理。

DisposableEffect 的键是一个值,用于定义 DisposableEffect 的身份。如果某个按键发生更改,DisposableEffect 必须 dispose 其当前 effect,并通过再次调用 effect 进行重置。键的示例包括:

  • 效果订阅的可观察对象

  • 操作的唯一请求参数,如果这些参数发生更改,必须取消并重试

DisposableEffect 可用于初始化或订阅密钥,并在提供其他密钥时重新初始化,在初始化新密钥之前对旧操作执行清理操作。例如:

import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

DisposableEffect 必须在其 effect 块中包含一个 onDispose 子句作为最后一个语句。如果您的操作不需要处置,则可能是 SideEffect;如果操作启动了应由组合管理的协程,则可能是 LaunchedEffect

保证每次调用 effect 时都会对 dispose 进行一次调用。effectdispose 将始终在组合的应用调度程序上运行,且永远不会与自身并发运行、将更改应用到组合树或运行 RememberObserver 事件回调。

LaunchedEffect(启动效果)

@Composable
fun LaunchedEffect(block: suspend CoroutineScope.() -> Unit): Unit

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block。当 LaunchedEffect 退出组合时,协程将为 cancelled

在缺少至少一个 key 参数的情况下调用 LaunchedEffect 是错误的。

LaunchedEffect(启动效果)

@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, block: suspend CoroutineScope.() -> Unit): Unit

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block。当使用不同的 key1 重组 LaunchedEffect 时,协程将处于 cancelled 状态并重新启动。当 LaunchedEffect 退出组合时,协程将为 cancelled

此函数应用于(重新启动)启动正在进行的任务来响应回调事件,方法是将回调数据存储在传递给 key1MutableState 中。请改为参阅 rememberCoroutineScope 以获取 CoroutineScope,它可用于启动作用域限定为组合的持续作业,以响应事件回调。

LaunchedEffect(启动效果)

@Composable
@NonRestartableComposable
fun LaunchedEffect(vararg keys: Any?, block: suspend CoroutineScope.() -> Unit): Unit

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block。当使用任何不同的 keys 重组 LaunchedEffect 时,协程将处于 cancelled 状态并重新启动。当 LaunchedEffect 退出组合时,协程将为 cancelled

此函数应用于(重新启动)启动正在进行的任务来响应回调事件,方法是将回调数据存储在传递给 keyMutableState 中。请改为参阅 rememberCoroutineScope 以获取 CoroutineScope,它可用于启动作用域限定为组合的持续作业,以响应事件回调。

LaunchedEffect(启动效果)

@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, key2: Any?, block: suspend CoroutineScope.() -> Unit): Unit

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block。当使用不同的 key1key2 重组 LaunchedEffect 时,协程将处于 cancelled 状态并重新启动。当 LaunchedEffect 退出组合时,协程将为 cancelled

此函数应用于(重新启动)启动正在进行的任务来响应回调事件,方法是将回调数据存储在传递给 keyMutableState 中。请改为参阅 rememberCoroutineScope 以获取 CoroutineScope,它可用于启动作用域限定为组合的持续作业,以响应事件回调。

LaunchedEffect(启动效果)

@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, key2: Any?, key3: Any?, block: suspend CoroutineScope.() -> Unit): Unit

LaunchedEffect 进入组合时,它会在组合的 CoroutineContext 中启动 block。当使用不同的 key1key2key3 重组 LaunchedEffect 时,协程将处于 cancelled 状态并重新启动。当 LaunchedEffect 退出组合时,协程将为 cancelled

此函数应用于(重新启动)启动正在进行的任务来响应回调事件,方法是将回调数据存储在传递给 keyMutableState 中。请改为参阅 rememberCoroutineScope 以获取 CoroutineScope,它可用于启动作用域限定为组合的持续作业,以响应事件回调。

ReusableComposeNode

@Composable
inline fun <T : Any, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit
): Unit

将可回收节点发送到 T 类型的组合中。

如果 E 不是 currentComposer 的 applier 的子类型,则此函数将抛出运行时异常。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
noinline factory: () -> T

一个用于创建 T 新实例的函数。不保证此函数会就地调用。

update: @DisallowComposableCalls Updater<T>.() -> Unit

用于在节点上执行更新的函数。每次执行 emit 时,此代码都会运行。此函数会就地调用并被内嵌。

另请参阅
Updater
Applier
Composition

ReusableComposeNode

@Composable
inline fun <T : Any?, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

将可回收节点发送到 T 类型的组合中。content 内发出的节点将成为已发出的节点的子节点。

如果 E 不是 currentComposer 的 applier 的子类型,则此函数将抛出运行时异常。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
noinline factory: () -> T

一个用于创建 T 新实例的函数。不保证此函数会就地调用。

update: @DisallowComposableCalls Updater<T>.() -> Unit

用于在节点上执行更新的函数。每次执行 emit 时,此代码都会运行。此函数会就地调用并被内嵌。

content: @Composable () -> Unit

将发出此节点“子项”的可组合项内容。

另请参阅
Updater
Applier
Composition

ReusableComposeNode

@Composable
@ExplicitGroupsComposable
inline fun <T : Any?, E : Applier<*>> ReusableComposeNode(
    noinline factory: () -> T,
    update: @DisallowComposableCalls Updater<T>.() -> Unit,
    noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit,
    content: @Composable () -> Unit
): Unit

将可回收节点发送到 T 类型的组合中。content 内发出的节点将成为已发出的节点的子节点。

如果 E 不是 currentComposer 的 applier 的子类型,则此函数将抛出运行时异常。

import androidx.compose.runtime.ComposeNode
import androidx.compose.runtime.Composition
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

// Provided we have a tree with a node base type like the following
abstract class Node {
    val children = mutableListOf<Node>()
}

// We would implement an Applier class like the following, which would teach compose how to
// manage a tree of Nodes.
class NodeApplier(root: Node) : AbstractApplier<Node>(root) {
    override fun insertTopDown(index: Int, instance: Node) {
        current.children.add(index, instance)
    }

    override fun insertBottomUp(index: Int, instance: Node) {
        // Ignored as the tree is built top-down.
    }

    override fun remove(index: Int, count: Int) {
        current.children.remove(index, count)
    }

    override fun move(from: Int, to: Int, count: Int) {
        current.children.move(from, to, count)
    }

    override fun onClear() {
        root.children.clear()
    }
}

// A function like the following could be created to create a composition provided a root Node.
fun Node.setContent(
    parent: CompositionContext,
    content: @Composable () -> Unit
): Composition {
    return Composition(NodeApplier(this), parent).apply {
        setContent(content)
    }
}

// assuming we have Node sub-classes like "TextNode" and "GroupNode"
class TextNode : Node() {
    var text: String = ""
    var onClick: () -> Unit = {}
}
class GroupNode : Node()

// Composable equivalents could be created
@Composable fun Text(text: String, onClick: () -> Unit = {}) {
    ComposeNode<TextNode, NodeApplier>(::TextNode) {
        set(text) { this.text = it }
        set(onClick) { this.onClick = it }
    }
}

@Composable fun Group(content: @Composable () -> Unit) {
    ComposeNode<GroupNode, NodeApplier>(::GroupNode, {}, content)
}

// and then a sample tree could be composed:
fun runApp(root: GroupNode, parent: CompositionContext) {
    root.setContent(parent) {
        var count by remember { mutableStateOf(0) }
        Group {
            Text("Count: $count")
            Text("Increment") { count++ }
        }
    }
}
参数
noinline factory: () -> T

一个用于创建 T 新实例的函数。不保证此函数会就地调用。

update: @DisallowComposableCalls Updater<T>.() -> Unit

用于在节点上执行更新的函数。每次执行 emit 时,此代码都会运行。此函数会就地调用并被内嵌。

noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit

用于在节点上执行更新的函数。与 update 不同,此函数是可组合函数,因此会被跳过,除非它已通过某种其他机制失效。如果要执行成本高昂的计算来更新节点,则随着时间的推移,这些计算可能会具有相同输入,因此可以跳过函数的执行。

content: @Composable () -> Unit

将发出此节点“子项”的可组合项内容。

可重复使用的组合

fun ReusableComposition(applier: Applier<*>, parent: CompositionContext): ReusableComposition

此方法用于启动可重复使用的组合。可以提供 parent 以使组合行为作为父组合的子组合。如果组合没有父项,则应提供 Recomposer 实例。

当不再需要组合时,必须调用 Composition.dispose 才能释放资源。

参数
applier: Applier<*>

要在组合中使用的 Applier 实例。

parent: CompositionContext

父级 CompositionContext

ReusableContent

@Composable
inline fun ReusableContent(key: Any?, content: @Composable () -> Unit): Unit

用于将组合标记为支持回收的实用函数。如果 key 更改了组合,则组合将替换为新的组合(就像 key 一样),但会重复使用 ReusableComposeNode 发出的可重用节点。

参数
key: Any?

用于触发回收的值。如果使用不同的值重组,Composer 会创建新的组合,但会尝试重复使用可重用的节点。

content: @Composable () -> Unit

可回收的可组合项子项。

ReusableContentHost

@Composable
@ExplicitGroupsComposable
inline fun ReusableContentHost(
    active: Boolean,
    crossinline content: @Composable () -> Unit
): Unit

托管 ReusableContent 时使用的可选实用函数。如果 active 为 false,则认为内容已删除,即从组合中移除所有记住的对象,但不会移除为树生成的节点。当组合稍后变为活动状态时,可以在 ReusableContent 内容内重复使用节点,而无需任意延长记住的组合生命周期状态。

参数
active: Boolean

activetrue 时,content 正常组合。当 activefalse 时,系统会停用内容,并将所有记住的状态视为已删除,但由组合的 Applier 管理的节点不受影响。active 会变为 true,之前活跃组合中的任何可重用节点都可以重复使用。

crossinline content: @Composable () -> Unit

由此可组合项管理的可组合项内容。

副作用

@Composable
@NonRestartableComposable
@ExplicitGroupsComposable
fun SideEffect(effect: () -> Unit): Unit

effect 调度到当前组合成功完成并应用更改时运行。SideEffect 可用于对由组合管理且不受 snapshots 支持的对象应用附带效应,以免在当前组合操作失败时使这些对象处于不一致状态。

effect 将始终在组合的应用调度程序上运行,且 applier 绝不会与自身并发运行,绝不会将更改应用于组合树或运行 RememberObserver 事件回调。SideEffect 始终在 RememberObserver 事件回调之后运行。

每次重组后都会运行 SideEffect如需启动一项可能涉及多次重组的持续性任务,请参阅 LaunchedEffect。如需管理事件订阅或其他对象生命周期,请参阅 DisposableEffect

CompositionLocalOf

fun <T : Any?> compositionLocalOf(
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy(),
    defaultFactory: () -> T
): ProvidableCompositionLocal<T>

创建可使用 CompositionLocalProvider 提供的 CompositionLocal 键。在重组期间更改提供的值将导致使用 CompositionLocal.current 读取该值的 CompositionLocalProvider 内容失效。

compositionLocalOf 会创建一个 ProvidableCompositionLocal,它可用于调用 CompositionLocalProvider。与 MutableListList 类似,如果密钥以 CompositionLocal(而非 ProvidableCompositionLocal)的形式公开,则可使用 CompositionLocal.current 读取,但不会重新提供。

参数
policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy()

一项政策,用于确定 CompositionLocal 何时会被视为已更改。如需了解详情,请参阅 SnapshotMutationPolicy

defaultFactory: () -> T

值工厂,用于在未提供值时提供值。如果没有使用 CompositionLocal.current 通过组件调用方的 CompositionLocalProvider 提供任何值,就会调用此工厂。如果无法提供合理的默认值,请考虑抛出异常。

derivedStateOf

@StateFactoryMarker
fun <T : Any?> derivedStateOf(calculation: () -> T): State<T>

创建一个 State 对象,其 State.valuecalculation 的结果。计算结果将缓存,这样反复调用 State.value 不会导致多次执行 calculation,但是读取 State.value 会导致在 calculation 期间读取的所有 State 对象都被读取到当前 Snapshot 中,这意味着如果在观察上下文(例如 Composable 函数)中读取值,这将正确订阅派生的状态对象。没有变更政策的派生状态会在每次依赖项发生更改时触发更新。为避免更新时失效,请通过 derivedStateOf 重载提供合适的 SnapshotMutationPolicy

import androidx.compose.material.Text
import androidx.compose.runtime.derivedStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable fun CountDisplay(count: State<Int>) {
    Text("Count: ${count.value}")
}

@Composable fun Example() {
    var a by remember { mutableStateOf(0) }
    var b by remember { mutableStateOf(0) }
    val sum = remember { derivedStateOf { a + b } }
    // Changing either a or b will cause CountDisplay to recompose but not trigger Example
    // to recompose.
    CountDisplay(sum)
}
参数
calculation: () -> T

计算以创建此状态对象所表示的值。

derivedStateOf

@StateFactoryMarker
fun <T : Any?> derivedStateOf(
    policy: SnapshotMutationPolicy<T>,
    calculation: () -> T
): State<T>

创建一个 State 对象,其 State.valuecalculation 的结果。计算结果将缓存,这样反复调用 State.value 不会导致多次执行 calculation,但是读取 State.value 会导致在 calculation 期间读取的所有 State 对象都被读取到当前 Snapshot 中,这意味着如果在观察上下文(例如 Composable 函数)中读取值,这将正确订阅派生的状态对象。

import androidx.compose.material.Text
import androidx.compose.runtime.derivedStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable fun CountDisplay(count: State<Int>) {
    Text("Count: ${count.value}")
}

@Composable fun Example() {
    var a by remember { mutableStateOf(0) }
    var b by remember { mutableStateOf(0) }
    val sum = remember { derivedStateOf { a + b } }
    // Changing either a or b will cause CountDisplay to recompose but not trigger Example
    // to recompose.
    CountDisplay(sum)
}
参数
policy: SnapshotMutationPolicy<T>

用于控制何时触发对 calculation 结果更改的更改的变更政策。

calculation: () -> T

计算以创建此状态对象所表示的值。

isTraceInProgress

@ComposeCompilerApi
fun isTraceInProgress(): Boolean

内部跟踪 API。

应在不进行线程同步的情况下调用,且偶尔会丢失信息。

key

@Composable
inline fun <T : Any?> key(vararg keys: Any?, block: @Composable () -> T): T

key 是一个实用程序可组合项,用于对组合中的执行块进行“分组”或“设置键”。有时需要此权限才能实现控制流内的正确性,而这可能导致给定的可组合项调用在组合期间执行多次。

键的值不必是全局唯一的,只需在组合过程中的 key 调用中保持唯一值。

例如,考虑以下示例:

import androidx.compose.runtime.key

for (user in users) {
    key(user.id) { UserPreview(user = user) }
}

for (user in users.filter { isAdmin }) {
    key(user.id) { Friend(friend = user) }
}

即使顶部循环和底部循环中存在具有相同 ID 的用户,但由于他们对 key 的调用不同,因此无需创建复合键。

不过,集合中每个元素的键必须是唯一的,否则子状态和本地状态可能会被意外重用。

例如,考虑以下示例:

import androidx.compose.runtime.key

for ((child, parent) in relationships) {
    key(parent.id) {
        User(user = child)
        User(user = parent)
    }
}

此示例假定 parent.id 是集合中每一项的唯一键,但仅在合理假设父项只会有一个子项时才会如此,而事实并非如此。以下做法可能更加正确:

import androidx.compose.runtime.key

for ((child, parent) in relationships) {
    key(parent.id to child.id) {
        User(user = child)
        User(user = parent)
    }
}

可以通过传入多个参数来创建复合键:

import androidx.compose.runtime.key
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

for (element in elements) {
    val selected by key(element.id, parentId) { remember { mutableStateOf(false) } }
    ListItem(item = element, selected = selected)
}
参数
vararg keys: Any?

用于创建复合键的一组值。这些变量将与之前使用 equalshashCode 的值进行比较

block: @Composable () -> T

该组的可组合子项。

movableContentOf

fun movableContentOf(content: @Composable () -> Unit): @Composable () -> Unit

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable () -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable () -> Unit

跟踪可组合 lambda

movableContentOf

fun <P : Any?> movableContentOf(content: @Composable (P) -> Unit): @Composable (P) -> Unit

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable (P) -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable (P) -> Unit

跟踪可组合 lambda

movableContentOf

fun <P1 : Any?, P2 : Any?> movableContentOf(content: @Composable (P1, P2) -> Unit): @Composable (P1, P2) -> Unit

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable (P1, P2) -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable (P1, P2) -> Unit

跟踪可组合 lambda

movableContentOf

fun <P1 : Any?, P2 : Any?, P3 : Any?> movableContentOf(
    content: @Composable (P1, P2, P3) -> Unit
): @Composable (P1, P2, P3) -> Unit

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable (P1, P2, P3) -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable (P1, P2, P3) -> Unit

跟踪可组合 lambda

movableContentOf

fun <P1 : Any?, P2 : Any?, P3 : Any?, P4 : Any?> movableContentOf(
    content: @Composable (P1, P2, P3, P4) -> Unit
): @Composable (P1, P2, P3, P4) -> Unit

将 lambda 转换为它将记住的状态和在上次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable (P1, P2, P3, P4) -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable (P1, P2, P3, P4) -> Unit

跟踪可组合 lambda

movableContentWithReceiverOf

fun <R : Any?> movableContentWithReceiverOf(content: @Composable R.() -> Unit): @Composable R.() -> Unit

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable R.() -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable R.() -> Unit

跟踪可组合 lambda

movableContentWithReceiverOf

fun <R : Any?, P : Any?> movableContentWithReceiverOf(content: @Composable R.(P) -> Unit): @Composable R.(P) -> Unit

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable R.(P) -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable R.(P) -> Unit

跟踪可组合 lambda

movableContentWithReceiverOf

fun <R : Any?, P1 : Any?, P2 : Any?> movableContentWithReceiverOf(
    content: @Composable R.(P1, P2) -> Unit
): @Composable R.(P1, P2) -> Unit

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable R.(P1, P2) -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable R.(P1, P2) -> Unit

跟踪可组合 lambda

movableContentWithReceiverOf

fun <R : Any?, P1 : Any?, P2 : Any?, P3 : Any?> movableContentWithReceiverOf(
    content: @Composable R.(P1, P2, P3) -> Unit
): @Composable R.(P1, P2, P3) -> Unit

将带有接收器的 lambda 转换为将记住的状态和在上一次调用中创建的节点移动到它调用的新位置的 lambda。

跟踪组合可用于生成根据如下参数在行和列之间移动内容的可组合项:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val movableContent = remember(content) { movableContentOf(content) }

if (vertical) {
    Column {
        movableContent()
    }
} else {
    Row {
        movableContent()
    }
}

或者,它们可用于确保随着模型在布局中的移动而组合状态跟踪,例如

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.movableContentOf
import androidx.compose.runtime.remember

val itemMap = remember {
    mutableMapOf<Item, @Composable () -> Unit>()
}
val movableItems =
    items.map { item -> itemMap.getOrPut(item) { movableContentOf { ItemView(item) } } }

val itemsPerColumn = 10
val columns = items.size / itemsPerColumn + (if (items.size % itemsPerColumn == 0) 0 else 1)
Row {
    repeat(columns) { column ->
        Column {
            val base = column * itemsPerColumn
            val end = minOf(base + itemsPerColumn, items.size)
            for (index in base until end) {
                movableItems[index]()
            }
        }
    }
}
参数
content: @Composable R.(P1, P2, P3) -> Unit

要转换为状态跟踪 lambda 的可组合 lambda。

返回
@Composable R.(P1, P2, P3) -> Unit

跟踪可组合 lambda

mutableDoubleStateOf

@StateFactoryMarker
fun mutableDoubleStateOf(value: Double): MutableDoubleState

返回使用传入的 value 初始化的新 MutableDoubleState

MutableDoubleState 类是单个值容器,其读取和写入由 Compose 观察到。此外,对它的写入操作是 Snapshot 系统的一部分。在 JVM 上,值作为基元 double 类型存储在内存中,以避免在使用 MutableState<Double> 时发生自动装箱现象。

参数
value: Double

MutableDoubleState 的初始值

mutableFloatStateOf

@StateFactoryMarker
fun mutableFloatStateOf(value: Float): MutableFloatState

返回使用传入的 value 初始化的新 MutableFloatState

MutableFloatState 类是单个值容器,其读取和写入由 Compose 观察。此外,对它的写入操作是 Snapshot 系统的一部分。在 JVM 上,值作为基元 float 类型存储在内存中,以避免在使用 MutableState<Float> 时发生自动装箱现象。

参数
value: Float

MutableFloatState 的初始值

mutableIntStateOf

@StateFactoryMarker
fun mutableIntStateOf(value: Int): MutableIntState

返回使用传入的 value 初始化的新 MutableIntState

MutableIntState 类是单个值容器,其读取和写入由 Compose 观察。此外,对它的写入操作是 Snapshot 系统的一部分。在 JVM 上,值作为基元 int 类型存储在内存中,以避免在使用 MutableState<Int> 时发生自动装箱现象。

参数
value: Int

MutableIntState 的初始值

mutableLongStateOf

@StateFactoryMarker
fun mutableLongStateOf(value: Long): MutableLongState

返回使用传入的 value 初始化的新 MutableLongState

MutableLongState 类是单个值容器,其读取和写入由 Compose 观察。此外,对它的写入操作是 Snapshot 系统的一部分。在 JVM 上,值作为基元 long 类型存储在内存中,以避免在使用 MutableState<Long> 时发生自动装箱现象。

参数
value: Long

MutableLongState 的初始值

mutableStateListOf

@StateFactoryMarker
fun <T : Any?> mutableStateListOf(): SnapshotStateList<T>

创建一个可观察且可截取快照的 MutableList 实例。

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun Names() {
    var name by remember { mutableStateOf("user") }
    val names = remember { mutableStateListOf<String>() }

    Column {
        Row {
            BasicTextField(
                value = name,
                onValueChange = { name = it }
            )
            Button(onClick = { names.add(name) }) {
                Text("Add")
            }
        }
        Text("Added names:")
        Column {
            for (addedName in names) {
                Text(addedName)
            }
        }
    }
}

mutableStateListOf

@StateFactoryMarker
fun <T : Any?> mutableStateListOf(vararg elements: T): SnapshotStateList<T>

创建一个可观察且可截取快照的 MutableList 实例。

mutableStateMapOf

@StateFactoryMarker
fun <K : Any?, V : Any?> mutableStateMapOf(): SnapshotStateMap<K, V>

创建一个可观察且可截取快照的 MutableMap<k, v=""> 实例。</k,>

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateMapOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun NamesAndAges() {
    var name by remember { mutableStateOf("name") }
    var saying by remember { mutableStateOf("saying") }
    val sayings = remember {
        mutableStateMapOf(
            "Caesar" to "Et tu, Brute?",
            "Hamlet" to "To be or not to be",
            "Richard III" to "My kingdom for a horse"
        )
    }

    Column {
        Row {
            BasicTextField(
                value = name,
                onValueChange = { name = it }
            )
            BasicTextField(
                value = saying,
                onValueChange = { saying = it }
            )
            Button(onClick = { sayings[name] = saying }) {
                Text("Add")
            }
            Button(onClick = { sayings.remove(name) }) {
                Text("Remove")
            }
        }
        Text("Sayings:")
        Column {
            for (entry in sayings) {
                Text("${entry.key} says '${entry.value}'")
            }
        }
    }
}

mutableStateMapOf

@StateFactoryMarker
fun <K : Any?, V : Any?> mutableStateMapOf(vararg pairs: Pair<K, V>): SnapshotStateMap<K, V>

创建一个可观察且可截取快照的 MutableMap<k, v=""> 实例。</k,>

mutableStateOf

@StateFactoryMarker
fun <T : Any?> mutableStateOf(
    value: T,
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy()
): MutableState<T>

返回使用传入的 value 初始化的新 MutableState

MutableState 类是单个值容器,其读取和写入由 Compose 观察。此外,对它的写入操作是 Snapshot 系统的一部分。

import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

val count = remember { mutableStateOf(0) }

Text(text = "You clicked ${count.value} times")
Button(onClick = { count.value++ }) {
    Text("Click me")
}
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

val (count, setCount) = remember { mutableStateOf(0) }

Text(text = "You clicked $count times")
Button(onClick = { setCount(count + 1) }) {
    Text("Click me")
}
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun observeUser(userId: Int): User? {
    val user = remember(userId) { mutableStateOf<User?>(null) }
    DisposableEffect(userId) {
        val subscription = UserAPI.subscribeToUser(userId) {
            user.value = it
        }
        onDispose {
            subscription.unsubscribe()
        }
    }
    return user.value
}
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun LoginScreen() {
    var username by remember { mutableStateOf("user") }
    var password by remember { mutableStateOf("pass") }

    fun login() = Api.login(username, password)

    BasicTextField(
        value = username,
        onValueChange = { username = it }
    )
    BasicTextField(
        value = password,
        onValueChange = { password = it }
    )
    Button(onClick = { login() }) {
        Text("Login")
    }
}
参数
value: T

MutableState 的初始值

policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy()

此政策用于控制如何在可变快照中处理更改。

neverEqualPolicy

fun <T : Any?> neverEqualPolicy(): SnapshotMutationPolicy<T>

政策绝不会将 MutableState 的值视为等效值。

系统会将设置 MutableState.value 视为一项更改。应用会更改状态的 MutableSnapshot 时,将始终与更改同一状态的其他快照发生冲突。

produceState

@Composable
fun <T : Any?> produceState(initialValue: T, producer: suspend ProduceStateScope<T>.() -> Unit): State<T>

返回一个可观察的 snapshot State,它会在没有定义数据源的情况下随时间生成值。

producerproduceState 进入组合时启动,在 produceState 退出组合时取消。producer 应使用 ProduceStateScope.value 为返回的 State 设置新值。

返回的 State 会混淆值;如果使用 ProduceStateScope.valueequal 设置为旧值,则不会观察到任何变化,并且观察者可能仅在快速连续地设置多个值时看到最新值。

produceState 可用于观察挂起或非挂起的外部数据源,例如:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
    viewModel.people
        .map { UiState.Data(it) }
        .collect { value = it }
}

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data -> Column {
        for (person in state.data) {
            Text("Hello, ${person.name}")
        }
    }
}
import androidx.compose.runtime.produceState

val currentPerson by produceState<Person?>(null, viewModel) {
    val disposable = viewModel.registerPersonObserver { person ->
        value = person
    }

    awaitDispose {
        disposable.dispose()
    }
}

produceState

@Composable
fun <T : Any?> produceState(initialValue: T, key1: Any?, producer: suspend ProduceStateScope<T>.() -> Unit): State<T>

返回一个可观察的 snapshot State,它会根据 key1 随时间生成值。

producerproduceState 进入组合时启动,在 produceState 退出组合时取消。如果 key1 发生变化,系统会取消正在运行的 producer 并针对新来源重新启动它。producer 应使用 ProduceStateScope.value 为返回的 State 设置新值。

返回的 State 会混淆值;如果使用 ProduceStateScope.valueequal 设置为旧值,则不会观察到任何变化,并且观察者可能仅在快速连续地设置多个值时看到最新值。

produceState 可用于观察挂起或非挂起的外部数据源,例如:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
    viewModel.people
        .map { UiState.Data(it) }
        .collect { value = it }
}

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data -> Column {
        for (person in state.data) {
            Text("Hello, ${person.name}")
        }
    }
}
import androidx.compose.runtime.produceState

val currentPerson by produceState<Person?>(null, viewModel) {
    val disposable = viewModel.registerPersonObserver { person ->
        value = person
    }

    awaitDispose {
        disposable.dispose()
    }
}

produceState

@Composable
fun <T : Any?> produceState(
    initialValue: T,
    vararg keys: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
): State<T>

返回一个可观察的 snapshot State,它会根据 keys 随时间生成值。

producerproduceState 进入组合时启动,在 produceState 退出组合时取消。如果 keys 发生变化,系统将取消正在运行的 producer 并针对新来源重新启动它。producer 应使用 ProduceStateScope.value 为返回的 State 设置新值。

返回的 State 会混淆值;如果使用 ProduceStateScope.valueequal 设置为旧值,则不会观察到任何变化,并且观察者可能仅在快速连续地设置多个值时看到最新值。

produceState 可用于观察挂起或非挂起的外部数据源,例如:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
    viewModel.people
        .map { UiState.Data(it) }
        .collect { value = it }
}

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data -> Column {
        for (person in state.data) {
            Text("Hello, ${person.name}")
        }
    }
}
import androidx.compose.runtime.produceState

val currentPerson by produceState<Person?>(null, viewModel) {
    val disposable = viewModel.registerPersonObserver { person ->
        value = person
    }

    awaitDispose {
        disposable.dispose()
    }
}

produceState

@Composable
fun <T : Any?> produceState(
    initialValue: T,
    key1: Any?,
    key2: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
): State<T>

返回一个可观察的 snapshot State,它会根据 key1key2 随时间生成值。

producerproduceState 进入组合时启动,在 produceState 退出组合时取消。如果 key1key2 发生更改,系统会针对新来源取消正在运行的 producer 并重新启动。producer 应使用 ProduceStateScope.value 为返回的 State 设置新值。

返回的 State 会混淆值;如果使用 ProduceStateScope.valueequal 设置为旧值,则不会观察到任何变化,并且观察者可能仅在快速连续地设置多个值时看到最新值。

produceState 可用于观察挂起或非挂起的外部数据源,例如:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
    viewModel.people
        .map { UiState.Data(it) }
        .collect { value = it }
}

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data -> Column {
        for (person in state.data) {
            Text("Hello, ${person.name}")
        }
    }
}
import androidx.compose.runtime.produceState

val currentPerson by produceState<Person?>(null, viewModel) {
    val disposable = viewModel.registerPersonObserver { person ->
        value = person
    }

    awaitDispose {
        disposable.dispose()
    }
}

produceState

@Composable
fun <T : Any?> produceState(
    initialValue: T,
    key1: Any?,
    key2: Any?,
    key3: Any?,
    producer: suspend ProduceStateScope<T>.() -> Unit
): State<T>

返回一个可观察的 snapshot State,它会根据 key1key2key3 随时间生成值。

producerproduceState 进入组合时启动,在 produceState 退出组合时取消。如果 key1key2key3 发生变化,系统会取消正在运行的 producer 并针对新来源重新启动它。[提供方应使用 ProduceStateScope.value 为返回的 State 设置新值。

返回的 State 会混淆值;如果使用 ProduceStateScope.valueequal 设置为旧值,则不会观察到任何变化,并且观察者可能仅在快速连续地设置多个值时看到最新值。

produceState 可用于观察挂起或非挂起的外部数据源,例如:

import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.produceState

val uiState by produceState<UiState<List<Person>>>(UiState.Loading, viewModel) {
    viewModel.people
        .map { UiState.Data(it) }
        .collect { value = it }
}

when (val state = uiState) {
    is UiState.Loading -> Text("Loading...")
    is UiState.Data -> Column {
        for (person in state.data) {
            Text("Hello, ${person.name}")
        }
    }
}
import androidx.compose.runtime.produceState

val currentPerson by produceState<Person?>(null, viewModel) {
    val disposable = viewModel.registerPersonObserver { person ->
        value = person
    }

    awaitDispose {
        disposable.dispose()
    }
}

参考 EqualityPolicy

fun <T : Any?> referentialEqualityPolicy(): SnapshotMutationPolicy<T>

一项政策,如果 MutableState 的值引用 (===) 相等,则将它们视为等效值。

MutableState.value 设置为其当前参照 (===) 相等值不会被视为更改。应用 MutableSnapshot 时,如果快照将值更改为等效值,则父快照不会被视为冲突。

记住

@Composable
inline fun <T : Any?> remember(crossinline calculation: @DisallowComposableCalls () -> T): T

记住 calculation 生成的值。仅在组合期间评估 calculation。重组将始终返回组合生成的值。

记住

@Composable
inline fun <T : Any?> remember(
    key1: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

如果 key1 等于前一个组合,请记住 calculation 返回的值,否则通过调用 calculation 生成并记住新值。

记住

@Composable
inline fun <T : Any?> remember(
    vararg keys: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

如果 keys 的所有值都等于前一个组合,请记住 calculation 返回的值,否则通过调用 calculation 生成并记住新值。

记住

@Composable
inline fun <T : Any?> remember(
    key1: Any?,
    key2: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

如果 key1key2 等于前一个组合,请记住 calculation 返回的值;否则,通过调用 calculation 生成并记住新值。

记住

@Composable
inline fun <T : Any?> remember(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    crossinline calculation: @DisallowComposableCalls () -> T
): T

如果 key1key2key3 等于前一个组合,请记住 calculation 返回的值;否则,通过调用 calculation 生成并记住新值。

rememberCompositionContext

@Composable
fun rememberCompositionContext(): CompositionContext

用于在当前合成点构建 CompositionContext 的效果。这可用于在当前组合的上下文中运行单独的组合,从而保留 CompositionLocal 并传播失效操作。当此调用退出组合时,上下文会失效。

rememberCoroutineScope

@Composable
inline fun rememberCoroutineScope(
    crossinline getContext: @DisallowComposableCalls () -> CoroutineContext = { EmptyCoroutineContext }
): CoroutineScope

使用 getContext 提供的可选 CoroutineContext 返回绑定到组合中此位置的 CoroutineScopegetContext 将仅调用一次,并且会在重组后返回相同的 CoroutineScope 实例。

当此调用退出组合时,此作用域将为 cancelledgetContext 返回的 CoroutineContext 可能不包含 Job,因为此作用域被视为组合的子级。

如果 getContext 返回的上下文未提供此调度程序,则此作用域的默认调度程序将成为组合的 Recomposer 的应用调度程序。

使用此作用域启动作业以响应点击事件或其他用户互动等回调事件,其中对该事件的响应需要随时间展开,并且如果管理该进程的可组合项退出组合,则会被取消。绝不应将作业启动到任何协程作用域内,这是组合本身的附带效应。如需了解由组合启动且限定了作用域的持续性作业,请参阅 LaunchedEffect

如果不满足前提条件,此函数将不会抛出,因为可组合函数尚未完全支持异常。相反,返回的作用域的 CoroutineScope.coroutineContext 将包含失败的 Job 以及相关联的异常,并且无法启动子作业。

rememberUpdatedState

@Composable
fun <T : Any?> rememberUpdatedState(newValue: T): State<T>

mutableStateOf 执行 remember 操作,并在每次重组 rememberUpdatedState 调用时将其值更新为 newValue

如果长期存在的 lambda 或对象表达式引用了在组合期间计算的参数或值,则应使用 rememberUpdatedState。重组将更新生成的 State,而不会重新创建长期存在的 lambda 或对象,从而允许该对象继续存在,而无需取消和重新订阅,也无需重新启动长期存在的操作,这些操作的重新创建和重启可能开销很高或难以执行。使用 DisposableEffectLaunchedEffect 时,这可能很常见,例如:

import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.rememberUpdatedState

@Composable
fun EventHandler(dispatcher: Dispatcher, onEvent: () -> Unit) {
    val currentOnEvent by rememberUpdatedState(onEvent)

    // Event handlers are ordered and a new onEvent should not cause us to re-register,
    // losing our position in the dispatcher.
    DisposableEffect(dispatcher) {
        val disposable = dispatcher.addListener {
            // currentOnEvent will always refer to the latest onEvent function that
            // the EventHandler was recomposed with
            currentOnEvent()
        }
        onDispose {
            disposable.dispose()
        }
    }
}

LaunchedEffect 通常用于描述在参数或事件回调发生更改时不应重置和重启的状态机,但它们应在需要时具有当前值。例如:

import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.rememberUpdatedState

@Composable
fun NotificationHost(state: NotificationState, onTimeout: (Notification) -> Unit) {
    val currentOnTimeout by rememberUpdatedState(onTimeout)

    state.currentNotification?.let { currentNotification ->
        LaunchedEffect(currentNotification) {
            // We should not restart this delay if onTimeout changes, but we want to call
            // the onTimeout we were last recomposed with when it completes.
            delay(NotificationTimeout)
            currentOnTimeout(currentNotification)
        }
    }

    // ...
}

通过使用 rememberUpdatedState,可组合函数可以更新正在进行的操作。

snapshotFlow

fun <T : Any?> snapshotFlow(block: () -> T): Flow<T>

根据可观察的 Snapshot 状态创建 Flow。(例如,mutableStateOf 返回的状态容器。)

snapshotFlow 会创建一个 Flow,它会在收集时运行 block 并发出结果,以记录所访问的任何快照状态。在收集继续期间,如果应用新的 Snapshot 会更改 block 访问的状态,则数据流将再次运行 block,从而重新记录所访问的快照状态。如果 block 的结果不是 equal to 前一个结果,则 flow 将发出该新结果。(此行为类似于 Flow.distinctUntilChanged 的行为。)除非被明确取消,或因使用其他 Flow 运算符而对其进行限制,否则收集将无限期地继续。

import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.snapshotFlow

// Define Snapshot state objects
var greeting by mutableStateOf("Hello")
var person by mutableStateOf("Adam")

// ...

// Create a flow that will emit whenever our person-specific greeting changes
val greetPersonFlow = snapshotFlow { "$greeting, $person" }

// ...

val collectionScope: CoroutineScope = TODO("Use your scope here")

// Collect the flow and offer greetings!
collectionScope.launch {
    greetPersonFlow.collect {
        println(greeting)
    }
}

// ...

// Change snapshot state; greetPersonFlow will emit a new greeting
Snapshot.withMutableSnapshot {
    greeting = "Ahoy"
    person = "Sean"
}

block只读 Snapshot 中运行,可能不会修改快照数据。如果 block 尝试修改快照数据,数据流收集将失败并显示 IllegalStateException

对于相同的输入集,block 可能会运行多次,或者在多次快速更改快照后仅运行一次;它应该具有幂等性且没有副作用。

使用 Snapshot 状态时,记住事件和状态之间的区别非常有用。snapshotFlow 将快照变化建模为事件,但事件无法有效地建模为可观察状态。可观察状态是对生成该状态的事件进行有损压缩。

可观察的事件会在某个时间点发生,并被舍弃。在事件发生时注册的所有观察者都会收到通知。数据流中的所有单个事件都被认为是相关的,并且可能是彼此相连的事件;重复的平等事件是有意义的,因此注册的观察者必须观察所有事件而不跳过。

当状态从一个值更改为不相等的新值时,可观察状态会引发更改事件。状态更改事件会被混淆;只有最新的状态才是重要的状态。因此,状态变化的观察者必须具有幂等性;在相同的状态值下,观察者应产生相同的结果。状态观察器可以跳过中间状态,也可以针对同一状态多次运行,并且结果应相同。

sourceInformation

@ComposeCompilerApi
fun sourceInformation(composer: Composer, sourceInformation: String): Unit

Compose 内部函数。请勿直接致电。

记录可用于工具确定相应可组合函数源位置的来源信息。默认情况下,此函数声明为没有任何副作用。代码缩减工具(如 R8 或 ProGuard)可以安全地将其移除。

sourceInformationMarkerEnd

@ComposeCompilerApi
fun sourceInformationMarkerEnd(composer: Composer): Unit

Compose 内部函数。请勿直接致电。

记录来源信息标记的结尾,该标记可用于确定相应可组合函数(如 ReadOnlyComposable 函数)原本不需要跟踪信息的相应可组合函数的来源位置。默认情况下,此函数声明为没有任何副作用。代码缩减工具(如 R8 或 ProGuard)可以安全地将其移除。

请务必同时移除 sourceInformationMarkerStartsourceInformationMarkerEnd,或同时移除二者。仅移除其中一项将会导致运行时行为不正确。

sourceInformationMarkerStart

@ComposeCompilerApi
fun sourceInformationMarkerStart(
    composer: Composer,
    key: Int,
    sourceInformation: String
): Unit

Compose 内部函数。请勿直接致电。

记录来源信息标记的开头,该工具可用于确定相应可组合函数(原本不需要跟踪信息,例如 ReadOnlyComposable 函数)的来源位置。默认情况下,此函数声明为没有任何副作用。代码缩减工具(如 R8 或 ProGuard)可以安全地将其移除。

请务必同时移除 sourceInformationMarkerStartsourceInformationMarkerEnd,或同时移除二者。仅移除其中一项将会导致运行时行为不正确。

staticCompositionLocalOf

fun <T : Any?> staticCompositionLocalOf(defaultFactory: () -> T): ProvidableCompositionLocal<T>

创建可使用 CompositionLocalProvider 提供的 CompositionLocal 键。

compositionLocalOf 不同,Compose 不会跟踪 staticCompositionLocalOf 的读取,并且更改 CompositionLocalProvider 调用中提供的值将导致重组整个内容,而不仅仅是重组局部值在组合中的使用位置。不过,由于缺少跟踪,当提供的值不太可能或永远不会更改时,这会使 staticCompositionLocalOf 的效率更高。例如,对于 CompositionLocalProvider 内容中的组件,Android 上下文、字体加载器或类似共享值不太可能会发生变化,应考虑使用 staticCompositionLocalOf。颜色或其他主题(如值)可能会发生变化,甚至可能会添加动画效果,因此应使用 compositionLocalOf

staticCompositionLocalOf 会创建一个 ProvidableCompositionLocal,它可用于调用 CompositionLocalProvider。与 MutableListList 类似,如果密钥以 CompositionLocal(而非 ProvidableCompositionLocal)的形式公开,则可使用 CompositionLocal.current 读取,但不会重新提供。

参数
defaultFactory: () -> T

值工厂,用于在未提供值时提供值。如果没有使用 CompositionLocal.current 通过组件调用方的 CompositionLocalProvider 提供任何值,就会调用此工厂。如果无法提供合理的默认值,请考虑抛出异常。

structuralEqualityPolicy

fun <T : Any?> structuralEqualityPolicy(): SnapshotMutationPolicy<T>

此政策旨在将 MutableState 的值在结构 (==) 相等的情况下视为等效值。

MutableState.value 设置为当前在结构上 (==) 相等的值不被视为更改。应用 MutableSnapshot 时,如果快照将值更改为等效值,则父快照不会被视为冲突。

traceEventEnd

@ComposeCompilerApi
fun traceEventEnd(): Unit

内部跟踪 API。

应在不进行线程同步的情况下调用,且偶尔会丢失信息。

traceEventStart

@ComposeCompilerApi
fun traceEventStart(key: Int, dirty1: Int, dirty2: Int, info: String): Unit

内部跟踪 API。

应在不进行线程同步的情况下调用,且偶尔会丢失信息。

参数
dirty1: Int

$dirty 元数据:强制重组和函数参数 1..10(如果存在)

dirty2: Int

$dirty2 元数据:强制重组和函数参数 11..20(如果存在)

withFrameMillis

suspend fun <R : Any?> withFrameMillis(onFrame: (frameTimeMillis: Long) -> R): R

挂起,直到请求新帧为止,在帧的调用上下文中立即使用帧时间(以毫秒为单位)调用 onFrame,然后恢复并返回 onFrame 的结果。

在计算每一帧的动画时间增量时,应使用 frameTimeMillis,因为它可能会标准化为帧的目标时间,而不一定是直接的“现在”值。

MonotonicFrameClock.withFrameMillis 所提供值的时间基准由实现定义。提供的时间值单调递增;对 withFrameMillis 的调用完成后,不得为后续调用提供较小的值。

此函数将使用调用方 CoroutineContextMonotonicFrameClock 调用 MonotonicFrameClock.withFrameNanos;如果 CoroutineContext 中不存在相应值,该函数会抛出 IllegalStateException

withFrameNanos

suspend fun <R : Any?> withFrameNanos(onFrame: (frameTimeNanos: Long) -> R): R

挂起,直到请求新帧为止,在帧调度的调用上下文中立即使用帧时间(以纳秒为单位)调用 onFrame,然后恢复为 onFrame 的结果。

在计算每一帧的动画时间增量时,应使用 frameTimeNanos,因为它可能会标准化为帧的目标时间,而不一定是直接的“现在”值。

withFrameNanos 所提供值的时间基准由实现定义。提供的时间值严格单调递增;在对 withFrameNanos 的调用完成后,不得为后续调用再次提供相同的值。

此函数将使用调用方 CoroutineContextMonotonicFrameClock 调用 MonotonicFrameClock.withFrameNanos;如果 CoroutineContext 中不存在相应值,该函数会抛出 IllegalStateException

withRunningRecomposer

suspend fun <R : Any?> withRunningRecomposer(block: suspend CoroutineScope.(recomposer: Recomposer) -> R): R

使用新的活跃 Recomposer 运行 block,并在调用 CoroutineContext 中应用更改。在 block 返回后,Recomposer 将为 closed。当 RecomposerRecomposer.State.ShutDownblock 启动的所有子作业都具有 joined 后,withRunningRecomposer 将返回。

扩展函数

asDoubleState

fun State<Double>.asDoubleState(): DoubleState

State<Double>(例如,由盒装 Double 组成的 State)转换为由基元支持的 Double。状态将自动开箱为所需的基元类型。返回的状态为只读。返回的状态将镜像基本状态的值,并以接收器定义的方式应用更新。

在 JVM 上,此转换不会避免 Double 尝试转义的自动装箱,而是旨在允许在使用任一 Double 类型状态表示法的组件之间实现互操作性。

asFloatState

fun State<Float>.asFloatState(): FloatState

State<Float>(例如,由盒装 Float 组成的 State)转换为由基元支持的 Float。状态将自动开箱为所需的基元类型。返回的状态为只读。返回的状态将镜像基本状态的值,并以接收器定义的方式应用更新。

在 JVM 上,此转换不会避免 Float 尝试转义的自动装箱,而是旨在允许在使用任一 Float 类型状态表示法的组件之间实现互操作性。

asIntState

fun State<Int>.asIntState(): IntState

State<Int>(例如,由盒装 Int 组成的 State)转换为由基元支持的 IntState。状态将自动开箱为所需的基元类型。返回的状态为只读。返回的状态将镜像基本状态的值,并以接收器定义的方式应用更新。

在 JVM 上,此转换不会避免 IntState 尝试转义的自动装箱,而是旨在允许在使用任一 Int 类型状态表示法的组件之间实现互操作性。

asLongState

fun State<Long>.asLongState(): LongState

State<Long>(例如,由盒装 Long 组成的 State)转换为由基元支持的 LongState。状态将自动开箱为所需的基元类型。返回的状态为只读。返回的状态将镜像基本状态的值,并以接收器定义的方式应用更新。

在 JVM 上,此转换不会避免 LongState 尝试转义的自动装箱,而是旨在允许在使用任一 Long 类型状态表示法的组件之间实现互操作性。

缓存

@ComposeCompilerApi
inline fun <T : Any?> Composer.cache(
    invalid: Boolean,
    block: @DisallowComposableCalls () -> T
): T

Compose 编译器插件 API。请勿直接致电。

缓存,也就是记住,组合数据中的一个值。它用于实现 remember,并供编译器插件在确定这些优化是安全的时生成对 remember 的更高效的调用。

collectionAsState

@Composable
fun <T : Any?> StateFlow<T>.collectAsState(
    context: CoroutineContext = EmptyCoroutineContext
): State<T>

从此 StateFlow 收集值,并通过 State 表示其最新值。StateFlow.value 用作初始值。每次向 StateFlow 发布新值时,返回的 State 都会更新,这会导致所有 State.value 用法重组。

import androidx.compose.material.Text
import androidx.compose.runtime.collectAsState

val value: String by stateFlow.collectAsState()
Text("Value is $value")
参数
context: CoroutineContext = EmptyCoroutineContext

用于收集数据的 CoroutineContext

collectionAsState

@Composable
fun <T : R, R : Any?> Flow<T>.collectAsState(
    initial: R,
    context: CoroutineContext = EmptyCoroutineContext
): State<R>

从此 Flow 收集值,并通过 State 表示其最新值。每次向 Flow 发布新值时,返回的 State 都会更新,这会导致所有 State.value 用法重组。

import androidx.compose.material.Text
import androidx.compose.runtime.collectAsState

val value: String by flow.collectAsState("initial")
Text("Value is $value")
参数
context: CoroutineContext = EmptyCoroutineContext

用于收集数据的 CoroutineContext

getValue

inline operator fun DoubleState.getValue(thisObj: Any?, property: KProperty<*>): Double

允许使用 DoubleStatebyval 进行属性委托。

getValue

inline operator fun FloatState.getValue(thisObj: Any?, property: KProperty<*>): Float

允许使用 FloatStatebyval 进行属性委托。

getValue

inline operator fun IntState.getValue(thisObj: Any?, property: KProperty<*>): Int

允许使用 IntStatebyval 进行属性委托。

getValue

inline operator fun LongState.getValue(thisObj: Any?, property: KProperty<*>): Long

允许使用 LongStatebyval 进行属性委托。

getValue

inline operator fun <T : Any?> State<T>.getValue(thisObj: Any?, property: KProperty<*>): T

允许使用 Statebyval 进行属性委托。

import androidx.compose.foundation.layout.Row
import androidx.compose.material.Text

// Composable function that manages a subscription to a data source, returning it as State
@Composable
fun observeSampleData(): State<String> = TODO()

// Subscription is managed here, but currentValue is not read yet
val currentValue by observeSampleData()

Row {
    // This scope will recompose when currentValue changes
    Text("Data: $currentValue")
}

setValue

inline operator fun MutableDoubleState.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: Double
): Unit

允许使用 MutableDoubleStatebyvar 进行属性委托。

setValue

inline operator fun MutableFloatState.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: Float
): Unit

允许使用 MutableFloatStatebyvar 进行属性委托。

setValue

inline operator fun MutableIntState.setValue(thisObj: Any?, property: KProperty<*>, value: Int): Unit

允许使用 MutableIntStatebyvar 进行属性委托。

setValue

inline operator fun MutableLongState.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: Long
): Unit

允许使用 MutableLongStatebyvar 进行属性委托。

setValue

inline operator fun <T : Any?> MutableState<T>.setValue(
    thisObj: Any?,
    property: KProperty<*>,
    value: T
): Unit

允许使用 MutableStatebyvar 进行属性委托。

import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

var count by remember { mutableStateOf(0) }

Text(text = "You clicked $count times")
Button(onClick = { count = count + 1 }) {
    Text("Click me")
}

toMutableStateList

fun <T : Any?> Collection<T>.toMutableStateList(): SnapshotStateList<T>

从可观察且可截取快照的集合中创建 MutableList 的实例。

toMutableStateMap

fun <K : Any?, V : Any?> Iterable<Pair<K, V>>.toMutableStateMap(): SnapshotStateMap<K, V>

从一组可观察且可截取快照的对中创建一个 MutableMap<k, v=""> 实例。</k,>

withFrameMillis

suspend inline fun <R : Any?> MonotonicFrameClock.withFrameMillis(
    crossinline onFrame: (frameTimeMillis: Long) -> R
): R

挂起,直到请求新帧为止,在帧的调用上下文中立即使用帧时间(以毫秒为单位)调用 onFrame,然后恢复并返回 onFrame 的结果。

在计算每一帧的动画时间增量时,应使用 frameTimeMillis,因为它可能会标准化为帧的目标时间,而不一定是直接的“现在”值。

MonotonicFrameClock.withFrameMillis 所提供值的时间基准由实现定义。提供的时间值单调递增;对 withFrameMillis 的调用完成后,不得为后续调用提供较小的值。

顶层属性

DefaultMonotonicFrameClock

val DefaultMonotonicFrameClockMonotonicFrameClock

withFrameNanoswithFrameMillis 使用的 MonotonicFrameClock(如果调用 kotlin.coroutines.CoroutineContext 中不存在)。

Compose 运行时不再使用此值。

currentComposer

val currentComposerComposer

TODO(lmr):提供文档

currentCompositeKeyHash

val currentCompositeKeyHashInt

这是一个哈希值,用于将外部存储的状态映射到组合。例如,保存的实例状态会使用该属性来跨 activity 生命周期边界保留状态。

此值可能是唯一的,但不保证是唯一的。还存在一些已知的情况,例如没有 key 的 for 循环,即运行时没有足够的信息来使复合键哈希具有唯一性。

currentCompositionLocalContext

val currentCompositionLocalContextCompositionLocalContext

返回当前的 CompositionLocalContext,其中包含当前组合中的所有 CompositionLocal 及其由 CompositionLocalProvider 提供的值。此上下文可用于通过 CompositionLocalProvider 将局部变量传递给另一个组合。如果其他组合不是当前组合的子组合,通常需要此属性。

currentRecomposeScope

val currentRecomposeScopeRecomposeScope

返回一个对象,该对象可用于在组合的这一时间点使当前作用域失效。该对象可用于手动导致重组。

扩展属性

monotonicFrameClock

@ExperimentalComposeApi
val CoroutineContext.monotonicFrameClockMonotonicFrameClock

返回此 CoroutineContextMonotonicFrameClock,如果不存在,则抛出 IllegalStateException

recomposeCoroutineContext

@ExperimentalComposeApi
val ControlledComposition.recomposeCoroutineContextCoroutineContext

在支持并发组合的环境中使用时,应该用于对此 ControlledComposition 执行并发重组的 CoroutineContext

如需了解如何配置此类环境,请参阅 Recomposer.runRecomposeConcurrentlyAndApplyChanges