组件总览

2026-11-03评分加载中…

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

自定义组件效果总览

总览

自定义组件效果总览

自定义UI组件

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.ktopen in new window 在 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,遵循同一套模型:

  1. 创建:helper.createXxx(),此时组件在本地生成一个运行时唯一 id(getId() 获取)。
  2. 配置:调用 setText / setBackgroundShape 等,属性先缓存在本地 propertyMap。
  3. 挂载:parent.addToRemote(view, layoutParam) 或 root.addToRoot(),把组件真正添加到 Pilot 端。
  4. 后续更新:修改属性后调用 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.ktopen in new window)。

最近修改: