下拉框 Spinner

2026-09-20评分加载中…

一、功能描述

RemoteSpinner 是用于从一组选项中单选的下拉框组件,对应 ViewType.SPINNER。它支持设置选项列表、指定默认选中项、自定义下拉弹窗背景色 / 选项文字色 / 选中项文字色 / 右侧图标色,并可监听选项选中事件,适合展示可切换的枚举型配置(如飞行模式、档位等)。

通过 RemoteViewHelper.createSpinner() 创建:

val spinner = helper.createSpinner()

二、通用属性

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

下拉框属性

方法参数说明
setItemsList<String>选项文本列表
setItemsByResIdsList<Int>通过 R.string.xxx 资源 ID 列表设置选项,随服务端语言自动刷新文案
setSelectedIndexInt当前选中项索引(从 0 开始)
setDropdownBackgroundColorInt下拉弹窗背景色(ARGB Int),仅影响弹出列表区域,不影响头部
setDropdownTextColorInt下拉弹窗中选项文字颜色(ARGB Int)
setSelectedTextColorInt选中项文字颜色(ARGB Int)
setSpinnerIconColorInt右侧下拉图标颜色(ARGB Int)
setGravityGravityType头部文字对齐:CENTER / START / END / LEFT / RIGHT 等

事件

方法参数说明
setOnItemSelectedListenerIRemoteViewOnItemSelectedListener选项选中回调 onItemSelected(index: Int, item: String),运行在 Binder 线程池

三、Tips

  1. 颜色只能传 ARGB Int。setDropdownBackgroundColor / setDropdownTextColor / setSelectedTextColor / setSpinnerIconColor 均接收 Int 颜色值(如 0xFF2696FF.toInt() 或 Color.WHITE)。不要传 "#RRGGBB"、"0xAARRGGBB" 或 R.color.xxx。
  2. 选中回调运行在 Binder 线程池。setOnItemSelectedListener 的 onItemSelected 回调不在主线程,若要更新界面或触碰仅限主线程的 API,务必自行切回主线程(如 Handler(Looper.getMainLooper()).post { ... })。
  3. 修改已挂载组件的属性后要 syncToRemote()。setXxx 只更新本地缓存,调用 syncToRemote() 才会批量同步到 Pilot。挂载前配置好属性则无需额外调用。
  4. setSelectedIndex 索引从 0 开始,取值需落在 setItems 列表长度范围内,越界不会生效。
  5. 多语言场景优先用 setItemsByResIds。传入 R.string.xxx 资源 ID 列表,服务端语言切换时会自动刷新选项文案;而 setItems 传入的字符串为固定文案,不随语言变化。
  6. 当前服务端尚未支持对 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.ktopen in new window。

最近修改: