使用 animate*AsState 為單一值加上動畫效果
animate*AsState 函式是 Compose 中最簡單的動畫 API，可用於為單一值建立動畫效果。您只需提供目標值 (或結束值)，該 API 就會從現值開始播放動畫，直到達到指定值。
以下範例說明如何使用這個 API 為 alpha 建立動畫效果。只要目標值納入 animateFloatAsState 中，alpha 值就會成為所提供的值 (在本例中為 1f 或 0.5f) 之間的動畫值。
var enabled by remember { mutableStateOf(true) }
val alpha: Float by animateFloatAsState(if (enabled) 1f else 0.5f)
Box(
Modifier.fillMaxSize()
.graphicsLayer(alpha = alpha)
.background(Color.Red)
)
請注意，您不需要建立任何動畫類別的執行個體，也不必處理中斷情形。基本上，系統會在呼叫點上建立及記住動畫物件 (亦即 Animatable 執行個體)，並將第一個目標值設為初始值。此後，只要您為這個可組合項提供不同的目標值，系統就會自動開始執行動畫，直到達到該值為止。如果已有正在執行的動畫，動畫會從現值 (和目前速率) 開始執行動畫，直到達到目標值。在動畫播放期間，這個可組合項會重新組合，並針對每個影格傳回更新的動畫值。
Compose 的特點在於可為 Float、Color、Dp、Size、Offset、Rect、Int、IntOffset 和 IntSize 提供 animate*AsState 函式。只要為可接受一般類型的 animateValueAsState 提供 TwoWayConverter，即可輕鬆將其他資料類型納入支援。
您可以納入 AnimationSpec 來自訂動畫規格。詳情請參閱「AnimationSpec」。
使用轉場效果同時為多個屬性建立動畫
Transition 可管理一或多個動畫做為其子項，並在多個狀態之間同時執行這些動畫。
狀態可以是任何資料類型。在許多情況下，您可以使用自訂 enum 類型以確保類型安全，如以下範例所示：
enum class BoxState {
Collapsed,
Expanded
}
updateTransition 可建立及記住 Transition 的執行個體，並更新其狀態。
var currentState by remember { mutableStateOf(BoxState.Collapsed) }
val transition = updateTransition(currentState, label = "box state")
接著，您可以使用其中一個 animate* 擴充函式來定義這個轉場效果中的子動畫，並為每個狀態指定目標值。這些 animate* 函式會傳回動畫值，當您在動畫播放期間使用 updateTransition 更新轉場狀態時，該值會隨著每個影格更新。
val rect by transition.animateRect(label = "rectangle") { state ->
when (state) {
BoxState.Collapsed -> Rect(0f, 0f, 100f, 100f)
BoxState.Expanded -> Rect(100f, 100f, 300f, 300f)
}
}
val borderWidth by transition.animateDp(label = "border width") { state ->
when (state) {
BoxState.Collapsed -> 1.dp
BoxState.Expanded -> 0.dp
}
}
您也可以選擇傳遞 transitionSpec 參數，為每個轉場狀態變更組合指定不同的 AnimationSpec。詳情請參閱「AnimationSpec」。
val color by transition.animateColor(
transitionSpec = {
when {
BoxState.Expanded isTransitioningTo BoxState.Collapsed ->
spring(stiffness = 50f)
else ->
tween(durationMillis = 500)
}
}, label = "color"
) { state ->
when (state) {
BoxState.Collapsed -> MaterialTheme.colorScheme.primary
BoxState.Expanded -> MaterialTheme.colorScheme.background
}
}
當轉場效果到達目標狀態時，Transition.currentState 將與 Transition.targetState 相同，可用來做為轉場效果是否完成的訊號。
我們有時會希望初始狀態與第一個目標狀態不同，這時可將 updateTransition 與 MutableTransitionState 搭配使用來達成。舉例來說，這麼做可讓我們在程式碼進入組合階段後立即開始執行動畫。
// Start in collapsed state and immediately animate to expanded
var currentState = remember { MutableTransitionState(BoxState.Collapsed) }
currentState.targetState = BoxState.Expanded
val transition = updateTransition(currentState, label = "box state")
// ……
如果是涉及多個可組合函式的複雜轉場效果，可使用 createChildTransition 來建立下層轉場。這個技巧適合用於在複雜的可組合項中分隔多個重要子元件。上層轉場會得知下層轉場中的所有動畫值。
enum class DialerState { DialerMinimized, NumberPad }
@Composable
fun DialerButton(isVisibleTransition: Transition<Boolean>) {
// `isVisibleTransition` spares the need for the content to know
// about other DialerStates. Instead, the content can focus on
// animating the state change between visible and not visible.
}
@Composable
fun NumberPad(isVisibleTransition: Transition<Boolean>) {
// `isVisibleTransition` spares the need for the content to know
// about other DialerStates. Instead, the content can focus on
// animating the state change between visible and not visible.
}
@Composable
fun Dialer(dialerState: DialerState) {
val transition = updateTransition(dialerState, label = "dialer state")
Box {
// Creates separate child transitions of Boolean type for NumberPad
// and DialerButton for any content animation between visible and
// not visible
NumberPad(
transition.createChildTransition {
it == DialerState.NumberPad
}
)
DialerButton(
transition.createChildTransition {
it == DialerState.DialerMinimized
}
)
}
}
搭配 AnimatedVisibility 和 AnimatedContent 使用轉場效果
AnimatedVisibility 和 AnimatedContent 可做為 Transition 的擴充函式。Transition.AnimatedVisibility 和 Transition.AnimatedContent 的 targetState 衍生自 Transition，會在 Transition 的 targetState 變更時視需要觸發進入/結束轉換效果。這些擴充函式可允許原本位於 AnimatedVisibility/AnimatedContent 內部的所有 enter/exit/sizeTransform 動畫提升到 Transition 中。只要有這些擴充函式，即可從外部觀察 AnimatedVisibility/AnimatedContent 的狀態變化情形。這個版本的 AnimatedVisibility 會接受可將上層轉換的目標狀態轉換為布林值的 lambda，但不接受布林值的 visible 參數。
詳情請參閱「AnimatedVisibility」和「AnimatedContent」。
var selected by remember { mutableStateOf(false) }
// Animates changes when `selected` is changed.
val transition = updateTransition(selected, label = "selected state")
val borderColor by transition.animateColor(label = "border color") { isSelected ->
if (isSelected) Color.Magenta else Color.White
}
val elevation by transition.animateDp(label = "elevation") { isSelected ->
if (isSelected) 10.dp else 2.dp
}
Surface(
onClick = { selected = !selected },
shape = RoundedCornerShape(8.dp),
border = BorderStroke(2.dp, borderColor),
elevation = elevation
) {
Column(modifier = Modifier.fillMaxWidth().padding(16.dp)) {
Text(text = "Hello, world!")
// AnimatedVisibility as a part of the transition.
transition.AnimatedVisibility(
visible = { targetSelected -> targetSelected },
enter = expandVertically(),
exit = shrinkVertically()
) {
Text(text = "It is fine today.")
}
// AnimatedContent as a part of the transition.
transition.AnimatedContent { targetState ->
if (targetState) {
Text(text = "Selected")
} else {
Icon(imageVector = Icons.Default.Phone, contentDescription = "Phone")
}
}
}
}
封裝轉場效果以重複使用
如果是簡單用途，在與 UI 相同的可組合項中定義轉換動畫是相當有效的選項。不過，使用含有多個動畫值的複雜元件時，您可能需要將動畫實作與可組合 UI 分開。
具體方法是建立包含所有動畫值的類別，同時建立可傳回該類別執行個體的「update」函式。可以將轉換實作擷取到新的獨立函式中。如果需要整合動畫邏輯，或讓複雜動畫可重複使用，這個模式相當實用。
enum class BoxState { Collapsed, Expanded }
@Composable
fun AnimatingBox(boxState: BoxState) {
val transitionData = updateTransitionData(boxState)
// UI tree
Box(
modifier = Modifier
.background(transitionData.color)
.size(transitionData.size)
)
}
// Holds the animation values.
private class TransitionData(
color: State<Color>,
size: State<Dp>
) {
val color by color
val size by size
}
// Create a Transition and return its animation values.
@Composable
private fun updateTransitionData(boxState: BoxState): TransitionData {
val transition = updateTransition(boxState, label = "box state")
val color = transition.animateColor(label = "color") { state ->
when (state) {
BoxState.Collapsed -> Color.Gray
BoxState.Expanded -> Color.Red
}
}
val size = transition.animateDp(label = "size") { state ->
when (state) {
BoxState.Collapsed -> 64.dp
BoxState.Expanded -> 128.dp
}
}
return remember(transition) { TransitionData(color, size) }
}
使用 rememberInfiniteTransition 建立無限重複動畫
InfiniteTransition 會保留一或多個子動畫，例如 Transition，但這些動畫會在進入組合階段後立即開始執行。除非您將動畫移除，否則動畫不會停止。您可以使用 rememberInfiniteTransition 建立 InfiniteTransition 的執行個體，同時可使用 animateColor、animatedFloat 或 animatedValue 新增子動畫。您還需要指定 infiniteRepeatable 以指定動畫規格。
val infiniteTransition = rememberInfiniteTransition()
val color by infiniteTransition.animateColor(
initialValue = Color.Red,
targetValue = Color.Green,
animationSpec = infiniteRepeatable(
animation = tween(1000, easing = LinearEasing),
repeatMode = RepeatMode.Reverse
)
)
Box(Modifier.fillMaxSize().background(color))
低階動畫 API
上一節提及的所有高階動畫 API 都是以低階動畫 API 為基礎建構而成。
animate*AsState 函式是最簡單的 API，可將即時值變化轉譯為動畫值。這個函式採用的 Animatable 是以協同程式為基礎的 API，可為單一值建立動畫效果。updateTransition 可建立轉場物件，用於管理多個動畫值並依據狀態變化執行這些值。rememberInfiniteTransition 也是類似的函式，但可建立無限轉場效果，用於管理多個無限期執行的動畫。這些 API (Animatable 除外) 都是可組合項，意味著您可以在組合外建立這些動畫效果。
這些 API 都是根據最根本的 Animation API 所建立。雖然多數應用程式不會直接與 Animation 互動，但可透過高階 API 使用 Animation 的某些自訂功能。如要進一步瞭解 AnimationVector 和 AnimationSpec，請參閱「自訂動畫」。
Animatable：以協同程式為基礎的單一值動畫
Animatable 可做為保留值的元件，並在透過 animateTo 變更值時為值建立動畫效果。這是用來支援 animate*AsState 實作的 API，可確保一致的持續性和互斥性，這表示值的變動會持續發生，並一併取消任何執行中的動畫。
系統會提供 Animatable 的許多功能 (包括 animateTo) 做為暫停函式。這表示這些功能需要納入適當的協同程式範圍中。舉例來說，您可以使用 LaunchedEffect 可組合項為指定鍵值的期間建立範圍。
// Start out gray and animate to green/red based on `ok`
val color = remember { Animatable(Color.Gray) }
LaunchedEffect(ok) {
color.animateTo(if (ok) Color.Green else Color.Red)
}
Box(Modifier.fillMaxSize().background(color.value))
在上述範例中，我們建立並記住了初始值為 Color.Gray 的 Animatable 執行個體。根據布林值旗標 ok 的值，動畫顏色會設為 Color.Green 或 Color.Red。對布林值進行後續變更時，動畫會開始呈現另一個顏色。如果在變更該值時有正在執行的動畫，則系統會取消動畫，且新動畫會以目前速率從目前的快照值開始執行。
以上便是根據上一節所述的 animate*AsState API 建構的動畫實作內容。與 animate*AsState 相比，我們可直接使用 Animatable 多方面進行更精細的控制。首先，Animatable 的初始值可以與其第一個目標值不同。舉例來說，上述程式碼範例最初顯示灰色方塊，隨後開始呈現轉為綠色或紅色的動畫效果。其次，Animatable 針對內容值提供更多操作，也就是 snapTo 和 animateDecay。snapTo 會立即將現值設為目標值。如果動畫本身並非唯一的可靠來源，且需要與其他狀態 (例如觸控事件) 保持同步，這個函式就非常實用。animateDecay 會開始執行從指定速率開始減慢的動畫，有助於實作快速滑過行為。詳情請參閱「手勢和動畫」。
Animatable 的特點在於可支援 Float 和 Color，但只要納入 TwoWayConverter 即可使用任何資料類型。詳情請參閱「AnimationVector」。
您可以納入 AnimationSpec 來自訂動畫規格。詳情請參閱 AnimationSpec。
Animation：手動控制的動畫
Animation 是可用的最低階 Animation API。目前為止，我們看到的許多動畫都是以 Animation 為基礎。有兩種 Animation 子類型：TargetBasedAnimation 和 DecayAnimation。
Animation 只該用來手動控制動畫的時間。Animation 是無狀態的，沒有任何生命週期概念。它用做較高階 API 使用的動畫計算引擎。
TargetBasedAnimation
其他 API 涵蓋大部分應用實例，但直接使用 TargetBasedAnimation，可讓您自行控制動畫播放時間。在以下範例中，您要根據 withFrameNanos 提供的影格時間手動控制 TargetAnimation 的播放時間。
val anim = remember {
TargetBasedAnimation(
animationSpec = tween(200),
typeConverter = Float.VectorConverter,
initialValue = 200f,
targetValue = 1000f
)
}
var playTime by remember { mutableStateOf(0L) }
LaunchedEffect(anim) {
val startTime = withFrameNanos { it }
do {
playTime = withFrameNanos { it } - startTime
val animationValue = anim.getValueFromNanos(playTime)
} while (someCustomCondition())
}
DecayAnimation
與 TargetBasedAnimation 不同，DecayAnimation 不需要提供 targetValue。相反，它會根據啟動條件 (由 initialVelocity 和 initialValue 以及提供的 DecayAnimationSpec 設定) 計算其 targetValue。
衰退動畫通常在在翻轉手勢後使用，以將元素放慢至停止。動畫速率以 initialVelocityVector 設定的值開始，且會隨時間變慢。
為您推薦
- 注意：系統會在 JavaScript 關閉時顯示連結文字
- 自訂動畫 {:#customize-animations}
- Compose 中的動畫
- 動畫修飾符和可組合函式