复选框 CheckBox
一、功能描述
RemoteCheckBox 是带文本标签的复选框组件,对应 ViewType.CHECK_BOX。它支持默认选中状态、勾选框染色、文本、字号、字形、对齐以及选中状态变化监听,适合多选列表、协议勾选、开关型选项等场景。
通过 RemoteViewHelper.createCheckBox() 创建:
val check = helper.createCheckBox()
二、通用属性
以下属性通过对应的 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 | 背景形状:填充色 / 描边 / 圆角 |
复选框属性
| 方法 | 参数 | 说明 |
|---|---|---|
setChecked | Boolean | 是否选中 |
setCheckBoxTint | Int | 勾选框染色(ARGB Int) |
setText | String | 文本标签内容 |
setTextSize | Float | 字号(内部取整为 sp) |
setTextColor | Int | 文字颜色(ARGB Int) |
setGravity | GravityType | 对齐:CENTER / START / END / LEFT / RIGHT / TOP / BOTTOM 等 |
setFontStyle | FontStyleType | 字形:NORMAL / BOLD / ITALIC / BOLD_ITALIC |
事件
| 方法 | 参数 | 说明 |
|---|---|---|
setOnCheckChangeListener | IRemoteViewOnCheckedChangeListener | 选中状态变化监听:onCheckedChanged(view, isChecked)。回调运行在 Binder 线程池 |
三、Tips
- 颜色只能传 ARGB Int。
setCheckBoxTint/setTextColor接收 Int 颜色值(如0xFF1A8BFF.toInt()或Color.RED)。不要传"#RRGGBB"、"0xAARRGGBB"或R.color.xxx。 setOnCheckChangeListener的回调运行在 Binder 线程池,不在主线程。若要在回调中更新 UI,务必先切回主线程(如Handler(Looper.getMainLooper()).post { ... })。- 修改已挂载组件的属性后要
syncToRemote()。setXxx只更新本地缓存,调用syncToRemote()才会批量同步到 Pilot。 - 禁用态需
setEnabled(false)配合setAlpha(...)。仅setEnabled(false)只阻止交互,配合降透明度才有视觉上的置灰效果。 setCheckBoxTint只影响勾选框(方框)的染色,文本颜色由setTextColor单独控制。
四、示例代码
下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。
01 复选框(未选中 / 已选中 / 蓝色 / 红色 / 禁用态)
// 未选中
val unchecked = helper.createCheckBox().apply {
setText("未选中"); setHeight(30); setChecked(false)
}
// 已选中
val checked = helper.createCheckBox().apply {
setText("已选中"); setHeight(30); setChecked(true)
}
// 蓝色染色
val blue = helper.createCheckBox().apply {
setText("蓝色"); setHeight(30); setChecked(true)
setCheckBoxTint(0xFF1A8BFF.toInt())
}
// 红色染色
val red = helper.createCheckBox().apply {
setText("红色"); setHeight(30); setChecked(true)
setCheckBoxTint(0xFFE41F29.toInt())
}
// 禁用态:先创建再降透明度
val disabled = helper.createCheckBox().apply {
setText("禁用态"); setHeight(30); setChecked(true)
setEnabled(false)
setAlpha(0.6f)
}
// 选中状态监听(回调在 Binder 线程池,更新 UI 需切主线程)
checked.setOnCheckChangeListener(object : IRemoteViewOnCheckedChangeListener {
override fun onCheckedChanged(view: RemoteView, isChecked: Boolean) {
Handler(Looper.getMainLooper()).post {
// 在主线程安全地更新 UI
}
}
})
说明: 完整可运行示例见官方 Sample
open-pilot-plugin-sample的 drawing/CheckBoxDrawer.kt。