ui_slider
ui_slider 模块提供滑动条组件，支持滑动调节与滑动事件监听。
Class Summary
OHOS::UISlider
表示滑块控件，用户可通过拖拽或点击滑块旋钮调整进度值
- 构造：无
-
成员函数：
接口名称 功能简述 GetViewType 获取视图类型 SetKnobWidth 设置滑块旋钮宽度 GetKnobWidth 获取滑块旋钮宽度 SetKnobImage 设置滑块旋钮图片 SetKnobColor 设置滑块旋钮颜色 SetKnobRadius 设置滑块旋钮圆角半径 SetKnobStyle 设置滑块旋钮样式 GetKnobStyle 获取滑块旋钮样式 SetImage 设置滑块背景与前景图片 SetSliderColor 设置滑块背景与前景颜色 SetSliderRadius 设置滑块背景与前景圆角半径 GetRotateFactor 获取旋转因子 SetRotateFactor 设置旋转因子 OnRotateEvent 处理旋转事件 OnRotateEndEvent 处理旋转结束事件 OnClickEvent 处理点击事件 OnDragEvent 处理拖拽事件 OnDragEndEvent 处理拖拽结束事件 OnPreDraw 绘制前回调 OnDraw 执行滑块绘制 SetSliderEventListener 设置滑块变化监听器 -
使用包含头文件：
#include "components/ui_slider.h" - 声明头文件：
middleware/services/gui/uikit/ui/interfaces/kits/components/ui_slider.h - 公有运算符：无
- 继承关系：UIBoxProgress
- 嵌套类型：UISliderEventListener
- 模板形参：无
OHOS::UISlider::UISliderEventListener
滑块变化事件监听器，用于监听滑块拖拽、点击和释放事件并触发回调
- 构造：无
-
成员函数：
接口名称 功能简述 OnChange 滑块值变化时的回调函数 OnRelease 滑块释放时的回调函数 -
使用包含头文件：
#include "components/ui_slider.h" - 声明头文件：
middleware/services/gui/uikit/ui/interfaces/kits/components/ui_slider.h - 公有运算符：无
- 继承关系：HeapBase
- 嵌套类型：无
- 模板形参：无
Functions
OHOS::UISlider
GetViewType
UIViewType GetViewType() const override
功能说明
- 核心用途：获取当前视图的类型标识
- 返回值为 UI_SLIDER，用于在视图体系中区分滑块控件
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
UIViewType
返回滑块视图类型标识
| 返回值 | 触发场景 |
|---|---|
| UI_SLIDER | 当前对象为 UISlider 类型时返回 |
SetKnobWidth
void SetKnobWidth(int16_t width)
功能说明
- 核心用途：设置滑块旋钮的宽度
- 旋钮宽度与高度相同，默认宽度与水平滑块高度或垂直滑块宽度一致
- 设置后影响旋钮绘制尺寸
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| width | int16_t | 旋钮宽度值，单位像素 | ≥ 0 |
GetKnobWidth
int16_t GetKnobWidth()
功能说明
- 核心用途：获取滑块旋钮的当前宽度
- 返回值为旋钮的像素宽度
- 该函数可用于在设置后确认旋钮尺寸
返回值
- 返回类型：
int16_t
返回旋钮宽度值
| 返回值 | 触发场景 |
|---|---|
| ≥ 0 | 返回当前旋钮宽度像素值 |
SetKnobImage
void SetKnobImage(const ImageInfo* knobImage)
功能说明
- 核心用途：以像素图方式设置滑块旋钮图片
- 设置后旋钮将使用指定图片进行绘制
- 入参指针指向的 ImageInfo 对象生命周期需由调用方维护
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| knobImage | const ImageInfo* | 入参指针，指向旋钮图片像素信息 | 非 nullptr |
void SetKnobImage(const char* knobImage)
功能说明
- 核心用途：以图片路径方式设置滑块旋钮图片
- 设置后旋钮将根据路径加载并绘制指定图片
- 入参指针指向的字符串生命周期需由调用方维护
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| knobImage | const char* | 入参指针，指向旋钮图片路径字符串 | 非 nullptr |
SetKnobColor
void SetKnobColor(const ColorType knobColor)
功能说明
- 核心用途：设置滑块旋钮的背景颜色
- 内部通过设置 STYLE_BACKGROUND_COLOR 样式键实现
- 设置后旋钮以指定颜色填充绘制
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| knobColor | const ColorType | 旋钮颜色值 | ColorType 有效范围 |
SetKnobRadius
void SetKnobRadius(int16_t knobRadius)
功能说明
- 核心用途：设置滑块旋钮的圆角半径
- 内部通过设置 STYLE_BORDER_RADIUS 样式键实现
- 设置后旋钮绘制时应用指定圆角
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| knobRadius | int16_t | 旋钮圆角半径值，单位像素 | ≥ 0 |
SetKnobStyle
void SetKnobStyle(const Style& style)
功能说明
- 核心用途：整体设置滑块旋钮的样式
- 入参为只读引用，不修改传入的 Style 对象
- 设置后旋钮绘制时应用指定样式
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| style | const Style& | 入参只读引用，旋钮样式对象 | Style 有效实例 |
void SetKnobStyle(uint8_t key, int64_t value)
功能说明
- 核心用途：按键值对方式设置滑块旋钮的单个样式属性
- 指定样式键与对应值，仅修改旋钮的特定样式项
- 适用于仅需修改部分样式属性的场景
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | uint8_t | 样式键标识 | Style 定义的键值 |
| value | int64_t | 样式键对应的值 | 由 key 决定有效范围 |
GetKnobStyle
const Style& GetKnobStyle() const
功能说明
- 核心用途：获取滑块旋钮的完整样式
- 返回旋钮样式的只读引用
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
const Style&
返回旋钮样式的只读引用
| 返回值 | 触发场景 |
|---|---|
| const Style& | 返回当前旋钮样式引用 |
int64_t GetKnobStyle(uint8_t key) const
功能说明
- 核心用途：按样式键获取滑块旋钮的单个样式属性值
- 指定样式键，返回对应的样式值
- 该函数为 const 成员函数，不修改对象状态
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | uint8_t | 样式键标识 | Style 定义的键值 |
返回值
- 返回类型：
int64_t
返回指定样式键对应的值
| 返回值 | 触发场景 |
|---|---|
| int64_t | 返回样式键对应的属性值 |
SetImage
void SetImage(const ImageInfo* backgroundImage, const ImageInfo* foregroundImage)
功能说明
- 核心用途：以像素图方式设置滑块的背景和前景图片
- 背景图片用于绘制滑块轨道，前景图片用于绘制已填充进度区域
- 入参指针指向的 ImageInfo 对象生命周期需由调用方维护
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| backgroundImage | const ImageInfo* | 入参指针，背景图片像素信息 | 非 nullptr |
| foregroundImage | const ImageInfo* | 入参指针，前景图片像素信息 | 非 nullptr |
void SetImage(const char* backgroundImage, const char* foregroundImage)
功能说明
- 核心用途：以图片路径方式设置滑块的背景和前景图片
- 背景图片用于绘制滑块轨道，前景图片用于绘制已填充进度区域
- 入参指针指向的字符串生命周期需由调用方维护
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| backgroundImage | const char* | 入参指针，背景图片路径字符串 | 非 nullptr |
| foregroundImage | const char* | 入参指针，前景图片路径字符串 | 非 nullptr |
SetSliderColor
void SetSliderColor(const ColorType backgroundColor, const ColorType foregroundColor)
功能说明
- 核心用途：设置滑块的背景颜色和前景颜色
- 背景颜色用于绘制滑块轨道，前景颜色用于绘制已填充进度区域
- 内部分别设置背景和前景的 STYLE_BACKGROUND_COLOR 样式键
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| backgroundColor | const ColorType | 滑块背景颜色值 | ColorType 有效范围 |
| foregroundColor | const ColorType | 滑块前景颜色值 | ColorType 有效范围 |
SetSliderRadius
void SetSliderRadius(int16_t backgroundRadius, int16_t foregroundRadius)
功能说明
- 核心用途：设置滑块背景和前景的圆角半径
- 内部分别设置背景和前景的 STYLE_BORDER_RADIUS 样式键
- 设置后影响滑块轨道和进度区域的圆角绘制效果
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| backgroundRadius | int16_t | 背景圆角半径值，单位像素 | ≥ 0 |
| foregroundRadius | int16_t | 前景圆角半径值，单位像素 | ≥ 0 |
GetRotateFactor
float GetRotateFactor()
功能说明
- 核心用途：获取滑块的旋转因子
- 旋转因子用于调节旋钮旋转输入与滑块值变化的映射比例
- 该接口需启用 ENABLE_ROTATE_INPUT 宏
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 启用旋转输入支持 | n |
返回值
- 返回类型：
float
返回当前旋转因子
| 返回值 | 触发场景 |
|---|---|
| float | 返回当前旋转因子值 |
SetRotateFactor
void SetRotateFactor(float factor)
功能说明
- 核心用途：设置滑块的旋转因子
- 旋转因子绝对值超过 MAX_ROTATE_FACTOR(128) 时将被截断为边界值
- 该接口需启用 ENABLE_ROTATE_INPUT 宏
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| factor | float | 旋转因子值 | -128.0 ~ 128.0 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 启用旋转输入支持 | n |
OnRotateEvent
bool OnRotateEvent(const RotateEvent& event) override
功能说明
- 核心用途：处理旋转输入事件，根据旋转量更新滑块当前值
- 旋转量经旋转因子缩放后累加到滑块值上
- 该接口需启用 ENABLE_ROTATE_INPUT 宏
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转事件对象 | RotateEvent 有效实例 |
返回值
- 返回类型：
bool
返回事件处理结果
| 返回值 | 触发场景 |
|---|---|
| true | 旋转事件被消费 |
| false | 旋转事件未被消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 启用旋转输入支持 | n |
OnRotateEndEvent
bool OnRotateEndEvent(const RotateEvent& event) override
功能说明
- 核心用途：处理旋转结束事件，清除缓存的旋转累积量
- 该接口需启用 ENABLE_ROTATE_INPUT 宏
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const RotateEvent& | 入参只读引用，旋转结束事件对象 | RotateEvent 有效实例 |
返回值
- 返回类型：
bool
返回事件处理结果
| 返回值 | 触发场景 |
|---|---|
| true | 旋转结束事件被消费 |
| false | 旋转结束事件未被消费 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_ROTATE_INPUT | 启用旋转输入支持 | n |
OnClickEvent
bool OnClickEvent(const ClickEvent& event) override
功能说明
- 核心用途：处理点击事件，根据点击位置更新滑块当前值
- 点击位置映射为滑块值后，触发监听器的 OnChange 回调
- 该函数为 override，重写基类事件处理
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const ClickEvent& | 入参只读引用，点击事件对象 | ClickEvent 有效实例 |
返回值
- 返回类型：
bool
返回事件处理结果
| 返回值 | 触发场景 |
|---|---|
| true | 点击事件被消费 |
| false | 点击事件未被消费 |
OnDragEvent
bool OnDragEvent(const DragEvent& event) override
功能说明
- 核心用途：处理拖拽事件，根据拖拽位置实时更新滑块当前值
- 拖拽位置映射为滑块值后，触发监听器的 OnChange 回调
- 该函数为 override，重写基类事件处理
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽事件对象 | DragEvent 有效实例 |
返回值
- 返回类型：
bool
返回事件处理结果
| 返回值 | 触发场景 |
|---|---|
| true | 拖拽事件被消费 |
| false | 拖拽事件未被消费 |
OnDragEndEvent
bool OnDragEndEvent(const DragEvent& event) override
功能说明
- 核心用途：处理拖拽结束事件，根据最终位置更新滑块值并触发释放回调
- 拖拽结束位置映射为滑块值后，依次触发监听器的 OnChange 和 OnRelease 回调
- 该函数为 override，重写基类事件处理
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| event | const DragEvent& | 入参只读引用，拖拽结束事件对象 | DragEvent 有效实例 |
返回值
- 返回类型：
bool
返回事件处理结果
| 返回值 | 触发场景 |
|---|---|
| true | 拖拽结束事件被消费 |
| false | 拖拽结束事件未被消费 |
OnPreDraw
bool OnPreDraw(Rect& invalidatedArea) const override
功能说明
- 核心用途：绘制前回调，判断是否需要跳过绘制
- 该滑块实现始终返回 false，表示不跳过绘制
- 该函数为 const override，不修改对象状态
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| invalidatedArea | Rect& | 出参引用，无效区域矩形 | Rect 有效实例 |
返回值
- 返回类型：
bool
返回是否跳过绘制
| 返回值 | 触发场景 |
|---|---|
| false | 不跳过绘制，继续执行 OnDraw |
OnDraw
void OnDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override
功能说明
- 核心用途：执行滑块绘制，依次绘制背景、前景进度和旋钮
- 该函数为 override，重写基类绘制逻辑
- 绘制顺序为：背景矩形 → 背景图 → 前景进度 → 旋钮
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| gfxDstBuffer | BufferInfo& | 出参引用，图形目标缓冲区 | BufferInfo 有效实例 |
| invalidatedArea | const Rect& | 入参只读引用，需要重绘的区域 | Rect 有效实例 |
SetSliderEventListener
void SetSliderEventListener(UISliderEventListener* listener)
功能说明
- 核心用途：设置滑块变化事件监听器
- 当用户拖拽或点击滑块时触发 OnChange 回调，释放时触发 OnRelease 回调
- 入参指针由调用方管理生命周期
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| listener | UISliderEventListener* | 入参指针，滑块事件监听器对象 | 可为 nullptr 表示取消监听 |
OHOS::UISlider::UISliderEventListener
OnChange
virtual void OnChange(int32_t value)
功能说明
- 核心用途：滑块值变化时的虚回调函数，需由子类重写实现具体逻辑
- 当用户拖拽或点击滑块导致值变化时被调用
- 默认实现为空，开发者需继承并重写该函数以响应滑块值变化
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| value | int32_t | 滑块当前值 | 由滑块范围决定 |
OnRelease
virtual void OnRelease(int32_t value)
功能说明
- 核心用途：滑块释放时的虚回调函数，需由子类重写实现具体逻辑
- 当用户释放滑块时被调用
- 默认实现为空，开发者需继承并重写该函数以响应滑块释放事件
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| value | int32_t | 滑块当前值 | 由滑块范围决定 |