ui_scroll_view

ui_scroll_view 模块提供滚动视图组件，支持内容滚动与滚动事件监听。

Class Summary

OHOS::UIScrollView

支持子视图水平或垂直滚动的视图组，继承自 UIAbstractScroll

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  OnDragEvent	处理拖拽事件
  OnDragEndEvent	处理拖拽结束事件
  OnPressEvent	处理按下事件
  ScrollBy	按指定偏移量滚动视图内容
  SetHorizontalScrollState	设置是否启用水平滚动
  GetHorizontalScrollState	查询是否启用水平滚动
  SetVerticalScrollState	设置是否启用垂直滚动
  GetVerticalScrollState	查询是否启用垂直滚动
  RegisterScrollListener	注册滚动状态变化监听器
  SetVibrationLenThreshold	设置振动长度阈值
  GetVibrationLenThreshold	获取振动长度阈值

• 使用包含头文件：#include "components/ui_scroll_view.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_scroll_view.h
• 公有运算符：无
• 继承关系：UIAbstractScroll
• 嵌套类型：公有嵌套类 OnScrollListener
• 模板形参：无

OHOS::UIScrollView::OnScrollListener

滚动状态变化监听器，包含滚动开始和结束的回调，继承自 HeapBase

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnScrollStart	滚动开始时的回调
  OnScrollEnd	滚动结束时的回调
  GetScrollState	获取当前滚动状态
  SetScrollState	设置滚动状态

• 使用包含头文件：#include "components/ui_scroll_view.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_scroll_view.h
• 公有运算符：无
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::UIScrollView

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 设计目的：为视图类型判断提供统一接口，区分 UIScrollView 与其他视图类型
• 使用场景：视图类型识别、类型安全转换前的类型校验

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_SCROLL_VIEW	当前视图为 UIScrollView 类型

OnDragEvent

bool OnDragEvent(const DragEvent& event) override

功能说明

• 核心用途：处理拖拽事件，实现视图内容随拖拽手势滚动
• 设计目的：将用户的拖拽操作转化为视图内容的滚动偏移
• 使用场景：用户在滚动视图上执行拖拽手势时触发

入参

名称	参数类型	详细说明	约束取值范围
event	const DragEvent&	入参只读引用，拖拽事件对象，包含拖拽方向与距离信息	非 nullptr 的有效 DragEvent 对象

返回值

• 返回类型：bool

返回事件是否已被处理

返回值	触发场景
true(1)	拖拽事件已被处理
false(0)	拖拽事件未被处理

OnDragEndEvent

bool OnDragEndEvent(const DragEvent& event) override

功能说明

• 核心用途：处理拖拽结束事件，执行惯性滚动或回弹动画
• 设计目的：在拖拽手势释放后，根据拖拽速度判断是否继续惯性滚动或回弹到边界
• 使用场景：用户在滚动视图上释放拖拽手势时触发

入参

名称	参数类型	详细说明	约束取值范围
event	const DragEvent&	入参只读引用，拖拽结束事件对象，包含最终拖拽位置信息	非 nullptr 的有效 DragEvent 对象

返回值

• 返回类型：bool

返回事件是否已被处理

返回值	触发场景
true(1)	拖拽结束事件已被处理
false(0)	拖拽结束事件未被处理

OnPressEvent

bool OnPressEvent(const PressEvent& event) override

功能说明

• 核心用途：处理按下事件，在拖拽开始前记录初始触控状态
• 设计目的：为后续拖拽与惯性滚动提供按下时刻的触控基准
• 使用场景：用户在滚动视图上按下触控时触发

入参

名称	参数类型	详细说明	约束取值范围
event	const PressEvent&	入参只读引用，按下事件对象，包含触控点坐标信息	非 nullptr 的有效 PressEvent 对象

返回值

• 返回类型：bool

返回事件是否已被处理

返回值	触发场景
true(1)	按下事件已被处理
false(0)	按下事件未被处理

ScrollBy

void ScrollBy(int16_t xDistance, int16_t yDistance)

功能说明

• 核心用途：按指定偏移量滚动视图内容
• 设计目的：提供程序化控制视图滚动位置的能力，无需依赖手势事件
• 使用场景：代码中主动滚动视图到指定偏移位置、动画驱动的滚动更新

入参

名称	参数类型	详细说明	约束取值范围
xDistance	int16_t	x 轴方向滚动偏移距离（像素）	int16_t 取值范围
yDistance	int16_t	y 轴方向滚动偏移距离（像素）	int16_t 取值范围

