ui_label

ui_label 模块提供文本标签组件，支持文本显示、字体设置与对齐方式配置。

Class Summary

OHOS::UILabel

提供标签文本显示能力，支持文本内容设置、对齐方式、换行模式、字体配置及滚动动画

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  GetWidth	获取标签宽度
  GetHeight	获取标签高度
  SetStyle	设置视图样式
  OnPreDraw	判断标签绘制前是否需要被覆盖
  OnDraw	绘制标签内容
  SetText	设置标签文本内容
  GetText	获取标签文本内容
  SetLineBreakMode	设置长文本换行模式
  GetLineBreakMode	获取长文本换行模式
  SetTextColor	设置文本颜色
  GetTextColor	获取文本颜色
  SetAlign	设置文本对齐方式
  GetHorAlign	获取水平对齐方式
  GetVerAlign	获取垂直对齐方式
  SetDirect	设置文本方向
  GetDirect	获取文本方向
  SetFontId	设置字体ID
  GetFontId	获取字体ID
  SetFont	设置字体名称和大小
  SetRollSpeed	设置文本滚动速度
  GetRollSpeed	获取文本滚动速度
  GetTextWidth	获取文本宽度
  GetTextHeight	获取文本高度
  SetRollStartPos	设置文本滚动起始位置
  GetRollStartPos	获取文本滚动起始位置
  SetWidth	设置标签宽度
  SetHeight	设置标签高度
  Resize	调整标签尺寸
  ReMeasure	重新测量标签
  SetSupportBaseLine	设置是否支持基线对齐
  SetBackgroundColorSpan	设置指定范围的背景色
  SetForegroundColorSpan	设置指定范围的前景色
  SetEliminateTrailingSpaces	设置是否消除尾部空格
  SetLineBackgroundSpan	设置指定范围的行背景色
  SetAbsoluteSizeSpan	设置指定范围的绝对字体大小
  SetRelativeSizeSpan	设置指定范围的相对字体大小
  GetFontSize	获取字体大小
  ForceResetText	强制重置文本
  GetGuiInfo	获取GUI调试信息
  SetAnimState	设置动画状态
  GetAnimRealState	获取动画实际状态
  SetMarqueeBlankNum	设置跑马灯空白间隔数量
  GetLabelText	获取内部Text对象指针

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

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

Functions

OHOS::UILabel

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 返回值为 UI_LABEL，用于区分UILabel与其他UIView子类
• const成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_LABEL	当前对象为UILabel类型

GetWidth

int16_t GetWidth() override

功能说明

• 核心用途：获取标签的宽度
• 返回标签在布局中的实际宽度值
• override成员函数，重写UIView基类实现

返回值

• 返回类型：int16_t

返回标签宽度（像素）

返回值	触发场景
>= 0	标签正常显示时的宽度
< 0	异常值

GetHeight

int16_t GetHeight() override

功能说明

• 核心用途：获取标签的高度
• 返回标签在布局中的实际高度值
• override成员函数，重写UIView基类实现

返回值

• 返回类型：int16_t

返回标签高度（像素）

返回值	触发场景
>= 0	标签正常显示时的高度
< 0	异常值

SetStyle

void SetStyle(Style& style) override

功能说明

• 核心用途：设置标签的视图样式
• 通过Style对象批量配置标签样式属性
• override成员函数，调用UIView基类SetStyle实现

入参

名称	参数类型	详细说明	约束取值范围
style	Style&	入参引用，待设置的样式对象	已初始化的Style对象

void SetStyle(uint8_t key, int64_t value) override

功能说明

• 核心用途：按键值对方式设置单个样式属性
• 通过key指定样式属性类型，value设置对应值
• override成员函数，UILabel对该接口有扩展处理

入参

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

OnPreDraw

bool OnPreDraw(Rect& invalidatedArea) const override

功能说明

