复选框 CheckBox

2026-09-20评分加载中…

一、功能描述

RemoteCheckBox 是带文本标签的复选框组件,对应 ViewType.CHECK_BOX。它支持默认选中状态、勾选框染色、文本、字号、字形、对齐以及选中状态变化监听,适合多选列表、协议勾选、开关型选项等场景。

通过 RemoteViewHelper.createCheckBox() 创建:

val check = helper.createCheckBox()

二、通用属性

以下属性通过对应的 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背景形状:填充色 / 描边 / 圆角

复选框属性

方法参数说明
setCheckedBoolean是否选中
setCheckBoxTintInt勾选框染色(ARGB Int)
setTextString文本标签内容
setTextSizeFloat字号(内部取整为 sp)
setTextColorInt文字颜色(ARGB Int)
setGravityGravityType对齐:CENTER / START / END / LEFT / RIGHT / TOP / BOTTOM 等
setFontStyleFontStyleType字形:NORMAL / BOLD / ITALIC / BOLD_ITALIC

事件

方法参数说明
setOnCheckChangeListenerIRemoteViewOnCheckedChangeListener选中状态变化监听:onCheckedChanged(view, isChecked)。回调运行在 Binder 线程池

三、Tips

  1. 颜色只能传 ARGB Int。setCheckBoxTint / setTextColor 接收 Int 颜色值(如 0xFF1A8BFF.toInt() 或 Color.RED)。不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  2. setOnCheckChangeListener 的回调运行在 Binder 线程池,不在主线程。若要在回调中更新 UI,务必先切回主线程(如 Handler(Looper.getMainLooper()).post { ... })。
  3. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot。
  4. 禁用态需 setEnabled(false) 配合 setAlpha(...)。仅 setEnabled(false) 只阻止交互,配合降透明度才有视觉上的置灰效果。
  5. 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.ktopen in new window。

最近修改: