ui_abstract_progress

ui_abstract_progress 模块提供抽象进度条组件基类，定义进度条的通用属性与范围设置接口。

Class Summary

OHOS::UIAbstractProgress

进度条抽象基类，提供进度值设置、范围控制、样式配置及渐变填充等通用功能

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取组件类型
  EnableBackground	设置进度条背景是否可见
  SetValue	设置进度条当前值
  GetValue	获取进度条当前值
  SetRange	设置进度条取值范围
  GetRangeMin	获取进度条最小值
  GetRangeMax	获取进度条最大值
  SetImage	通过图片路径设置进度条前景与背景图片
  SetImage	通过 ImageInfo 设置进度条前景与背景图片
  SetStep	设置进度条步长
  GetStep	获取进度条当前步长
  SetBackgroundStyle	通过 Style 对象设置背景样式
  SetBackgroundStyle	通过键值对设置背景样式
  GetBackgroundStyle	获取背景样式对象
  GetBackgroundStyle	获取指定键的背景样式值
  SetForegroundStyle	通过 Style 对象设置前景样式
  SetForegroundStyle	通过键值对设置前景样式
  GetForegroundStyle	获取前景样式对象
  GetForegroundStyle	获取指定键的前景样式值
  SetCapType	设置进度条背景与前景端点样式
  SetForegroundGradient	设置前景线性渐变

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

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

Functions

OHOS::UIAbstractProgress

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前组件的类型标识
• 返回值为 UI_ABSTRACT_PROGRESS，用于区分进度条组件与其他 UI 组件
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回组件类型标识

返回值	触发场景
UI_ABSTRACT_PROGRESS(20)	当前对象为 UIAbstractProgress 类型

EnableBackground

void EnableBackground(bool enable)

功能说明

• 核心用途：设置进度条背景是否可见
• 传入 true 时背景可见，传入 false 时背景隐藏
• 该函数为非 const 成员函数，调用后会修改对象内部状态

入参

名称	参数类型	详细说明	约束取值范围
enable	bool	指定进度条背景是否可见，入参只读	true：背景可见；false：背景隐藏

SetValue

void SetValue(int32_t value)

功能说明

• 核心用途：设置进度条的当前值
• 若传入值小于 rangeMin，则自动使用 rangeMin；若大于 rangeMax，则自动使用 rangeMax
• 当值变化超过步长或达到范围边界时，触发进度条重绘

入参

名称	参数类型	详细说明	约束取值范围
value	int32_t	进度条当前值，入参只读	[rangeMin, rangeMax] 范围内，超出则自动截断

GetValue

int32_t GetValue() const

功能说明

• 核心用途：获取进度条的当前值
• 返回值为上次通过 SetValue 设置并经范围截断后的值
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：int32_t

返回进度条当前值

返回值	触发场景
int32_t 值	当前进度值，范围在 [rangeMin, rangeMax] 内

SetRange

void SetRange(int32_t rangeMax, int32_t rangeMin)

功能说明

• 核心用途：设置进度条的取值范围
• rangeMax 必须大于等于 rangeMin，否则设置不生效
• 设置成功后会自动以新范围重新校验当前值

入参

名称	参数类型	详细说明	约束取值范围
rangeMax	int32_t	进度条最大值，入参只读	int32_t 范围内，须大于等于 rangeMin
rangeMin	int32_t	进度条最小值，入参只读	int32_t 范围内，默认值 0

GetRangeMin

int32_t GetRangeMin() const

功能说明

• 核心用途：获取进度条的最小值
• 默认值为 0
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：int32_t

返回进度条最小值

返回值	触发场景
int32_t 值	当前配置的最小值

GetRangeMax

int32_t GetRangeMax() const

功能说明

• 核心用途：获取进度条的最大值
• 默认值为 100
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：int32_t

返回进度条最大值

返回值	触发场景
int32_t 值	当前配置的最大值

SetImage

void SetImage(const char* foregroundImage, const char* backgroundImage = nullptr)

功能说明

• 核心用途：通过图片路径设置进度条的前景与背景图片
• 图片尺寸须与进度条尺寸一致以确保正常显示
• 任一参数为 nullptr 时取消图片填充，改为颜色填充

入参

名称	参数类型	详细说明	约束取值范围
foregroundImage	const char*	前景图片路径，入参只读指针	合法图片路径字符串或 nullptr
backgroundImage	const char*	背景图片路径，入参只读指针，缺省值为 nullptr	合法图片路径字符串或 nullptr

SetImage

void SetImage(const ImageInfo* foregroundImage, const ImageInfo* backgroundImage = nullptr)

功能说明

• 核心用途：通过 ImageInfo 像素图数据设置进度条的前景与背景图片
• 图片尺寸须与进度条尺寸一致以确保正常显示
• 任一参数为 nullptr 时取消图片填充，改为颜色填充

入参

名称	参数类型	详细说明	约束取值范围
foregroundImage	const ImageInfo*	前景像素图信息，入参只读指针	合法 ImageInfo 指针或 nullptr
backgroundImage	const ImageInfo*	背景像素图信息，入参只读指针，缺省值为 nullptr	合法 ImageInfo 指针或 nullptr

SetStep

void SetStep(uint32_t step)

功能说明

• 核心用途：设置进度条的步长，控制重绘频率
• 当值变化量超过步长时触发重绘；到达范围边界时无论步长均重绘
• 默认步长为 1

入参

名称	参数类型	详细说明	约束取值范围
step	uint32_t	进度条步长，入参只读	uint32_t 范围内，默认值 1

GetStep

uint32_t GetStep() const

功能说明

• 核心用途：获取进度条当前的步长值
• 步长用于控制进度值变化触发重绘的最小幅度
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：uint32_t

返回当前步长

返回值	触发场景
uint32_t 值	当前步长值

SetBackgroundStyle

void SetBackgroundStyle(const Style& style)

功能说明

• 核心用途：通过 Style 对象整体设置进度条背景样式
• 入参为只读引用，不修改传入的 Style 对象
• 首次调用时内部会分配独立的 Style 存储空间

入参

名称	参数类型	详细说明	约束取值范围
style	const Style&	背景样式对象，入参只读引用	合法 Style 对象引用

SetBackgroundStyle

void SetBackgroundStyle(uint8_t key, int64_t value)

功能说明

• 核心用途：通过键值对设置进度条背景样式的单个属性
• 首次调用时内部会分配独立的 Style 存储空间并拷贝原有样式
• 适用于仅修改单个样式属性的场景

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值，入参只读	Style 定义的样式键
value	int64_t	样式值，入参只读	与 key 对应的合法样式值

GetBackgroundStyle

const Style& GetBackgroundStyle() const

功能说明

• 核心用途：获取进度条背景的完整样式对象引用
• 返回为只读引用，不可通过返回值修改背景样式
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：const Style&

返回背景样式对象的只读引用

返回值	触发场景
const Style&	当前背景样式对象引用

GetBackgroundStyle

int64_t GetBackgroundStyle(uint8_t key) const

功能说明

• 核心用途：获取进度条背景样式中指定键的值
• 通过键查询单个背景样式属性
• 该函数为 const 成员函数，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值，入参只读	Style 定义的样式键

返回值

• 返回类型：int64_t

返回指定键对应的背景样式值

返回值	触发场景
int64_t 值	key 对应的样式值

SetForegroundStyle

void SetForegroundStyle(const Style& style)

功能说明

• 核心用途：通过 Style 对象整体设置进度条前景样式
• 入参为只读引用，不修改传入的 Style 对象
• 首次调用时内部会分配独立的 Style 存储空间

入参

名称	参数类型	详细说明	约束取值范围
style	const Style&	前景样式对象，入参只读引用	合法 Style 对象引用

SetForegroundStyle

void SetForegroundStyle(uint8_t key, int64_t value)

功能说明

• 核心用途：通过键值对设置进度条前景样式的单个属性
• 首次调用时内部会分配独立的 Style 存储空间并拷贝原有样式
• 适用于仅修改单个样式属性的场景

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值，入参只读	Style 定义的样式键
value	int64_t	样式值，入参只读	与 key 对应的合法样式值

GetForegroundStyle

const Style& GetForegroundStyle() const

功能说明

• 核心用途：获取进度条前景的完整样式对象引用
• 返回为只读引用，不可通过返回值修改前景样式
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：const Style&

返回前景样式对象的只读引用

返回值	触发场景
const Style&	当前前景样式对象引用

GetForegroundStyle

int64_t GetForegroundStyle(uint8_t key) const

功能说明

• 核心用途：获取进度条前景样式中指定键的值
• 通过键查询单个前景样式属性
• 该函数为 const 成员函数，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值，入参只读	Style 定义的样式键

返回值

• 返回类型：int64_t

返回指定键对应的前景样式值

返回值	触发场景
int64_t 值	key 对应的样式值

SetCapType

void SetCapType(CapType cap)

功能说明

• 核心用途：同时设置进度条背景与前景的端点样式
• 该函数内部同时调用 SetBackgroundStyle(STYLE_LINE_CAP, cap) 和 SetForegroundStyle(STYLE_LINE_CAP, cap)
• 端点样式影响进度条起止位置的绘制形状

入参

名称	参数类型	详细说明	约束取值范围
cap	CapType	端点样式枚举值，入参只读	CAP_NONE(0)：无端点；CAP_ROUND(1)：圆形端点

SetForegroundGradient

bool SetForegroundGradient(const LinearGradient& linear, const ColorStop* stops, uint16_t stopCount)

功能说明

• 核心用途：设置进度条前景的线性渐变效果
• 传入的 ColorStop 数组由被调用方深拷贝，调用方可在调用后释放原始数据
• stops 为 nullptr 或 stopCount 为 0 时返回 false，设置不生效

入参

名称	参数类型	详细说明	约束取值范围
linear	const LinearGradient&	线性渐变参数，入参只读引用	合法 LinearGradient 对象引用
stops	const ColorStop*	颜色停止点数组，入参只读指针	非 nullptr，数组长度等于 stopCount
stopCount	uint16_t	颜色停止点数量，入参只读	大于 0

返回值

• 返回类型：bool

返回渐变设置是否成功

返回值	触发场景
true(1)	渐变设置成功
false(0)	stops 为 nullptr 或 stopCount 为 0 或内存分配失败

Enumerations

CapType

enum CapType : uint8_t {
    CAP_NONE,
    CAP_ROUND,
    CAP_ROUND_UNSHOW,
};

枚举成员	取值	描述
CAP_NONE	0	无端点样式
CAP_ROUND	1	圆形端点样式
CAP_ROUND_UNSHOW	2	圆形端点样式（不显示）

Structures

LinearGradient

struct LinearGradient {
    int16_t startX;
    int16_t startY;
    int16_t endX;
    int16_t endY;
};

成员说明

成员名称	数据类型	描述
startX	int16_t	渐变起点 X 坐标
startY	int16_t	渐变起点 Y 坐标
endX	int16_t	渐变终点 X 坐标
endY	int16_t	渐变终点 Y 坐标

ColorStop

struct ColorStop {
    float stop;
    uint32_t color;
};

成员说明

成员名称	数据类型	描述
stop	float	渐变停止点位置，范围 0.0 ~ 1.0
color	uint32_t	渐变停止点颜色值