圆形进度条 CircleProgressBar

2026-09-20评分加载中…

一、功能描述

RemoteCircleProgressBar 是以圆环形式展示进度的组件,对应 ViewType.CIRCULAR_PROGRESS_BAR。它支持设置进度、最大值、进度弧颜色,并可在圆心显示文字(文字内容 / 颜色 / 字号),以及在正常 / 成功 / 失败三种状态间切换,适合展示带结果反馈的圆形进度(如任务执行、下载校验等)。

通过 RemoteViewHelper.createCircleProgressBar() 创建:

val circleBar = helper.createCircleProgressBar()

二、通用属性

以下属性通过对应的 setXxx() 方法设置。除标注外,属性修改后若组件已挂载,需调用 syncToRemote() 使其在 Pilot 端生效。

尺寸与布局

方法参数说明
setWidthInt宽度(dp);特殊值 RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2)
setHeightInt高度(dp);同上支持特殊值
setMinSizeminWidth: Int, minHeight: Int最小尺寸(dp)
setPaddingleft, top, right, bottom: Int内边距(dp)
setVisibilityVisibilityType可见性:VISIBLE / INVISIBLE / GONE
setAlphaFloat透明度,0.0 ~ 1.0
setEnabledBoolean是否可用

背景与形状

方法参数说明
setBackgroundInt背景纯色(ARGB Int)
setBackgroundShapeShapeDescriptor背景形状:填充色 / 描边 / 圆角

圆形进度条属性

方法参数说明
setProgressInt当前进度,范围 0-100(内部会 coerceIn(0, 100))
setMaxInt最大进度值,默认 100,需大于 0
setProgressColorInt进度弧颜色(ARGB Int)
setTextString圆心显示文字,仅 NORMAL 状态下生效
setTextColorInt圆心文字颜色(ARGB Int)
setTextSizeFloat圆心文字大小(sp,内部取整)
setStatusProgressStatusType进度条状态:NORMAL(显示文字)/ SUCCESS(显示成功图标,隐藏文字)/ FAIL(显示失败图标,隐藏文字)

三、Tips

  1. 颜色只能传 ARGB Int。setProgressColor / setTextColor / setBackground 接收 Int 颜色值(如 0xFF1A8BFF.toInt() 或 Color.RED)。不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  2. SUCCESS / FAIL 状态会隐藏圆心文字。这两种状态下圆心改为显示成功 / 失败图标,setText 设置的文字不会显示;只有 NORMAL 状态才展示圆心文字。切回 NORMAL 后文字重新显示。
  3. 进度范围固定 0-100。setProgress 内部会将入参 coerceIn(0, 100),超出范围会被钳制;如需自定义最大值请配合 setMax,并自行保证 progress ≤ max。
  4. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。
  5. 圆心文字大小单位为 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.ktopen in new window。

最近修改: