Material 3 进度组件识别：LinearProgressIndicator、CircularProgressIndicator 的 Compose API

在 UI 自动化测试中，准确识别待测进度组件是编写可靠断言的前提。Material 3 提供了两种互补的进度指示器：LinearProgressIndicator（线性）和 CircularProgressIndicator（圆形）。本章从测试视角梳理两者的 Compose API 核心参数、构造方式与可观察属性，为后续在测试代码中通过 Semantics 树定位进度元素奠定基础。

dependencies {
    implementation("androidx.compose.material3:material3:1.2.0")
    androidTestImplementation("androidx.compose.ui:ui-test-junit4:1.6.0")
}

2.1 核心 API 对比

2.2 LinearProgressIndicator API 详解

线性进度条通常用于页面顶部或卡片内，展现连续任务的整体进度。构造函数签名如下（省略装饰参数）：

@Composable
fun LinearProgressIndicator(
    progress: Float?,           // null → 不确定模式; 0f..1f → 确定模式
    modifier: Modifier = Modifier,
    color: Color = MaterialTheme.colorScheme.primary,
    trackColor: Color = MaterialTheme.colorScheme.surfaceVariant,
    strokeWidth: Dp = ProgressIndicatorDefaults.StrokeWidth,
    ... // 其他 Material 3 特定参数
)

• 确定模式示例：progress = 0.5f → 填充 50%
• 不确定模式示例：progress = null → 持续滚动动画（未显示具体百分比）
• 测试定位：通过 onNodeWithTag("linearProgress") 或 onNode(hasProgressBarRole()) 获取

@get:Rule
val composeTestRule = createComposeRule()

// 在 Compose 中设置
composeTestRule.setContent {
    val progress by remember { mutableStateOf(0.3f) }
    LinearProgressIndicator(
        progress = progress,
        modifier = Modifier.testTag("downloadProgress")
    )
}

// 断言
composeTestRule
    .onNodeWithTag("downloadProgress")
    .assertExists()
    .assertSemanticsMatcher("progressValue") {
        it.getFloat(SemanticsProperties.ProgressBarRangeInfo)?.current ?: 0f
    }

2.3 CircularProgressIndicator API 详解

圆形进度条常用于加载转圈、文件上传等场景。API 结构与线性版本高度一致：

@Composable
fun CircularProgressIndicator(
    progress: Float?,
    modifier: Modifier = Modifier,
    color: Color = MaterialTheme.colorScheme.primary,
    trackColor: Color = MaterialTheme.colorScheme.surfaceVariant,
    strokeWidth: Dp = ProgressIndicatorDefaults.StrokeWidth,
    ... // 大小、间隙等参数
)

• 确定模式：progress = 0.75f → 圆弧角度为 270°
• 不确定模式：progress = null → 圆环连续旋转
• 测试中区分：可通过 onNodeWithTag("circularProgress") 定位；两种指示器 Semantics 角色均为 ProgressBar，需用 Tag 或额外属性区分

// ❌ 错误：进度值越界
CircularProgressIndicator(progress = 1.5f) // 运行时崩溃
// ✅ 正确：使用 clamp 或业务逻辑约束
CircularProgressIndicator(progress = currentValue.coerceIn(0f, 1f))

2.4 通过 Semantics 树识别进度组件

测试框架通过 Composable 的 Semantics 属性感知进度指示器。两个组件自动附加以下关键属性：

2.5 性能与稳定性优化提示

• 避免在 Compose 中频繁触发 recomposition： 进度值更新应使用 derivedStateOf 或 snapshotFlow 过滤高频变化，防止测试中超时。
• 测试中等待进度： 使用 composeTestRule.waitForIdle() 或 waitUntil 等待进度值稳定。
• 异步更新进度： 协程中的进度更新应挂起于 Dispatchers.Main，测试时可通过 runTest + advanceUntilIdle() 控制时间。