ui_label_button
ui_label_button 模块提供带标签的按钮组件，在按钮基础上增加文本标签显示能力。
Class Summary
OHOS::UILabelButton
带文本标签的按钮组件，继承自 UIButton，支持设置按钮上的文本内容、位置、对齐方式、方向及样式
- 构造：无
-
成员函数：
接口名称 功能简述 OnDraw 绘制标签按钮 GetViewType 获取视图类型 SetText 设置标签按钮文本 GetText 获取标签按钮文本 SetLabelPosition 设置标签相对按钮的偏移位置 GetLabelPosition 获取标签相对按钮的偏移位置 SetAlign 设置文本对齐方式 GetAlign 获取文本对齐方式 SetDirect 设置文本方向 GetDirect 获取文本方向 SetLabelStyle 设置标签样式（整体样式对象） SetLabelStyle 设置标签样式中指定键的值 GetLabelStyle 获取标签整体样式 GetLabelStyle 获取标签样式中指定键的值 SetTextColor 设置文本颜色 SetFont 设置文本字体 SetFontId 设置字体 ID GetFontId 获取字体 ID ForceResetText 强制重置文本 -
使用包含头文件：
#include "components/ui_label_button.h" - 声明头文件：
middleware/services/gui/uikit/ui/interfaces/kits/components/ui_label_button.h - 公有运算符：无
- 继承关系：UIButton
- 嵌套类型：无
- 模板形参：无
Functions
OHOS::UILabelButton
OnDraw
void OnDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override
功能说明
- 核心用途：在指定缓冲区的无效区域内绘制标签按钮
- 设计目的：将按钮背景与文本标签统一绘制，文本位置受偏移量影响
- 使用场景：UI 框架渲染流程中自动调用，开发者通常无需直接调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| gfxDstBuffer | BufferInfo& | 目标图形缓冲区，入参引用，写入 | 有效的图形缓冲区对象 |
| invalidatedArea | const Rect& | 需要重绘的无效区域，入参只读引用 | 有效的矩形区域 |
GetViewType
UIViewType GetViewType() const override
功能说明
- 核心用途：获取当前视图的类型标识
- 设计目的：在视图类型判断时区分 UILabelButton 与其他视图
- 使用场景：UI 框架中需要根据视图类型执行差异化逻辑时调用
返回值
- 返回类型：
UIViewType
返回视图类型标识
| 返回值 | 触发场景 |
|---|---|
| UI_LABEL_BUTTON(4) | 当前对象为 UILabelButton 类型 |
SetText
void SetText(const char* text)
功能说明
- 核心用途：设置标签按钮上显示的文本内容
- 设计目的：提供按钮文本的统一设置接口
- 使用场景：按钮创建后或需要动态更新按钮文本时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| text | const char* | 指向文本内容的指针，入参指针，不可为 nullptr | 有效的 C 字符串指针 |
GetText
const char* GetText() const
功能说明
- 核心用途：获取标签按钮当前显示的文本内容
- 设计目的：读取按钮文本用于显示或逻辑判断
- 使用场景：需要读取按钮当前文本内容时调用；若未初始化内部文本对象则返回 nullptr
返回值
- 返回类型：
const char*
返回文本内容指针
| 返回值 | 触发场景 |
|---|---|
| 非 nullptr | 内部文本对象已初始化，返回文本字符串指针 |
| nullptr | 内部文本对象未初始化 |
SetLabelPosition
void SetLabelPosition(int16_t x, int16_t y)
功能说明
- 核心用途：设置标签文本相对按钮的偏移位置
- 设计目的：控制文本在按钮内的精确绘制位置
- 使用场景：按钮创建后需要调整文本位置时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| x | int16_t | X 轴偏移距离 | int16_t 取值范围 |
| y | int16_t | Y 轴偏移距离 | int16_t 取值范围 |
GetLabelPosition
Point GetLabelPosition() const
功能说明
- 核心用途：获取标签文本相对按钮的偏移位置
- 设计目的：读取当前文本偏移量用于布局计算或状态判断
- 使用场景：需要获取文本偏移位置信息时调用
返回值
- 返回类型：
Point
返回标签相对按钮的偏移位置
| 返回值 | 触发场景 |
|---|---|
| Point{0, 0} | 默认偏移，未调用 SetLabelPosition |
| Point{x, y} | 已通过 SetLabelPosition 设置的偏移值 |
SetAlign
void SetAlign(UITextLanguageAlignment align)
功能说明
- 核心用途：设置标签文本的水平对齐方式，垂直方向默认居中对齐
- 设计目的：控制文本在按钮区域内的水平对齐模式
- 使用场景：按钮创建后需要调整文本对齐方式时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| align | UITextLanguageAlignment | 文本水平对齐模式 | TEXT_ALIGNMENT_LEFT(0) / TEXT_ALIGNMENT_RIGHT(1) / TEXT_ALIGNMENT_CENTER(2) / TEXT_ALIGNMENT_TOP(3) / TEXT_ALIGNMENT_BOTTOM(4) |
GetAlign
UITextLanguageAlignment GetAlign()
功能说明
- 核心用途：获取标签文本的水平对齐方式
- 设计目的：读取当前文本对齐模式用于布局或状态判断
- 使用场景：需要获取文本对齐方式时调用
返回值
- 返回类型：
UITextLanguageAlignment
返回文本水平对齐模式
| 返回值 | 触发场景 |
|---|---|
| TEXT_ALIGNMENT_LEFT(0) | 左对齐 |
| TEXT_ALIGNMENT_RIGHT(1) | 右对齐 |
| TEXT_ALIGNMENT_CENTER(2) | 水平居中 |
| TEXT_ALIGNMENT_TOP(3) | 顶部对齐 |
| TEXT_ALIGNMENT_BOTTOM(4) | 底部对齐 |
SetDirect
void SetDirect(UITextLanguageDirect direct)
功能说明
- 核心用途：设置标签文本的书写方向
- 设计目的：支持从左到右、从右到左等不同语言的文本方向
- 使用场景：需要适配不同语言文字方向时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| direct | UITextLanguageDirect | 文本方向 | TEXT_DIRECT_LTR(0) / TEXT_DIRECT_RTL(1) / TEXT_DIRECT_MIXED(2) |
GetDirect
UITextLanguageDirect GetDirect()
功能说明
- 核心用途：获取标签文本的书写方向
- 设计目的：读取当前文本方向用于布局或状态判断
- 使用场景：需要获取文本书写方向时调用
返回值
- 返回类型：
UITextLanguageDirect
返回文本书写方向
| 返回值 | 触发场景 |
|---|---|
| TEXT_DIRECT_LTR(0) | 从左到右 |
| TEXT_DIRECT_RTL(1) | 从右到左 |
| TEXT_DIRECT_MIXED(2) | 混合方向 |
SetLabelStyle
void SetLabelStyle(Style& labelStyle)
功能说明
- 核心用途：整体设置标签的样式对象
- 设计目的：一次性替换标签的全部样式属性
- 使用场景：需要批量修改标签样式时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| labelStyle | Style& | 标签样式对象，入参引用，写入 | 有效的 Style 对象 |
SetLabelStyle
void SetLabelStyle(uint8_t key, int64_t value)
功能说明
- 核心用途：设置标签样式中指定键的值
- 设计目的：按键值对方式单独修改某一项样式属性
- 使用场景：需要单独修改标签某一样式属性时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | uint8_t | 样式键 | Style 中定义的合法键值 |
| value | int64_t | 样式值 | 与 key 对应的合法取值 |
GetLabelStyle
const Style& GetLabelStyle() const
功能说明
- 核心用途：获取标签的整体样式对象的只读引用
- 设计目的：读取标签全部样式属性用于查询或判断
- 使用场景：需要获取标签完整样式信息时调用
返回值
- 返回类型：
const Style&
返回标签样式对象的只读引用
| 返回值 | 触发场景 |
|---|---|
| const Style& | 当前标签的样式对象引用 |
GetLabelStyle
int64_t GetLabelStyle(uint8_t key) const
功能说明
- 核心用途：获取标签样式中指定键对应的值
- 设计目的：按键值对方式读取某一项样式属性
- 使用场景：需要查询标签某一样式属性值时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| key | uint8_t | 样式键 | Style 中定义的合法键值 |
返回值
- 返回类型：
int64_t
返回指定键对应的样式值
| 返回值 | 触发场景 |
|---|---|
| int64_t 值 | 指定键对应的样式属性值 |
SetTextColor
void SetTextColor(ColorType color)
功能说明
- 核心用途：设置标签文本的颜色
- 设计目的：独立设置文本颜色，无需整体替换样式
- 使用场景：需要修改按钮文本颜色时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| color | ColorType | 文本颜色值 | ColorType 有效取值范围 |
SetFont
void SetFont(const char* name, uint8_t size)
功能说明
- 核心用途：设置标签文本的字体名称和字号
- 设计目的：指定文本渲染使用的字体资源
- 使用场景：需要修改按钮文本字体时调用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| name | const char* | 字体名称指针，入参指针，不可为 nullptr | 有效的字体名称字符串 |
| size | uint8_t | 字体大小 | uint8_t 取值范围 |
SetFontId
void SetFontId(uint16_t fontId)
功能说明
- 核心用途：通过字体 ID 设置标签文本字体
- 设计目的：使用预注册的字体 ID 快速指定字体
- 使用场景：已知字体 ID 时调用，避免传入字体名称字符串
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| fontId | uint16_t | 字体 ID，由字体名称和大小组成 | uint16_t 取值范围 |
GetFontId
uint16_t GetFontId()
功能说明
- 核心用途：获取标签文本当前的字体 ID
- 设计目的：读取字体 ID 用于查询或状态判断
- 使用场景：需要获取当前字体标识时调用
返回值
- 返回类型：
uint16_t
返回字体 ID
| 返回值 | 触发场景 |
|---|---|
| uint16_t 值 | 当前文本的字体 ID |
ForceResetText
virtual void ForceResetText()
功能说明
- 核心用途：强制重置文本内容
- 设计目的：在字体全局矢量配置启用时提供文本重置能力
- 使用场景：需要强制清除并重建文本状态时调用
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_FONT_VECTOR_GLOBAL | 启用字体全局矢量配置，该配置开启时此接口可用 | n |