进度指示器以直观的方式显示操作的状态。 它们通过动画效果让用户注意到流程(例如加载或处理数据)即将完成。它们还可以表示正在进行处理,而无需提及处理进度。
请考虑以下三种可能需要使用进度指示器的应用场景:
- 加载内容:从网络提取内容时,例如加载图片或用户个人资料数据。
- 文件上传:向用户反馈上传可能需要多长时间。
- 长时间处理:当应用正在处理大量数据时,向用户传达已完成的总量。
在 Material Design 中,进度指示器分为两种类型:
- 确定:确切显示已取得的进度。
- 不确定:持续播放动画,不考虑进度。
同样,进度指示器可以采用以下两种形式之一:
- 线性:从左到右填充的水平条。
- 圆形:一个圆圈,其描边长度会不断增加,直到覆盖整个圆周。
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 进度指示器指南。
进度指示器采用圆润、多彩的样式,并提供更多配置供您选择,包括波浪形和可变轨道高度。活动指示器有两种形状选项:波浪形和扁平形。
波浪哈哈镜
波浪形进度指示器提供确定性和不确定性两种变体,并允许您使用波浪形参数自定义其外观,以实现更具表现力的视觉效果。
波浪形线性指示器会增加整个容器的高度。
波浪形进度指示器有两种变体:线性和圆形。
确定性线性波浪状进度指示器
默认情况下,使用波浪形进度指示器时,系统会应用波浪速度来创建持续的波浪运动,即使在确定模式下也是如此。您可以通过将 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) } }
当加载部分完成时,上述示例中的线性指示器会显示如下:
同样,圆形指示器如下所示:
不确定进度指示器
不确定指示器不会反映操作距离完成还有多远。相反,它会使用动画向用户指示正在进行处理,但不会指定任何完成程度。
如需创建不确定进度指示器,请使用 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") } } }
以下是该指示器处于活动状态时的实现示例:
以下是相同实现的示例,但使用的是 LinearProgressIndicator 而不是 CircularProgressIndicator: