进度指示器

进度指示器以直观的方式显示操作的状态。 它们通过动画效果让用户注意到流程(例如加载或处理数据)即将完成。它们还可以表示正在进行处理,而无需提及处理进度。

请考虑以下三种可能需要使用进度指示器的应用场景:

  • 加载内容:从网络提取内容时,例如加载图片或用户个人资料数据。
  • 文件上传:向用户反馈上传可能需要多长时间。
  • 长时间处理:当应用正在处理大量数据时,向用户传达已完成的总量。

在 Material Design 中,进度指示器分为两种类型:

  • 确定:确切显示已取得的进度。
  • 不确定:持续播放动画,不考虑进度。

同样,进度指示器可以采用以下两种形式之一:

  • 线性:从左到右填充的水平条。
  • 圆形:一个圆圈,其描边长度会不断增加,直到覆盖整个圆周。
线性进度指示器和环形进度指示器。
图 1. 两种类型的进度指示器。

API Surface

虽然您可以使用多个可组合项来创建符合 Material Design 规范的进度指示器,但它们的参数并无太大差异。您应注意的关键参数包括:

  • progress:指示器显示的当前进度。传递介于 0.0 和 1.0 之间的 Float。
  • color:实际指示器的颜色。也就是说,组件中反映进度的部分,在进度完成时会完全覆盖组件。
  • trackColor:绘制指示器的轨道的颜色。

M3 Expressive 更新

Material 3 Expressive 引入了 LinearWavyProgressIndicator 和 CircularWavyProgressIndicator,作为标准平面 LinearProgressIndicator 和 CircularProgressIndicator 的额外选项。这些指示器采用圆角样式,并提供轨道高度和波形配置。 选择最适合您产品的视觉风格。

如需详细了解进度指示器的 M3 Expressive 更新,请参阅 Material Design 3 进度指示器指南。

图 2. Material 3 Expressive 进度指示器,具有波浪形状和可变轨道高度。

进度指示器采用圆润、多彩的样式,并提供更多配置供您选择,包括波浪形和可变轨道高度。活动指示器有两种形状选项:波浪形和扁平形。

波浪哈哈镜

波浪形进度指示器提供确定性和不确定性两种变体,并允许您使用波浪形参数自定义其外观,以实现更具表现力的视觉效果。

图 3.具有富有表现力的波浪参数的波浪状进度指示器。

波浪形线性指示器会增加整个容器的高度。

波浪形进度指示器有两种变体:线性和圆形。

确定性线性波浪状进度指示器

默认情况下,使用波浪形进度指示器时,系统会应用波浪速度来创建持续的波浪运动,即使在确定模式下也是如此。您可以通过将 0.dp 传递给 waveSpeed 来关闭此波浪运动。

以下代码段演示了如何实现由 Slider 控制的确定性 LinearWavyProgressIndicator:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LinearWavyProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearWavyProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

不确定线性波浪状进度指示器

当等待时间未知时,使用不确定指示器来显示进程正在进行。以下代码段演示了如何实现不确定 LinearWavyProgressIndicator:

@Composable
fun IndeterminateLinearWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearWavyProgressIndicator() }
}

确定性圆形波浪状进度指示器

波浪形可以让较长的过程感觉不那么静态,最适合在需要更具表现力的风格时使用。以下代码段演示了如何实现由 Slider 控制的确定的 CircularWavyProgressIndicator:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CircularWavyProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        CircularWavyProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

不确定环形波浪状进度指示器

圆形进度指示器应直接位于正在加载的容器或页面(例如按钮或卡片)的中心。以下代码段演示了如何实现不确定 CircularWavyProgressIndicator:

@Composable
fun IndeterminateCircularWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularWavyProgressIndicator() }
}

扁平式

确定性指示器

确定性指示器可准确反映操作的完成程度。请使用 LinearProgressIndicator 或 CircularProgressIndicator 可组合项,并为 progress 参数传递一个值。

以下代码段演示了如何实现由 Slider 控制的确定性 LinearProgressIndicator:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LinearProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

以下代码段演示了如何实现由 Slider 控制的确定性 CircularProgressIndicator:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CircularProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        CircularProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

以下代码段提供了一个相对详细的示例。当用户按下按钮时,应用会将其替换为进度指示器,并启动一个协程来逐渐增加 progress 的值。这会导致进度指示器依次向上迭代。

@Composable
fun LinearDeterminateIndicator() {
    var currentProgress by remember { mutableFloatStateOf(0f) }
    var loading by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope() // Create a coroutine scope
    // Animate between progress updates so the indicator fills smoothly.
    val animatedProgress by animateFloatAsState(
        targetValue = currentProgress,
        animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
    )

    if (loading) {
        LinearProgressIndicator(
            progress = { animatedProgress },
            modifier = Modifier.fillMaxWidth(),
        )
    } else {
        Button(onClick = {
            loading = true
            scope.launch {
                loadProgress { progress ->
                    currentProgress = progress
                }
                loading = false // Reset loading when the coroutine finishes
            }
        }) {
            Text("Start loading")
        }
    }
}

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

当加载部分完成时,上述示例中的线性指示器会显示如下:

图 4. 线性确定进度指示器。

同样,圆形指示器如下所示:

图 5. 一个圆形确定进度指示器。

不确定进度指示器

不确定指示器不会反映操作距离完成还有多远。相反,它会使用动画向用户指示正在进行处理,但不会指定任何完成程度。

如需创建不确定进度指示器,请使用 LinearProgressIndicator 或 CircularProgressIndicator 可组合项,但不要为 progress 传入值。以下代码段演示了如何实现不确定 LinearProgressIndicator:

@Composable
fun IndeterminateLinearProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearProgressIndicator() }
}

以下代码段演示了如何实现不确定 CircularProgressIndicator:

@Composable
fun IndeterminateCircularProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularProgressIndicator() }
}

以下示例演示了如何通过按下按钮来切换不确定指示器。此示例还演示了如何为 color 和 trackColor 参数传递值,以自定义指示器的外观:

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

    if (loading) {
        CircularProgressIndicator(
            modifier = Modifier.size(64.dp),
            color = MaterialTheme.colorScheme.secondary,
            trackColor = MaterialTheme.colorScheme.surfaceVariant,
        )
    } else {
        Button(onClick = { loading = true }) {
            Text("Start loading")
        }
    }
}

以下是该指示器处于活动状态时的实现示例:

图 6. 环形不确定进度指示器。

以下是相同实现的示例,但使用的是 LinearProgressIndicator 而不是 CircularProgressIndicator:

图 7. 线性不确定进度指示器。

其他资源