列表 ListView

2026-09-20评分加载中…

一、功能描述

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 端生效。

尺寸与布局

方法参数说明
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背景形状:填充色 / 描边 / 圆角

列表属性

方法参数说明
addToRootparams: WidgetLayoutParam?挂载列表到根布局(可选布局参数)
setItemsList<ListItemData>全量设置列表数据,最多 100 条;返回 OperationResult
insertItemposition: Int, item: ListItemData在指定位置插入一条;返回 OperationResult
removeItemposition: Int删除指定位置一条;返回 OperationResult
updateItemposition: Int, item: ListItemData更新指定位置一条(整体替换);返回 OperationResult
setDividerConfigDividerConfig分割线配置;返回 OperationResult
setItemClickEnabledBoolean是否启用 Item 点击;返回 OperationResult

DividerConfig 构造参数:

参数类型说明
heightInt分割线高度(dp)
colorString分割线颜色,"#RRGGBB" 或 "#AARRGGBB"(如 "#33FFFFFF")
paddingLeftInt左侧缩进(dp)
paddingRightInt右侧缩进(dp)
showLastDividerBoolean是否显示最后一条 Item 下方的分割线

事件

方法说明
setOnItemClickListenerItem 点击回调,参数为 (position: Int, itemId: String)。回调在 Binder 线程池执行,更新 UI / 业务需自行切主线程

三、Tips

  1. 列表最多 100 条。setItems 传入超过 MAX_ITEM_COUNT(100)条会抛出 IllegalArgumentException。数据量大时应自行分页或裁剪,不要一次性灌入。
  2. 点击回调不在主线程。setOnItemClickListener 的回调运行在 AIDL 的 Binder 线程池,若要更新 App 自身 View 或做主线程相关操作,需 Handler(Looper.getMainLooper()).post { ... } 切回主线程。
  3. 图标需先上传到 Pilot。ListItemData 的 iconFileName 引用的是 Pilot 端已存在的文件,务必先用 helper.pushImageFile(path, callback) 上传成功后再 setItems,否则 Server 端找不到图标。
  4. updateItem 是整体替换,不是局部更新——新 ListItemData 会完整覆盖该位置旧数据,未设置的字段将回落到默认值。
  5. 分割线颜色用字符串,不同于组件颜色。DividerConfig 与 ListItemData 的颜色是 "#RRGGBB" / "#AARRGGBB" 字符串格式;而 setBackground 等通用属性用的是 ARGB Int。两者不要混用。
  6. 列表需受限高度才能滚动。给 setHeight 一个固定值(如 400dp),内容超出时才会在列表内部滚动,否则会一直撑高。
  7. 修改已挂载组件的属性后要 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.ktopen in new window。

最近修改: