進度指標

進度指標可視覺化呈現作業狀態。它們會使用動態效果，讓使用者注意到程序 (例如載入或處理資料) 完成的進度。也可以表示處理程序正在進行，但不代表處理程序已接近完成。

請考慮下列三種可能會使用進度指標的用途：

• 載入內容：從網路擷取內容時，例如載入使用者個人資料的圖片或資料。
• 檔案上傳：提供使用者有關上傳時間的意見回饋。
• 處理時間過長：當應用程式處理大量資料時，請向使用者說明完成的總量。

在 Material Design 中，進度指標分為兩種：

• Determinate：顯示進度。
• 未確定：無視進度，持續播放動畫。

同樣地，進度指標可採用下列任一形式：

• 線性：由左至右填滿的水平列。
• 圓形：圓形的筆劃會逐漸變長，直到包含整個圓形的周長為止。

圖 1. 兩種類型的進度指標。

API 途徑

雖然您可以使用多個可組合項來建立與 Material Design 一致的進度指標，但這些可組合項的參數並沒有太大差異。請注意下列關鍵參數：

• progress：指標顯示的目前進度。在 0.0 和 1.0 之間傳遞 Float。
• color：實際指標的顏色。也就是反映進度的元件部分，並在進度完成時完全涵蓋該元件。
• trackColor：指標繪製時所用的軌道顏色。

注意： LinearProgressIndicator 和 CircularProgressIndicator 的 API 本質上相同，使用方式也完全相同。您可以使用下列程式碼片段來執行這兩項操作。

確定指標

確定指標會準確反映動作的完成程度。請使用 LinearProgressIndicator 或 CircularProgressIndicator 可組合項，並傳遞 progress 參數的值。

以下程式碼片段提供較詳細的範例。使用者按下按鈕時，應用程式會同時顯示進度指標，並啟動協同程式，逐步增加 progress 的值。這會導致進度指標依序迭代。

注意： 以下範例使用協同程式執行 progress 值的迴迭作業，因為這會阻斷 UI 執行緒。

@Composable
fun LinearDeterminateIndicator() {
    var currentProgress by remember { mutableStateOf(0f) }
    var loading by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope() // Create a coroutine scope

    Column(
        verticalArrangement = Arrangement.spacedBy(12.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        modifier = Modifier.fillMaxWidth()
    ) {
        Button(onClick = {
            loading = true
            scope.launch {
                loadProgress { progress ->
                    currentProgress = progress
                }
                loading = false // Reset loading when the coroutine finishes
            }
        }, enabled = !loading) {
            Text("Start loading")
        }

        if (loading) {
            LinearProgressIndicator(
                progress = { currentProgress },
                modifier = Modifier.fillMaxWidth(),
            )
        }
    }
}

/** Iterate the progress value */
suspend fun loadProgress(updateProgress: (Float) -> Unit) {
    for (i in 1..100) {
        updateProgress(i.toFloat() / 100)
        delay(100)
    }
}
ProgressIndicator.kt

載入作業部分完成後，上例中的線性指標會顯示如下：

同樣地，圓形指標會顯示如下：

未確定指標

不確定的指標並不會反映作業完成的進度，而是透過動畫向使用者表示處理作業正在進行中，但不會指定任何完成程度。

如要建立不確定的進度指標，請使用 LinearProgressIndicator 或 CircularProgressIndicator 可組合項，但請勿為 progress 傳入值。以下範例說明如何透過按下按鈕來切換不確定指標。

注意： 此範例也說明如何傳遞 color 和 trackColor 參數的值，以自訂指標的外觀。

@Composable
fun IndeterminateCircularIndicator() {
    var loading by remember { mutableStateOf(false) }

    Button(onClick = { loading = true }, enabled = !loading) {
        Text("Start loading")
    }

    if (!loading) return

    CircularProgressIndicator(
        modifier = Modifier.width(64.dp),
        color = MaterialTheme.colorScheme.secondary,
        trackColor = MaterialTheme.colorScheme.surfaceVariant,
    )
}
ProgressIndicator.kt

以下是指標啟用時實作方式的範例：

以下是相同實作的範例，但使用 LinearProgressIndicator 而非 CircularProgressIndicator。

其他資源

• Material UI 說明文件