开关 Switch

2026-09-20评分加载中…

一、功能描述

RemoteSwitch 是用于在「开 / 关」两种状态间切换的开关组件,对应 ViewType.SWITCH。它支持默认选中状态、滑块颜色、轨道颜色、文本、字号、字形、对齐以及选中状态变化监听,适合设置项开关、功能启停等场景。

通过 RemoteViewHelper.createSwitch() 创建:

val toggle = helper.createSwitch()

二、通用属性

以下属性通过对应的 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是否选中(开 / 关)
setThumbColorInt滑块颜色(ARGB Int)
setTrackColorInt轨道颜色(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。setThumbColor / setTrackColor / 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. setThumbColor 控制滑块色、setTrackColor 控制轨道色,两者独立设置,可自由组合配色。

四、示例代码

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

01 开关(默认关 / 默认开 / 绿色滑块 / 红色轨道 / 自定义配色 / 禁用态)

// 默认关
val off = helper.createSwitch().apply {
    setWidth(40); setHeight(20); setChecked(false)
}

// 默认开
val on = helper.createSwitch().apply {
    setWidth(40); setHeight(20); setChecked(true)
}

// 绿色滑块
val greenThumb = helper.createSwitch().apply {
    setWidth(55); setHeight(25); setChecked(true)
    setThumbColor(0xFF00C774.toInt())
}

// 红色轨道
val redTrack = helper.createSwitch().apply {
    setWidth(55); setHeight(25); setChecked(true)
    setTrackColor(0xFFE41F29.toInt())
}

// 自定义配色:蓝轨道 + 白滑块
val custom = helper.createSwitch().apply {
    setWidth(55); setHeight(25); setChecked(true)
    setTrackColor(0xFF1A8BFF.toInt())
    setThumbColor(0xFFFFFFFF.toInt())
}

// 禁用态:先创建再降透明度
val disabled = helper.createSwitch().apply {
    setWidth(40); setHeight(20); setChecked(true)
    setEnabled(false)
    setAlpha(0.6f)
}

// 选中状态监听(回调在 Binder 线程池,更新 UI 需切主线程)
on.setOnCheckChangeListener(object : IRemoteViewOnCheckedChangeListener {
    override fun onCheckedChanged(view: RemoteView, isChecked: Boolean) {
        Handler(Looper.getMainLooper()).post {
            // 在主线程安全地更新 UI
        }
    }
})

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

最近修改: