列表 ListView
一、功能描述
RemoteListView 是纵向滚动的列表组件,对应 ViewType.VERTICAL_LIST_VIEW。它以数据驱动的方式渲染列表项(ListItemData),内置 3 种预定义 Item 类型(纯文本、图标+标题、图标+双行文本),支持全量设置、单条增删改、分割线配置、点击开关与点击事件,适合展示设置项、文件列表、状态清单等。
通过 RemoteViewHelper.createListView() 创建,再用 addToRoot() 挂载:
val listView = helper.createListView()
listView.setWidth(300)
listView.setHeight(400)
listView.addToRoot()
关键概念
数据模型
ListItemData:通过 3 个静态工厂方法创建 Item:ListItemData.text(itemId, title):纯文本ListItemData.iconText(itemId, iconFileName, title):图标 + 标题ListItemData.iconTwoLine(itemId, iconFileName, title, subtitle):图标 + 双行文本
其中
itemId为 Item 唯一标识(点击回调据此区分),iconFileName为已上传到 Pilot 的图标文件名。列表数据上限:最多
RemoteListView.MAX_ITEM_COUNT(100)条,setItems超出会抛出IllegalArgumentException。
二、通用属性
以下属性通过对应的 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 | 背景形状:填充色 / 描边 / 圆角 |
列表属性
| 方法 | 参数 | 说明 |
|---|---|---|
addToRoot | params: WidgetLayoutParam? | 挂载列表到根布局(可选布局参数) |
setItems | List<ListItemData> | 全量设置列表数据,最多 100 条;返回 OperationResult |
insertItem | position: Int, item: ListItemData | 在指定位置插入一条;返回 OperationResult |
removeItem | position: Int | 删除指定位置一条;返回 OperationResult |
updateItem | position: Int, item: ListItemData | 更新指定位置一条(整体替换);返回 OperationResult |
setDividerConfig | DividerConfig | 分割线配置;返回 OperationResult |
setItemClickEnabled | Boolean | 是否启用 Item 点击;返回 OperationResult |
DividerConfig 构造参数:
| 参数 | 类型 | 说明 |
|---|---|---|
height | Int | 分割线高度(dp) |
color | String | 分割线颜色,"#RRGGBB" 或 "#AARRGGBB"(如 "#33FFFFFF") |
paddingLeft | Int | 左侧缩进(dp) |
paddingRight | Int | 右侧缩进(dp) |
showLastDivider | Boolean | 是否显示最后一条 Item 下方的分割线 |
事件
| 方法 | 说明 |
|---|---|
setOnItemClickListener | Item 点击回调,参数为 (position: Int, itemId: String)。回调在 Binder 线程池执行,更新 UI / 业务需自行切主线程 |
三、Tips
- 列表最多 100 条。
setItems传入超过MAX_ITEM_COUNT(100)条会抛出IllegalArgumentException。数据量大时应自行分页或裁剪,不要一次性灌入。 - 点击回调不在主线程。
setOnItemClickListener的回调运行在 AIDL 的 Binder 线程池,若要更新 App 自身 View 或做主线程相关操作,需Handler(Looper.getMainLooper()).post { ... }切回主线程。 - 图标需先上传到 Pilot。
ListItemData的iconFileName引用的是 Pilot 端已存在的文件,务必先用helper.pushImageFile(path, callback)上传成功后再setItems,否则 Server 端找不到图标。 updateItem是整体替换,不是局部更新——新ListItemData会完整覆盖该位置旧数据,未设置的字段将回落到默认值。- 分割线颜色用字符串,不同于组件颜色。
DividerConfig与ListItemData的颜色是"#RRGGBB"/"#AARRGGBB"字符串格式;而setBackground等通用属性用的是 ARGB Int。两者不要混用。 - 列表需受限高度才能滚动。给
setHeight一个固定值(如 400dp),内容超出时才会在列表内部滚动,否则会一直撑高。 - 修改已挂载组件的属性后要
syncToRemote()。而setItems/insertItem等数据方法内部已直接下发到 Pilot,无需额外syncToRemote()。
四、示例代码
下方每组左侧为示例代码,右侧为对应的 Pilot 端渲染预览效果。
01 基础列表(三种 Item 类型)
// 创建并挂载列表
val listView = helper.createListView().apply {
setWidth(300); setHeight(400)
}
listView.addToRoot()
// 三种预定义 Item 类型(图标文件需先 pushImageFile 上传)
listView.setItems(listOf(
// 纯文本
ListItemData.text("item_1", "纯文本项 1"),
ListItemData.text("item_2", "纯文本项 2"),
// 图标 + 标题
ListItemData.iconText("item_ok", "check.png", "成功"),
ListItemData.iconText("item_fail", "close.png", "失败"),
// 图标 + 双行文本
ListItemData.iconTwoLine("item_photo", "photo.png", "照片 B.jpg", "5.1 MB"),
ListItemData.iconTwoLine("item_video", "video.png", "视频 C.mp4", "128 MB")
))
02 数据操作(增 / 删 / 改)
// 先建立初始列表
val listView = helper.createListView().apply {
setWidth(300); setHeight(400)
}
listView.addToRoot()
listView.setItems(listOf(
ListItemData.text("id_a", "列表项 A"),
ListItemData.text("id_b", "列表项 B"),
ListItemData.text("id_c", "列表项 C")
))
// 插入:在第 1 位插入一条
listView.insertItem(1, ListItemData.text("id_new", "新插入项"))
// 更新:整体替换第 0 位(未设置字段回落默认值)
listView.updateItem(0, ListItemData.iconText("id_a", "star.png", "列表项 A(已更新)"))
// 删除:移除最后一位
listView.removeItem(3)
// 返回值可用于校验操作结果
val result = listView.removeItem(0)
if (result != OperationResult.SUCCESS) {
// 处理失败(如 position 越界)
}
03 分割线与点击
val listView = helper.createListView().apply {
setWidth(300); setHeight(400)
}
listView.addToRoot()
// 分割线:高 1dp、半透明白、左缩进 56dp、不显示末条分割线
listView.setDividerConfig(
DividerConfig(1, "#33FFFFFF", 56, 0, false)
)
listView.setItems(listOf(
ListItemData.iconText("wifi", "wifi.png", "无线网络"),
ListItemData.iconText("bt", "bt.png", "蓝牙"),
ListItemData.iconText("about", "info.png", "关于设备")
))
// 开启点击
listView.setItemClickEnabled(true)
// 点击回调运行在 Binder 线程,更新 UI 需切主线程
listView.setOnItemClickListener { position, itemId ->
Handler(Looper.getMainLooper()).post {
// 在主线程处理点击,例如按 itemId 跳转
// toast("点击了 $itemId @$position")
}
}
完整可运行示例见官方 Sample
open-pilot-plugin-sample的 drawing/ListViewDrawer.kt。