Compose 動畫快速指南

Compose 提供許多內建動畫機制，可能會讓您不知所措 確定要選擇哪一個以下列舉幾種常見的動畫用途。適用對象 進一步瞭解可用的完整 API 選項組合 請參閱完整的 Compose 動畫說明文件。

為常見可組合屬性建立動畫效果

Compose 提供便利的 API，您可以解決許多 動畫用途本節說明如何建立常見的動畫動畫 可組合函式的屬性。

顯示 / 消失動畫

顯示並隱藏的綠色可組合函式
圖 1. 為資料欄內項目的外觀和消失加入動畫效果

使用 AnimatedVisibility 隱藏或顯示可組合函式。裡面的兒童 AnimatedVisibility可以使用「Modifier.animateEnterExit()」做為進入狀況 或結束轉場效果

var visible by remember {
    mutableStateOf(true)
}
// Animated visibility will eventually remove the item from the composition once the animation has finished.
AnimatedVisibility(visible) {
    // your composable here
    // ...
}
AnimationQuickGuide.kt

使用 AnimatedVisibility 的進入和結束參數來設定方式： 當可組合項出現或消失時，就會行為。閱讀全文 說明文件。

另一個方式是為可組合項的瀏覽權限加上動畫效果 使用 animateFloatAsState 隨時間變化 Alpha 版：

var visible by remember {
    mutableStateOf(true)
}
val animatedAlpha by animateFloatAsState(
    targetValue = if (visible) 1.0f else 0f,
    label = "alpha"
)
Box(
    modifier = Modifier
        .size(200.dp)
        .graphicsLayer {
            alpha = animatedAlpha
        }
        .clip(RoundedCornerShape(8.dp))
        .background(colorGreen)
        .align(Alignment.TopCenter)
) {
}
AnimationQuickGuide.kt

不過，變更 Alpha 版的注意事項會讓可組合函式保持不變 組成部分，並持續佔用空間所在的空間。這個 可能會導致螢幕閱讀器和其他無障礙機制 螢幕上的項目另一方面，AnimatedVisibility 最終會移除 透過組合中的項目

為可組合項的 Alpha 建立動畫效果
圖 2. 為可組合項的 Alpha 建立動畫效果

動畫背景顏色

具備背景顏色的可組合項會隨時間變化，並以動畫形式呈現，其中色彩會逐漸淡入。
圖 3. 為可組合函式的背景顏色加上動畫效果

val animatedColor by animateColorAsState(
    if (animateBackgroundColor) colorGreen else colorBlue,
    label = "color"
)
Column(
    modifier = Modifier.drawBehind {
        drawRect(animatedColor)
    }
) {
    // your composable here
}
AnimationQuickGuide.kt

這個選項的效能比使用 Modifier.background() 更好。 Modifier.background() 可用於單樣本色彩設定，但若使用這種顏色， 隨著時間的推移，為顏色加上動畫效果，這可能會導致重組次數超過 無從得知

如需無限套用背景顏色的動畫，請參閱重複使用動畫 專區。

以動畫呈現可組合項的大小

綠色可組合項為大小變更建立動畫流暢的動畫。
圖 4. 一個小號和大尺寸之間，能夠流暢呈現動畫效果的可組合項

Compose 可讓您以幾種不同方式為可組合項的大小建立動畫。使用 animateContentSize() 用於可組合項大小變更之間的動畫。

舉例來說，假設某個方塊中的文字為從 1 到 2 鍵 使用 Modifier.animateContentSize() 即可讓多行文字更流暢 轉換：

var expanded by remember { mutableStateOf(false) }
Box(
    modifier = Modifier
        .background(colorBlue)
        .animateContentSize()
        .height(if (expanded) 400.dp else 200.dp)
        .fillMaxWidth()
        .clickable(
            interactionSource = remember { MutableInteractionSource() },
            indication = null
        ) {
            expanded = !expanded
        }

) {
}
AnimationQuickGuide.kt

您也可以使用 AnimatedContent 搭配 SizeTransform 來描述 如何做出大小變更

可組合項的動畫位置

綠色可組合項流暢地上下播放動畫
圖 5. 可組合元件移動

如要為可組合項的位置加上動畫效果，請使用 Modifier.offset{ } 搭配 animateIntOffsetAsState()。

var moved by remember { mutableStateOf(false) }
val pxToMove = with(LocalDensity.current) {
    100.dp.toPx().roundToInt()
}
val offset by animateIntOffsetAsState(
    targetValue = if (moved) {
        IntOffset(pxToMove, pxToMove)
    } else {
        IntOffset.Zero
    },
    label = "offset"
)

Box(
    modifier = Modifier
        .offset {
            offset
        }
        .background(colorBlue)
        .size(100.dp)
        .clickable(
            interactionSource = remember { MutableInteractionSource() },
            indication = null
        ) {
            moved = !moved
        }
)
AnimationQuickGuide.kt

如果想確保可組合項不會繪製在其他可組合項或上方 為位置或大小加上動畫效果時，請使用 Modifier.layout{ }。這個 修飾符會將大小和位置變更傳播至父項，然後影響這些父項 更是如此

例如，您要在 Column 和其他子項中移動 Box 需要在 Box 移動時移動，並納入偏移資訊加上 Modifier.layout{ }，如下所示：

var toggled by remember {
    mutableStateOf(false)
}
val interactionSource = remember {
    MutableInteractionSource()
}
Column(
    modifier = Modifier
        .padding(16.dp)
        .fillMaxSize()
        .clickable(indication = null, interactionSource = interactionSource) {
            toggled = !toggled
        }
) {
    val offsetTarget = if (toggled) {
        IntOffset(150, 150)
    } else {
        IntOffset.Zero
    }
    val offset = animateIntOffsetAsState(
        targetValue = offsetTarget, label = "offset"
    )
    Box(
        modifier = Modifier
            .size(100.dp)
            .background(colorBlue)
    )
    Box(
        modifier = Modifier
            .layout { measurable, constraints ->
                val offsetValue = if (isLookingAhead) offsetTarget else offset.value
                val placeable = measurable.measure(constraints)
                layout(placeable.width + offsetValue.x, placeable.height + offsetValue.y) {
                    placeable.placeRelative(offsetValue)
                }
            }
            .size(100.dp)
            .background(colorGreen)
    )
    Box(
        modifier = Modifier
            .size(100.dp)
            .background(colorBlue)
    )
}
AnimationQuickGuide.kt

第 2 個方塊呈現 X、Y 的動畫，第三個方塊會同時移動 Y 值。
圖 6. 使用 Modifier.layout{ } 製作動畫

建立可組合項的邊框間距動畫

綠色可組合函式變小、點擊時變大，邊框間距呈現動畫效果
圖 7. 可組合項加上邊框間距動畫

如要為可組合項的邊框間距加上動畫效果，請使用 animateDpAsState 搭配 Modifier.padding():

var toggled by remember {
    mutableStateOf(false)
}
val animatedPadding by animateDpAsState(
    if (toggled) {
        0.dp
    } else {
        20.dp
    },
    label = "padding"
)
Box(
    modifier = Modifier
        .aspectRatio(1f)
        .fillMaxSize()
        .padding(animatedPadding)
        .background(Color(0xff53D9A1))
        .clickable(
            interactionSource = remember { MutableInteractionSource() },
            indication = null
        ) {
            toggled = !toggled
        }
)
AnimationQuickGuide.kt

建立可組合項的高度動畫

圖 8.可組合元件的高度在點擊時以動畫呈現

如要為可組合的高度建立動畫效果，請使用 animateDpAsState 搭配 Modifier.graphicsLayer{ }。如果是一次性的高度變更，請使用 Modifier.shadow()。如要製作陰影動畫，請使用 Modifier.graphicsLayer{ } 修飾符是效能較佳的選項。

val mutableInteractionSource = remember {
    MutableInteractionSource()
}
val pressed = mutableInteractionSource.collectIsPressedAsState()
val elevation = animateDpAsState(
    targetValue = if (pressed.value) {
        32.dp
    } else {
        8.dp
    },
    label = "elevation"
)
Box(
    modifier = Modifier
        .size(100.dp)
        .align(Alignment.Center)
        .graphicsLayer {
            this.shadowElevation = elevation.value.toPx()
        }
        .clickable(interactionSource = mutableInteractionSource, indication = null) {
        }
        .background(colorGreen)
) {
}
AnimationQuickGuide.kt

或者，您也可以使用 Card 可組合函式，並將高度屬性設為 每種狀態都有不同的值

為文字比例、翻譯或旋轉設定動畫

Text 可組合函式說明
圖 9.在兩種尺寸之間流暢顯示文字

為文字縮放比例、翻譯或旋轉動畫時，請設定 textMotion 參數 (TextStyle 至 TextMotion.Animated)。這可確保您 文字動畫之間的轉場效果使用 Modifier.graphicsLayer{ }： 翻譯、旋轉或縮放文字 

val infiniteTransition = rememberInfiniteTransition(label = "infinite transition")
val scale by infiniteTransition.animateFloat(
    initialValue = 1f,
    targetValue = 8f,
    animationSpec = infiniteRepeatable(tween(1000), RepeatMode.Reverse),
    label = "scale"
)
Box(modifier = Modifier.fillMaxSize()) {
    Text(
        text = "Hello",
        modifier = Modifier
            .graphicsLayer {
                scaleX = scale
                scaleY = scale
                transformOrigin = TransformOrigin.Center
            }
            .align(Alignment.Center),
        // Text composable does not take TextMotion as a parameter.
        // Provide it via style argument but make sure that we are copying from current theme
        style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated)
    )
}

AnimationQuickGuide.kt

動畫文字顏色

主題
圖 10.範例：動畫文字顏色

如要為文字顏色加上動畫效果，請在 BasicText 可組合函式上使用 color lambda： 

val infiniteTransition = rememberInfiniteTransition(label = "infinite transition")
val animatedColor by infiniteTransition.animateColor(
    initialValue = Color(0xFF60DDAD),
    targetValue = Color(0xFF4285F4),
    animationSpec = infiniteRepeatable(tween(1000), RepeatMode.Reverse),
    label = "color"
)

BasicText(
    text = "Hello Compose",
    color = {
        animatedColor
    },
    // ...
)
AnimationQuickGuide.kt

切換不同類型的內容

綠幕說：
圖 11.使用 AnimatedContent 為不同可組合項之間的變化加上動畫效果 (減速)

使用 AnimatedContent 為不同的可組合函式建立動畫效果 (如有) 只需使用可組合項之間的標準淡出效果，就可以使用 Crossfade。 

var state by remember {
    mutableStateOf(UiState.Loading)
}
AnimatedContent(
    state,
    transitionSpec = {
        fadeIn(
            animationSpec = tween(3000)
        ) togetherWith fadeOut(animationSpec = tween(3000))
    },
    modifier = Modifier.clickable(
        interactionSource = remember { MutableInteractionSource() },
        indication = null
    ) {
        state = when (state) {
            UiState.Loading -> UiState.Loaded
            UiState.Loaded -> UiState.Error
            UiState.Error -> UiState.Loading
        }
    },
    label = "Animated Content"
) { targetState ->
    when (targetState) {
        UiState.Loading -> {
            LoadingScreen()
        }
        UiState.Loaded -> {
            LoadedScreen()
        }
        UiState.Error -> {
            ErrorScreen()
        }
    }
}
AnimationQuickGuide.kt

只要自訂 AnimatedContent，就能顯示各種不同的輸入內容 退出轉場效果詳情請參閱 AnimatedContent或閱讀這篇有關以下網站的網誌文章 AnimatedContent。

導覽至不同目的地時以動畫呈現

兩個可組合函式，一個綠色顯示「到達網頁」，另一個顯示「詳細資料」，將詳細資料可組合項滑至登陸可組合項上方，以動畫呈現。
圖 12.使用 Navigation-Compose 在可組合項之間建立動畫

在使用 navigation-compose 構件，指定 enterTransition 和 可組合項的 exitTransition。您也可以將預設動畫設為 用於頂層 NavHost 的所有目的地： 

val navController = rememberNavController()
NavHost(
    navController = navController, startDestination = "landing",
    enterTransition = { EnterTransition.None },
    exitTransition = { ExitTransition.None }
) {
    composable("landing") {
        ScreenLanding(
            // ...
        )
    }
    composable(
        "detail/{photoUrl}",
        arguments = listOf(navArgument("photoUrl") { type = NavType.StringType }),
        enterTransition = {
            fadeIn(
                animationSpec = tween(
                    300, easing = LinearEasing
                )
            ) + slideIntoContainer(
                animationSpec = tween(300, easing = EaseIn),
                towards = AnimatedContentTransitionScope.SlideDirection.Start
            )
        },
        exitTransition = {
            fadeOut(
                animationSpec = tween(
                    300, easing = LinearEasing
                )
            ) + slideOutOfContainer(
                animationSpec = tween(300, easing = EaseOut),
                towards = AnimatedContentTransitionScope.SlideDirection.End
            )
        }
    ) { backStackEntry ->
        ScreenDetails(
            // ...
        )
    }
}
AnimationQuickGuide.kt

套用的進入和離開轉場效果有很多種 傳入和傳出的內容各有不同效果，請參閱 說明文件。

重複播放動畫

在兩個顏色之間建立動畫，能轉換成藍色背景，形成無限可能。
圖 13.背景色彩在兩個值之間建立無限動畫

將 rememberInfiniteTransition 與 infiniteRepeatable 搭配使用 animationSpec即可連續重複播放動畫。將 RepeatModes 變更為 指定來回呼叫的方式

使用 finiteRepeatable 可重複指定次數。 

val infiniteTransition = rememberInfiniteTransition(label = "infinite")
val color by infiniteTransition.animateColor(
    initialValue = Color.Green,
    targetValue = Color.Blue,
    animationSpec = infiniteRepeatable(
        animation = tween(1000, easing = LinearEasing),
        repeatMode = RepeatMode.Reverse
    ),
    label = "color"
)
Column(
    modifier = Modifier.drawBehind {
        drawRect(color)
    }
) {
    // your composable here
}
AnimationQuickGuide.kt

啟動可組合函式時啟動動畫

當可組合項進入組合時，LaunchedEffect 就會執行。開始 在啟動可組合函式時加入動畫，您可以使用此元素呈現動畫 狀態變更。搭配 animateTo 方法使用 Animatable 以啟動 啟動時的動畫：

val alphaAnimation = remember {
    Animatable(0f)
}
LaunchedEffect(Unit) {
    alphaAnimation.animateTo(1f)
}
Box(
    modifier = Modifier.graphicsLayer {
        alpha = alphaAnimation.value
    }
)
AnimationQuickGuide.kt

建立依序動畫

四個圓圈，圓圈內有綠色箭頭，圓圈中的一個動畫。
圖 14. 這張圖表顯示依序播放動畫的進度。

使用 Animatable 協同程式 API 執行序列或並行作業 動畫。依序在 Animatable 上呼叫 animateTo 的其他原因 每個動畫都等上一個動畫結束後再繼續 。 因為這屬於暫停函式。

val alphaAnimation = remember { Animatable(0f) }
val yAnimation = remember { Animatable(0f) }

