ui_arc_label

ui_arc_label 模块提供弧形标签组件，支持沿圆弧路径排列的文本显示与滚动。

Class Summary

OHOS::ArcLabelScrollListener

弧形文本滚动监听器抽象基类，提供滚动结束回调接口

• 构造：无

• 成员函数：

  接口名称	功能简述
  Finish	滚动动画结束回调

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

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

OHOS::UIArcLabel

弧形文本标签控件，支持沿圆弧排列文本并提供文本对齐、字体、弧心、半径、角度、朝向、兼容模式及滚动动画等配置能力

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  GetWidth	获取弧形文本宽度
  GetHeight	获取弧形文本高度
  SetStyle	设置整体样式
  SetStyle	按键值对设置单项样式
  SetText	设置弧形标签的文本内容
  GetText	获取弧形标签的文本内容
  SetAlign	设置文本水平对齐方式
  GetHorAlign	获取文本水平对齐方式
  GetDirect	获取文本方向
  SetFontId	设置字体 ID
  GetFontId	获取字体 ID
  SetFont	设置字体名称和大小
  SetArcTextCenter	设置弧形文本圆心坐标
  GetArcTextCenter	获取弧形文本圆心坐标
  SetArcTextRadius	设置弧形文本半径
  GetArcTextRadius	获取弧形文本半径
  SetArcTextAngle	设置弧形文本起始和结束角度
  GetArcTextStartAngle	获取弧形文本起始角度
  GetArcTextEndAngle	获取弧形文本结束角度
  SetArcTextOrientation	设置弧形文本朝向
  GetArcTextOrientation	获取弧形文本朝向
  SetCompatibilityMode	设置兼容模式
  OnDraw	绘制弧形文本
  Start	启动滚动动画
  Stop	停止滚动动画
  SetRollCount	设置滚动循环次数
  RegisterScrollListener	注册滚动状态监听器
  SetRollSpeed	设置滚动速度
  GetRollSpeed	获取滚动速度
  ReMeasure	重新测量弧形文本布局
  GetGuiInfo	获取控件调试信息

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

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

Functions

OHOS::ArcLabelScrollListener

Finish

virtual void Finish() = 0

功能说明

• 纯虚函数，弧形标签滚动动画结束时由框架回调
• 派生类必须实现此接口以接收滚动完成通知
• 该函数为虚函数，由子类实现具体行为

OHOS::UIArcLabel

GetViewType

UIViewType GetViewType() const override

功能说明

• 获取当前视图的类型标识
• 返回 UI_ARC_LABEL，用于在视图体系中区分弧形标签控件
• 该函数为 const，不修改对象状态

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_ARC_LABEL(3)	当前控件为弧形标签

GetWidth

int16_t GetWidth() override

功能说明

• 获取弧形文本的宽度
• 调用前会触发重新测量以确保尺寸准确
• 返回值包含弧形文本实际占据的水平范围

返回值

• 返回类型：int16_t

返回弧形文本宽度（像素）

返回值	触发场景
非负整数	弧形文本正常测量后的宽度

GetHeight

int16_t GetHeight() override

功能说明

• 获取弧形文本的高度
• 调用前会触发重新测量以确保尺寸准确
• 返回值包含弧形文本实际占据的垂直范围

返回值

• 返回类型：int16_t

返回弧形文本高度（像素）

返回值	触发场景
非负整数	弧形文本正常测量后的高度

SetStyle

void SetStyle(Style& style) override

功能说明

• 设置弧形标签的整体样式
• 调用基类 UIView 的 SetStyle 完成样式应用
• 入参为引用，传入的样式对象在调用期间须保持有效

入参

名称	参数类型	详细说明	约束取值范围
style	Style&	入参引用，写入样式配置对象	有效的 Style 对象引用

SetStyle

void SetStyle(uint8_t key, int64_t value) override

功能说明

• 按键值对设置单项样式属性
• key 标识样式属性类型，value 为对应取值
• 该接口支持精细化的单项样式修改，无需构造完整 Style 对象

入参

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

SetText

void SetText(const char* text)

功能说明

• 设置弧形标签显示的文本内容
• 入参为只读指针，调用后弧形标签内部会复制文本数据
• 设置新文本后弧形标签自动标记为需要刷新

入参

名称	参数类型	详细说明	约束取值范围
text	const char*	入参只读指针，不修改所指对象	非 nullptr，指向以 '\0' 结尾的字符串

GetText

const char* GetText() const

功能说明

