本頁面由 Cloud Translation API 翻譯而成。

進度指標

進度指標會以視覺化方式顯示作業狀態。他們會使用動態效果，讓使用者注意程序完成的程度，例如載入或處理資料。也可以表示正在處理，但不會提及完成進度。

以下三種情況可能需要使用進度指標：

載入內容：從網路擷取內容時，例如載入圖片或使用者個人資料的資料。
檔案上傳：向使用者說明上傳作業可能需要多久時間。
長時間處理：應用程式處理大量資料時，請向使用者說明完成進度。

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

確定：顯示確切的進度。
不確定：持續產生動畫，不考慮進度。

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

線性：由左至右填滿的水平長條。
圓形：筆劃長度會不斷增加，直到涵蓋圓形的完整圓周。

API 介面

雖然您可以使用多個可組合函式建立符合 Material Design 的進度指標，但這些函式的參數差異不大。請注意下列重要參數：

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