组件总览
自定义 UI 组件让你的插件 App 把按钮、文本、开关、列表等 UI 远程绘制到 Pilot 的界面上,就像在 Pilot 里「长出」一块属于插件的界面。组件通过浮窗(FLOATING_BOX)叠加在 Pilot 界面上,承载插件的业务交互。


IRemoteViewPageManager 是 Pilot 开放的服务端自定义布局管理器:插件与 Pilot 运行在两个进程,它通过 AIDL 把「创建视图、添加约束、更新属性」等指令跨进程传给 Pilot 端,由 Pilot 侧真正实例化并渲染。配合它,SDK 在 uxsdk 中提供了一套开箱即用的组件封装(RemoteButton、RemoteText、RemoteSwitch 等)与统一入口 RemoteViewHelper。本章介绍如何用这套组件在 Pilot 上搭建自定义界面。
一、快速上手(三步)
// ① 获取浮窗 Helper(单例)
val helper = RemoteViewHelper.floatingBoxHelper
helper.clearLayout() // 清空旧布局
helper.setPageLayoutParamWrapContent() // 浮窗高度自适应内容
// ② 建根容器并挂到页面根节点
val root = helper.createLinearLayoutVertical().apply {
setWidth(RemoteView.MATCH_PARENT)
setHeight(RemoteView.WRAP_CONTENT)
setPadding(4, 4, 4, 4)
}
root.addToRoot()
// ③ 创建组件并添加到容器
val button = helper.createButton().apply {
setText("Hello Pilot")
setWidth(RemoteView.MATCH_PARENT)
setHeight(30)
}
button.setOnClickListener { /* 处理点击 */ }
root.addToRemote(button, helper.margin(4))
说明: AIDL 调用无需在主线程执行。官方 Sample RemoteViewPageDemoViewModel.kt 在
Activity.onCreate中用子线程执行绘制,避免阻塞 UI。
二、组件清单
helper.createXxx() 可创建以下组件,每个组件的详细属性见对应子章节:
| 组件 | 说明 |
|---|---|
| 按钮 Button | 可点击按钮,支持填充 / 描边 / 文字样式 |
| 文本 Text | 静态文本,支持字号 / 装饰 / 对齐 |
| 图片 Image | 显示图片(需先上传到 Pilot) |
| 网页 WebView | 加载网页 |
| 输入框 EditText | 文本输入,支持键盘类型 / 限长 |
| 开关 Switch | 开 / 关状态切换 |
| 复选框 CheckBox | 勾选状态 |
| 下拉框 Spinner | 单项选择下拉列表 |
| 进度条 ProgressBar | 水平进度条 |
| 圆形进度条 CircleProgressBar | 圆形进度条,支持圆心文字与状态 |
| 列表 ListView | 垂直滚动列表 |
| 布局容器 Layout | 线性 / 约束布局容器 |
三、通用概念
浮窗尺寸
浮窗的页面类型为 ViewPageType.FLOATING_BOX,宽度固定 140dp,默认高度 200dp。可通过 setPageLayoutParam 设置浮窗高度(单位 dp),或使用 helper.setPageLayoutParamWrapContent() 让高度自适应内容。
组件的生命周期:创建 → 挂载 → 同步
所有组件封装(RemoteXxx)都继承自 RemoteViewProvider,遵循同一套模型:
- 创建:
helper.createXxx(),此时组件在本地生成一个运行时唯一id(getId()获取)。 - 配置:调用
setText/setBackgroundShape等,属性先缓存在本地propertyMap。 - 挂载:
parent.addToRemote(view, layoutParam)或root.addToRoot(),把组件真正添加到 Pilot 端。 - 后续更新:修改属性后调用
view.syncToRemote(),把变更批量同步到 Pilot(内部逐条走updateView)。
注意: 视图 id 必须复用。
updateView/setConstraints都按id定位,不要重新createXxx()再更新,否则会得到新 id 导致NO_SUCH_VIEW_ID。
布局参数(WidgetLayoutParam)
addToRemote 的第二个参数控制子视图在父容器中的排布:
WidgetLayoutParam().apply {
setMargin(6, 2, 6, 2) // left, top, right, bottom(dp)
weight = 1f // 线性布局中的权重
}
也可用 helper.margin(4) 快速构造四边等距的 margin。
操作结果(OperationResult)
IRemoteViewPageManager 的方法多为同步返回 OperationResult,务必检查。完整枚举与处理建议见各子章节的「Tips」及下表:
| 枚举 | 含义 | 处理建议 |
|---|---|---|
SUCCESS | 成功 | — |
NO_SUCH_VIEW_ID | 视图 ID 不存在 | 确认 id 来源于已挂载的组件 |
NO_SUCH_PARENT_VIEW_ID | 父容器 ID 不存在 | 确认父容器已先挂载 |
SERVICE_NOT_FOUND | 服务已断连 | 等 Pilot 连接就绪后重试 |
INVALID_PROPERTY | 属性 / 取值非法 | 检查属性与取值格式 |
REMOTE_VIEWS_LIMIT_EXCEEDED | 页面视图缓存已达上限 | clearLayout(viewPageType) 全量清空后重建 |
四、性能建议
频繁切换不同面板时,不要反复 clearLayout + 重绘,而是一次性全量绘制所有内容容器,切换时只用 updateView 改 VISIBILITY("0"=VISIBLE / "8"=GONE)。这样能避免闪动、减少 IPC 次数。
注意: 反复清空重绘会导致界面闪动并放大 IPC 开销。高效做法是「一次绘制、按需显隐」,通过控制
VISIBILITY切换面板(参见官方 Sample RemoteViewPageDemoViewModel.kt)。