ui_swipe_view

ui_swipe_view 模块提供滑动切换视图组件，支持子视图左右滑动切换与滑动事件监听。

Class Summary

OHOS::UISwipeView

滑动视图组件，支持水平或垂直方向上多个子视图的滑动切换

• 构造：UISwipeView(uint8_t direction = HORIZONTAL)

• 成员函数：

  接口名称	功能简述
  UISwipeView	构造滑动视图实例，指定滑动方向
  GetViewType	获取组件类型
  SetDirection	设置滑动方向
  GetDirection	获取当前滑动方向
  Add	添加子视图
  Insert	在指定视图后插入子视图
  Remove	删除子视图
  SetCurrentPage	设置当前显示页索引
  GetCurrentPage	获取当前页索引
  GetCurrentView	获取当前显示的子视图
  SetBlankSize	设置页间空白间距
  OnDragEvent	处理拖拽事件
  OnDragEndEvent	处理拖拽结束事件
  OnRotateEvent	处理旋转输入事件
  OnRotateEndEvent	处理旋转结束事件
  SetAnimatorTime	设置翻页动画时长
  SetLoopState	设置是否支持循环滑动
  GetViewByIndex	根据索引获取子视图
  GetOnSwipeListener	获取滑动事件监听器
  SetOnSwipeListener	设置滑动事件监听器
  SetAlignMode	设置子视图对齐模式
  GetAlignMode	获取子视图对齐模式

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

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_swipe_view.h
• 公有运算符：无
• 继承关系：public UIAbstractScroll
• 嵌套类型：enum AlignMode : uint8_t { ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT }；公有嵌套类 OnSwipeListener；static constexpr uint8_t HORIZONTAL = 0；static constexpr uint8_t VERTICAL = 1
• 模板形参：无

OHOS::UISwipeView::OnSwipeListener

滑动视图状态变化监听器抽象基类，包含滑动事件回调接口

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnSwipe	滑动事件回调纯虚函数

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

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

Functions

OHOS::UISwipeView

UISwipeView

UISwipeView(uint8_t direction = HORIZONTAL)

功能说明

• 构造 UISwipeView 实例，通过 direction 参数指定滑动方向
• 滑动方向取 HORIZONTAL（水平）或 VERTICAL（垂直），默认为 HORIZONTAL
• 构造完成后对象处于可用状态，可调用其他成员函数添加子视图并配置滑动行为

入参

名称	参数类型	详细说明	约束取值范围
direction	uint8_t	滑动方向	HORIZONTAL(0)：水平滑动；VERTICAL(1)：垂直滑动

GetViewType

UIViewType GetViewType() const override

功能说明

• 获取当前视图的组件类型标识
• 返回值固定为 UI_SWIPE_VIEW，用于运行时类型识别
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回组件类型标识

返回值	触发场景
UI_SWIPE_VIEW	当前对象为 UISwipeView 类型

SetDirection

void SetDirection(uint8_t direction)

功能说明

• 设置滑动视图的拖拽方向
• 可在运行时动态切换水平或垂直方向
• 设置后影响后续拖拽和翻页行为

入参

名称	参数类型	详细说明	约束取值范围
direction	uint8_t	拖拽方向	HORIZONTAL(0)：水平；VERTICAL(1)：垂直

GetDirection

uint8_t GetDirection() const

功能说明

• 获取当前滑动视图的拖拽方向
• 该函数为 const 成员函数，不修改对象状态
• 返回值与 SetDirection 设置的值一致

返回值

• 返回类型：uint8_t

返回当前拖拽方向

返回值	触发场景
0	水平方向
1	垂直方向

Add

void Add(UIView* view) override

功能说明

• 向滑动视图末尾添加子视图
• 添加的子视图按顺序排列，构成可滑动切换的页面序列
• 调用后需要刷新界面以显示新添加的子视图

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	待添加的子视图指针，入参指针，不可为 nullptr	有效 UIView 对象指针

Insert

void Insert(UIView* prevView, UIView* insertView) override

功能说明

• 在指定子视图之后插入新的子视图
• 插入位置由 prevView 在子视图列表中的位置决定
• 插入后子视图索引顺序随之调整

入参

名称	参数类型	详细说明	约束取值范围
prevView	UIView*	前一个子视图指针，入参指针，不可为 nullptr	已添加到当前滑动视图中的有效 UIView 指针
insertView	UIView*	待插入的子视图指针，入参指针，不可为 nullptr	有效 UIView 对象指针

Remove

virtual void Remove(UIView* view) override

功能说明

• 从滑动视图中删除指定子视图
• 删除后剩余子视图的索引顺序自动调整
• 该函数为虚函数，允许子类重写删除行为

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	待删除的子视图指针，入参指针，不可为 nullptr	已添加到当前滑动视图中的有效 UIView 指针

SetCurrentPage

void SetCurrentPage(uint16_t index, bool needAnimator = false)

功能说明

• 设置当前显示的页面索引
• 可通过 needAnimator 参数控制是否播放翻页动画
• 索引超出范围时行为未定义，调用者需确保索引合法

入参

名称	参数类型	详细说明	约束取值范围
index	uint16_t	目标页索引	0 ~ 子视图数量 - 1
needAnimator	bool	是否播放翻页动画	false（默认）：无动画；true：播放动画

GetCurrentPage

uint16_t GetCurrentPage() const

功能说明

• 获取当前显示页面的索引
• 该函数为 const 成员函数，不修改对象状态
• 返回值与 SetCurrentPage 设置的值一致

返回值

• 返回类型：uint16_t

返回当前页索引

返回值	触发场景
0 ~ N-1	当前显示页面的索引值，N 为子视图总数

GetCurrentView

UIView* GetCurrentView() const

功能说明

• 获取当前显示的子视图指针
• 该函数为 const 成员函数，不修改对象状态
• 返回的指针由滑动视图内部管理，调用者不应释放该指针

返回值

• 返回类型：UIView*

返回当前显示的子视图

返回值	触发场景
非 nullptr	当前正在显示的子视图指针
nullptr	无子视图或当前视图无效

SetBlankSize

void SetBlankSize(uint16_t size)

功能说明

• 设置页面之间的空白间距大小
• 空白间距用于非循环滑动模式下首尾页的回弹距离
• 默认值为 DEFAULT_BLANK_SIZE(30)

入参

名称	参数类型	详细说明	约束取值范围
size	uint16_t	空白间距大小（像素）	≥ 0

OnDragEvent

bool OnDragEvent(const DragEvent& event) override

功能说明

• 处理拖拽事件，根据拖拽方向和距离切换到指定视图
• 该函数由 UI 框架在拖拽交互时自动调用
• 返回 true 表示事件已处理，不再向父视图传递

入参

名称	参数类型	详细说明	约束取值范围
event	const DragEvent&	拖拽事件，入参只读引用，不修改所指对象	有效的 DragEvent 对象

返回值

• 返回类型：bool

返回事件处理结果

返回值	触发场景
true	拖拽事件已处理
false	拖拽事件未处理

OnDragEndEvent

bool OnDragEndEvent(const DragEvent& event) override

功能说明

• 处理拖拽结束事件，根据拖拽速度和距离决定是否切换页面
• 该函数由 UI 框架在拖拽结束时自动调用
• 返回 true 表示事件已处理

入参

名称	参数类型	详细说明	约束取值范围
event	const DragEvent&	拖拽结束事件，入参只读引用，不修改所指对象	有效的 DragEvent 对象

返回值

• 返回类型：bool

返回事件处理结果

返回值	触发场景
true	拖拽结束事件已处理
false	拖拽结束事件未处理

OnRotateEvent

bool OnRotateEvent(const RotateEvent& event) override

功能说明

• 处理旋转输入事件，根据旋转方向切换页面
• 该函数仅在 ENABLE_ROTATE_INPUT 宏启用时可用
• 该函数由 UI 框架在旋转输入交互时自动调用

入参

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

返回值

• 返回类型：bool

返回事件处理结果

返回值	触发场景
true	旋转事件已处理
false	旋转事件未处理

Kconfig 配置

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

OnRotateEndEvent

bool OnRotateEndEvent(const RotateEvent& event) override

功能说明

• 处理旋转结束事件，根据旋转惯量决定是否切换页面
• 该函数仅在 ENABLE_ROTATE_INPUT 宏启用时可用
• 该函数由 UI 框架在旋转输入结束时自动调用

入参

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

返回值

• 返回类型：bool

返回事件处理结果

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

Kconfig 配置

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

SetAnimatorTime

void SetAnimatorTime(uint16_t time)

功能说明

• 设置翻页动画的持续时间（以 tick 为单位）
• 动画期间页面将滑过空白区域到达目标位置
• 默认值为 ANIMATOR_TIME(12)

入参

名称	参数类型	详细说明	约束取值范围
time	uint16_t	动画时长（tick 数）	> 0

SetLoopState

void SetLoopState(bool loop)

功能说明

• 设置滑动视图是否支持循环滑动模式
• 循环模式下，最后一页之后继续滑动将回到第一页
• 非循环模式下，滑动到首尾页时产生回弹效果

入参

名称	参数类型	详细说明	约束取值范围
loop	bool	是否启用循环滑动	true：启用循环；false：禁用循环

GetViewByIndex

UIView* GetViewByIndex(uint16_t index) const

功能说明

• 根据索引获取对应位置的子视图指针
• 该函数为 const 成员函数，不修改对象状态
• 索引超出范围时返回 nullptr

入参

名称	参数类型	详细说明	约束取值范围
index	uint16_t	子视图索引	0 ~ 子视图数量 - 1

返回值

• 返回类型：UIView*

返回对应索引的子视图

返回值	触发场景
非 nullptr	索引有效时返回对应子视图指针
nullptr	索引超出范围

GetOnSwipeListener

OnSwipeListener*& GetOnSwipeListener()

功能说明

• 获取当前设置的滑动事件监听器引用
• 返回值为引用，可通过返回值直接修改监听器指针
• 若未设置监听器，返回的引用指向 nullptr

返回值

• 返回类型：OnSwipeListener*&

返回滑动事件监听器指针的引用

返回值	触发场景
非 nullptr 引用	已设置监听器
nullptr 引用	未设置监听器

SetOnSwipeListener

void SetOnSwipeListener(OnSwipeListener* onSwipeListener)

功能说明

• 设置滑动事件监听器，监听器中的回调函数将在滑动状态变化时被调用
• 调用者需确保监听器对象在滑动视图使用期间保持有效
• 设置新监听器将替换之前设置的监听器

入参

名称	参数类型	详细说明	约束取值范围
onSwipeListener	OnSwipeListener*	滑动事件监听器指针，入参指针，可为 nullptr	OnSwipeListener 派生类对象指针或 nullptr

SetAlignMode

void SetAlignMode(AlignMode alignMode = ALIGN_CENTER)

功能说明

• 设置滑动视图中子视图的对齐模式
• 对齐模式影响子视图在滑动方向垂直方向上的位置
• 默认对齐模式为 ALIGN_CENTER

入参

名称	参数类型	详细说明	约束取值范围
alignMode	AlignMode	对齐模式	ALIGN_LEFT(0)：左对齐；ALIGN_CENTER(1)：居中；ALIGN_RIGHT(2)：右对齐

GetAlignMode

AlignMode GetAlignMode()

功能说明

• 获取当前子视图的对齐模式
• 返回值与 SetAlignMode 设置的值一致
• 默认值为 ALIGN_CENTER

返回值

• 返回类型：AlignMode

返回当前对齐模式

返回值	触发场景
ALIGN_LEFT(0)	左对齐
ALIGN_CENTER(1)	居中对齐
ALIGN_RIGHT(2)	右对齐

OHOS::UISwipeView::OnSwipeListener

OnSwipe

virtual void OnSwipe(UISwipeView& view) = 0

功能说明

• 滑动事件回调纯虚函数，在滑动视图状态变化时被调用
• 派生类必须实现此函数以接收滑动通知
• 回调参数为当前滑动视图的引用，可通过该引用获取滑动状态信息

入参

名称	参数类型	详细说明	约束取值范围
view	UISwipeView&	触发滑动事件的滑动视图引用，入参引用	有效的 UISwipeView 对象引用

Enumerations

UISwipeView::AlignMode

enum AlignMode : uint8_t { ALIGN_LEFT = 0, ALIGN_CENTER = 1, ALIGN_RIGHT = 2 };

枚举成员	取值	描述
ALIGN_LEFT	0	子视图左对齐
ALIGN_CENTER	1	子视图居中对齐
ALIGN_RIGHT	2	子视图右对齐