• 获取弧形标签当前显示的文本内容
• 返回只读指针，调用者不应通过该指针修改文本数据
• 该函数为 const，不修改对象状态

返回值

• 返回类型：const char*

返回文本内容指针

返回值	触发场景
非 nullptr	已设置文本内容
nullptr	未设置文本内容

SetAlign

void SetAlign(UITextLanguageAlignment horizontalAlign)

功能说明

• 设置弧形标签文本的水平对齐方式
• 支持左对齐、居中对齐、右对齐三种模式
• 设置后弧形标签自动标记为需要刷新

入参

名称	参数类型	详细说明	约束取值范围
horizontalAlign	UITextLanguageAlignment	水平对齐方式	TEXT_ALIGNMENT_LEFT(0) / TEXT_ALIGNMENT_RIGHT(1) / TEXT_ALIGNMENT_CENTER(2)

GetHorAlign

UITextLanguageAlignment GetHorAlign()

功能说明

• 获取弧形标签文本的当前水平对齐方式
• 返回枚举值标识对齐模式
• 该接口与 SetAlign 配对使用

返回值

• 返回类型：UITextLanguageAlignment

返回水平对齐方式

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

GetDirect

UITextLanguageDirect GetDirect()

功能说明

• 获取弧形标签文本的书写方向
• 返回枚举值标识文本是从左到右、从右到左或混合方向
• 该属性影响弧形文本的排列方向

返回值

• 返回类型：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 包含字体名称与字号信息
• 该接口与 SetFontId 配对使用

返回值

• 返回类型：uint16_t

返回字体 ID

返回值	触发场景
非零值	已设置字体 ID
0	未设置字体 ID

SetFont

void SetFont(const char* name, uint8_t size)

功能说明

• 通过字体名称和字号设置弧形标签字体
• 入参 name 为只读指针，指向字体名称字符串
• 设置后弧形标签自动标记为需要刷新

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参只读指针，不修改所指对象	非 nullptr，指向以 '\0' 结尾的字体名称字符串
size	uint8_t	字体大小	1 ~ 255

SetArcTextCenter

void SetArcTextCenter(int16_t x, int16_t y)

功能说明

• 设置弧形文本的圆心坐标
• 当新坐标与当前圆心不同时触发弧形标签刷新
• 圆心坐标决定弧形文本围绕绘制的基准点

入参

名称	参数类型	详细说明	约束取值范围
x	int16_t	圆心 x 坐标	有效屏幕坐标范围
y	int16_t	圆心 y 坐标	有效屏幕坐标范围

GetArcTextCenter

Point GetArcTextCenter() const

功能说明

• 获取弧形文本的圆心坐标
• 返回 Point 结构体包含 x 和 y 坐标
• 该函数为 const，不修改对象状态

返回值

• 返回类型：Point

返回圆心坐标

返回值	触发场景
Point	包含当前圆心 x、y 坐标

SetArcTextRadius

void SetArcTextRadius(uint16_t radius)

功能说明

• 设置弧形文本的半径
• 当新半径与当前半径不同时触发弧形标签刷新
• 半径决定弧形文本所在圆弧的大小

入参

名称	参数类型	详细说明	约束取值范围
radius	uint16_t	弧形文本半径	0 ~ 65535

GetArcTextRadius

uint16_t GetArcTextRadius() const

功能说明

• 获取弧形文本的半径
• 该函数为 const，不修改对象状态
• 返回值与 SetArcTextRadius 设置值一致

返回值

• 返回类型：uint16_t

返回弧形文本半径

返回值	触发场景
非零值	已设置半径
0	未设置半径

SetArcTextAngle

void SetArcTextAngle(float startAngle, float endAngle)

功能说明

• 设置弧形文本的起始角度和结束角度
• 12 点钟方向为 0 度，顺时针角度递增；终止角大于起始角时文本顺时针排列，反之为逆时针
• 当新角度与当前角度不同时触发弧形标签刷新

入参

名称	参数类型	详细说明	约束取值范围
startAngle	float	起始角度（度）	0.0 ~ 360.0
endAngle	float	结束角度（度）	0.0 ~ 360.0

GetArcTextStartAngle

float GetArcTextStartAngle() const

功能说明

• 获取弧形文本的起始角度
• 12 点钟方向为 0 度，顺时针角度递增
• 该函数为 const，不修改对象状态

返回值

• 返回类型：float

返回起始角度（度）

返回值	触发场景
浮点数	当前弧形文本的起始角度

GetArcTextEndAngle

float GetArcTextEndAngle() const

功能说明

• 获取弧形文本的结束角度
• 12 点钟方向为 0 度，顺时针角度递增
• 该函数为 const，不修改对象状态

返回值

• 返回类型：float

返回结束角度（度）

返回值	触发场景
浮点数	当前弧形文本的结束角度

SetArcTextOrientation

void SetArcTextOrientation(TextOrientation orientation)

功能说明

• 设置弧形文本的朝向
• 支持朝内（INSIDE）和朝外（OUTSIDE）两种朝向
• 当新朝向与当前朝向不同时触发弧形标签刷新

入参

名称	参数类型	详细说明	约束取值范围
orientation	TextOrientation	文本朝向	TextOrientation::INSIDE(0) / TextOrientation::OUTSIDE(1)

GetArcTextOrientation

TextOrientation GetArcTextOrientation() const

功能说明

• 获取弧形文本的朝向
• 该函数为 const，不修改对象状态
• 返回值与 SetArcTextOrientation 设置值一致

返回值

• 返回类型：TextOrientation

返回文本朝向

返回值	触发场景
TextOrientation::INSIDE(0)	文本朝内
TextOrientation::OUTSIDE(1)	文本朝外

SetCompatibilityMode

void SetCompatibilityMode(bool compatibilityMode)

功能说明

• 设置是否启用兼容模式
• 兼容模式用于适配旧版本弧形文本渲染行为
• 当新模式与当前模式不同时触发弧形标签刷新

入参

名称	参数类型	详细说明	约束取值范围
compatibilityMode	bool	是否启用兼容模式	true / false

OnDraw

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

功能说明

• 绘制弧形文本到指定图形缓冲区
• 由 UI 框架在刷新脏区域时自动调用
• 入参均为引用，调用期间须保证引用对象有效

入参

名称	参数类型	详细说明	约束取值范围
gfxDstBuffer	BufferInfo&	入参引用，写入目标图形缓冲区信息	有效的 BufferInfo 对象引用
invalidatedArea	const Rect&	入参只读引用，不修改所指对象	有效的 Rect 对象引用

Start

void Start()

功能说明

• 启动弧形标签滚动动画
• 调用后弧形文本将按设定速度沿圆弧滚动
• 滚动结束后触发已注册的 ArcLabelScrollListener 回调

Stop

void Stop()

功能说明

• 停止弧形标签滚动动画
• 调用后弧形文本停止在当前位置
• 可与 Start 配合使用实现滚动控制

SetRollCount

void SetRollCount(const uint16_t rollCount)

功能说明

• 设置弧形标签滚动的循环次数
• 入参为值传递，无需关心生命周期
• 滚动达到指定次数后动画自动停止

入参

名称	参数类型	详细说明	约束取值范围
rollCount	const uint16_t	入参值传递	1 ~ 65535

RegisterScrollListener

void RegisterScrollListener(ArcLabelScrollListener* scrollListener)

功能说明

• 注册滚动状态变化监听器
• 入参为指针，调用者负责监听器对象的生命周期管理
• 滚动动画结束时回调监听器的 Finish 方法

入参

名称	参数类型	详细说明	约束取值范围
scrollListener	ArcLabelScrollListener*	入参指针，可为 nullptr	指向 ArcLabelScrollListener 派生类实例或 nullptr

SetRollSpeed

void SetRollSpeed(const uint16_t speed)

功能说明

• 设置弧形标签滚动动画速度
• 入参为值传递，无需关心生命周期
• 速度值越大滚动越快

入参

名称	参数类型	详细说明	约束取值范围
speed	const uint16_t	入参值传递	1 ~ 65535

GetRollSpeed

uint16_t GetRollSpeed() const

功能说明

• 获取弧形标签当前的滚动速度
• 该函数为 const，不修改对象状态
• 返回值与 SetRollSpeed 设置值一致

返回值

• 返回类型：uint16_t

返回滚动速度

返回值	触发场景
非零值	已设置滚动速度
0	未设置滚动速度

ReMeasure

void ReMeasure() override

功能说明

• 重新测量弧形文本布局信息
• 当弧形参数（圆心、半径、角度等）发生变化后需调用以更新布局
• GetWidth 和 GetHeight 内部会自动调用此方法

GetGuiInfo

std::string GetGuiInfo() const override

功能说明

• 获取控件调试信息字符串
• 该函数为 const，不修改对象状态
• 返回的字符串包含控件类型、位置、尺寸等调试信息

返回值

• 返回类型：std::string

返回调试信息字符串

