下拉框 Spinner
一、功能描述
RemoteSpinner 是用于从一组选项中单选的下拉框组件,对应 ViewType.SPINNER。它支持设置选项列表、指定默认选中项、自定义下拉弹窗背景色 / 选项文字色 / 选中项文字色 / 右侧图标色,并可监听选项选中事件,适合展示可切换的枚举型配置(如飞行模式、档位等)。
通过 RemoteViewHelper.createSpinner() 创建:
val spinner = helper.createSpinner()
二、通用属性
以下属性通过对应的 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 | 背景形状:填充色 / 描边 / 圆角 |
下拉框属性
| 方法 | 参数 | 说明 |
|---|---|---|
setItems | List<String> | 选项文本列表 |
setItemsByResIds | List<Int> | 通过 R.string.xxx 资源 ID 列表设置选项,随服务端语言自动刷新文案 |
setSelectedIndex | Int | 当前选中项索引(从 0 开始) |
setDropdownBackgroundColor | Int | 下拉弹窗背景色(ARGB Int),仅影响弹出列表区域,不影响头部 |
setDropdownTextColor | Int | 下拉弹窗中选项文字颜色(ARGB Int) |
setSelectedTextColor | Int | 选中项文字颜色(ARGB Int) |
setSpinnerIconColor | Int | 右侧下拉图标颜色(ARGB Int) |
setGravity | GravityType | 头部文字对齐:CENTER / START / END / LEFT / RIGHT 等 |
事件
| 方法 | 参数 | 说明 |
|---|---|---|
setOnItemSelectedListener | IRemoteViewOnItemSelectedListener | 选项选中回调 onItemSelected(index: Int, item: String),运行在 Binder 线程池 |
三、Tips
- 颜色只能传 ARGB Int。
setDropdownBackgroundColor/setDropdownTextColor/setSelectedTextColor/setSpinnerIconColor均接收 Int 颜色值(如0xFF2696FF.toInt()或Color.WHITE)。不要传"#RRGGBB"、"0xAARRGGBB"或R.color.xxx。 - 选中回调运行在 Binder 线程池。
setOnItemSelectedListener的onItemSelected回调不在主线程,若要更新界面或触碰仅限主线程的 API,务必自行切回主线程(如Handler(Looper.getMainLooper()).post { ... })。 - 修改已挂载组件的属性后要
syncToRemote()。setXxx只更新本地缓存,调用syncToRemote()才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。 setSelectedIndex索引从 0 开始,取值需落在setItems列表长度范围内,越界不会生效。- 多语言场景优先用
setItemsByResIds。传入R.string.xxx资源 ID 列表,服务端语言切换时会自动刷新选项文案;而setItems传入的字符串为固定文案,不随语言变化。 - 当前服务端尚未支持对 Spinner 头部文字应用字号 / 文字色 / 字形,故 SDK 未开放对应设置方法;如需区分选中项颜色,请使用
setSelectedTextColor。
四、示例代码
下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。
01 下拉框(默认选中 / 指定选中 / 自定义弹窗配色)
val items = listOf("降落", "返航", "悬停")
// 默认选中第 0 项,并监听选中事件(回调在 Binder 线程,切主线程更新 UI)
val defaultSpinner = helper.createSpinner().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(40)
setBackgroundShape(
ShapeDescriptor.Builder()
.stroke(1, 0xFFFFFFFF.toInt()).fillColor(0xFF000000.toInt()).cornerRadius(4f).build()
)
setItems(items)
setSelectedIndex(0)
setGravity(GravityType.CENTER)
setSelectedTextColor(0xFF2696FF.toInt())
setDropdownTextColor(0x88E7E7E7.toInt())
setSpinnerIconColor(0x88E7E7E7.toInt())
setOnItemSelectedListener { index, item ->
Handler(Looper.getMainLooper()).post {
// 切主线程后再更新 UI
}
}
}
// 指定默认选中第 2 项(索引从 0 开始,即"悬停")
val indexSpinner = helper.createSpinner().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(40)
setBackgroundShape(
ShapeDescriptor.Builder()
.stroke(1, 0xFFFFFFFF.toInt()).fillColor(0xFF000000.toInt()).cornerRadius(4f).build()
)
setItems(items)
setSelectedIndex(2)
setGravity(GravityType.CENTER)
setSelectedTextColor(0xFF2696FF.toInt())
setDropdownTextColor(0x88E7E7E7.toInt())
setSpinnerIconColor(0x88E7E7E7.toInt())
}
// 自定义下拉背景色与文字颜色(灰底、白色选中文字、白色图标)
val customSpinner = helper.createSpinner().apply {
setWidth(RemoteView.MATCH_PARENT); setHeight(40)
setBackgroundShape(
ShapeDescriptor.Builder()
.stroke(1, 0xFF000000.toInt()).fillColor(0xFF373A41.toInt()).cornerRadius(4f).build()
)
setItems(items)
setSelectedIndex(0)
setGravity(GravityType.CENTER)
setSelectedTextColor(0xFFFFFFFF.toInt())
setDropdownBackgroundColor(0xFF373A41.toInt())
setDropdownTextColor(0x88E7E7E7.toInt())
setSpinnerIconColor(0xFFFFFFFF.toInt())
}
完整可运行示例见官方 Sample
open-pilot-plugin-sample的 drawing/SpinnerDrawer.kt。