ui_menu_item

ui_menu_item 模块提供菜单项组件，用于构建菜单列表中的单个菜单项。

Class Summary

OHOS::UIMenuItem

菜单项组件，用于在菜单列表中展示包含图标与文本的单个条目

构造：无

成员函数：

接口名称	功能简述
GetViewType	获取视图类型，返回 UI_MENU_ITEM
SetImageSrc	通过图片路径设置菜单项图标
SetImageSrc	通过 ImageInfo 指针设置菜单项图标
SetText	设置菜单项文本内容
SetAlign	设置文本水平对齐方式
SetDirect	设置文本书写方向
SetLabelStyle	通过 Style 对象设置文本标签样式
SetLabelStyle	通过键值对设置文本标签样式
SetTextColor	设置文本颜色
SetFont	通过字体名称和大小设置文本字体
SetFontId	通过字体 ID 设置文本字体
SetLineBreakMode	设置文本换行模式
SetTextId	设置文本资源 ID
SetImgResizeMode	设置图标缩放模式
SetImgOffset	设置图标相对于条目左边界的偏移量
SetTextOffset	设置文本相对于图标右边界（或条目左边界）的偏移量
SetScaleAlignMode	设置缩放变换的对齐模式
GetScaleCenter	获取缩放变换的中心点坐标
ReMeasure	重新测量并更新子视图布局
OnDraw	绘制菜单项背景矩形
DumpImgInfo	打印图标调试信息

使用包含头文件：#include "components/ui_menu_item.h"
声明头文件：middleware/services/gui/uikit/proprietary/include/components/ui_menu_item.h
公有运算符：无
继承关系：UIViewGroup
嵌套类型：enum class ScaleAlignMode { ALIGN_TEXT_LEFT, ALIGN_IMAGE_LEFT, ALIGN_ITEM_CENTER }
模板形参：无

Functions

OHOS::UIMenuItem

GetViewType

UIViewType GetViewType() const override

功能说明

核心用途：获取当前视图的类型标识
设计目的：在视图类型体系中标识 UIMenuItem 实例，供框架进行类型分发与判断
使用场景：视图树遍历、类型判断、条件分支中识别菜单项视图

返回值

返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_MENU_ITEM	当前对象为 UIMenuItem 实例

SetImageSrc

void SetImageSrc(const char* imgSrc)

功能说明

核心用途：通过图片文件路径设置菜单项的图标
设计目的：支持从文件系统加载图片资源作为菜单项图标
使用场景：菜单项需展示文件系统中的图片资源时调用

入参

名称	参数类型	详细说明	约束取值范围
imgSrc	const char*	入参指针，指向图片文件路径字符串，不可为 nullptr	有效的图片文件路径

SetImageSrc

void SetImageSrc(const ImageInfo* imgSrc)

功能说明

核心用途：通过 ImageInfo 指针设置菜单项的图标
设计目的：支持从内存中的 ImageInfo 结构加载图片资源作为菜单项图标
使用场景：菜单项需展示程序内嵌或运行时生成的图片资源时调用

入参

名称	参数类型	详细说明	约束取值范围
imgSrc	const ImageInfo*	入参只读指针，指向 ImageInfo 结构，不可为 nullptr	有效的 ImageInfo 对象指针

SetText

void SetText(const char* text)

功能说明

核心用途：设置菜单项的文本内容
设计目的：为菜单项设置显示文字，调用后自动触发重新测量
使用场景：菜单项需显示或更新文字信息时调用

入参

名称	参数类型	详细说明	约束取值范围
text	const char*	入参指针，指向待显示的文本字符串，不可为 nullptr	有效的 C 字符串

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)

SetDirect

void SetDirect(UITextLanguageDirect direct)

功能说明

核心用途：设置菜单项文本的书写方向
设计目的：支持从左到右（LTR）或从右到左（RTL）的文本排版方向
使用场景：多语言场景下需切换文本书写方向时调用

入参

名称	参数类型	详细说明	约束取值范围
direct	UITextLanguageDirect	文本书写方向	TEXT_DIRECT_LTR(0) / TEXT_DIRECT_RTL(1) / TEXT_DIRECT_MIXED(2)

SetLabelStyle

void SetLabelStyle(Style& labelStyle)

功能说明

核心用途：通过 Style 对象整体设置文本标签的样式
设计目的：一次性应用多个样式属性到菜单项的文本标签
使用场景：需批量设置文本标签背景色、边框、圆角等多个样式属性时调用

入参

名称	参数类型	详细说明	约束取值范围
labelStyle	Style&	入参引用，写入，指向待应用的样式对象	有效的 Style 对象引用

SetLabelStyle

void SetLabelStyle(uint8_t key, int64_t value)

功能说明

核心用途：通过键值对逐项设置文本标签的样式属性
设计目的：按样式键单独设置某一个样式属性值
使用场景：仅需修改文本标签的某个特定样式属性（如背景色、边框宽度等）时调用

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式属性键	有效的 Style 枚举键值
value	int64_t	样式属性值	与 key 对应的有效取值

SetTextColor

void SetTextColor(ColorType color)

功能说明

核心用途：设置菜单项文本的颜色
设计目的：独立控制文本颜色，不影响标签其他样式属性
使用场景：需修改菜单项文字颜色时调用

入参

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

SetFont

void SetFont(const char* name, uint8_t size)

功能说明

核心用途：通过字体名称和大小设置菜单项文本字体
设计目的：指定文本渲染所使用的字体名称与字号
使用场景：需自定义菜单项文字字体和字号时调用

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参指针，指向字体名称字符串，不可为 nullptr	有效的字体名称
size	uint8_t	字体大小	1 ~ 255