返回值	触发场景
非空字符串	包含控件调试信息

Enumerations

TextOrientation

enum class TextOrientation : uint8_t {
    INSIDE,
    OUTSIDE,
};

枚举成员	取值	描述
INSIDE	0	文本朝向圆弧内侧
OUTSIDE	1	文本朝向圆弧外侧

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	混合方向

UIViewType

enum UIViewType : uint8_t {
    UI_ROOT_VIEW = 0,
    UI_VIEW_GROUP,
    UI_LABEL,
    UI_ARC_LABEL,
    UI_LABEL_BUTTON,
    UI_CHECK_BOX,
    UI_TOGGLE_BUTTON,
    UI_RADIO_BUTTON,
    UI_IMAGE_VIEW,
    UI_BOX_PROGRESS,
    UI_SLIDER,
    UI_CIRCLE_PROGRESS,
    UI_SCROLL_VIEW,
    UI_LIST,
    UI_DIGITAL_CLOCK,
    UI_ANALOG_CLOCK,
    UI_PICKER,
    UI_SWIPE_VIEW,
    UI_TIME_PICKER,
    UI_ABSTRACT_CLOCK,
    UI_ABSTRACT_PROGRESS,
    UI_ABSTRACT_SCROLL,
    UI_AXIS,
    UI_BUTTON,
    UI_CANVAS,
    UI_CHART,
    UI_IMAGE_ANIMATOR_VIEW,
    UI_REPEAT_BUTTON,
    UI_TEXTURE_MAPPER,
    UI_DIALOG,
    UI_QRCODE,
    UI_LABEL_EXT,
    UI_LABEL_BUTTON_EXT,
    UI_CANVAS_EXT,
    UI_CHART_PILLAR,
};

枚举成员	取值	描述
UI_ROOT_VIEW	0	根视图
UI_VIEW_GROUP	1	视图组
UI_LABEL	2	标签
UI_ARC_LABEL	3	弧形标签
UI_LABEL_BUTTON	4	标签按钮
UI_CHECK_BOX	5	复选框
UI_TOGGLE_BUTTON	6	切换按钮
UI_RADIO_BUTTON	7	单选按钮
UI_IMAGE_VIEW	8	图片视图
UI_BOX_PROGRESS	9	条形进度条
UI_SLIDER	10	滑块
UI_CIRCLE_PROGRESS	11	圆形进度条
UI_SCROLL_VIEW	12	滚动视图
UI_LIST	13	列表
UI_DIGITAL_CLOCK	14	数字时钟
UI_ANALOG_CLOCK	15	模拟时钟
UI_PICKER	16	选择器
UI_SWIPE_VIEW	17	滑动视图
UI_TIME_PICKER	18	时间选择器
UI_ABSTRACT_CLOCK	19	抽象时钟
UI_ABSTRACT_PROGRESS	20	抽象进度条
UI_ABSTRACT_SCROLL	21	抽象滚动
UI_AXIS	22	坐标轴
UI_BUTTON	23	按钮
UI_CANVAS	24	画布
UI_CHART	25	图表
UI_IMAGE_ANIMATOR_VIEW	26	图片动画视图
UI_REPEAT_BUTTON	27	重复按钮
UI_TEXTURE_MAPPER	28	纹理映射
UI_DIALOG	29	对话框
UI_QRCODE	30	二维码
UI_LABEL_EXT	31	扩展标签
UI_LABEL_BUTTON_EXT	32	扩展标签按钮
UI_CANVAS_EXT	33	扩展画布
UI_CHART_PILLAR	34	柱状图

Structures

ArcTextInfo

struct ArcTextInfo {
    uint16_t radius;
    float startAngle;
    float endAngle;
    Point arcCenter;
    uint32_t lineStart;
    uint32_t lineEnd;
    UITextLanguageDirect direct;
    bool hasAnimator;
    uint32_t* codePoints;
    uint16_t codePointsNum;
    uint8_t shapingFontId;
};

成员说明

成员名称	数据类型	描述
radius	uint16_t	弧形文本半径
startAngle	float	起始角度（度）
endAngle	float	结束角度（度）
arcCenter	Point	弧形圆心坐标
lineStart	uint32_t	行起始位置
lineEnd	uint32_t	行结束位置
direct	UITextLanguageDirect	文本书写方向
hasAnimator	bool	是否有动画
codePoints	uint32_t*	Unicode 码点数组
codePointsNum	uint16_t	码点数量
shapingFontId	uint8_t	字形字体 ID