• 核心用途：在绘制前判断标签是否需要被覆盖区域遮挡
• 默认返回false，表示标签不需要被遮挡
• const成员函数，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
invalidatedArea	Rect&	入参引用，待绘制的无效区域	有效的Rect对象

返回值

• 返回类型：bool

返回是否需要被覆盖

返回值	触发场景
true	标签需要被覆盖
false(0)	标签不需要被覆盖（UILabel默认返回false）

OnDraw

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

功能说明

• 核心用途：执行标签的绘制操作
• 将文本内容绘制到指定的图形缓冲区
• override成员函数，由UI框架在刷新时调用

入参

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

SetText

void SetText(const char* text)

功能说明

• 核心用途：设置标签显示的文本内容
• 传入C风格字符串指针作为文本内容
• 设置后标签将刷新显示

入参

名称	参数类型	详细说明	约束取值范围
text	const char*	入参指针，指向待显示的文本字符串	非nullptr，指向以'\0'结尾的有效字符串

void SetText(const SpannableString* text)

功能说明

• 核心用途：设置标签的SpannableString富文本内容
• 支持对文本局部设置不同样式（如前景色、背景色、字体大小等）
• 传入SpannableString指针以支持分段样式

入参

名称	参数类型	详细说明	约束取值范围
text	const SpannableString*	入参指针，指向SpannableString富文本对象	可为nullptr表示清除

GetText

const char* GetText() const

功能说明

• 核心用途：获取标签当前显示的文本内容
• 返回内部Text对象所持有的文本字符串指针
• const成员函数，不修改对象状态

返回值

• 返回类型：const char*

返回文本字符串指针

返回值	触发场景
非nullptr	内部Text对象已设置文本
nullptr	内部Text对象未设置文本

SetLineBreakMode

void SetLineBreakMode(const uint8_t lineBreakMode)

功能说明

• 核心用途：设置长文本的换行显示模式
• 支持自适应、拉伸、换行、省略号、跑马灯、裁剪、振荡、截断等多种模式
• 模式值对应UILabel::LineBreakMode枚举

入参

名称	参数类型	详细说明	约束取值范围
lineBreakMode	const uint8_t	换行模式值	LineBreakMode枚举值：0~8

GetLineBreakMode

uint8_t GetLineBreakMode() const

功能说明

• 核心用途：获取当前长文本换行模式
• 返回值对应UILabel::LineBreakMode枚举
• const成员函数，不修改对象状态

返回值

• 返回类型：uint8_t

返回换行模式

返回值	触发场景
0	LINE_BREAK_ADAPT
1	LINE_BREAK_STRETCH
2	LINE_BREAK_WRAP
3	LINE_BREAK_ELLIPSIS
4	LINE_BREAK_MARQUEE
5	LINE_BREAK_CLIP
6	LINE_BREAK_OSCILLATION
7	LINE_BREAK_TRUNCATE
8	LINE_BREAK_MAX

SetTextColor

void SetTextColor(ColorType color)

功能说明

• 核心用途：设置标签文本颜色
• 设置后标记使用自定义文本颜色，不再从Style中获取
• 颜色值通过ColorType类型指定

入参

名称	参数类型	详细说明	约束取值范围
color	ColorType	文本颜色值	ColorType合法取值

GetTextColor

ColorType GetTextColor() const

功能说明

• 核心用途：获取标签文本颜色
• 若已通过SetTextColor设置自定义颜色则返回该值，否则返回Style中的textColor_
• const成员函数，不修改对象状态

返回值

• 返回类型：ColorType

返回文本颜色

返回值	触发场景
自定义颜色值	已通过SetTextColor设置
Style中的textColor_	未通过SetTextColor设置

SetAlign

void SetAlign(UITextLanguageAlignment horizontalAlign, UITextLanguageAlignment verticalAlign = TEXT_ALIGNMENT_TOP)

功能说明

• 核心用途：设置标签文本的水平与垂直对齐方式
• 水平对齐支持左对齐、居中、右对齐
• 垂直对齐支持顶部对齐、居中、底部对齐，默认为顶部对齐

入参

名称	参数类型	详细说明	约束取值范围
horizontalAlign	UITextLanguageAlignment	水平对齐方式	UITextLanguageAlignment：TEXT_ALIGNMENT_LEFT/TEXT_ALIGNMENT_CENTER/TEXT_ALIGNMENT_RIGHT
verticalAlign	UITextLanguageAlignment	垂直对齐方式	UITextLanguageAlignment：TEXT_ALIGNMENT_TOP/TEXT_ALIGNMENT_CENTER/TEXT_ALIGNMENT_BOTTOM；缺省值TEXT_ALIGNMENT_TOP

GetHorAlign

UITextLanguageAlignment GetHorAlign()

功能说明

• 核心用途：获取文本的水平对齐方式
• 返回UITextLanguageAlignment枚举值

返回值

• 返回类型：UITextLanguageAlignment

返回水平对齐方式

返回值	触发场景
TEXT_ALIGNMENT_LEFT(0)	左对齐
TEXT_ALIGNMENT_RIGHT(1)	右对齐
TEXT_ALIGNMENT_CENTER(2)	居中对齐

GetVerAlign

UITextLanguageAlignment GetVerAlign()

功能说明

• 核心用途：获取文本的垂直对齐方式
• 返回UITextLanguageAlignment枚举值

返回值

• 返回类型：UITextLanguageAlignment

返回垂直对齐方式

返回值	触发场景
TEXT_ALIGNMENT_TOP(3)	顶部对齐
TEXT_ALIGNMENT_BOTTOM(4)	底部对齐
TEXT_ALIGNMENT_CENTER(2)	居中对齐

SetDirect

void SetDirect(UITextLanguageDirect direct)

功能说明

• 核心用途：设置文本排列方向
• 支持从左到右（LTR）、从右到左（RTL）及混合方向
• 设置后影响文本绘制方向

入参

名称	参数类型	详细说明	约束取值范围
direct	UITextLanguageDirect	文本方向	UITextLanguageDirect：TEXT_DIRECT_LTR/TEXT_DIRECT_RTL/TEXT_DIRECT_MIXED

GetDirect

UITextLanguageDirect GetDirect()

功能说明

• 核心用途：获取文本排列方向
• 返回UITextLanguageDirect枚举值

返回值

• 返回类型：UITextLanguageDirect

返回文本方向

返回值	触发场景
TEXT_DIRECT_LTR(0)	从左到右
TEXT_DIRECT_RTL(1)	从右到左
TEXT_DIRECT_MIXED(2)	混合方向

SetFontId

void SetFontId(uint16_t fontId)

功能说明

• 核心用途：通过字体ID设置标签字体
• 字体ID由字体名称和大小组合编码
• 设置后标签文本将使用指定字体渲染

入参

名称	参数类型	详细说明	约束取值范围
fontId	uint16_t	字体ID	已注册字体的合法ID值

GetFontId

uint16_t GetFontId()

功能说明

• 核心用途：获取当前标签的字体ID
• 字体ID由字体名称和大小组合编码

返回值

• 返回类型：uint16_t

返回字体ID

返回值	触发场景
合法fontId	已设置字体
0	未设置字体

SetFont

void SetFont(const char* name, uint8_t size)

功能说明

• 核心用途：通过字体名称和大小设置标签字体
• 分别指定字体名称和字体大小
• 设置后标签文本将使用指定字体渲染

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参指针，字体名称字符串	非nullptr，指向已注册字体的名称
size	uint8_t	字体大小	合法的字体大小值

SetRollSpeed

void SetRollSpeed(uint16_t speed)

功能说明

• 核心用途：设置文本滚动速度
• 在LINE_BREAK_MARQUEE或LINE_BREAK_OSCILLATION模式下生效
• 默认速度为DEFAULT_ANIMATOR_SPEED(35)

入参

名称	参数类型	详细说明	约束取值范围
speed	uint16_t	滚动速度值	> 0

GetRollSpeed

uint16_t GetRollSpeed() const

功能说明

• 核心用途：获取文本滚动速度
• 返回当前设置的滚动速度
• const成员函数，不修改对象状态

返回值

• 返回类型：uint16_t

返回滚动速度

返回值	触发场景
> 0	已设置滚动速度
35	默认滚动速度

GetTextWidth

uint16_t GetTextWidth()

功能说明

• 核心用途：获取文本内容的实际渲染宽度
• 基于当前字体和文本内容计算
• 返回值不受标签宽度限制影响

返回值

• 返回类型：uint16_t

返回文本宽度（像素）

返回值	触发场景
>= 0	文本宽度

GetTextHeight

uint16_t GetTextHeight()

功能说明

• 核心用途：获取文本内容的实际渲染高度
• 基于当前字体和文本内容计算
• 返回值不受标签高度限制影响

返回值

• 返回类型：uint16_t

返回文本高度（像素）

返回值	触发场景
>= 0	文本高度

SetRollStartPos

void SetRollStartPos(int16_t pos)

功能说明

• 核心用途：设置文本滚动的起始位置
• 在LINE_BREAK_MARQUEE或LINE_BREAK_OSCILLATION模式下生效
• 指定滚动动画开始时的偏移位置

入参

名称	参数类型	详细说明	约束取值范围
pos	int16_t	滚动起始位置偏移	合法偏移值

GetRollStartPos

int16_t GetRollStartPos() const

功能说明

• 核心用途：获取文本滚动起始位置
• 返回当前设置的滚动起始偏移
• const成员函数，不修改对象状态

返回值

• 返回类型：int16_t

返回滚动起始位置偏移

返回值	触发场景
合法偏移值	已设置滚动起始位置

SetWidth

void SetWidth(int16_t width) override

功能说明

• 核心用途：设置标签的宽度
• override成员函数，重写UIView基类实现
• 设置宽度后标签将按新宽度重新布局

入参

名称	参数类型	详细说明	约束取值范围
width	int16_t	标签宽度值（像素）	> 0

SetHeight

void SetHeight(int16_t height) override

功能说明

• 核心用途：设置标签的高度
• override成员函数，重写UIView基类实现
• 设置高度后标签将按新高度重新布局

入参

名称	参数类型	详细说明	约束取值范围
height	int16_t	标签高度值（像素）	> 0

Resize

void Resize(int16_t width, int16_t height) override

功能说明

• 核心用途：同时调整标签的宽度和高度
• override成员函数，重写UIView基类实现
• 等效于依次调用SetWidth和SetHeight

入参

名称	参数类型	详细说明	约束取值范围
width	int16_t	标签宽度值（像素）	> 0
height	int16_t	标签高度值（像素）	> 0

ReMeasure

void ReMeasure() override

功能说明

• 核心用途：触发标签重新测量
• override成员函数，重写UIView基类实现
• 在文本或样式变更后调用以确保布局正确

SetSupportBaseLine

void SetSupportBaseLine(bool baseLine)

功能说明

• 核心用途：设置标签是否支持基线对齐
• 启用基线对齐后，多行文本按基线对齐排列
• 设置后将刷新标签显示

入参

名称	参数类型	详细说明	约束取值范围
baseLine	bool	是否启用基线对齐	true：启用；false：不启用

SetBackgroundColorSpan

void SetBackgroundColorSpan(ColorType backgroundColor, int16_t start, int16_t end)

功能说明

• 核心用途：设置文本指定字符范围的背景色
• 通过start和end指定起止位置，仅该范围内的文本应用背景色
• 需配合SpannableString模式使用

入参

名称	参数类型	详细说明	约束取值范围
backgroundColor	ColorType	背景颜色值	ColorType合法取值
start	int16_t	起始字符位置	>= 0
end	int16_t	结束字符位置	>= start

