ui_list
ui_list 模块提供列表组件，支持列表项滚动与滚动事件监听。
Class Summary
OHOS::ListScrollListener
列表滚动状态监听器，包含滚动状态变化和子视图选中时的回调接口
- 构造：无
-
成员函数：
接口名称 功能简述 OnScrollStart 滚动开始时回调 OnScrollEnd 滚动结束时回调 OnScrollTop 滚动到顶部时回调 OnScrollBottom 滚动到底部时回调 OnItemSelected 预设位置子视图被选中时回调 GetScrollState 获取当前滚动状态 SetScrollState 设置滚动状态 -
使用包含头文件：
#include "components/ui_list.h" - 声明头文件：
middleware/services/gui/uikit/ui/interfaces/kits/components/ui_list.h - 公有运算符：无
- 继承关系：HeapBase
- 嵌套类型：无
- 模板形参：无
OHOS::UIList
可滚动列表组件，配合适配器实现滚动、惯性滚动、自动对齐及子视图选中回调
- 构造：
explicit UIList(uint8_t direction) -
成员函数：
接口名称 功能简述 UIList 按指定方向构造列表实例 GetViewType 获取视图类型 OnDragEvent 处理拖拽事件 OnDragEndEvent 处理拖拽结束事件 OnPressEvent 处理按压事件 OnRotateStartEvent 处理旋转开始事件 OnRotateEndEvent 处理旋转结束事件 SetAdapter 设置列表适配器 MoveChildByOffset 按偏移量移动所有子视图 ScrollTo 滚动到指定索引位置 ScrollBy 按距离滚动列表内容 SetStartIndex 设置列表起始索引 GetStartIndex 获取列表起始索引 SetLoopState 设置列表循环状态 GetLoopState 获取列表循环状态 SetSelectPosition 设置子视图选中位置 GetSelectView 获取预设位置的选中子视图 SetScrollStateListener 设置滚动状态监听器 RefreshList 刷新列表 EnableAutoAlign 设置自动对齐状态 SetAutoAlignTime 设置自动对齐动画时长 EnableCrossDragBack 设置自动对齐回拉模式 GetAutoAlignTime 获取自动对齐动画时长 GetItemCount 获取列表项数量 SetXScrollBarVisible 设置水平滚动条可见性 SetYScrollBarVisible 设置垂直滚动条可见性 RemoveAll 移除所有子视图 -
使用包含头文件：
#include "components/ui_list.h" - 声明头文件：
middleware/services/gui/uikit/ui/interfaces/kits/components/ui_list.h - 公有运算符：无
- 继承关系：UIAbstractScroll
- 嵌套类型：无
- 模板形参：无
Functions
OHOS::ListScrollListener
OnScrollStart
virtual void OnScrollStart(int16_t index, UIView* view)
功能说明
- 核心用途：列表滚动开始时的回调通知
- 设计目的：允许派生类在滚动起始时执行自定义逻辑
- 使用场景：滚动开始时触发选中项高亮、动画启动等交互效果
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| index | int16_t | 预设位置处被选中的子视图索引 | NULL_SELECT_INDEX(-1) 表示无选中 |
| view | UIView* | 预设位置处被选中的子视图指针 | nullptr 表示无选中或未设置预设位置 |
OnScrollEnd
virtual void OnScrollEnd(int16_t index, UIView* view)
功能说明
- 核心用途：列表滚动结束时的回调通知
- 设计目的：允许派生类在滚动结束时执行自定义逻辑
- 使用场景：滚动停止后更新选中项状态、触发数据加载等
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| index | int16_t | 预设位置处被选中的子视图索引 | NULL_SELECT_INDEX(-1) 表示无选中 |
| view | UIView* | 预设位置处被选中的子视图指针 | nullptr 表示无选中或未设置预设位置 |
OnScrollTop
virtual void OnScrollTop(int16_t index, UIView* view)
功能说明
- 核心用途：列表滚动到顶部时的回调通知
- 设计目的：允许派生类在列表到达顶部时执行自定义逻辑
- 使用场景：到达顶部时禁用向上滚动指示器、触发刷新等
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| index | int16_t | 预设位置处被选中的子视图索引 | NULL_SELECT_INDEX(-1) 表示无选中 |
| view | UIView* | 预设位置处被选中的子视图指针 | nullptr 表示无选中或未设置预设位置 |
OnScrollBottom
virtual void OnScrollBottom(int16_t index, UIView* view)
功能说明
- 核心用途：列表滚动到底部时的回调通知
- 设计目的：允许派生类在列表到达底部时执行自定义逻辑
- 使用场景：到达底部时禁用向下滚动指示器、触发加载更多等
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| index | int16_t | 预设位置处被选中的子视图索引 | NULL_SELECT_INDEX(-1) 表示无选中 |
| view | UIView* | 预设位置处被选中的子视图指针 | nullptr 表示无选中或未设置预设位置 |
OnItemSelected
virtual void OnItemSelected(int16_t index, UIView* view)
功能说明
- 核心用途：列表滚动过程中预设位置子视图被选中时的回调通知
- 设计目的：允许派生类在子视图经过预设位置时执行自定义逻辑，如缩放、变色等效果
- 使用场景：实现列表项选中放大、高亮等视觉效果
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| index | int16_t | 预设位置处被选中的子视图索引 | NULL_SELECT_INDEX(-1) 表示无选中 |
| view | UIView* | 预设位置处被选中的子视图指针 | nullptr 表示无选中或未设置预设位置 |
GetScrollState
uint8_t GetScrollState() const
功能说明
- 核心用途：获取当前列表的滚动状态
- 设计目的：为调用者提供滚动状态查询能力
- 使用场景：根据滚动状态决定是否响应某些交互操作
返回值
- 返回类型：
uint8_t
返回滚动状态
| 返回值 | 触发场景 |
|---|---|
| SCROLL_STATE_STOP(0) | 列表处于停止状态 |
| SCROLL_STATE_MOVE(1) | 列表处于滚动状态 |
SetScrollState
void SetScrollState(uint8_t state)
功能说明
- 核心用途：设置列表的滚动状态
- 设计目的：允许外部代码修改滚动状态标识
- 使用场景：手动控制滚动状态标记
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| state | uint8_t | 待设置的滚动状态 | SCROLL_STATE_STOP(0) / SCROLL_STATE_MOVE(1) |
OHOS::UIList
UIList(uint8_t direction)
explicit UIList(uint8_t direction)
功能说明
- 核心用途：按指定方向构造 UIList 实例
- 设计目的：创建水平或垂直方向的可滚动列表
- 使用场景：需要创建指定方向的列表组件时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| direction | uint8_t | 列表滚动方向 | HORIZONTAL / VERTICAL |
GetViewType
UIViewType GetViewType() const override
功能说明
- 核心用途：获取当前视图的类型标识
- 设计目的：区分不同类型的 UIView，支持视图类型判断
- 使用场景：需要判断视图是否为列表类型时调用
返回值
- 返回类型：
UIViewType
返回视图类型标识
| 返回值 | 触发场景 |
|---|---|
| UI_LIST | 当前视图为列表类型 |
OnDragEvent
bool OnDragEvent(const DragEvent& event) override
功能说明
- 核心用途：处理拖拽事件
- 设计目的：响应列表拖拽操作，实现列表内容跟随手指移动
- 使用场景：用户在列表区域执行拖拽手势时由事件分发系统调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件数据 | - |
返回值
- 返回类型：
bool
返回事件是否被消费
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已被消费 |
| false(0) | 事件未被消费 |
OnDragEndEvent
bool OnDragEndEvent(const DragEvent& event) override
功能说明
- 核心用途：处理拖拽结束事件
- 设计目的：响应拖拽结束操作，触发惯性滚动或自动对齐
- 使用场景：用户在列表区域结束拖拽手势时由事件分发系统调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽结束事件数据 | - |
返回值
- 返回类型：
bool
返回事件是否被消费
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已被消费 |
| false(0) | 事件未被消费 |
OnPressEvent
bool OnPressEvent(const PressEvent& event) override
功能说明
- 核心用途：处理按压事件
- 设计目的：响应列表按压操作
- 使用场景：用户在列表区域执行按压操作时由事件分发系统调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const PressEvent& | 入参只读引用，按压事件数据 | - |
返回值
- 返回类型：
bool
返回事件是否被消费
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已被消费 |
| false(0) | 事件未被消费 |
OnRotateStartEvent
bool OnRotateStartEvent(const RotateEvent& event) override
功能说明
- 核心用途：处理旋转开始事件
- 设计目的：响应旋转输入设备的开始旋转操作
- 使用场景：用户通过旋转输入设备开始操作时由事件分发系统调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转开始事件数据 | - |
返回值
- 返回类型：
bool
返回事件是否被消费
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已被消费 |
| false(0) | 事件未被消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 启用旋转输入支持 | n |
OnRotateEndEvent
bool OnRotateEndEvent(const RotateEvent& event) override
功能说明
- 核心用途：处理旋转结束事件
- 设计目的：响应旋转输入设备的结束旋转操作
- 使用场景：用户通过旋转输入设备结束操作时由事件分发系统调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转结束事件数据 | - |
返回值
- 返回类型：
bool
返回事件是否被消费
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已被消费 |
| false(0) | 事件未被消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 启用旋转输入支持 | n |
SetAdapter
void SetAdapter(AbstractAdapter* adapter)
功能说明
- 核心用途：设置列表适配器，设置时自动初始化列表内容
- 设计目的：通过适配器模式为列表提供数据和子视图创建能力
- 使用场景：列表创建后、显示数据前设置适配器以绑定数据源
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| adapter | AbstractAdapter* | 入参指针，适配器实例 | nullptr 表示清除适配器 |
MoveChildByOffset
virtual void MoveChildByOffset(int16_t x, int16_t y) override
功能说明
- 核心用途：按指定偏移量移动所有子视图位置
- 设计目的：实现列表内容整体偏移，支持滚动过程中子视图位置更新
- 使用场景：列表滚动时需整体移动子视图位置
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| x | int16_t | X 轴偏移距离（像素） | - |
| y | int16_t | Y 轴偏移距离（像素） | - |
ScrollTo
void ScrollTo(uint16_t index)
功能说明
- 核心用途：滚动列表使指定索引成为当前视图的首行/首列
- 设计目的：提供列表的绝对定位滚动能力
- 使用场景：需要跳转到列表指定位置时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| index | uint16_t | 目标首行/首列索引 | 0 ~ GetItemCount() - 1 |
ScrollBy
void ScrollBy(int16_t distance)
功能说明
- 核心用途：按指定距离滚动列表内容
- 设计目的：提供列表的相对距离滚动能力
- 使用场景：需要按像素距离滚动列表时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| distance | int16_t | 滚动距离（像素） | - |
SetStartIndex
void SetStartIndex(uint16_t index)
功能说明
- 核心用途：设置列表的起始索引
- 设计目的：指定列表显示的起始位置，默认值为 0
- 使用场景：需要从指定位置开始显示列表内容时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| index | uint16_t | 起始索引 | 0 ~ GetItemCount() - 1 |
GetStartIndex
uint16_t GetStartIndex() const
功能说明
- 核心用途：获取列表的起始索引
- 设计目的：查询列表当前显示的起始位置
- 使用场景：需要获知列表从哪个位置开始显示时调用
返回值
- 返回类型：
uint16_t
返回起始索引
| 返回值 | 触发场景 |
|---|---|
| 0 | 默认起始位置 |
| 其他值 | 通过 SetStartIndex 设置的起始位置 |
SetLoopState
void SetLoopState(bool state)
功能说明
- 核心用途：设置列表的循环滚动状态
- 设计目的：启用后列表首尾相连，支持无限循环滚动
- 使用场景：需要列表首尾衔接循环滚动时启用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| state | bool | 循环状态 | true 启用循环 / false 关闭循环 |
GetLoopState
bool GetLoopState() const
功能说明
- 核心用途：获取列表的循环滚动状态
- 设计目的：查询列表是否处于循环模式
- 使用场景：需要判断列表是否为循环模式时调用
返回值
- 返回类型：
bool
返回循环状态
| 返回值 | 触发场景 |
|---|---|
| true(1) | 列表处于循环模式 |
| false(0) | 列表处于普通模式 |
SetSelectPosition
void SetSelectPosition(uint16_t position)
功能说明
- 核心用途：设置列表滚动时子视图被选中的预设位置
- 设计目的：当子视图经过预设位置时触发 ListScrollListener 回调，可在回调中实现缩放、变色等效果
- 使用场景：需要标记列表中某个位置为选中位置时调用，默认值为 0
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| position | uint16_t | 选中位置 | 0 表示未设置预设位置 |
GetSelectView
UIView* GetSelectView()
功能说明
- 核心用途：获取预设位置处当前被选中的子视图
- 设计目的：查询预设位置的选中子视图实例
- 使用场景：需要获取当前选中项的视图对象进行操作时调用
返回值
- 返回类型：
UIView*
返回选中子视图指针
| 返回值 | 触发场景 |
|---|---|
| 非空指针 | 预设位置有子视图被选中 |
| nullptr | 无子视图被选中或未设置预设位置 |
SetScrollStateListener
void SetScrollStateListener(ListScrollListener* scrollListener)
功能说明
- 核心用途：设置滚动状态监听器
- 设计目的：注册监听器以接收滚动状态变化和子视图选中回调
- 使用场景：需要在列表滚动状态变化或子视图选中时执行自定义逻辑时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| scrollListener | ListScrollListener* | 入参指针，滚动状态监听器实例 | nullptr 表示清除监听器 |
RefreshList
void RefreshList()
功能说明
- 核心用途：刷新列表显示
- 设计目的：保持当前视图内子视图数量固定，滚动时保留子视图位置不变
- 使用场景：数据源发生变化后需要更新列表显示时调用
EnableAutoAlign
void EnableAutoAlign(bool state)
功能说明
- 核心用途：设置列表自动对齐状态
- 设计目的：启用后滚动停止时自动将子视图对齐到预设位置
- 使用场景：需要列表滚动停止后自动吸附对齐到最近子视图时启用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| state | bool | 自动对齐状态 | true 启用自动对齐 / false 关闭自动对齐 |
SetAutoAlignTime
void SetAutoAlignTime(uint16_t time)
功能说明
- 核心用途：设置自动对齐动画时长
- 设计目的：控制自动对齐过程的动画持续时间，依赖 EnableAutoAlign 启用后生效
- 使用场景：需要调整自动对齐动画速度时调用，0 表示无动画
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| time | uint16_t | 自动对齐动画时长（毫秒） | 0 表示无动画，默认 100 毫秒 |
EnableCrossDragBack
void EnableCrossDragBack(bool dragBack)
功能说明
- 核心用途：设置自动对齐回拉模式
- 设计目的：控制子视图部分越过预设位置时的对齐方向——回拉到原位或继续前进到下一项
- 使用场景：需要精细控制自动对齐行为时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| dragBack | bool | 对齐模式 | true 部分越过时回拉 / false 部分越过时前进到下一项 |
GetAutoAlignTime
uint16_t GetAutoAlignTime() const
功能说明
- 核心用途：获取自动对齐动画时长
- 设计目的：查询当前自动对齐动画的持续时间配置
- 使用场景：需要读取自动对齐动画时长设置时调用
返回值
- 返回类型：
uint16_t
返回自动对齐动画时长（毫秒）
| 返回值 | 触发场景 |
|---|---|
| 0 | 无动画 |
| 100 | 默认动画时长 |
| 其他值 | 通过 SetAutoAlignTime 设置的时长 |
GetItemCount
uint16_t GetItemCount()
功能说明
- 核心用途：获取列表项数量
- 设计目的：查询适配器提供的数据项总数
- 使用场景：需要获知列表数据项数量时调用
返回值
- 返回类型：
uint16_t
返回列表项数量
| 返回值 | 触发场景 |
|---|---|
| 0 | 未设置适配器或适配器无数据 |
| 其他值 | 适配器提供的数据项数量 |
SetXScrollBarVisible
void SetXScrollBarVisible(bool visible)
功能说明
- 核心用途：设置水平滚动条可见性
- 设计目的：控制水平方向滚动条的显示与隐藏
- 使用场景：需要显示或隐藏水平滚动条时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| visible | bool | 可见性 | true 显示 / false 隐藏 |
SetYScrollBarVisible
void SetYScrollBarVisible(bool visible)
功能说明
- 核心用途：设置垂直滚动条可见性
- 设计目的：控制垂直方向滚动条的显示与隐藏
- 使用场景：需要显示或隐藏垂直滚动条时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| visible | bool | 可见性 | true 显示 / false 隐藏 |
RemoveAll
void RemoveAll() override
功能说明
- 核心用途：移除列表中所有子视图
- 设计目的：清空列表显示内容
- 使用场景：需要清空列表全部子视图时调用