SetFontId

void SetFontId(uint16_t fontId)

功能说明

核心用途：通过字体 ID 设置菜单项文本字体
设计目的：使用预注册的字体 ID 快速指定字体，ID 由字体名称与大小组合编码
使用场景：已知字体 ID 时直接设置，避免重复传入名称和大小

入参

名称	参数类型	详细说明	约束取值范围
fontId	uint16_t	字体 ID，由字体名称与大小组合编码	有效的字体 ID

SetLineBreakMode

void SetLineBreakMode(const uint8_t lineBreakMode)

功能说明

核心用途：设置菜单项文本的换行模式
设计目的：控制文本超出标签宽度时的截断或换行行为
使用场景：需指定文本超长时省略、换行或裁剪等处理方式时调用

入参

名称	参数类型	详细说明	约束取值范围
lineBreakMode	const uint8_t	文本换行模式	UILabel::LineBreakMode 枚举值

SetTextId

void SetTextId(uint16_t textId)

功能说明

核心用途：设置菜单项文本的资源 ID
设计目的：通过资源 ID 引用多语言文本资源，调用后自动触发重新测量
使用场景：多语言场景下通过资源 ID 加载对应语言的文本时调用

入参

名称	参数类型	详细说明	约束取值范围
textId	uint16_t	文本资源 ID	有效的文本资源 ID

SetImgResizeMode

void SetImgResizeMode(UIImageView::ImageResizeMode mode)

功能说明

核心用途：设置菜单项图标的缩放模式
设计目的：控制图标在指定区域内的缩放与对齐行为
使用场景：需调整图标填充、居中、等比缩放等显示模式时调用

入参

名称	参数类型	详细说明	约束取值范围
mode	UIImageView::ImageResizeMode	图标缩放模式	NONE(0) / COVER(1) / CONTAIN(2) / FILL(3) / CENTER(4) / SCALE_DOWN(5)

SetImgOffset

void SetImgOffset(int16_t offset)

功能说明

核心用途：设置图标相对于菜单项左边界的水平偏移量
设计目的：精细控制图标在菜单项内的水平位置
使用场景：需调整图标与条目左边界间距时调用

入参

名称	参数类型	详细说明	约束取值范围
offset	int16_t	图标水平偏移量（像素），相对于条目左边界	-32768 ~ 32767

SetTextOffset

void SetTextOffset(int16_t offset)

功能说明

核心用途：设置文本相对于图标右边界（无图标时相对于条目左边界）的水平偏移量
设计目的：精细控制文本在菜单项内的水平位置
使用场景：需调整文本与图标或条目边界间距时调用

入参

名称	参数类型	详细说明	约束取值范围
offset	int16_t	文本水平偏移量（像素）	-32768 ~ 32767，默认值 20

SetScaleAlignMode

void SetScaleAlignMode(ScaleAlignMode mode)

功能说明

核心用途：设置菜单项缩放变换的对齐模式
设计目的：决定缩放变换时以文本左侧、图标左侧或条目中心为对齐参考点
使用场景：需控制菜单项缩放动画的锚点对齐方式时调用

入参

名称	参数类型	详细说明	约束取值范围
mode	ScaleAlignMode	缩放对齐模式	ALIGN_TEXT_LEFT(0) / ALIGN_IMAGE_LEFT(1) / ALIGN_ITEM_CENTER(2)

GetScaleCenter

Vector2<float> GetScaleCenter()

功能说明

核心用途：获取菜单项缩放变换的中心点坐标
设计目的：根据当前 ScaleAlignMode 计算缩放中心，供变换动画使用
使用场景：执行缩放动画前需获取变换中心坐标时调用

返回值

返回类型：Vector2<float>

返回缩放中心点坐标

返回值	触发场景
Vector2{label_->GetX(), label_->GetHeight() / 2.0f}	ALIGN_TEXT_LEFT 模式
Vector2{image_->GetX(), image_->GetHeight() / 2.0f}	ALIGN_IMAGE_LEFT 模式
Vector2{GetWidth() / 2.0f, GetHeight() / 2.0f}	ALIGN_ITEM_CENTER 模式

ReMeasure

void ReMeasure() override

功能说明

核心用途：重新测量并更新子视图（图标与文本标签）的布局位置
设计目的：根据当前偏移量和尺寸重新计算图标与文本的位置，并同步变换矩阵
使用场景：修改偏移量、文本内容或图标后由框架自动或手动触发重新布局

OnDraw

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

功能说明

核心用途：绘制菜单项的背景矩形
设计目的：使用当前样式与透明度在指定区域内绘制背景矩形
使用场景：由渲染框架在重绘阶段调用，通常不直接调用

入参

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

DumpImgInfo

void DumpImgInfo() override

功能说明

核心用途：打印菜单项图标的调试信息
设计目的：输出视图指针、视图类型及图标 ImageInfo 到标准输出，用于调试诊断
使用场景：调试阶段需查看菜单项图标加载状态时调用

Enumerations

ScaleAlignMode

enum class ScaleAlignMode {
    ALIGN_TEXT_LEFT,
    ALIGN_IMAGE_LEFT,
    ALIGN_ITEM_CENTER
};

枚举成员	取值	描述
ALIGN_TEXT_LEFT	0	以文本左侧为缩放对齐参考点
ALIGN_IMAGE_LEFT	1	以图标左侧为缩放对齐参考点
ALIGN_ITEM_CENTER	2	以条目中心为缩放对齐参考点