進度指標

進度指標會視覺化呈現作業狀態。並使用動態效果讓使用者註意程序接近完成進度 (例如載入或處理資料)。他們也可以表示處理程序正在發生，而不會提到可能有多接近完成作業。

以下是可能會使用進度指標的三種用途：

• 載入內容：從網路擷取內容，例如載入使用者個人資料的圖片或資料。
• 檔案上傳：為使用者提供意見回饋，說明上傳作業可能需要多久時間。
• 長時間處理：當應用程式處理大量資料時，向使用者說明完成的總和。

Material Design 中有兩種進度指標：

• Determinate：確切顯示已完成的進度。
• 不確定：持續動畫，不考慮進度。

同樣地，進度指標可以採用下列其中一種形式：

• 線性：由左至右填滿的水平長條。
• 圓形：筆劃長度會長，直到圓週完整圍繞的圓形。

API 介面

雖然有許多可組合項可用來建立與質感設計一致的懸浮動作按鈕，但其參數的差異不大。以下是需要留意的幾個重要參數：

• progress：指標顯示的目前進度。在 0.0 和 1.0 之間傳遞 Float。
• color：實際指標的顏色。也就是說，元件中反映進度的元件，以及進度完成後完整涵蓋元件。
• trackColor：繪製指標的軌跡顏色。

終止指標

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

以下程式碼片段提供了相對詳細的範例。當使用者按下按鈕時，應用程式會顯示進度指標，並啟動協同程式來逐漸增加 progress 的值。這會導致進度指標不斷疊代。

@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 的值。以下範例說明如何按按鈕切換不確定指標。

@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 文件