androidx.compose.runtime
本頁面提供 androidx.compose.runtime 套件中可用的類型、屬性和函式相關說明文件。例如：
-
狀態 API，例如
State、remember、mutableStateOf和collectAsState。 -
連帶效果 API，例如
LaunchedEffect和SideEffect。 -
協同程式相關 API，例如
rememberCoroutineScope和snapshotFlow。 -
CompositionLocalAPI，例如compositionLocalOf。 -
組合相關 API，例如
Composition、Recomposer、ComposeNode和RecomposeScope。 -
時鐘 API，例如
MonotonicFrameClock、withFrameMillis、 -
特定註解，例如
Composable和Stable。
如果您想要瞭解相關指引，請參閱下列 Compose 指南：
介面
類別
AbstractApplier |
抽象 |
CM
|
AtomicReference |
CM
|
|
BroadcastFrameClock |
簡單的影格時鐘。 |
CM
|
CompositionContext |
|
CM
|
CompositionLocal |
Compose 會透過參數將資料明確傳遞到可組合函式。 |
CM
|
CompositionLocalContext |
儲存 |
CM
|
DisposableEffectScope |
|
CM
|
MovableContent |
Compose 編譯器外掛程式 API。 |
CM
|
MovableContentState |
Compose 編譯器外掛程式 API。 |
CM
|
MovableContentStateReference |
Compose 編譯器外掛程式 API。 |
CM
|
PausableMonotonicFrameClock |
可 |
CM
|
ProvidableCompositionLocal |
在 |
CM
|
ProvidedValue |
此執行個體可保留 |
CM
|
Recomposer |
執行重組作業，並將更新套用至一或多個 |
CM
|
SkippableUpdater |
CM
|
|
Updater |
|
CM
|
物品
註解
CheckResult |
CM
Android
|
|
Composable |
|
CM
|
ComposableInferredTarget |
Compose 編譯器外掛程式產生的註解。 |
CM
|
ComposableOpenTarget |
|
CM
|
ComposableTarget |
已宣告 |
CM
|
ComposableTargetMarker |
您可以使用 |
CM
|
ComposeCompilerApi |
CM
|
|
DisallowComposableCalls |
這樣一來，可組合的呼叫就不會在其套用的函式中發出。 |
CM
|
ExperimentalComposeApi |
CM
|
|
ExperimentalComposeRuntimeApi |
CM
|
|
ExplicitGroupsComposable |
您可以將此註解套用至 |
CM
|
Immutable |
|
CM
|
InternalComposeApi |
CM
|
|
InternalComposeTracingApi |
CM
|
|
NoLiveLiterals |
這個註解用於向 Compose Compiler 指示，不會在其套用的宣告範圍內嘗試產生即時常值，即使已開啟即時常值程式碼產生功能亦然。 |
CM
|
NonRestartableComposable |
此註解可以套用至 |
CM
|
ReadOnlyComposable |
您可以將此註解套用至 |
CM
|
Stable |
穩定版可用來向 Compose 編譯器傳達特定類型或函式的行為。 |
CM
|
StableMarker |
|
CM
|
TestOnly |
CM
|
列舉
Recomposer.State |
|
CM
|
頂層函式摘要
inline Unit |
@Composable將節點發送至 |
CM
|
inline Unit |
@Composable將節點發送至 |
CM
|
inline Unit |
@Composable將節點發送至 |
CM
|
Composition |
Composition(applier: Applier<*>, parent: CompositionContext)這個方法是啟動組合的方式。 |
CM
|
Composition |
@ExperimentalComposeApi使用 |
CM
|
Unit |
@Composable
|
CM
|
Unit |
@Composable
|
CM
|
Unit |
@Composable
|
CM
|
ControlledComposition |
@TestOnly這個方法是啟動組合的方式。 |
CM
|
ControlledComposition |
@TestOnly |
CM
|
Unit |
@Composable此函式已淘汰不用。DisposableEffect 必須提供一或多個定義 DisposableEffect 的「key」參數，並決定何時應處置先前的效果，以及為新金鑰啟動新的「效果」。 |
CM
|
Unit |
@Composable組合的副作用，必須針對任何新的 |
CM
|
Unit |
@Composable組合的副作用，必須針對任何新的 |
CM
|
Unit |
@Composable組合的副作用，必須針對任何新不重複值 |
CM
|
Unit |
@Composable組合的副作用，必須針對任何新不重複值 |
CM
|
Unit |
@Composable此函式已淘汰不用。LaunchedEffect 必須提供一或多個定義 LaunchedEffect 的「key」參數，並判斷何時應取消其先前的「作用」協同程式，並啟動新金鑰的新效果。 |
CM
|
Unit |
@Composable當 |
CM
|
Unit |
@Composable當 |
CM
|
Unit |
@Composable當 |
CM
|
Unit |
@Composable當 |
CM
|
inline Unit |
@Composable將可回收節點發送至 |
CM
|
inline Unit |
@Composable將可回收節點發送至 |
CM
|
inline Unit |
@Composable將可回收節點發送至 |
CM
|
ReusableComposition |
ReusableComposition(applier: Applier<*>, parent: CompositionContext)這種方法是啟動可重複使用的組合的方式。 |
CM
|
inline Unit |
@Composable這是將樂曲標示為輔助回收的公用程式函式。 |
CM
|
inline Unit |
@Composable託管 |
CM
|
Unit |
@Composable排定 |
CM
|
ProvidableCompositionLocal<T> |
<T : Any?> compositionLocalOf(建立可使用 |
CM
|
State<T> |
@StateFactoryMarker建立 |
CM
|
State<T> |
@StateFactoryMarker建立 |
CM
|
Boolean |
內部追蹤 API。 |
CM
|
inline T |
@Composable
|
CM
|
@Composable () -> Unit |
movableContentOf(content: @Composable () -> Unit)將 lambda 轉換為一個 lambda，其中將記憶的狀態和在上一個呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable (P) -> Unit |
<P : Any?> movableContentOf(content: @Composable (P) -> Unit)將 lambda 轉換為一個 lambda，其中將記憶的狀態和在上一個呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable (P1, P2) -> Unit |
<P1 : Any?, P2 : Any?> movableContentOf(content: @Composable (P1, P2) -> Unit)將 lambda 轉換為一個 lambda，其中將記憶的狀態和在上一個呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable (P1, P2, P3) -> Unit |
<P1 : Any?, P2 : Any?, P3 : Any?> movableContentOf(將 lambda 轉換為一個 lambda，其中將記憶的狀態和在上一個呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable (P1, P2, P3, P4) -> Unit |
<P1 : Any?, P2 : Any?, P3 : Any?, P4 : Any?> movableContentOf(將 lambda 轉換為一個 lambda，其中將記憶的狀態和在上一個呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable R.() -> Unit |
<R : Any?> movableContentWithReceiverOf(content: @Composable R.() -> Unit)將含有接收器的 lambda 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable R.(P) -> Unit |
<R : Any?, P : Any?> movableContentWithReceiverOf(content: @Composable R.(P) -> Unit)將含有接收器的 lambda 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable R.(P1, P2) -> Unit |
<R : Any?, P1 : Any?, P2 : Any?> movableContentWithReceiverOf(將含有接收器的 lambda 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。 |
CM
|
@Composable R.(P1, P2, P3) -> Unit |
<R : Any?, P1 : Any?, P2 : Any?, P3 : Any?> movableContentWithReceiverOf(將含有接收器的 lambda 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。 |
CM
|
MutableDoubleState |
傳回使用 |
CM
|
MutableFloatState |
傳回使用 |
CM
|
MutableIntState |
@StateFactoryMarker傳回使用 |
CM
|
MutableLongState |
@StateFactoryMarker傳回使用 |
CM
|
SnapshotStateList<T> |
@StateFactoryMarker建立可觀察且可為快照的 |
CM
|
SnapshotStateList<T> |
@StateFactoryMarker建立可觀察且可為快照的 |
CM
|
SnapshotStateMap<K, V> |
@StateFactoryMarker建立可觀察且可以是快照的 |
CM
|
SnapshotStateMap<K, V> |
@StateFactoryMarker建立可觀察且可以是快照的 |
CM
|
MutableState<T> |
@StateFactoryMarker傳回使用 |
CM
|
SnapshotMutationPolicy<T> |
<T : Any?> neverEqualPolicy()政策不會將 |
CM
|
State<T> |
@Composable |
CM
|
State<T> |
@Composable |
CM
|
State<T> |
@Composable |
CM
|
State<T> |
@Composable |
CM
|
State<T> |
@Composable |
CM
|
SnapshotMutationPolicy<T> |
<T : Any?> referentialEqualityPolicy()如果 |
CM
|
inline T |
@Composable記住 |
CM
|
inline T |
@Composable記住 |
CM
|
inline T |
@Composable記住 |
CM
|
inline T |
@Composable記住 |
CM
|
inline T |
@Composable請記住 |
CM
|
CompositionContext |
可在組合目前點建構 |
CM
|
inline CoroutineScope |
@Composable使用 |
CM
|
State<T> |
@Composable
|
CM
|
Flow<T> |
<T : Any?> snapshotFlow(block: () -> T) |
CM
|
Unit |
@ComposeCompilerApiCompose 內部函式。 |
CM
|
Unit |
@ComposeCompilerApiCompose 內部函式。 |
CM
|
Unit |
@ComposeCompilerApiCompose 內部函式。 |
CM
|
ProvidableCompositionLocal<T> |
<T : Any?> staticCompositionLocalOf(defaultFactory: () -> T)建立可使用 |
CM
|
SnapshotMutationPolicy<T> |
<T : Any?> structuralEqualityPolicy()如果 |
CM
|
Unit |
內部追蹤 API。 |
CM
|
Unit |
@ComposeCompilerApi內部追蹤 API。 |
CM
|
suspend R |
<R : Any?> withFrameMillis(onFrame: (frameTimeMillis: Long) -> R)暫停，直到要求新影格為止，立即在分派影格的呼叫結構定義中，以毫秒為單位叫用 |
CM
|
suspend R |
<R : Any?> withFrameNanos(onFrame: (frameTimeNanos: Long) -> R)暫停，直到要求新影格為止，立即在分派影格的呼叫結構定義中，以奈秒為單位透過影格時間叫用 |
CM
|
suspend R |
<R : Any?> withRunningRecomposer(block: suspend CoroutineScope.(recomposer: Recomposer) -> R)使用新的 |
CM
|
擴充功能函式摘要
DoubleState |
CM
|
|
FloatState |
CM
|
|
IntState |
State<Int>.asIntState() |
CM
|
LongState |
State<Long>.asLongState() |
CM
|
inline T |
@ComposeCompilerApiCompose 編譯器外掛程式 API。 |
CM
|
State<T> |
@Composable |
CM
|
State<R> |
@Composable |
CM
|
inline operator Double |
DoubleState.getValue(thisObj: Any?, property: KProperty<*>)允許 |
CM
|
inline operator Float |
FloatState.getValue(thisObj: Any?, property: KProperty<*>)允許 |
CM
|
inline operator Int |
允許 |
CM
|
inline operator Long |
允許 |
CM
|
inline operator T |
允許 |
CM
|
inline operator Unit |
MutableDoubleState.setValue(允許 |
CM
|
inline operator Unit |
MutableFloatState.setValue(允許 |
CM
|
inline operator Unit |
MutableIntState.setValue(thisObj: Any?, property: KProperty<*>, value: Int)允許 |
CM
|
inline operator Unit |
MutableLongState.setValue(允許 |
CM
|
inline operator Unit |
<T : Any?> MutableState<T>.setValue(允許 |
CM
|
SnapshotStateList<T> |
<T : Any?> Collection<T>.toMutableStateList()從可觀測且可為快照的集合建立 |
CM
|
SnapshotStateMap<K, V> |
<K : Any?, V : Any?> Iterable<Pair<K, V>>.toMutableStateMap()從一組可觀察且可以是快照的組合中建立 |
CM
|
suspend inline R |
<R : Any?> MonotonicFrameClock.withFrameMillis(暫停，直到要求新影格為止，立即在分派影格的呼叫結構定義中，以毫秒為單位叫用 |
CM
|
頂層房源摘要
MonotonicFrameClock |
此屬性已淘汰。MonotonicFrameClocks 不適用於全球跨平台。 |
CM
Android
|
Composer |
TODO(lmr)：提供文件 |
CM
|
Int |
這個雜湊值用於將外部儲存的狀態對應至組合。 |
CM
|
CompositionLocalContext |
傳回目前的 |
CM
|
RecomposeScope |
傳回可用於在組合中撤銷目前範圍的物件。 |
CM
|
額外資訊屬性摘要
MonotonicFrameClock |
傳回這個 |
CM
|
CoroutineContext |
在支援並行組合的環境中使用時，此 |
CM
|
頂層函式
ComposeNode
@Composable
inline fun <T : Any, E : Applier<*>> ComposeNode(
noinline factory: () -> T,
update: @DisallowComposableCalls Updater<T>.() -> Unit
): Unit
將節點發送至 T 類型的組合中。
如果 E 不是 currentComposer 套用應用程式的子類型，這個函式就會擲回執行階段例外狀況。
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 |
這個函式將建立新的 |
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 套用應用程式的子類型，這個函式就會擲回執行階段例外狀況。
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 |
這個函式將建立新的 |
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 套用應用程式的子類型，這個函式就會擲回執行階段例外狀況。
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 |
這個函式將建立新的 |
update: @DisallowComposableCalls Updater<T>.() -> Unit |
在節點上執行更新的函式。這個指令會在每次執行 emit 時執行。系統會隨即呼叫這個函式，並以內嵌方式進行呼叫。 |
noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit |
在節點上執行更新的函式。與 |
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<*> |
要用於組合的 |
parent: CompositionContext |
| 另請參閱 | |
|---|---|
Applier |
|
Composition |
|
Recomposer |
樂曲
@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 會將值繫結至 CompositionLocal (由 context 提供)。使用 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 中直接或間接呼叫的所有可組合函式，傳回 CompositionLocalProvider 的 value 參數中提供的值。
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 中直接或間接呼叫的所有可組合函式，傳回 CompositionLocalProvider 的 values 參數中提供的值。
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 這個 Composer 來釋出資源。
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<*> |
要用於組合的 |
parent: CompositionContext |
| 另請參閱 | |
|---|---|
Applier |
|
Composition |
|
Recomposer |
受控組合
@TestOnly
@ExperimentalComposeApi
fun ControlledComposition(
applier: Applier<*>,
parent: CompositionContext,
recomposeCoroutineContext: CoroutineContext
): ControlledComposition
DisposableEffect
@Composable
@NonRestartableComposable
funDisposableEffect(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 必須包含 onDispose 子句做為其 effect 區塊中的最終陳述式。如果作業不需要處置，則可能是 SideEffect；如果作業啟動的協同程式應由該組合管理，則可能是 LaunchedEffect。
保證每次呼叫 effect 時都會對 dispose 發出一次呼叫。effect 和 dispose 一律必須在組合的套用調度工具上執行，且套用器不得與自身同時執行、將變更套用至組合樹狀結構，或執行 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 必須包含 onDispose 子句做為其 effect 區塊中的最終陳述式。如果作業不需要處置，則可能是 SideEffect；如果作業啟動的協同程式應由該組合管理，則可能是 LaunchedEffect。
保證每次呼叫 effect 時都會對 dispose 發出一次呼叫。effect 和 dispose 一律必須在組合的套用調度工具上執行，且套用器不得與自身同時執行、將變更套用至組合樹狀結構，或執行 RememberObserver 事件回呼。
DisposableEffect
@Composable
@NonRestartableComposable
fun DisposableEffect(key1: Any?, key2: Any?, effect: DisposableEffectScope.() -> DisposableEffectResult): Unit
組合的副作用，必須針對任何新不重複值 key1 或 key2 執行，且當 key1 或 key2 變更，或者 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 必須包含 onDispose 子句做為其 effect 區塊中的最終陳述式。如果作業不需要處置，則可能是 SideEffect；如果作業啟動的協同程式應由該組合管理，則可能是 LaunchedEffect。
保證每次呼叫 effect 時都會對 dispose 發出一次呼叫。effect 和 dispose 一律必須在組合的套用調度工具上執行，且套用器不得與自身同時執行、將變更套用至組合樹狀結構，或執行 RememberObserver 事件回呼。
DisposableEffect
@Composable
@NonRestartableComposable
fun DisposableEffect(
key1: Any?,
key2: Any?,
key3: Any?,
effect: DisposableEffectScope.() -> DisposableEffectResult
): Unit
組合的副作用，必須針對任何新不重複值 key1、key2 或 key3 執行，且當 key1、key2 或 key3 變更，或 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 必須包含 onDispose 子句做為其 effect 區塊中的最終陳述式。如果作業不需要處置，則可能是 SideEffect；如果作業啟動的協同程式應由該組合管理，則可能是 LaunchedEffect。
保證每次呼叫 effect 時都會對 dispose 發出一次呼叫。effect 和 dispose 一律必須在組合的套用調度工具上執行，且套用器不得與自身同時執行、將變更套用至組合樹狀結構，或執行 RememberObserver 事件回呼。
推出效果
@Composable
funLaunchedEffect(block: suspend CoroutineScope.() -> Unit): Unit
當 LaunchedEffect 輸入組合時，它會在組合的 CoroutineContext 中啟動 block。當 LaunchedEffect 離開組合時，協同程式會 cancelled。
在沒有至少一個 key 參數的情況下呼叫 LaunchedEffect 會發生錯誤。
推出效果
@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, block: suspend CoroutineScope.() -> Unit): Unit
當 LaunchedEffect 輸入組合時，它會在組合的 CoroutineContext 中啟動 block。使用不同的 key1 重新組成 LaunchedEffect 時，協同程式將會 cancelled，並重新啟動。當 LaunchedEffect 離開組合時，協同程式會 cancelled。
這個函式「不應」用來藉由將回呼資料儲存在傳送至 key1 的 MutableState 中，藉此 (重新啟動) 以回應回呼事件。請改為參閱 rememberCoroutineScope 以取得 CoroutineScope，以用於啟動受組合為範圍的持續工作，以回應事件回呼。
推出效果
@Composable
@NonRestartableComposable
fun LaunchedEffect(vararg keys: Any?, block: suspend CoroutineScope.() -> Unit): Unit
當 LaunchedEffect 輸入組合時，它會在組合的 CoroutineContext 中啟動 block。使用任何不同的 keys 重組 LaunchedEffect 時，協同程式將會 cancelled，並重新啟動。當 LaunchedEffect 離開組合時，協同程式會 cancelled。
這個函式「不應」用來藉由將回呼資料儲存在傳送至 key 的 MutableState 中，藉此 (重新啟動) 以回應回呼事件。請改為參閱 rememberCoroutineScope 以取得 CoroutineScope，以用於啟動受組合為範圍的持續工作，以回應事件回呼。
推出效果
@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, key2: Any?, block: suspend CoroutineScope.() -> Unit): Unit
當 LaunchedEffect 輸入組合時，它會在組合的 CoroutineContext 中啟動 block。使用不同的 key1 或 key2 重新組成 LaunchedEffect 時，協同程式將會 cancelled 並重新啟動。當 LaunchedEffect 離開組合時，協同程式會 cancelled。
這個函式「不應」用來藉由將回呼資料儲存在傳送至 key 的 MutableState 中，藉此 (重新啟動) 以回應回呼事件。請改為參閱 rememberCoroutineScope 以取得 CoroutineScope，以用於啟動受組合為範圍的持續工作，以回應事件回呼。
推出效果
@Composable
@NonRestartableComposable
fun LaunchedEffect(key1: Any?, key2: Any?, key3: Any?, block: suspend CoroutineScope.() -> Unit): Unit
當 LaunchedEffect 輸入組合時，它會在組合的 CoroutineContext 中啟動 block。使用不同的 key1、key2 或 key3 重新組合 LaunchedEffect 時，協同程式將會 cancelled，並重新啟動。當 LaunchedEffect 離開組合時，協同程式會 cancelled。
這個函式「不應」用來藉由將回呼資料儲存在傳送至 key 的 MutableState 中，藉此 (重新啟動) 以回應回呼事件。請改為參閱 rememberCoroutineScope 以取得 CoroutineScope，以用於啟動受組合為範圍的持續工作，以回應事件回呼。
可重複使用的 ComposeNode
@Composable
inline fun <T : Any, E : Applier<*>> ReusableComposeNode(
noinline factory: () -> T,
update: @DisallowComposableCalls Updater<T>.() -> Unit
): Unit
將可回收節點發送至 T 類型的組合中。
如果 E 不是 currentComposer 套用應用程式的子類型，這個函式就會擲回執行階段例外狀況。
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 |
這個函式將建立新的 |
update: @DisallowComposableCalls Updater<T>.() -> Unit |
在節點上執行更新的函式。這個指令會在每次執行 emit 時執行。系統會隨即呼叫這個函式，並以內嵌方式進行呼叫。 |
| 另請參閱 | |
|---|---|
Updater |
|
Applier |
|
Composition |
可重複使用的 ComposeNode
@Composable
inline fun <T : Any?, E : Applier<*>> ReusableComposeNode(
noinline factory: () -> T,
update: @DisallowComposableCalls Updater<T>.() -> Unit,
content: @Composable () -> Unit
): Unit
將可回收節點發送至 T 類型的組合中。在 content 內發出的節點，會成為發出的節點的子項。
如果 E 不是 currentComposer 套用應用程式的子類型，這個函式就會擲回執行階段例外狀況。
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 |
這個函式將建立新的 |
update: @DisallowComposableCalls Updater<T>.() -> Unit |
在節點上執行更新的函式。這個指令會在每次執行 emit 時執行。系統會隨即呼叫這個函式，並以內嵌方式進行呼叫。 |
content: @Composable () -> Unit |
會發送此節點「子項」的可組合內容。 |
| 另請參閱 | |
|---|---|
Updater |
|
Applier |
|
Composition |
可重複使用的 ComposeNode
@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 套用應用程式的子類型，這個函式就會擲回執行階段例外狀況。
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 |
這個函式將建立新的 |
update: @DisallowComposableCalls Updater<T>.() -> Unit |
在節點上執行更新的函式。這個指令會在每次執行 emit 時執行。系統會隨即呼叫這個函式，並以內嵌方式進行呼叫。 |
noinline skippableUpdate: @Composable SkippableUpdater<T>.() -> Unit |
在節點上執行更新的函式。與 |
content: @Composable () -> Unit |
會發送此節點「子項」的可組合內容。 |
可重複使用的組合
fun ReusableComposition(applier: Applier<*>, parent: CompositionContext): ReusableComposition
這種方法是啟動可重複使用的組合的方式。提供 parent，讓組合行為成為父項的子組合。如果組合沒有父項，則必須提供 Recomposer 執行個體。
當不再需要組合時，請務必呼叫 Composition.dispose 以釋出資源。
| 參數 | |
|---|---|
applier: Applier<*> |
要用於組合的 |
parent: CompositionContext |
可重複使用的內容
@Composable
inline fun ReusableContent(key: Any?, content: @Composable () -> Unit): Unit
這是將樂曲標示為輔助回收的公用程式函式。如果 key 變更組合，就會以新的組合取代 (與 key 相同)，但會重複使用 ReusableComposeNode 發出的可重複使用節點。
| 參數 | |
|---|---|
key: Any? |
用於觸發回收機制的值。如果使用不同的值進行重組，Compose 會建立新的組合，但嘗試重複使用可重複使用的節點。 |
content: @Composable () -> Unit |
可以回收的可組合項子項 |
可重複使用的內容主機
@Composable
@ExplicitGroupsComposable
inline fun ReusableContentHost(
active: Boolean,
crossinline content: @Composable () -> Unit
): Unit
託管 ReusableContent 時使用的選用公用程式函式。如果 active 為 false，系統會從組合中移除所有記憶物件，將內容視為已刪除，但不會移除為樹狀結構產生的節點。當組合生效後，節點就能在 ReusableContent 內容中重複使用，而不需任意延長組合生命週期所記錄的狀態。
副作用
@Composable
@NonRestartableComposable
@ExplicitGroupsComposable
fun SideEffect(effect: () -> Unit): Unit
排定 effect，在目前的組合成功完成時執行並套用變更。SideEffect 可用於對不受 snapshots 支援的組合管理的物件套用副作用，以免在目前的組合作業失敗時，讓這些物件處於不一致的狀態。
effect 一律會在組合的套用調度工具上執行，且應用程式不得彼此並行執行、將變更套用至組合樹狀結構，或執行 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。與 MutableList 和 List 類似，如果金鑰是以 CompositionLocal (而非 ProvidableCompositionLocal) 設為公開，可以使用 CompositionLocal.current 讀取，但不會重新提供。
| 參數 | |
|---|---|
policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy() |
判定 |
defaultFactory: () -> T |
在未提供值時用於提供值的值工廠。如未使用 |
derivedStateOf
@StateFactoryMarker
fun <T : Any?> derivedStateOf(calculation: () -> T): State<T>
建立 State 物件，其 State.value 為 calculation 的結果。系統會快取計算結果，讓重複呼叫 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.value 為 calculation 的結果。系統會快取計算結果，讓重複呼叫 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: () -> T |
計算此狀態物件所代表的值的計算結果。 |
isTraceInProgress
@ComposeCompilerApi
fun isTraceInProgress(): Boolean
內部追蹤 API。
應在不同步處理執行緒的情況下呼叫，且偶爾會遺失資訊。
金鑰
@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? |
|
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 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。
追蹤組合可用來產生可組合項，根據參數在資料列和資料欄之間移動內容，例如：
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 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。
追蹤組合可用來產生可組合項，根據參數在資料列和資料欄之間移動內容，例如：
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 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。
追蹤組合可用來產生可組合項，根據參數在資料列和資料欄之間移動內容，例如：
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 轉換為一種含有接收器的狀態，並將先前呼叫中建立的狀態和在先前呼叫中建立的節點移至呼叫的新位置。
追蹤組合可用來產生可組合項，根據參數在資料列和資料欄之間移動內容，例如：
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 |
可變動的 DoubleStateOf
@StateFactoryMarker
fun mutableDoubleStateOf(value: Double): MutableDoubleState
傳回使用 value 中傳遞的新 MutableDoubleState 初始化的新 MutableDoubleState
MutableDoubleState 類別是單一值容器，它會由 Compose 觀察到讀取和寫入。此外，對物件的寫入作業會以 Snapshot 系統的一部分進行交易。在 JVM 上，值會以原始 double 類型儲存在記憶體中，避免使用 MutableState<Double> 時發生的自動黑邊功能。
| 參數 | |
|---|---|
value: Double |
|
可變動的浮點數
@StateFactoryMarker
fun mutableFloatStateOf(value: Float): MutableFloatState
傳回使用 value 中傳遞的新 MutableFloatState 初始化的新 MutableFloatState
MutableFloatState 類別是單一值容器，Compose 會觀察讀取和寫入作業。此外，對物件的寫入作業會以 Snapshot 系統的一部分進行交易。在 JVM 上，值會以原始 float 類型儲存在記憶體中，避免使用 MutableState<Float> 時發生的自動黑邊功能。
| 參數 | |
|---|---|
value: Float |
|
mutableIntStateOf
@StateFactoryMarker
fun mutableIntStateOf(value: Int): MutableIntState
傳回使用 value 中傳遞的新 MutableIntState 初始化的新 MutableIntState
MutableIntState 類別是單一值容器，Compose 會觀察讀取和寫入作業。此外，對物件的寫入作業會以 Snapshot 系統的一部分進行交易。在 JVM 上，值會以原始 int 類型儲存在記憶體中，避免使用 MutableState<Int> 時發生的自動黑邊功能。
| 參數 | |
|---|---|
value: Int |
|
可變動的 LongStateOf
@StateFactoryMarker
fun mutableLongStateOf(value: Long): MutableLongState
傳回使用 value 中傳遞的新 MutableLongState 初始化的新 MutableLongState
MutableLongState 類別是單一值容器，Compose 會觀察讀取和寫入作業。此外，對物件的寫入作業會以 Snapshot 系統的一部分進行交易。在 JVM 上，值會以原始 long 類型儲存在記憶體中，避免使用 MutableState<Long> 時發生的自動黑邊功能。
| 參數 | |
|---|---|
value: Long |
|
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
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 |
|
policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy() |
這項政策可控管可變動快照處理變更的方式。 |
noEqualPolicy
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 值。
當 produceState 進入組合時，producer 會啟動，並在 produceState 離開組合時取消。producer 應該使用 ProduceStateScope.value，在傳回的 State 上設定新值。
傳回的 State 會合併值。如果使用 ProduceStateScope.value 將 equal 設為舊值，則不會觀察到任何變更，且觀察器只有在快速連續設定多個值的情況下，才會看到最新的值。
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>
傳回從 key1 產生隨時間變化的可觀察 snapshot State。
當 produceState 進入組合時，producer 會啟動，並在 produceState 離開組合時取消。如果 key1 有所變更，系統會取消執行中的 producer，並重新啟動新來源的執行作業。producer 應該使用 ProduceStateScope.value，在傳回的 State 上設定新值。
傳回的 State 會合併值。如果使用 ProduceStateScope.value 將 equal 設為舊值，則不會觀察到任何變更，且觀察器只有在快速連續設定多個值的情況下，才會看到最新的值。
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>
傳回從 keys 產生隨時間變化的可觀察 snapshot State。
當 produceState 進入組合時，producer 會啟動，並在 produceState 離開組合時取消。如果 keys 變更，系統會取消執行中的 producer，並重新啟動新來源的執行中。producer 應該使用 ProduceStateScope.value，在傳回的 State 上設定新值。
傳回的 State 會合併值。如果使用 ProduceStateScope.value 將 equal 設為舊值，則不會觀察到任何變更，且觀察器只有在快速連續設定多個值的情況下，才會看到最新的值。
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>
傳回從 key1 和 key2 長期產生值的可觀察 snapshot State。
當 produceState 進入組合時，producer 會啟動，並在 produceState 離開組合時取消。如果 key1 或 key2 有所變更，系統會取消執行中的 producer，並重新啟動新來源的執行作業。producer 應該使用 ProduceStateScope.value，在傳回的 State 上設定新值。
傳回的 State 會合併值。如果使用 ProduceStateScope.value 將 equal 設為舊值，則不會觀察到任何變更，且觀察器只有在快速連續設定多個值的情況下，才會看到最新的值。
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>
傳回從 key1、key2 和 key3 長期產生值的可觀察 snapshot State。
當 produceState 進入組合時，producer 會啟動，並在 produceState 離開組合時取消。如果 key1、key2 或 key3 有所變更，系統會取消執行中的 producer，並重新啟動新來源的執行作業。[生產端應使用 ProduceStateScope.value 在傳回的 State 上設定新值。
傳回的 State 會合併值。如果使用 ProduceStateScope.value 將 equal 設為舊值，則不會觀察到任何變更，且觀察器只有在快速連續設定多個值的情況下，才會看到最新的值。
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()
}
}
ReferenceentialEqualityPolicy
fun <T : Any?> referentialEqualityPolicy(): SnapshotMutationPolicy<T>
如果 MutableState 的值在意指 (===) 相同，則這項政策會將該值視為相等。
將 MutableState.value 設為目前的參照值 (===) 不等於變更。套用 MutableSnapshot 時，如果快照將值變更為父項快照的同等值，並不會視為衝突。
remember
@Composable
inline fun <T : Any?> remember(crossinline calculation: @DisallowComposableCalls () -> T): T
記住 calculation 產生的值。系統只會在組合期間評估 calculation。重組程序一律會傳回組合產生的值。
remember
@Composable
inline fun <T : Any?> remember(
key1: Any?,
crossinline calculation: @DisallowComposableCalls () -> T
): T
記住 key1 等於前一個組合時 calculation 傳回的值，否則呼叫 calculation 即可產生並記住新的值。
remember
@Composable
inline fun <T : Any?> remember(
vararg keys: Any?,
crossinline calculation: @DisallowComposableCalls () -> T
): T
記住 calculation 傳回的值，如果 keys 的所有值都等於先前組合，否則呼叫 calculation 即可產生並記住新的值。
remember
@Composable
inline fun <T : Any?> remember(
key1: Any?,
key2: Any?,
crossinline calculation: @DisallowComposableCalls () -> T
): T
記住 key1 和 key2 等於前一個組合時 calculation 傳回的值，否則呼叫 calculation 即可產生並記住新的值。
remember
@Composable
inline fun <T : Any?> remember(
key1: Any?,
key2: Any?,
key3: Any?,
crossinline calculation: @DisallowComposableCalls () -> T
): T
請記住 calculation 傳回的值，如果 key1、key2 和 key3 等於先前的組合，否則呼叫 calculation 會產生並記住新的值。
rememberCompositionContext
@Composable
fun rememberCompositionContext(): CompositionContext
可在組合目前點建構 CompositionContext 的特效。這可用於在目前組合的結構定義下執行獨立的組合，並保留 CompositionLocal 及傳播無效值。當這個呼叫離開組合時，背景資訊就會失效。
rememberCoroutineScope
@Composable
inline fun rememberCoroutineScope(
crossinline getContext: @DisallowComposableCalls () -> CoroutineContext = { EmptyCoroutineContext }
): CoroutineScope
使用 getContext 提供的選用 CoroutineContext，傳回繫結至組合中這個點的 CoroutineScope。系統只會呼叫 getContext 一次，且會在重新組成後傳回相同的 CoroutineScope 例項。
當這個呼叫離開組合時，這個範圍將是 cancelled。getContext 傳回的 CoroutineContext 可能不會包含 Job，因為這個範圍被視為組合的子項。
如果 getContext 傳回的結構定義未提供內容，這個範圍的預設調度工具將為套用組合的 Recomposer 的調度工具。
使用這個範圍來啟動工作以回應回呼事件，例如點擊或其他使用者互動，其中事件的回應需要隨時間展開，而管理程序的可組合項離開組合時，請取消。您不應在「任何」協同程式範圍內啟動工作，這是組合本身的副作用。如要瞭解由組合啟動的限定範圍工作，請參閱 LaunchedEffect。
如果並未符合先決條件，就不會擲回這個函式，因為可組合函式尚未完全支援例外狀況。而是傳回範圍的 CoroutineScope.coroutineContext 會包含失敗的 Job，包含相關的例外狀況，而且無法啟動子工作。
rememberUpdatedState
@Composable
fun <T : Any?> rememberUpdatedState(newValue: T): State<T>
remember 是 mutableStateOf，並在每次重新組成 rememberUpdatedState 呼叫時將其值更新為 newValue。
如果長期存在的 lambda 或物件運算式參照組合期間計算的參數或值，則應使用 rememberUpdatedState。重組程序會更新產生的 State，而不會重新建立長效的 lambda 或物件，允許該物件在不取消並重新訂閱的情況下繼續，或是重新啟動長期作業，這類作業可能會耗費大量成本或禁止重新建立及重新啟動。使用 DisposableEffect 或 LaunchedEffect 時可能會發生這種情況，例如：
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.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 模型會根據事件變更快照，但事件「無法」有效模擬為可觀測狀態。可觀測狀態指的是產生該狀態的事件有損壓縮。
可觀測的事件會在某個時間點發生，且系統會捨棄該事件。事件發生當下所有已註冊的觀察器都會收到通知。系統會將串流中的所有個別事件視為相關，且可能會彼此建構；重複相同的事件具有意義，因此已註冊的觀察器必須觀察所有事件，而不會略過。
可觀察的 state 會在狀態從某個值變更為不相等的新值時引發變更事件。狀態變更事件會繫結；只有最新的狀態很重要。因此，狀態變更的觀察者必須為「冪等」；如果狀態值相同，觀察器應會產生相同的結果。狀態觀察器可以同時略過中繼狀態，以及針對相同狀態多次執行，而且結果應該要相同。
來源資訊
@ComposeCompilerApi
fun sourceInformation(composer: Composer, sourceInformation: String): Unit
Compose 內部函式。請勿直接致電。
記錄來源資訊，方便工具判斷對應可組合函式的來源位置。根據預設，此函式會宣告為沒有副作用。可以放心移除程式碼縮減工具 (例如 R8 或 ProGuard)。
sourceInformationMarkerEnd
@ComposeCompilerApi
fun sourceInformationMarkerEnd(composer: Composer): Unit
Compose 內部函式。請勿直接致電。
記錄來源資訊標記的結尾，工具可用來判斷對應可組合函式 (原本不需要追蹤資訊 (例如 ReadOnlyComposable 函式)) 的來源位置。根據預設，此函式會宣告為沒有副作用。可以放心移除程式碼縮減工具 (例如 R8 或 ProGuard)。
請注意，同時移除 sourceInformationMarkerStart 和 sourceInformationMarkerEnd，或同時保留兩者。如果只移除一個應用程式，執行階段行為會不正確。
sourceInformationMarkerStart
@ComposeCompilerApi
fun sourceInformationMarkerStart(
composer: Composer,
key: Int,
sourceInformation: String
): Unit
Compose 內部函式。請勿直接致電。
記錄來源資訊標記的開頭，這項工具可用來判斷對應可組合函式 (原本不需要追蹤資訊 (例如 ReadOnlyComposable 函式)) 的來源位置。根據預設，此函式會宣告為沒有副作用。可以放心移除程式碼縮減工具 (例如 R8 或 ProGuard)。
請注意，同時移除 sourceInformationMarkerStart 和 sourceInformationMarkerEnd，或同時保留兩者。如果只移除一個應用程式，執行階段行為會不正確。
staticCompositionLocalOf
fun <T : Any?> staticCompositionLocalOf(defaultFactory: () -> T): ProvidableCompositionLocal<T>
建立可使用 CompositionLocalProvider 提供的 CompositionLocal 金鑰。
與 compositionLocalOf 不同，Compose 不會追蹤 staticCompositionLocalOf 的讀取作業，而且變更 CompositionLocalProvider 呼叫中提供的值會導致整個內容經過重組，而不僅僅是在組合中使用本機值的位置。不過，由於缺少追蹤功能，所以提供的值不可能變動或永遠不會變動時，staticCompositionLocalOf 的效率會更高。舉例來說，Android 結構定義、字型載入器或類似的共用值不太可能變更 CompositionLocalProvider 內容中的元件，因此建議使用 staticCompositionLocalOf。顏色或其他主題 (例如值) 可能會變更，甚至是動畫，因此請使用 compositionLocalOf。
staticCompositionLocalOf 會建立 ProvidableCompositionLocal，可用於呼叫 CompositionLocalProvider。與 MutableList 和 List 類似，如果金鑰是以 CompositionLocal (而非 ProvidableCompositionLocal) 設為公開，可以使用 CompositionLocal.current 讀取，但不會重新提供。
| 參數 | |
|---|---|
defaultFactory: () -> T |
在未提供值時用於提供值的值工廠。如未使用 |
structuralEqualityPolicy
fun <T : Any?> structuralEqualityPolicy(): SnapshotMutationPolicy<T>
如果 MutableState 的值在結構上 (==) 相同，就將這個值視為相等的政策。
將 MutableState.value 設為目前的結構 (==) 等值不算是變更。套用 MutableSnapshot 時，如果快照將值變更為父項快照的同等值，並不會視為衝突。
traceEventStart
@ComposeCompilerApi
fun traceEventStart(key: Int, dirty1: Int, dirty2: Int, info: String): Unit
內部追蹤 API。
應在不同步處理執行緒的情況下呼叫，且偶爾會遺失資訊。
withFrameMillis
suspend fun <R : Any?> withFrameMillis(onFrame: (frameTimeMillis: Long) -> R): R
暫停，直到要求新影格為止，立即在分派影格的呼叫結構定義中，以毫秒為單位叫用 onFrame，然後根據 onFrame 的結果繼續執行。
frameTimeMillis在計算每個影格的動畫時間差異時，都應使用，因為該值可能會正規化為影格的目標時間，不一定是直接「現在」值。
MonotonicFrameClock.withFrameMillis 提供的值的時間基準已定義。提供的時間值單調遞增；呼叫 withFrameMillis 後，後續呼叫的數值不得較小的值。
這個函式會使用呼叫的 CoroutineContext 的 MonotonicFrameClock 來叫用 MonotonicFrameClock.withFrameNanos，如果 CoroutineContext 中沒有出現，則系統會擲回 IllegalStateException。
withFrameNanos
suspend fun <R : Any?> withFrameNanos(onFrame: (frameTimeNanos: Long) -> R): R
暫停，直到要求新影格為止，立即在分派影格的呼叫結構定義中，以奈秒為單位透過影格時間叫用 onFrame，然後繼續執行來自 onFrame 的結果。
frameTimeNanos在計算每個影格的動畫時間差異時，都應使用，因為該值可能會正規化為影格的目標時間，不一定是直接「現在」值。
withFrameNanos 提供的值的時間基準已定義。提供的時間值嚴格遞增；呼叫 withFrameNanos 後，無法在後續呼叫中再次提供相同的值。
這個函式會使用呼叫的 CoroutineContext 的 MonotonicFrameClock 來叫用 MonotonicFrameClock.withFrameNanos，如果 CoroutineContext 中沒有出現，則系統會擲回 IllegalStateException。
搭配 RunningRecomposer
suspend fun <R : Any?> withRunningRecomposer(block: suspend CoroutineScope.(recomposer: Recomposer) -> R): R
使用新的 Recomposer 執行 block，這會套用呼叫 CoroutineContext 中的變更。Recomposer 將於 block 傳回後 closed。當 Recomposer 為 Recomposer.State.ShutDown 且 block 啟動的所有子項工作都有 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 |
|
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 |
|
getValue
inline operator fun DoubleState.getValue(thisObj: Any?, property: KProperty<*>): Double
允許 DoubleState 使用 by 對 val 進行屬性委派。
getValue
inline operator fun FloatState.getValue(thisObj: Any?, property: KProperty<*>): Float
允許 FloatState 使用 by 對 val 進行屬性委派。
getValue
inline operator fun IntState.getValue(thisObj: Any?, property: KProperty<*>): Int
允許 IntState 使用 by 對 val 進行屬性委派。
getValue
inline operator fun LongState.getValue(thisObj: Any?, property: KProperty<*>): Long
允許 LongState 使用 by 對 val 進行屬性委派。
getValue
inline operator fun <T : Any?> State<T>.getValue(thisObj: Any?, property: KProperty<*>): T
允許 State 使用 by 對 val 進行屬性委派。
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")
}
設定值
inline operator fun MutableDoubleState.setValue(
thisObj: Any?,
property: KProperty<*>,
value: Double
): Unit
允許 MutableDoubleState 使用 by 對 var 進行屬性委派。
設定值
inline operator fun MutableFloatState.setValue(
thisObj: Any?,
property: KProperty<*>,
value: Float
): Unit
允許 MutableFloatState 使用 by 對 var 進行屬性委派。
設定值
inline operator fun MutableIntState.setValue(thisObj: Any?, property: KProperty<*>, value: Int): Unit
允許 MutableIntState 使用 by 對 var 進行屬性委派。
設定值
inline operator fun MutableLongState.setValue(
thisObj: Any?,
property: KProperty<*>,
value: Long
): Unit
允許 MutableLongState 使用 by 對 var 進行屬性委派。
設定值
inline operator fun <T : Any?> MutableState<T>.setValue(
thisObj: Any?,
property: KProperty<*>,
value: T
): Unit
允許 MutableState 使用 by 對 var 進行屬性委派。
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 DefaultMonotonicFrameClock: MonotonicFrameClock
withFrameNanos 和 withFrameMillis 使用的 MonotonicFrameClock (如果呼叫 kotlin.coroutines.CoroutineContext 中沒有)。
Compose 執行階段已不再使用這個值。
currentCompositeKeyHash
val currentCompositeKeyHash: Int
這個雜湊值用於將外部儲存的狀態對應至組合。舉例來說，已儲存的例項狀態會使用此值，將狀態保留在活動生命週期邊界內。
這個值可以重複，但不保證能獲得不重複值。有些已知的情況 (例如沒有 key 的迴圈)，該執行階段的資訊不足，導致複合金鑰雜湊不重複。
currentCompositionLocalContext
val currentCompositionLocalContext: CompositionLocalContext
傳回目前的 CompositionLocalContext，其中包含目前組合中的所有 CompositionLocal，以及其由 CompositionLocalProvider 提供的值。這個結構定義可透過 CompositionLocalProvider 將本機傳遞到另一個組合。如果其他組合不是目前組合的子組合，通常就需要這麼做。
擴充功能屬性
MonotonicFrameClock
@ExperimentalComposeApi
val CoroutineContext.monotonicFrameClock: MonotonicFrameClock
傳回這個 CoroutineContext 的 MonotonicFrameClock；如果沒有，則擲回 IllegalStateException。
recomposeCoroutineContext
@ExperimentalComposeApi
val ControlledComposition.recomposeCoroutineContext: CoroutineContext
在支援並行組合的環境中使用時，此 CoroutineContext 應用於執行這個 ControlledComposition 的並行重組。
如需設定這類環境的範例，請參閱 Recomposer.runRecomposeConcurrentlyAndApplyChanges。