LaunchedEffect("animationKey") {
    alphaAnimation.animateTo(1f)
    yAnimation.animateTo(100f)
    yAnimation.animateTo(500f, animationSpec = tween(100))
}
AnimationQuickGuide.kt

建立並行動畫

三個圓圈，有綠色箭頭分別代表每個圓圈的動畫，同時呈現動畫。
圖 15.顯示同時並行動畫進度的圖表。

使用協同程式 API (Animatable#animateTo() 或 animate)，或 Transition API 可以達到並行動畫。如果您使用多個 會在協同程式結構定義中啟動函式，瀏覽器也會在同一時間啟動動畫 時間： 

val alphaAnimation = remember { Animatable(0f) }
val yAnimation = remember { Animatable(0f) }

LaunchedEffect("animationKey") {
    launch {
        alphaAnimation.animateTo(1f)
    }
    launch {
        yAnimation.animateTo(100f)
    }
}
AnimationQuickGuide.kt

您可以使用 updateTransition API 來使用相同的狀態 可以同時顯示許多不同的屬性動畫以下範例的動畫 由狀態變更控制的兩個屬性 rect 和 borderWidth：

var currentState by remember { mutableStateOf(BoxState.Collapsed) }
val transition = updateTransition(currentState, label = "transition")

val rect by transition.animateRect(label = "rect") { state ->
    when (state) {
        BoxState.Collapsed -> Rect(0f, 0f, 100f, 100f)
        BoxState.Expanded -> Rect(100f, 100f, 300f, 300f)
    }
}
val borderWidth by transition.animateDp(label = "borderWidth") { state ->
    when (state) {
        BoxState.Collapsed -> 1.dp
        BoxState.Expanded -> 0.dp
    }
}
AnimationQuickGuide.kt

最佳化動畫效能

Compose 中的動畫可能會導致效能問題。這是因為 例如動畫的播放進度：快速移動或變更畫面上的像素 。

考量 Compose 的不同階段：組合、版面配置和繪圖。如果 動畫會變更版面配置階段，因此所有受影響的可組合函式都必須符合以下條件： 重新版面配置及重新繪製如果動畫在繪圖階段發生 預設值會比在版面配置中執行動畫效果更佳 因為整體處理工作較少

為確保應用程式在建立動畫時盡可能減少，請選擇 lambda Modifier 版本。這麼做會略過重組程序，並執行 組合階段以外的動畫，否則請使用 Modifier.graphicsLayer{ }，因為此修飾符一律會在繪圖中執行 事實上，Gartner 的資料顯示 只有一半的企業機器學習專案通過前測階段詳情請參閱 以及效能說明文件

變更動畫時間

Compose 預設會為大部分動畫使用 spring 動畫。彈簧 享受更自然流暢的物理動畫容器也可能中斷 都會考量物件的目前速度，而非固定時間。 如要覆寫預設值，會示範上述所有動畫 API 能夠設定 animationSpec 來自訂動畫的播放方式 是否希望在特定期間執行 或提升靈活度

以下摘要說明不同 animationSpec 選項：

  • spring：所有動畫預設採用物理動畫。個人中心 可以調整硬度或濕度變化 即可得出不同的動畫 外觀和風格。
  • tween (介於「介於」之間)：以時間長度為基礎的動畫、動畫 維持在兩個值之間Easing。
  • keyframes：指定在
  • repeatable：以時間長度為準的規格，可以執行特定次數、 由 RepeatMode 指定。
  • infiniteRepeatable：會無限期執行，以時間長度為準的規格。
  • snap：立即對齊結束值，不含任何動畫。
，瞭解如何調查及移除這項存取權。
在這裡輸入替代文字
圖 16.沒有規格集與自訂春季規格組合

如要進一步瞭解 animationSpecs，請參閱完整說明文件。

其他資源

如需更多 Compose 趣味動畫的範例，請參閱下列資源：

上一頁
選擇動畫 API
下一頁
動畫修飾符和可組合函式