SetHorizontalScrollState

void SetHorizontalScrollState(bool state)

功能说明

• 核心用途：设置是否启用水平方向滚动
• 设计目的：控制视图在水平方向的滚动行为，根据业务需求启用或禁用水平滚动
• 使用场景：需要限制只能垂直滚动时禁用水平滚动、需要双向滚动时启用水平滚动

入参

名称	参数类型	详细说明	约束取值范围
state	bool	是否启用水平滚动	true：启用水平滚动；false：禁用水平滚动

GetHorizontalScrollState

bool GetHorizontalScrollState() const

功能说明

• 核心用途：查询当前是否启用水平方向滚动
• 设计目的：为上层业务提供水平滚动状态的查询能力
• 使用场景：业务逻辑需要判断水平滚动是否可用时调用

返回值

• 返回类型：bool

返回水平滚动是否启用

返回值	触发场景
true(1)	水平滚动已启用
false(0)	水平滚动未启用

SetVerticalScrollState

void SetVerticalScrollState(bool state)

功能说明

• 核心用途：设置是否启用垂直方向滚动
• 设计目的：控制视图在垂直方向的滚动行为，根据业务需求启用或禁用垂直滚动
• 使用场景：需要限制只能水平滚动时禁用垂直滚动、需要双向滚动时启用垂直滚动

入参

名称	参数类型	详细说明	约束取值范围
state	bool	是否启用垂直滚动	true：启用垂直滚动；false：禁用垂直滚动

GetVerticalScrollState

bool GetVerticalScrollState() const

功能说明

• 核心用途：查询当前是否启用垂直方向滚动
• 设计目的：为上层业务提供垂直滚动状态的查询能力
• 使用场景：业务逻辑需要判断垂直滚动是否可用时调用

返回值

• 返回类型：bool

返回垂直滚动是否启用

返回值	触发场景
true(1)	垂直滚动已启用
false(0)	垂直滚动未启用

RegisterScrollListener

void RegisterScrollListener(OnScrollListener* scrollListener)

功能说明

• 核心用途：注册滚动状态变化监听器，监听滚动开始和结束事件
• 设计目的：为外部业务提供滚动状态变化的回调通知机制
• 使用场景：需要在滚动开始或结束时执行自定义逻辑（如刷新指示器、同步其他视图）

入参

名称	参数类型	详细说明	约束取值范围
scrollListener	OnScrollListener*	入参指针，滚动监听器对象指针	有效指针或 nullptr

SetVibrationLenThreshold

void SetVibrationLenThreshold(uint16_t value)

功能说明

• 核心用途：设置滚动触发振动的长度阈值
• 设计目的：控制滚动过程中触发振动反馈的距离门槛
• 使用场景：需要调整滚动触感振动灵敏度时设置该阈值

入参

名称	参数类型	详细说明	约束取值范围
value	uint16_t	振动长度阈值（像素）	uint16_t 取值范围

Kconfig 配置

配置项	说明	默认值
ENABLE_VIBRATOR	启用振动功能	n

GetVibrationLenThreshold

uint16_t GetVibrationLenThreshold() const

功能说明

• 核心用途：获取当前滚动触发振动的长度阈值
• 设计目的：为上层业务提供振动阈值查询能力
• 使用场景：需要读取当前振动灵敏度设置时调用

返回值

• 返回类型：uint16_t

返回振动长度阈值

返回值	触发场景
uint16_t 值	当前设置的振动长度阈值（像素）

Kconfig 配置

配置项	说明	默认值
ENABLE_VIBRATOR	启用振动功能	n

OHOS::UIScrollView::OnScrollListener

OnScrollStart

virtual void OnScrollStart()

功能说明

• 核心用途：滚动开始时的回调，由子类重写以实现自定义的滚动开始逻辑
• 设计目的：提供滚动开始事件的通知入口，支持业务在滚动启动时执行自定义处理
• 使用场景：需要在滚动开始时刷新 UI 状态、记录日志或同步其他组件

OnScrollEnd

virtual void OnScrollEnd()

功能说明

• 核心用途：滚动结束时的回调，由子类重写以实现自定义的滚动结束逻辑
• 设计目的：提供滚动结束事件的通知入口，支持业务在滚动停止时执行自定义处理
• 使用场景：需要在滚动结束后刷新数据、隐藏滚动条或触发后续操作

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)