Compose 提供許多內建常見行為的修飾符,但您也可以建立自訂修飾符。
修飾符包含多個部分:
- 修飾符工廠
- 這是
Modifier
的擴充功能函式,可為修飾符提供慣用的 API,並讓修飾符可輕鬆鏈結在一起。修飾符工廠會產生 Compose 用來修改 UI 的修飾符元素。
- 這是
- 修飾符元素
- 您可以在這裡實作修飾符的行為。
視所需的功能而定,您可以透過多種方式實作自訂修飾符。實作自訂修飾符最簡單的方式,通常就是實作自訂修飾符工廠,並結合其他已定義的修飾符工廠。如果需要更多自訂行為,請使用 Modifier.Node
API 實作修飾符元素。這類 API 較低層級,但更有彈性。
鏈結現有修飾符
通常只要使用現有的修飾符來建立自訂修飾符。舉例來說,Modifier.clip()
是使用 graphicsLayer
修飾符實作。這項策略會使用現有的修飾符元素,您可以自行提供自訂修飾符工廠。
在實作自己的自訂修飾符前,請確認您是否能使用相同的策略。
fun Modifier.clip(shape: Shape) = graphicsLayer(shape = shape, clip = true)
或者,如果您經常重複使用同一組修飾符,也可以將其納入自己的修飾符中:
fun Modifier.myBackground(color: Color) = padding(16.dp) .clip(RoundedCornerShape(8.dp)) .background(color)
使用可組合修飾符工廠建立自訂修飾符
您也可以使用可組合函式建立自訂修飾符,將值傳遞至現有的修飾符。這就是所謂的可組合修飾符工廠。
使用可組合輔助鍵建立修飾符時,您也可以使用更高層級的 Compose API,例如 animate*AsState
和其他 Compose 狀態支援的動畫 API。舉例來說,下列程式碼片段顯示的修飾符會在啟用/停用時,加上 Alpha 變更的動畫效果:
@Composable fun Modifier.fade(enable: Boolean): Modifier { val alpha by animateFloatAsState(if (enable) 0.5f else 1.0f) return this then Modifier.graphicsLayer { this.alpha = alpha } }
如果自訂修飾符是方便從 CompositionLocal
提供預設值的方法,最簡單的做法是使用可組合修飾符工廠:
@Composable fun Modifier.fadedBackground(): Modifier { val color = LocalContentColor.current return this then Modifier.background(color.copy(alpha = 0.5f)) }
這種做法有一些詳細說明。
修飾符工廠的呼叫站點已解析 CompositionLocal
值
使用可組合修飾符工廠建立自訂修飾符時,組合本機會從建立時所在的組合樹狀結構中取得 (而非使用)。這可能會導致非預期的結果。舉例來說,以上述組合本機修飾符範例為例,使用可組合函式實作方式略有不同:
@Composable fun Modifier.myBackground(): Modifier { val color = LocalContentColor.current return this then Modifier.background(color.copy(alpha = 0.5f)) } @Composable fun MyScreen() { CompositionLocalProvider(LocalContentColor provides Color.Green) { // Background modifier created with green background val backgroundModifier = Modifier.myBackground() // LocalContentColor updated to red CompositionLocalProvider(LocalContentColor provides Color.Red) { // Box will have green background, not red as expected. Box(modifier = backgroundModifier) } } }
如果這不符合預期修飾符的運作方式,請改用自訂 Modifier.Node
,因為組合本機值會在使用網站上正確解析,且可以安全提升。
系統絕不會略過可組合函式修飾符
可組合函式絕對不會略過,因為您無法略過含有回傳值的可組合函式。這表示每次重組時都會呼叫修飾符函式,如果經常重組,可能相當昂貴。
您必須在可組合函式中呼叫可組合函式修飾符
與所有可組合函式一樣,可組合函式必須在組合內呼叫。這項限制會限制修飾符可以提升的位置,因為修飾符絕不會從組合中提升。相較之下,非可組合函式工廠可以從可組合函式中提升,以便更輕鬆地重複使用及提升效能:
val extractedModifier = Modifier.background(Color.Red) // Hoisted to save allocations @Composable fun Modifier.composableModifier(): Modifier { val color = LocalContentColor.current.copy(alpha = 0.5f) return this then Modifier.background(color) } @Composable fun MyComposable() { val composedModifier = Modifier.composableModifier() // Cannot be extracted any higher }
使用 Modifier.Node
實作自訂修飾符行為
Modifier.Node
是較低層級的 API,可在 Compose 中建立修飾符。這與 Compose 實作自身修飾符的 API 是相同的,也是建立自訂修飾符最有效率的方法。
使用 Modifier.Node
實作自訂修飾符
使用 Modifier.Node 實作自訂修飾符可分為三個部分:
- 保存修飾符邏輯和狀態的
Modifier.Node
實作。 - 建立及更新修飾符節點執行個體的
ModifierNodeElement
。 - 如上所述,選用修飾符工廠。
ModifierNodeElement
類別為無狀態,且每個重新組成都會分配新的執行個體,Modifier.Node
類別可以是有狀態的,且會在多個重組期間保留,甚至可以重複使用。
以下章節將說明各個部分,並示範如何建構自訂修飾符來繪製圓形。
Modifier.Node
Modifier.Node
實作 (在此範例中為 CircleNode
) 會實作自訂修飾符的功能。
// Modifier.Node private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() { override fun ContentDrawScope.draw() { drawCircle(color) } }
在本例中,我們會利用傳入修飾符函式的顏色來繪製圓形。
節點會實作 Modifier.Node
以及零個或多個節點類型。視修飾符所需的功能而定,會使用不同的節點類型。上述範例必須能夠繪圖,因此會實作 DrawModifierNode
來覆寫繪圖方法。
可用的類型如下:
節點 |
用法 |
範例連結 |
|
||
繪製在版面配置空間中的 |
||
實作這個介面可讓 |
||
|
||
接收 PointerInputChanges. 的 |
||
將資料提供給上層版面配置的 |
||
接收 |
||
|
||
實作 |
||
如要將多個節點實作組合成單一節點,這項功能就能派上用場。 |
||
允許 |
透過相應的元素呼叫節點時,節點會自動失效。由於我們的範例是 DrawModifierNode
,因此只要元素呼叫任何更新,節點就會觸發重新繪製並正確更新顏色。您可以選擇停用自動失效功能,詳情請參閱下文。
ModifierNodeElement
ModifierNodeElement
是不可變的類別,用來保留資料以建立或更新自訂修飾符:
// ModifierNodeElement private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() { override fun create() = CircleNode(color) override fun update(node: CircleNode) { node.color = color } }
ModifierNodeElement
實作需要覆寫下列方法:
create
:這個函式會將修飾符節點執行個體化。首次套用修飾符時,系統會呼叫此方法建立節點。通常,這個數字用於建構節點,並透過已傳入修飾符工廠的參數設定節點。update
:每當這個節點已經在相同位置提供此修飾符,但屬性已變更時,就會呼叫此函式。這取決於類別的equals
方法。先前建立的修飾符節點會以參數的形式傳送至update
呼叫。此時,您應更新節點的屬性,與更新後的參數對應。以這種方式重複使用節點的能力是影響Modifier.Node
帶來效能的關鍵,因此,您必須更新現有節點,而非透過update
方法建立新節點。在圓形範例中,節點的顏色已更新。
此外,ModifierNodeElement
實作也需要實作 equals
和 hashCode
。只有在與上一個元素的比較相等時傳回 false,系統才會呼叫 update
。
上述範例使用了資料類別來完成這項作業。這些方法可用於檢查節點是否需要更新。如果元素的屬性無法影響節點是否需要更新,或者您為了因應二進位檔相容性因素而想要避免資料類別,可以手動實作 equals
和 hashCode
(例如邊框間距修飾符元素)。
修飾符工廠
這是修飾符的公用 API 介面。大多數的實作方式只會建立修飾符元素,並新增至修飾符鏈結:
// Modifier factory fun Modifier.circle(color: Color) = this then CircleElement(color)
完整範例
這三個部分會合在一起,來建立使用 Modifier.Node
API 繪製圓形的自訂修飾符:
// Modifier factory fun Modifier.circle(color: Color) = this then CircleElement(color) // ModifierNodeElement private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() { override fun create() = CircleNode(color) override fun update(node: CircleNode) { node.color = color } } // Modifier.Node private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() { override fun ContentDrawScope.draw() { drawCircle(color) } }
使用 Modifier.Node
的常見情況
使用 Modifier.Node
建立自訂修飾符時,您可能會遇到以下幾個常見情況。
零參數
如果修飾符沒有參數,則一律不需要更新,也不需要屬於資料類別。以下是修飾符實作範例,將固定數量的邊框間距套用至可組合項:
fun Modifier.fixedPadding() = this then FixedPaddingElement data object FixedPaddingElement : ModifierNodeElement<FixedPaddingNode>() { override fun create() = FixedPaddingNode() override fun update(node: FixedPaddingNode) {} } class FixedPaddingNode : LayoutModifierNode, Modifier.Node() { private val PADDING = 16.dp override fun MeasureScope.measure( measurable: Measurable, constraints: Constraints ): MeasureResult { val paddingPx = PADDING.roundToPx() val horizontal = paddingPx * 2 val vertical = paddingPx * 2 val placeable = measurable.measure(constraints.offset(-horizontal, -vertical)) val width = constraints.constrainWidth(placeable.width + horizontal) val height = constraints.constrainHeight(placeable.height + vertical) return layout(width, height) { placeable.place(paddingPx, paddingPx) } } }
參照組合本機
Modifier.Node
修飾符不會自動觀察 Compose 狀態物件 (例如 CompositionLocal
) 的變更,相較於剛透過可組合項工廠建立的修飾符,Modifier.Node
修飾符可透過 currentValueOf
讀取在 UI 樹狀結構中使用修飾符的位置 (而非配置修飾符的位置) 的組合本機值。
然而,修飾符節點執行個體不會自動觀察狀態變更。如要自動回應本機組合變更,您可以在範圍內讀取目前的值:
DrawModifierNode
:ContentDrawScope
LayoutModifierNode
:MeasureScope
和IntrinsicMeasureScope
SemanticsModifierNode
:SemanticsPropertyReceiver
本範例會觀察 LocalContentColor
的值,根據顏色繪製背景。由於 ContentDrawScope
會觀察快照變更,因此當 LocalContentColor
的值變更時,系統會自動重新繪製:
class BackgroundColorConsumerNode : Modifier.Node(), DrawModifierNode, CompositionLocalConsumerModifierNode { override fun ContentDrawScope.draw() { val currentColor = currentValueOf(LocalContentColor) drawRect(color = currentColor) drawContent() } }
如要回應範圍外的狀態變更,並自動更新修飾符,請使用 ObserverModifierNode
。
舉例來說,Modifier.scrollable
會使用這項技術觀察 LocalDensity
中的變化。範例如下:
class ScrollableNode : Modifier.Node(), ObserverModifierNode, CompositionLocalConsumerModifierNode { // Place holder fling behavior, we'll initialize it when the density is available. val defaultFlingBehavior = DefaultFlingBehavior(splineBasedDecay(UnityDensity)) override fun onAttach() { updateDefaultFlingBehavior() observeReads { currentValueOf(LocalDensity) } // monitor change in Density } override fun onObservedReadsChanged() { // if density changes, update the default fling behavior. updateDefaultFlingBehavior() } private fun updateDefaultFlingBehavior() { val density = currentValueOf(LocalDensity) defaultFlingBehavior.flingDecay = splineBasedDecay(density) } }
為修飾符加上動畫效果
Modifier.Node
實作項目可以使用 coroutineScope
。如此一來,即可使用 Compose Animatable API。例如,下列程式碼片段會修改上述的 CircleNode
來重複淡入和淡出:
class CircleNode(var color: Color) : Modifier.Node(), DrawModifierNode { private val alpha = Animatable(1f) override fun ContentDrawScope.draw() { drawCircle(color = color, alpha = alpha.value) drawContent() } override fun onAttach() { coroutineScope.launch { alpha.animateTo( 0f, infiniteRepeatable(tween(1000), RepeatMode.Reverse) ) { } } } }
使用委派功能在修飾符之間共用狀態
Modifier.Node
修飾符可以委派給其他節點。此用途有許多用途,例如擷取不同修飾符的常見實作方式,但也可用於跨修飾符共用共同狀態。
例如,分享互動資料且可點擊的修飾符節點基本實作方式:
class ClickableNode : DelegatingNode() { val interactionData = InteractionData() val focusableNode = delegate( FocusableNode(interactionData) ) val indicationNode = delegate( IndicationNode(interactionData) ) }
選擇停用節點自動無效功能
當 Modifier.Node
個節點的對應的 ModifierNodeElement
呼叫更新時,就會自動失效。有時候,在較複雜的修飾符中,您可能要選擇不採用此行為,以更精細地控制修飾符何時撤銷階段。
如果自訂修飾符會同時修改版面配置和繪製,這項功能就特別實用。選擇停用自動撤銷後,只有在只有繪製相關屬性 (例如 color
、變更且不使版面配置) 時,繪圖才會失效。這麼做可提升修飾符的成效。
下方範例顯示了此假設的假設,其修飾符具有 color
、size
和 onClick
lambda 做為屬性。這個修飾符只會撤銷必要的項目,且會略過任何非的無效:
class SampleInvalidatingNode( var color: Color, var size: IntSize, var onClick: () -> Unit ) : DelegatingNode(), LayoutModifierNode, DrawModifierNode { override val shouldAutoInvalidate: Boolean get() = false private val clickableNode = delegate( ClickablePointerInputNode(onClick) ) fun update(color: Color, size: IntSize, onClick: () -> Unit) { if (this.color != color) { this.color = color // Only invalidate draw when color changes invalidateDraw() } if (this.size != size) { this.size = size // Only invalidate layout when size changes invalidateMeasurement() } // If only onClick changes, we don't need to invalidate anything clickableNode.update(onClick) } override fun ContentDrawScope.draw() { drawRect(color) } override fun MeasureScope.measure( measurable: Measurable, constraints: Constraints ): MeasureResult { val size = constraints.constrain(size) val placeable = measurable.measure(constraints) return layout(size.width, size.height) { placeable.place(0, 0) } } }