SetForegroundColorSpan

void SetForegroundColorSpan(ColorType fontColor, int16_t start, int16_t end)

功能说明

• 核心用途：设置文本指定字符范围的前景色
• 通过start和end指定起止位置，仅该范围内的文本应用前景色
• 需配合SpannableString模式使用

入参

名称	参数类型	详细说明	约束取值范围
fontColor	ColorType	前景颜色值	ColorType合法取值
start	int16_t	起始字符位置	>= 0
end	int16_t	结束字符位置	>= start

SetEliminateTrailingSpaces

void SetEliminateTrailingSpaces(bool eliminateTrailingSpaces)

功能说明

• 核心用途：设置是否消除文本尾部空格
• 启用后将移除文本末尾的空白字符
• 设置后若值发生变化将刷新标签显示

入参

名称	参数类型	详细说明	约束取值范围
eliminateTrailingSpaces	bool	是否消除尾部空格	true：消除；false：保留

SetLineBackgroundSpan

void SetLineBackgroundSpan(ColorType lineBackgroundColor, int16_t start, int16_t end)

功能说明

• 核心用途：设置文本指定范围的行背景色
• 与SetBackgroundColorSpan不同，行背景色覆盖整行区域
• 需配合SpannableString模式使用

入参

名称	参数类型	详细说明	约束取值范围
lineBackgroundColor	ColorType	行背景颜色值	ColorType合法取值
start	int16_t	起始字符位置	>= 0
end	int16_t	结束字符位置	>= start

SetAbsoluteSizeSpan

void SetAbsoluteSizeSpan(uint16_t start, uint16_t end, uint8_t size)

功能说明

• 核心用途：设置文本指定范围的绝对字体大小
• 通过start和end指定起止位置，仅该范围内的文本使用指定字体大小
• 需配合SpannableString模式使用

入参

名称	参数类型	详细说明	约束取值范围
start	uint16_t	起始字符位置	>= 0
end	uint16_t	结束字符位置	>= start
size	uint8_t	绝对字体大小	合法字体大小值

SetRelativeSizeSpan

void SetRelativeSizeSpan(uint16_t start, uint16_t end, float size)

功能说明

• 核心用途：设置文本指定范围的相对字体大小
• 相对大小为相对于默认字体大小的缩放比例
• 需配合SpannableString模式使用

入参

名称	参数类型	详细说明	约束取值范围
start	uint16_t	起始字符位置	>= 0
end	uint16_t	结束字符位置	>= start
size	float	相对字体大小缩放比例	> 0.0

GetFontSize

uint8_t GetFontSize()

功能说明

• 核心用途：获取当前标签的字体大小
• 返回内部Text对象所持有的字体大小值

返回值

• 返回类型：uint8_t

返回字体大小

返回值	触发场景
> 0	已设置字体
默认值	未设置字体

ForceResetText

virtual void ForceResetText()

功能说明

• 核心用途：强制重置标签文本
• virtual成员函数，子类可重写
• 仅在ENABLE_FONT_VECTOR_GLOBAL宏开启时可用

Kconfig 配置

配置项	说明	默认值
ENABLE_FONT_VECTOR_GLOBAL	启用矢量字体全局支持	n

GetGuiInfo

std::string GetGuiInfo() const override

功能说明

• 核心用途：获取标签的GUI调试信息
• override成员函数，重写UIView基类实现
• 返回包含标签属性的字符串，用于调试和日志输出

返回值

• 返回类型：std::string

返回GUI调试信息字符串

返回值	触发场景
非空字符串	标签对象有效

SetAnimState

void SetAnimState(uint8_t state)

功能说明

• 核心用途：设置标签动画状态
• 在LINE_BREAK_MARQUEE或LINE_BREAK_OSCILLATION模式下使用
• 支持START（启动/恢复）、STOP（停止）、PAUSE（暂停）三种状态

