圆形进度条 CircleProgressBar
一、功能描述
RemoteCircleProgressBar 是以圆环形式展示进度的组件,对应 ViewType.CIRCULAR_PROGRESS_BAR。它支持设置进度、最大值、进度弧颜色,并可在圆心显示文字(文字内容 / 颜色 / 字号),以及在正常 / 成功 / 失败三种状态间切换,适合展示带结果反馈的圆形进度(如任务执行、下载校验等)。
通过 RemoteViewHelper.createCircleProgressBar() 创建:
val circleBar = helper.createCircleProgressBar()
二、通用属性
以下属性通过对应的 setXxx() 方法设置。除标注外,属性修改后若组件已挂载,需调用 syncToRemote() 使其在 Pilot 端生效。
尺寸与布局
| 方法 | 参数 | 说明 |
|---|---|---|
setWidth | Int | 宽度(dp);特殊值 RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2) |
setHeight | Int | 高度(dp);同上支持特殊值 |
setMinSize | minWidth: Int, minHeight: Int | 最小尺寸(dp) |
setPadding | left, top, right, bottom: Int | 内边距(dp) |
setVisibility | VisibilityType | 可见性:VISIBLE / INVISIBLE / GONE |
setAlpha | Float | 透明度,0.0 ~ 1.0 |
setEnabled | Boolean | 是否可用 |
背景与形状
| 方法 | 参数 | 说明 |
|---|---|---|
setBackground | Int | 背景纯色(ARGB Int) |
setBackgroundShape | ShapeDescriptor | 背景形状:填充色 / 描边 / 圆角 |
圆形进度条属性
| 方法 | 参数 | 说明 |
|---|---|---|
setProgress | Int | 当前进度,范围 0-100(内部会 coerceIn(0, 100)) |
setMax | Int | 最大进度值,默认 100,需大于 0 |
setProgressColor | Int | 进度弧颜色(ARGB Int) |
setText | String | 圆心显示文字,仅 NORMAL 状态下生效 |
setTextColor | Int | 圆心文字颜色(ARGB Int) |
setTextSize | Float | 圆心文字大小(sp,内部取整) |
setStatus | ProgressStatusType | 进度条状态:NORMAL(显示文字)/ SUCCESS(显示成功图标,隐藏文字)/ FAIL(显示失败图标,隐藏文字) |
三、Tips
- 颜色只能传 ARGB Int。
setProgressColor/setTextColor/setBackground接收 Int 颜色值(如0xFF1A8BFF.toInt()或Color.RED)。不要传"#RRGGBB"、"0xAARRGGBB"或R.color.xxx。 SUCCESS/FAIL状态会隐藏圆心文字。这两种状态下圆心改为显示成功 / 失败图标,setText设置的文字不会显示;只有NORMAL状态才展示圆心文字。切回NORMAL后文字重新显示。- 进度范围固定 0-100。
setProgress内部会将入参coerceIn(0, 100),超出范围会被钳制;如需自定义最大值请配合setMax,并自行保证progress ≤ max。 - 修改已挂载组件的属性后要
syncToRemote()。setXxx只更新本地缓存,调用syncToRemote()才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。 - 圆心文字大小单位为 sp,
setTextSize内部会取整。
四、示例代码
下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。
01 进度与文字(进度弧 / 圆心文字 / 尺寸颜色)
// 不同进度值,圆心显示百分比文字
val p33 = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setMax(100); setProgress(33); setProgressColor(0xFF1A8BFF.toInt())
setStatus(ProgressStatusType.NORMAL)
setText("33%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
}
val p66 = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setMax(100); setProgress(66); setProgressColor(0xFF1A8BFF.toInt())
setStatus(ProgressStatusType.NORMAL)
setText("66%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
}
val p100 = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setMax(100); setProgress(100); setProgressColor(0xFF1A8BFF.toInt())
setStatus(ProgressStatusType.NORMAL)
setText("100%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
}
// 不同颜色的进度弧:蓝 / 橙 / 红
val blue = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30); setProgress(33)
setProgressColor(0xFF1A8BFF.toInt()); setText("33%"); setTextColor(0xFFFFFFFF.toInt())
}
val orange = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30); setProgress(66)
setProgressColor(0xFFFF8100.toInt()); setText("66%"); setTextColor(0xFFFFFFFF.toInt())
}
val red = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30); setProgress(88)
setProgressColor(0xFFE41F29.toInt()); setText("88%"); setTextColor(0xFFFFFFFF.toInt())
}
02 组件状态(NORMAL / SUCCESS / FAIL)
// FAIL:圆心显示失败图标,隐藏文字
val fail = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setProgress(25); setProgressColor(0xFFE41F29.toInt())
setText("25%") // FAIL 状态下文字不显示
setStatus(ProgressStatusType.FAIL)
}
// NORMAL:正常态,圆心显示进度文字
val normal = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setProgress(45); setProgressColor(0xFF1A8BFF.toInt())
setText("45%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
setStatus(ProgressStatusType.NORMAL)
}
// SUCCESS:圆心显示成功图标,隐藏文字
val success = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setProgress(100); setProgressColor(0xFF00C774.toInt())
setText("100%") // SUCCESS 状态下文字不显示
setStatus(ProgressStatusType.SUCCESS)
}
说明: 完整可运行示例见官方 Sample
open-pilot-plugin-sample的 drawing/ProgressBarDrawer.kt。