进度条 ProgressBar

2026-09-20评分加载中…

一、功能描述

RemoteProgressBar 是用于展示任务进度的水平进度条组件,对应 ViewType.PROGRESS_BAR。它支持设置当前进度、最大值与进度条颜色,适合展示上传 / 下载 / 加载等线性进度。

通过 RemoteViewHelper.createProgressBar() 创建:

val progressBar = helper.createProgressBar()

二、通用属性

以下属性通过对应的 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当前进度值,需不超过 setMax 设置的最大值
setMaxInt最大进度值,默认 100
setProgressColorInt进度填充颜色(ARGB Int)

三、Tips

  1. 颜色只能传 ARGB Int。setProgressColor / setBackground 接收 Int 颜色值(如 0xFF1A8BFF.toInt() 或 Color.RED)。不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  2. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。
  3. 进度百分比 = progress / max。若使用非 100 的自定义最大值,请通过 setMax 设置,并确保 setProgress 传入的值不超过该最大值。
  4. 进度条粗细由 setHeight 控制。水平进度条的高度即为进度条的粗细,宽度建议设为 MATCH_PARENT 以充满容器。

四、示例代码

下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。

01 进度与样式(进度值 / 粗细 / 颜色)

// 不同进度值:33% / 66% / 100%
val p33 = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(12)
    setMax(100); setProgress(33); setProgressColor(0xFF1A8BFF.toInt())
}
val p66 = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(12)
    setMax(100); setProgress(66); setProgressColor(0xFF1A8BFF.toInt())
}
val p100 = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(12)
    setMax(100); setProgress(100); setProgressColor(0xFF1A8BFF.toInt())
}

// 不同粗细(通过 setHeight):4dp / 8dp / 12dp
val thin = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(4)
    setProgress(33); setProgressColor(0xFF1A8BFF.toInt())
}
val medium = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(8)
    setProgress(66); setProgressColor(0xFF1A8BFF.toInt())
}
val thick = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(12)
    setProgress(100); setProgressColor(0xFF1A8BFF.toInt())
}

// 不同颜色:蓝 / 橙 / 红
val blue = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(12)
    setProgress(33); setProgressColor(0xFF1A8BFF.toInt())
}
val orange = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(12)
    setProgress(66); setProgressColor(0xFFFF8100.toInt())
}
val red = helper.createProgressBar().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(12)
    setProgress(88); setProgressColor(0xFFE41F29.toInt())
}

说明: 完整可运行示例见官方 Sample open-pilot-plugin-sample 的 drawing/ProgressBarDrawer.ktopen in new window。

最近修改: