ui_roller_view
ui_roller_view 模块提供滚轮视图组件，支持滚轮式选项选择与滚动。
Class Summary
OHOS::UIRollerView
滚轮选择视图控件，以 3D 滚轮形式展示可滚动的图片列表项，支持镜像反射、模式切换与滚动动画
- 构造：
UIRollerView(bool isShowMirrorImg_ = true) -
成员函数：
接口名称 功能简述 UIRollerView 构造滚轮视图对象，指定是否启用镜像模式 SetItemSize 设置滚轮项的图片尺寸 SetItemPadding 设置滚轮项之间的间距 SetMirrorOpacity 设置镜像图片的不透明度 SetSensitivityFactor 设置拖拽灵敏度因子 GetSensitivityFactor 获取当前拖拽灵敏度因子 AddItem 添加一个滚轮项 RemoveItem 移除指定名称的滚轮项 ClearAll 清除所有滚轮项 GetCurrentItemName 获取当前选中项的名称 GetCurrentItem 获取当前选中项的视图组 SetCurrentItem 设置当前选中项 SetMode 设置滚轮显示模式 GetOnModeChangeListener 获取模式变更监听器引用 SetOnModeChangeListener 设置模式变更监听器 SetOnScrollListener 设置滚动监听器 GetOnScrollListener 获取滚动监听器引用 SetChildStateListener 设置子控件状态变更监听器 GetMode 获取当前滚轮显示模式 SetCamDistance 设置相机距离 SetCamY 设置相机绝对 Y 坐标 GetRollerItemName 获取指定视图的滚轮项名称 IsShowMirrorMode 查询是否启用镜像模式 GetViewType 获取视图类型 OnDragStartEvent 拖拽开始事件回调 OnDragEvent 拖拽进行中事件回调 OnDragEndEvent 拖拽结束事件回调 OnRotateStartEvent 旋转输入开始事件回调 OnRotateEvent 旋转输入进行中事件回调 OnRotateEndEvent 旋转输入结束事件回调 -
使用包含头文件：
#include "components/ui_roller_view.h" - 声明头文件：
middleware/services/gui/uikit/proprietary/include/components/ui_roller_view.h - 公有运算符：无
- 继承关系：UIAbstractScroll
- 嵌套类型：OnModeChangeListener、OnScrollListener、OnChildStateListener
- 模板形参：无
Functions
OHOS::UIRollerView
UIRollerView
UIRollerView(bool isShowMirrorImg_ = true)
功能说明
- 构造 UIRollerView 对象，通过参数控制是否启用镜像反射图片模式
- 当
isShowMirrorImg_为 true 时，每个滚轮项包含正常图片与镜像反射图片；为 false 时仅包含正常图片 - 镜像模式需在构造时指定，构造后不可更改
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| isShowMirrorImg_ | bool | 是否启用镜像反射模式，入参带缺省值 true | true：启用镜像；false：关闭镜像 |
SetItemSize
void SetItemSize(uint16_t width, uint16_t height)
功能说明
- 设置滚轮项的图片尺寸宽度与高度
- 该尺寸对应 DISPLAY 模式下图片的显示大小
- 设置后需重新布局子项
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| width | uint16_t | 滚轮项图片宽度（像素） | 1 ~ 65535 |
| height | uint16_t | 滚轮项图片高度（像素） | 1 ~ 65535 |
SetItemPadding
void SetItemPadding(uint16_t padding)
功能说明
- 设置滚轮项之间的间距
- 间距影响滚轮圆周上各项的分布密度
- 间距值越大，项与项之间的空白区域越大
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| padding | uint16_t | 滚轮项间距（像素） | 0 ~ 65535 |
SetMirrorOpacity
void SetMirrorOpacity(uint8_t opa)
功能说明
- 设置镜像反射图片的不透明度
- 仅在镜像模式启用时生效
- 不透明度值越小，镜像图片越透明
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| opa | uint8_t | 镜像图片不透明度 | 0 ~ 255，0 为全透明，255 为全不透明 |
SetSensitivityFactor
void SetSensitivityFactor(float sensitivity)
功能说明
- 设置拖拽操作的灵敏度因子
- 拖拽距离会被转换为旋转角度，再乘以此灵敏度因子
- 默认值为 1.0，值越大拖拽响应越灵敏
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| sensitivity | float | 灵敏度因子 | 大于 0.0 |
GetSensitivityFactor
float GetSensitivityFactor()
功能说明
- 获取当前拖拽灵敏度因子
- 默认值为 1.0
- 返回值用于判断当前拖拽响应灵敏程度
返回值
- 返回类型：
float
返回当前灵敏度因子值
| 返回值 | 触发场景 |
|---|---|
| > 0.0 | 正常返回当前灵敏度因子；默认为 1.0 |
AddItem
bool AddItem(std::string name, const ImageInfo* src)
功能说明
- 向滚轮中添加一个滚轮项，指定名称与图片资源
- 名称作为滚轮项的唯一标识，用于后续查找与移除
- 添加后滚轮会重新计算布局与圆周分布
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| name | std::string | 滚轮项名称，唯一标识 | 非空字符串 |
| src | const ImageInfo* | 入参只读指针，图片资源信息 | 非 nullptr，指向已加载的图片资源 |
返回值
- 返回类型：
bool
返回添加操作结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 添加成功 |
| false(0) | 添加失败 |
RemoveItem
void RemoveItem(std::string name)
功能说明
- 根据名称移除指定滚轮项
- 移除后滚轮会重新计算布局与圆周分布
- 若指定名称不存在，则无操作
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| name | std::string | 要移除的滚轮项名称 | 已添加的项名称 |
ClearAll
void ClearAll()
功能说明
- 清除所有滚轮项
- 清除后滚轮为空状态，需重新添加项才能使用
- 同时重置当前选中项状态
GetCurrentItemName
std::string GetCurrentItemName()
功能说明
- 获取当前选中滚轮项的名称
- 返回的名称与添加时指定的名称一致
- 用于标识当前处于选中位置的滚轮项
返回值
- 返回类型：
std::string
返回当前选中项名称
| 返回值 | 触发场景 |
|---|---|
| 非空字符串 | 当前存在选中项 |
| 空字符串 | 无选中项 |
GetCurrentItem
UIViewGroup* GetCurrentItem()
功能说明
- 获取当前选中项的视图组指针
- 镜像模式下该视图组包含 2 个子视图（正常图片和镜像图片）；非镜像模式下仅包含正常图片
- 返回的指针由 UIRollerView 内部管理，调用者不应释放
返回值
- 返回类型：
UIViewGroup*
返回当前选中项视图组指针
| 返回值 | 触发场景 |
|---|---|
| 非 nullptr | 当前存在选中项 |
| nullptr | 无选中项 |
SetCurrentItem
void SetCurrentItem(std::string name, bool enableAnimator = false)
功能说明
- 设置当前选中项为指定名称的滚轮项
- 可选是否启用动画过渡到目标项
- 首次使用时必须调用此方法设置初始选中项
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| name | std::string | 目标滚轮项名称 | 已添加的项名称 |
| enableAnimator | bool | 是否启用动画过渡，入参带缺省值 false | true：启用动画；false：直接切换 |
SetMode
void SetMode(RollerViewMode mode, bool enableAnimator = false)
功能说明
- 设置滚轮的显示模式，可选 DISPLAY 或 COVER
- DISPLAY 模式下所有项以滚轮形式展示；COVER 模式下当前项以全尺寸展示
- 可选是否启用模式切换动画过渡
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| mode | RollerViewMode | 目标显示模式 | RollerViewMode：DISPLAY / COVER |
| enableAnimator | bool | 是否启用模式切换动画过渡，入参带缺省值 false | true：启用动画；false：直接切换 |
GetOnModeChangeListener
OnModeChangeListener*& GetOnModeChangeListener()
功能说明
- 获取模式变更监听器的引用
- 通过引用可直接修改监听器指针
- 返回值为引用，可同时用于读取和写入
返回值
- 返回类型：
OnModeChangeListener*&
返回模式变更监听器指针的引用
| 返回值 | 触发场景 |
|---|---|
| 非 nullptr 引用 | 已设置监听器 |
| nullptr 引用 | 未设置监听器 |
SetOnModeChangeListener
void SetOnModeChangeListener(OnModeChangeListener* onModeChangeListener)
功能说明
- 设置模式变更监听器
- 当滚轮显示模式发生切换时，监听器的 OnModeChange 方法将被回调
- 传入 nullptr 可移除已有监听器
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| onModeChangeListener | OnModeChangeListener* | 入参指针，模式变更监听器对象 | 可为 nullptr 表示移除监听器 |
SetOnScrollListener
void SetOnScrollListener(OnScrollListener* onScrollListener)
功能说明
- 设置滚动监听器
- 当滚轮滚动时，监听器的 OnScroll 方法将被回调，传入当前项名称与旋转角度
- 传入 nullptr 可移除已有监听器
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| onScrollListener | OnScrollListener* | 入参指针，滚动监听器对象 | 可为 nullptr 表示移除监听器 |
GetOnScrollListener
OnScrollListener*& GetOnScrollListener()
功能说明
- 获取滚动监听器的引用
- 通过引用可直接修改监听器指针
- 返回值为引用，可同时用于读取和写入
返回值
- 返回类型：
OnScrollListener*&
返回滚动监听器指针的引用
| 返回值 | 触发场景 |
|---|---|
| 非 nullptr 引用 | 已设置监听器 |
| nullptr 引用 | 未设置监听器 |
SetChildStateListener
void SetChildStateListener(OnChildStateListener* listener)
功能说明
- 设置子控件状态变更监听器
- 当子控件的旋转角度状态变化时，监听器的 StateChange 方法将被回调
- 回调参数包含子控件视图指针与当前旋转角度（0~360）
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| listener | OnChildStateListener* | 入参指针，子控件状态变更监听器对象 | 可为 nullptr 表示移除监听器 |
GetMode
RollerViewMode GetMode()
功能说明
- 获取当前滚轮的显示模式
- 返回值为 DISPLAY、COVER 或 TRANSITION
- TRANSITION 为内部使用的过渡状态
返回值
- 返回类型：
RollerViewMode
返回当前显示模式
| 返回值 | 触发场景 |
|---|---|
| DISPLAY(0) | 当前为滚轮展示模式 |
| COVER(1) | 当前为全尺寸覆盖模式 |
| TRANSITION(2) | 当前处于模式切换过渡中 |
SetCamDistance
void SetCamDistance(int16_t distance)
功能说明
- 设置相机距离，影响 3D 透视效果
- 距离越大，透视效果越弱；距离越小，透视效果越强
- 默认距离为 1000
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| distance | int16_t | 相机距离值 | 大于 0，默认 1000 |
SetCamY
void SetCamY(int16_t y)
功能说明
- 设置相机的绝对 Y 坐标位置
- 影响滚轮 3D 透视的俯仰角度
- 默认值为 GetY() - GetHeight() / 3
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| y | int16_t | 相机绝对 Y 坐标 | -32768 ~ 32767 |
GetRollerItemName
static std::string GetRollerItemName(UIView* view)
功能说明
- 静态方法，获取指定视图的滚轮项名称
- 通过视图对象反查其所属滚轮项的名称标识
- 不依赖 UIRollerView 实例，可直接通过类名调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| view | UIView* | 入参指针，目标视图对象 | 非 nullptr |
返回值
- 返回类型：
std::string
返回该视图对应的滚轮项名称
| 返回值 | 触发场景 |
|---|---|
| 非空字符串 | 视图属于某个滚轮项 |
| 空字符串 | 视图不属于任何滚轮项 |
IsShowMirrorMode
bool IsShowMirrorMode()
功能说明
- 查询当前滚轮是否启用镜像反射模式
- 镜像模式在构造时指定，构造后不可更改
- 镜像模式下每个滚轮项包含正常图片与镜像反射图片
返回值
- 返回类型：
bool
返回是否启用镜像模式
| 返回值 | 触发场景 |
|---|---|
| true(1) | 已启用镜像模式 |
| false(0) | 未启用镜像模式 |
GetViewType
UIViewType GetViewType() const override
功能说明
- 获取视图类型标识，返回 UI_ROLLER_VIEW
- 重写自基类 UIAbstractScroll 的 GetViewType 方法
- 用于运行时类型识别与视图分发
返回值
- 返回类型：
UIViewType
返回视图类型
| 返回值 | 触发场景 |
|---|---|
| UI_ROLLER_VIEW | 当前为 UIRollerView 类型 |
OnDragStartEvent
bool OnDragStartEvent(const DragEvent& event) override
功能说明
- 拖拽开始事件回调，重写自基类
- 当用户开始拖拽滚轮时触发
- 返回 true 表示事件已消费，不再向下传递
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件信息 | - |
返回值
- 返回类型：
bool
返回事件消费结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已消费 |
| false(0) | 事件未消费 |
OnDragEvent
bool OnDragEvent(const DragEvent& event) override
功能说明
- 拖拽进行中事件回调，重写自基类
- 当用户持续拖拽滚轮时持续触发
- 内部将拖拽距离转换为旋转角度并更新滚轮位置
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件信息 | - |
返回值
- 返回类型：
bool
返回事件消费结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已消费 |
| false(0) | 事件未消费 |
OnDragEndEvent
bool OnDragEndEvent(const DragEvent& event) override
功能说明
- 拖拽结束事件回调，重写自基类
- 当用户结束拖拽时触发，内部启动对齐动画使滚轮对齐到最近项
- 返回 true 表示事件已消费
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件信息 | - |
返回值
- 返回类型：
bool
返回事件消费结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已消费 |
| false(0) | 事件未消费 |
OnRotateStartEvent
bool OnRotateStartEvent(const RotateEvent& event) override
功能说明
- 旋转输入开始事件回调，重写自基类
- 当旋钮输入开始时触发
- 仅在 ENABLE_ROTATE_INPUT 宏开启时可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转事件信息 | - |
返回值
- 返回类型：
bool
返回事件消费结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已消费 |
| false(0) | 事件未消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 旋转输入功能开关 | 1 |
OnRotateEvent
bool OnRotateEvent(const RotateEvent& event) override
功能说明
- 旋转输入进行中事件回调，重写自基类
- 当旋钮持续旋转时持续触发，内部将旋转量转换为滚轮角度偏移
- 仅在 ENABLE_ROTATE_INPUT 宏开启时可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转事件信息 | - |
返回值
- 返回类型：
bool
返回事件消费结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已消费 |
| false(0) | 事件未消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 旋转输入功能开关 | 1 |
OnRotateEndEvent
bool OnRotateEndEvent(const RotateEvent& event) override
功能说明
- 旋转输入结束事件回调，重写自基类
- 当旋钮旋转结束时触发，内部启动对齐动画使滚轮对齐到最近项
- 仅在 ENABLE_ROTATE_INPUT 宏开启时可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转事件信息 | - |
返回值
- 返回类型：
bool
返回事件消费结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 事件已消费 |
| false(0) | 事件未消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 旋转输入功能开关 | 1 |
Enumerations
RollerViewMode
enum RollerViewMode {
DISPLAY, // Display all items in roller form.
COVER, // Display current item at full size.
TRANSITION, // used internally.
};
| 枚举成员 | 取值 | 描述 |
|---|---|---|
| DISPLAY | 0 | 以滚轮形式展示所有项 |
| COVER | 1 | 以全尺寸展示当前选中项 |
| TRANSITION | 2 | 模式切换过渡状态，内部使用 |