入参

名称	参数类型	详细说明	约束取值范围
state	uint8_t	动画状态值	Animator::START/STOP/PAUSE

GetAnimRealState

uint8_t GetAnimRealState()

功能说明

• 核心用途：获取动画的实际运行状态
• 与SetAnimState设置的期望状态不同，返回动画器真实的运行状态
• 用于调试和状态检查

返回值

• 返回类型：uint8_t

返回动画实际状态

返回值	触发场景
Animator::START	动画正在运行
Animator::STOP	动画已停止
Animator::PAUSE	动画已暂停

SetMarqueeBlankNum

void SetMarqueeBlankNum(uint16_t size)

功能说明

• 核心用途：设置跑马灯模式下文本显示完毕后的空白间隔数量
• 仅在LINE_BREAK_MARQUEE模式下生效
• 默认值为3，即文本末尾与下一轮滚动开始之间间隔3个单位

入参

名称	参数类型	详细说明	约束取值范围
size	uint16_t	空白间隔数量	> 0

GetLabelText

Text* GetLabelText()

功能说明

• 核心用途：获取标签内部Text对象的指针
• 返回内部用于管理文本属性和渲染的Text对象
• 调用者不应释放返回的指针

返回值

• 返回类型：Text*

返回内部Text对象指针

返回值	触发场景
非nullptr	内部Text对象已初始化
nullptr	内部Text对象未初始化

Enumerations

UILabel::LineBreakMode

enum LineBreakMode : uint8_t {
    LINE_BREAK_ADAPT = 0,
    LINE_BREAK_STRETCH,
    LINE_BREAK_WRAP,
    LINE_BREAK_ELLIPSIS,
    LINE_BREAK_MARQUEE,
    LINE_BREAK_CLIP,
    LINE_BREAK_OSCILLATION,
    LINE_BREAK_TRUNCATE,
    LINE_BREAK_MAX,
};

枚举成员	取值	描述
LINE_BREAK_ADAPT	0	标签尺寸自适应文本大小
LINE_BREAK_STRETCH	1	高度不变，宽度自适应文本
LINE_BREAK_WRAP	2	宽度不变，高度自适应文本，超出宽度自动换行
LINE_BREAK_ELLIPSIS	3	宽高不变，超长文本显示省略号
LINE_BREAK_MARQUEE	4	宽高不变，超长文本滚动显示（跑马灯）
LINE_BREAK_CLIP	5	宽高不变，超长文本裁剪显示
LINE_BREAK_OSCILLATION	6	宽高不变，超长文本来回滚动显示
LINE_BREAK_TRUNCATE	7	宽高不变，超长文本截断显示
LINE_BREAK_MAX	8	换行模式最大值，用于合法性校验

UITextLanguageAlignment

enum UITextLanguageAlignment : uint8_t {
    TEXT_ALIGNMENT_LEFT = 0,
    TEXT_ALIGNMENT_RIGHT,
    TEXT_ALIGNMENT_CENTER,
    TEXT_ALIGNMENT_TOP,
    TEXT_ALIGNMENT_BOTTOM,
};

枚举成员	取值	描述
TEXT_ALIGNMENT_LEFT	0	左对齐
TEXT_ALIGNMENT_RIGHT	1	右对齐
TEXT_ALIGNMENT_CENTER	2	居中对齐
TEXT_ALIGNMENT_TOP	3	顶部对齐
TEXT_ALIGNMENT_BOTTOM	4	底部对齐

UITextLanguageDirect

enum UITextLanguageDirect : uint8_t {
    TEXT_DIRECT_LTR = 0,
    TEXT_DIRECT_RTL,
    TEXT_DIRECT_MIXED,
};

枚举成员	取值	描述
TEXT_DIRECT_LTR	0	从左到右
TEXT_DIRECT_RTL	1	从右到左
TEXT_DIRECT_MIXED	2	混合方向