ui_abstract_scroll

ui_abstract_scroll 模块提供抽象滚动组件，包含滚动条与滚动容器的通用属性、动画缓动与布局计算功能。

Class Summary

OHOS::BarEaseInOutAnimator

前向声明类，定义不在本头文件中

• 构造：无
• 成员函数：无
• 使用包含头文件：#include "components/ui_abstract_scroll.h"
• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_abstract_scroll.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

OHOS::UIAbstractScrollBar

前向声明类，定义不在本头文件中

• 构造：无
• 成员函数：无
• 使用包含头文件：#include "components/ui_abstract_scroll.h"
• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_abstract_scroll.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

OHOS::UIAbstractScroll

定义滚动视图的属性，包括滚动方向、空白大小、动画速度与效果

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  SetScrollBlankSize	设置滚动视图空白大小
  GetScrollBlankSize	获取滚动视图空白大小
  SetMaxScrollDistance	设置手指抬起后最大滚动距离
  SetReboundSize	设置回弹距离
  GetReboundSize	获取回弹距离
  GetMaxScrollDistance	获取最大滚动距离
  SetDragFunc	设置拖动缓动函数
  GetDragFunc	获取拖动缓动函数
  SetThrowDrag	设置手指抬起后是否继续滚动
  SetElastic	设置是否启用弹性回弹模式
  SetElasticTime	设置弹性回弹时间
  MoveChildByOffset	移动所有子视图位置
  SetDragACCLevel	设置拖动加速度
  GetDragACCLevel	获取拖动加速度
  SetSwipeACCLevel	设置手指抬起后补偿距离
  GetSwipeACCLevel	获取手指抬起后补偿距离
  SetRotateACCLevel	设置旋转拖抛动画系数
  GetRotateACCLevel	获取旋转拖抛动画系数
  GetRotateFactor	获取旋转因子
  SetRotateFactor	设置旋转因子
  SetRotateThrowThreshold	设置旋转拖抛阈值
  GetRotateThrowThreshold	获取旋转拖抛阈值
  OnRotateStartEvent	处理旋转开始事件
  OnRotateEvent	处理旋转事件
  OnRotateEndEvent	处理旋转结束事件
  SetXScrollBarVisible	设置水平滚动条可见性
  SetYScrollBarVisible	设置垂直滚动条可见性
  SetScrollBarSide	设置滚动条位置
  GetScrollBarSide	获取滚动条位置
  SetScrollBarCenter	设置滚动条中心点
  GetScrollBarCenter	获取滚动条中心点
  SetDirection	设置列表滚动方向
  GetDirection	获取列表滚动方向
  OnPostDraw	后置绘制回调
  GetScrollState	获取滚动动画状态

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

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

Functions

OHOS::UIAbstractScroll

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 返回值固定为 UI_ABSTRACT_SCROLL，用于区分不同类型的 UIView
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_ABSTRACT_SCROLL	当前对象为 UIAbstractScroll 类型

SetScrollBlankSize

void SetScrollBlankSize(uint16_t size, UIAbstractScroll::Direction direction = UIAbstractScroll::Direction::ALL)

功能说明

• 核心用途：设置滚动视图在指定方向上的空白大小
• 当 direction 为 ALL 时，同时设置所有方向的空白大小；指定方向时仅设置该方向的空白大小
• 默认空白大小为 0，即首尾节点滚动到视图边界即停止

入参

名称	参数类型	详细说明	约束取值范围
size	uint16_t	空白大小（像素）	0 ~ 65535
direction	UIAbstractScroll::Direction	空白大小设置的方向	Direction 枚举值，默认 ALL

GetScrollBlankSize

uint16_t GetScrollBlankSize(UIAbstractScroll::Direction direction = UIAbstractScroll::Direction::ALL) const

功能说明

• 核心用途：获取滚动视图在指定方向上的空白大小
• 根据传入方向返回对应的空白大小值
• 该函数为 const 成员函数，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
direction	UIAbstractScroll::Direction	查询空白大小的方向	Direction 枚举值，默认 ALL

返回值

• 返回类型：uint16_t

返回指定方向的空白大小（像素）

返回值	触发场景
0	该方向未设置空白大小
非0值	该方向已设置的空白大小

SetMaxScrollDistance

void SetMaxScrollDistance(uint16_t distance)

功能说明

• 核心用途：设置手指抬起后滚动视图的最大滚动距离
• 默认值为 0，表示不限制滚动距离
• 该值用于限制惯性滚动的总距离

入参

名称	参数类型	详细说明	约束取值范围
distance	uint16_t	最大滚动距离（像素）	0 ~ 65535，0 表示不限制

SetReboundSize

void SetReboundSize(uint16_t size, UIAbstractScroll::Direction direction = UIAbstractScroll::Direction::ALL)

功能说明

• 核心用途：设置滚动条滑块到达末端释放后的回弹距离
• 当 direction 为 ALL 时，同时设置所有方向的回弹距离；指定方向时仅设置该方向的回弹距离
• 回弹距离指滑块到达末端释放后可继续移动的距离

入参

名称	参数类型	详细说明	约束取值范围
size	uint16_t	回弹距离（像素）	0 ~ 65535
direction	UIAbstractScroll::Direction	回弹距离设置的方向	Direction 枚举值，默认 ALL

GetReboundSize

uint16_t GetReboundSize(UIAbstractScroll::Direction direction = UIAbstractScroll::Direction::ALL) const

功能说明

• 核心用途：获取滚动条滑块到达末端释放后的回弹距离
• 根据传入方向返回对应的回弹距离值
• 该函数为 const 成员函数，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
direction	UIAbstractScroll::Direction	查询回弹距离的方向	Direction 枚举值，默认 ALL

返回值

• 返回类型：uint16_t

返回指定方向的回弹距离（像素）

返回值	触发场景
0	该方向未设置回弹距离
非0值	该方向已设置的回弹距离

GetMaxScrollDistance

uint16_t GetMaxScrollDistance() const

功能说明

• 核心用途：获取手指抬起后滚动视图的最大滚动距离
• 默认值为 0，表示不限制滚动距离
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：uint16_t

返回最大滚动距离（像素）

返回值	触发场景
0	未限制滚动距离
非0值	已设置的最大滚动距离

SetDragFunc

void SetDragFunc(EasingFunc func)

功能说明

• 核心用途：设置手指抬起后滚动动画的缓动函数
• 默认缓动函数为 EasingEquation::CubicEaseOut
• 缓动函数决定滚动动画的速度曲线

入参

名称	参数类型	详细说明	约束取值范围
func	EasingFunc	缓动函数指针	有效的 EasingFunc 函数指针

GetDragFunc

EasingFunc GetDragFunc() const

功能说明

• 核心用途：获取当前设置的拖动缓动函数
• 默认缓动函数为 EasingEquation::CubicEaseOut
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：EasingFunc

返回当前缓动函数指针

返回值	触发场景
非nullptr	已设置的缓动函数指针
nullptr	未设置缓动函数

SetThrowDrag

void SetThrowDrag(bool throwDrag)

功能说明

• 核心用途：设置手指抬起后是否继续惯性滚动
• true 表示继续惯性滚动，false 表示手指抬起后立即停止
• 默认值为 false

入参

名称	参数类型	详细说明	约束取值范围
throwDrag	bool	是否启用惯性滚动	true / false

SetElastic

void SetElastic(bool isElastic)

功能说明

• 核心用途：设置滚动越界后是否启用弹性回弹模式
• true 表示启用弹性回弹，false 表示不启用
• 默认值为 false

入参

名称	参数类型	详细说明	约束取值范围
isElastic	bool	是否启用弹性回弹	true / false

SetElasticTime

void SetElasticTime(uint16_t elasticTime)

功能说明

• 核心用途：设置弹性回弹动画的持续时间
• 默认值为 200（毫秒）
• 仅在弹性模式启用时生效

入参

名称	参数类型	详细说明	约束取值范围
elasticTime	uint16_t	弹性回弹时间（毫秒）	0 ~ 65535，默认 200

MoveChildByOffset

void MoveChildByOffset(int16_t offsetX, int16_t offsetY) override

功能说明

• 核心用途：将所有子视图移动指定偏移量
• offsetX 为 X 轴偏移距离，offsetY 为 Y 轴偏移距离
• 该函数重写自 UIViewGroup 基类

入参

名称	参数类型	详细说明	约束取值范围
offsetX	int16_t	X 轴偏移距离（像素）	-32768 ~ 32767
offsetY	int16_t	Y 轴偏移距离（像素）	-32768 ~ 32767

SetDragACCLevel

void SetDragACCLevel(uint8_t value)

功能说明

• 核心用途：设置拖动加速度系数
• 加速度系数越大，惯性滚动速度越快
• 默认值为 10；传入 0 时设置不生效

入参

名称	参数类型	详细说明	约束取值范围
value	uint8_t	拖动加速度系数	1 ~ 255，0 不生效

GetDragACCLevel

uint8_t GetDragACCLevel() const

功能说明

• 核心用途：获取当前拖动加速度系数
• 默认值为 10
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：uint8_t

返回拖动加速度系数

返回值	触发场景
10	默认加速度系数
其他值	已设置的加速度系数

SetSwipeACCLevel

void SetSwipeACCLevel(uint8_t value)

功能说明

• 核心用途：设置手指抬起后补偿距离系数
• 补偿距离系数影响手指抬起后的额外滚动距离
• 默认值为 0

入参

名称	参数类型	详细说明	约束取值范围
value	uint8_t	补偿距离系数	0 ~ 255

GetSwipeACCLevel

uint8_t GetSwipeACCLevel() const

功能说明

• 核心用途：获取手指抬起后补偿距离系数
• 默认值为 0
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：uint8_t

返回补偿距离系数

返回值	触发场景
0	未设置补偿距离系数
非0值	已设置的补偿距离系数

SetRotateACCLevel

void SetRotateACCLevel(uint8_t value)

功能说明

• 核心用途：设置旋转拖抛动画系数
• 系数越大，旋转拖抛后滚动距离越远
• 默认值为 0

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置
• 当前对象已构造完成

入参

名称	参数类型	详细说明	约束取值范围
value	uint8_t	旋转拖抛动画系数	0 ~ 255

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

GetRotateACCLevel

uint8_t GetRotateACCLevel() const

功能说明

• 核心用途：获取旋转拖抛动画系数
• 系数越大，旋转拖抛后滚动距离越远
• 该函数为 const 成员函数，不修改对象状态

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置

返回值

• 返回类型：uint8_t

返回旋转拖抛动画系数

返回值	触发场景
0	未设置旋转拖抛系数
非0值	已设置的旋转拖抛系数

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

GetRotateFactor

float GetRotateFactor() const

功能说明

• 核心用途：获取旋转因子
• 旋转因子影响旋转输入与滚动距离的映射比例
• 该函数为 const 成员函数，不修改对象状态

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置

返回值

• 返回类型：float

返回旋转因子

返回值	触发场景
正值	正向旋转因子
负值	反向旋转因子

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

SetRotateFactor

void SetRotateFactor(float factor)

功能说明

• 核心用途：设置旋转因子
• 旋转因子绝对值超过 MAX_ROTATE_FACTOR(128) 时会被截断为边界值
• 正值表示正向旋转，负值表示反向旋转

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置
• 当前对象已构造完成

入参

名称	参数类型	详细说明	约束取值范围
factor	float	旋转因子	-128.0 ~ 128.0，超出范围自动截断

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

SetRotateThrowThreshold

void SetRotateThrowThreshold(uint8_t threshold)

功能说明

• 核心用途：设置旋转拖抛阈值
• 阈值越大，旋转拖抛越容易触发滚动
• 传入 0 时不生效

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置
• 当前对象已构造完成

入参

名称	参数类型	详细说明	约束取值范围
threshold	uint8_t	旋转拖抛阈值	1 ~ 255，0 不生效

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

GetRotateThrowThreshold

uint8_t GetRotateThrowThreshold() const

功能说明

• 核心用途：获取旋转拖抛阈值
• 阈值越大，旋转拖抛越容易触发滚动
• 该函数为 const 成员函数，不修改对象状态

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置

返回值

• 返回类型：uint8_t

返回旋转拖抛阈值

返回值	触发场景
0	未设置旋转拖抛阈值
非0值	已设置的旋转拖抛阈值

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

OnRotateStartEvent

bool OnRotateStartEvent(const RotateEvent& event) override

功能说明

• 核心用途：处理旋转开始事件
• 重写自基类的旋转事件处理函数
• 返回 true 表示事件已消费，false 表示未消费

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置
• 当前对象已添加到视图树中

入参

名称	参数类型	详细说明	约束取值范围
event	const RotateEvent&	入参只读引用，旋转事件数据	有效的 RotateEvent 对象

返回值

• 返回类型：bool

返回事件消费状态

返回值	触发场景
true	旋转开始事件已消费
false	旋转开始事件未消费

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

OnRotateEvent

bool OnRotateEvent(const RotateEvent& event) override

功能说明

• 核心用途：处理旋转进行中事件
• 重写自基类的旋转事件处理函数
• 返回 true 表示事件已消费，false 表示未消费

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置
• 旋转事件已开始（OnRotateStartEvent 已调用）

入参

名称	参数类型	详细说明	约束取值范围
event	const RotateEvent&	入参只读引用，旋转事件数据	有效的 RotateEvent 对象

返回值

• 返回类型：bool

返回事件消费状态

返回值	触发场景
true	旋转事件已消费
false	旋转事件未消费

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

OnRotateEndEvent

bool OnRotateEndEvent(const RotateEvent& event) override

功能说明

• 核心用途：处理旋转结束事件
• 重写自基类的旋转事件处理函数
• 返回 true 表示事件已消费，false 表示未消费

前置条件

• 需启用 ENABLE_ROTATE_INPUT 宏配置
• 旋转事件已开始（OnRotateStartEvent 已调用）

入参

名称	参数类型	详细说明	约束取值范围
event	const RotateEvent&	入参只读引用，旋转事件数据	有效的 RotateEvent 对象

返回值

• 返回类型：bool

返回事件消费状态

返回值	触发场景
true	旋转结束事件已消费
false	旋转结束事件未消费

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	启用旋转输入功能	n

SetXScrollBarVisible

void SetXScrollBarVisible(bool visible)

功能说明

• 核心用途：设置水平滚动条的可见性
• true 表示显示水平滚动条，false 表示隐藏
• 默认值为 false

入参

名称	参数类型	详细说明	约束取值范围
visible	bool	水平滚动条是否可见	true / false

SetYScrollBarVisible

void SetYScrollBarVisible(bool visible)

功能说明

• 核心用途：设置垂直滚动条的可见性
• true 表示显示垂直滚动条，false 表示隐藏
• 默认值为 false

入参

名称	参数类型	详细说明	约束取值范围
visible	bool	垂直滚动条是否可见	true / false

SetScrollBarSide

void SetScrollBarSide(uint8_t side)

功能说明

• 核心用途：设置滚动条的位置
• side 值决定滚动条显示在视图的哪一侧
• 默认值由内部成员 scrollBarSide_ 决定

入参

名称	参数类型	详细说明	约束取值范围
side	uint8_t	滚动条位置	0 ~ 255

GetScrollBarSide

uint8_t GetScrollBarSide()

功能说明

• 核心用途：获取滚动条的位置
• 返回当前滚动条的位置值

返回值

• 返回类型：uint8_t

返回滚动条位置

返回值	触发场景
当前值	当前滚动条位置

SetScrollBarCenter

void SetScrollBarCenter(const Point& center)

功能说明

• 核心用途：设置滚动条的中心点位置
• 设置中心点后，滚动条将以该点为中心绘制
• 调用此函数会同时设置 scrollBarCenterSetFlag_ 标志为 true

入参

名称	参数类型	详细说明	约束取值范围
center	const Point&	入参只读引用，滚动条中心点坐标	有效的 Point 对象

GetScrollBarCenter

Point GetScrollBarCenter()

功能说明

• 核心用途：获取滚动条的中心点位置
• 返回当前滚动条中心点的坐标

返回值

• 返回类型：Point

返回滚动条中心点坐标

返回值	触发场景
Point	当前滚动条中心点坐标

SetDirection

void SetDirection(uint8_t direction)

功能说明

• 核心用途：设置列表的滚动方向
• HORIZONTAL(0) 表示水平方向，VERTICAL(1) 表示垂直方向
• 默认方向由内部成员 direction_ 决定

入参

名称	参数类型	详细说明	约束取值范围
direction	uint8_t	滚动方向	HORIZONTAL(0) / VERTICAL(1)

GetDirection

uint8_t GetDirection() const

功能说明

• 核心用途：获取列表的滚动方向
• 返回 HORIZONTAL(0) 或 VERTICAL(1)
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：uint8_t

返回滚动方向

返回值	触发场景
0 (HORIZONTAL)	水平方向滚动
1 (VERTICAL)	垂直方向滚动

OnPostDraw

void OnPostDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override

功能说明

• 核心用途：在视图绘制完成后执行后置绘制操作
• 重写自基类的后置绘制回调函数
• 用于绘制滚动条等需要在子视图之上显示的元素

入参

名称	参数类型	详细说明	约束取值范围
gfxDstBuffer	BufferInfo&	出参引用，图形目标缓冲区	有效的 BufferInfo 对象
invalidatedArea	const Rect&	入参只读引用，需要重绘的区域	有效的 Rect 对象

GetScrollState

uint8_t GetScrollState()

功能说明

• 核心用途：获取滚动动画的当前状态
• 返回值来自内部 scrollAnimator_ 的状态
• 用于判断滚动动画是否正在执行

返回值

• 返回类型：uint8_t

返回滚动动画状态

返回值	触发场景
动画状态值	当前滚动动画的状态

Type definitions

EasingFunc

typedef int16_t (*EasingFunc)(int16_t startPos, int16_t endPos, uint16_t curTime, uint16_t durationTime);

使用说明：作为 SetDragFunc / GetDragFunc 接口的参数和返回类型，用于定义滚动动画的缓动函数

Enumerations

UIAbstractScroll::Direction

enum class Direction {
    ALL,
    TOP,
    BOTTOM,
    LEFT,
    RIGHT,
};

枚举成员	取值	描述
ALL	0	所有方向
TOP	1	顶部方向
BOTTOM	2	底部方向
LEFT	3	左侧方向
RIGHT	4	右侧方向