ui_button

ui_button 模块提供按钮组件，支持按钮按下/释放/取消事件的响应与样式切换。

Class Summary

OHOS::UIButton

按钮组件，响应按压与释放事件

• 构造：UIButton(const char* id)

• 成员函数：

  接口名称	功能简述
  UIButton	基于按钮 ID 构造 UIButton 实例
  GetViewType	获取组件类型
  OnPreDraw	绘制前检查是否需要覆盖无效区域
  OnPostDraw	绘制后执行按钮动画遮罩绘制
  OnDraw	执行按钮绘制
  OnPressEvent	处理按压事件
  OnReleaseEvent	处理释放事件
  OnCancelEvent	处理取消事件
  SetImageSrc	通过图片路径设置按钮的默认图片与触发图片
  SetImageSrc	通过 ImageInfo 指针设置按钮的默认图片与触发图片
  SetImagePosition	设置按钮图片位置
  GetImageX	获取按钮图片的 X 坐标
  GetImageY	获取按钮图片的 Y 坐标
  GetCurImageSrc	获取当前按钮状态对应的图片
  GetWidth	获取按钮内容区域宽度
  GetHeight	获取按钮内容区域高度
  SetWidth	设置按钮宽度
  SetHeight	设置按钮高度
  GetContentRect	获取按钮内容区域的矩形信息
  GetStyle	获取当前样式状态下的样式值
  SetStyle	设置当前样式状态下的样式值
  GetStyleForState	获取指定按钮状态下的样式值
  SetStyleForState	设置指定按钮状态下的样式值
  Disable	禁用按钮
  Enable	启用按钮
  SetStateForStyle	设置样式操作的目标按钮状态
  EnableButtonAnimation	启用或禁用按钮动画

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

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

Functions

OHOS::UIButton

UIButton

UIButton(const char* id)

功能说明

• 基于按钮 ID 构造 UIButton 实例，相同 ID 的按钮属于同一批次
• 构造后按钮默认处于 RELEASED 状态，可触摸
• 调用前无需额外初始化，构造即进入可用状态

入参

名称	参数类型	详细说明	约束取值范围
id	const char*	入参指针，按钮标识符，相同 ID 的按钮归为同一批次	有效 C 字符串指针

GetViewType

UIViewType GetViewType() const override

功能说明

• 获取当前组件的类型标识
• 返回值为 UI_BUTTON，用于区分其他 UIView 子类
• 该方法为 const，不修改对象状态

返回值

• 返回类型：UIViewType

返回组件类型标识

返回值	触发场景
UI_BUTTON	始终返回此值

OnPreDraw

bool OnPreDraw(Rect& invalidatedArea) const override

功能说明

• 绘制前检查当前按钮是否需要覆盖无效区域，供渲染管理器决定绘制层级
• 根据按钮的圆角样式判断无效区域与按钮区域的包含关系
• 该方法为 const，不修改对象状态

入参

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

返回值

• 返回类型：bool

返回是否需要覆盖无效区域

返回值	触发场景
true(1)	按钮区域完全包含无效区域，或圆角半径为 COORD_MAX
false(0)	按钮区域未完全包含无效区域

OnPostDraw

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

功能说明

• 绘制后执行按钮按压状态的动画遮罩绘制
• 仅在按钮处于 PRESSED 状态且动画启用时执行遮罩绘制
• 需在 DEFAULT_ANIMATION 宏开启时才可用

入参

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

Kconfig 配置

配置项	说明	默认值
DEFAULT_ANIMATION	按钮动画功能开关，控制 OnPostDraw 动画绘制是否可用	-

OnDraw

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

功能说明

• 执行按钮绘制，包括按钮矩形背景与图片资源的绘制
• 绘制时根据当前按钮状态选择对应样式
• 该方法由渲染框架在绘制阶段自动调用

入参

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

OnPressEvent

bool OnPressEvent(const PressEvent& event) override

功能说明

• 处理按压事件，将按钮状态切换为 PRESSED 并切换至触发图片
• 触发后自动刷新按钮显示区域
• 返回事件是否被当前按钮消费

入参

名称	参数类型	详细说明	约束取值范围
event	const PressEvent&	入参只读引用，按压事件信息，包含按压位置	有效 PressEvent 对象引用

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true(1)	事件被消费
false(0)	事件未被消费

OnReleaseEvent

bool OnReleaseEvent(const ReleaseEvent& event) override

功能说明

• 处理释放事件，将按钮状态切换为 RELEASED 并恢复默认图片
• 触发后自动刷新按钮显示区域
• 返回事件是否被当前按钮消费

入参

名称	参数类型	详细说明	约束取值范围
event	const ReleaseEvent&	入参只读引用，释放事件信息	有效 ReleaseEvent 对象引用

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true(1)	事件被消费
false(0)	事件未被消费

OnCancelEvent

bool OnCancelEvent(const CancelEvent& event) override

功能说明

• 处理取消事件，将按钮状态恢复为 RELEASED 并恢复默认图片
• 触发后自动刷新按钮显示区域
• 返回事件是否被当前按钮消费

入参

名称	参数类型	详细说明	约束取值范围
event	const CancelEvent&	入参只读引用，取消事件信息	有效 CancelEvent 对象引用

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true(1)	事件被消费
false(0)	事件未被消费

SetImageSrc

void SetImageSrc(const char* defaultImgSrc, const char* triggeredImgSrc)

功能说明

• 通过图片文件路径设置按钮的默认图片与触发图片
• 首次调用时自动创建内部 Image 对象
• 设置后图片将在下次绘制时生效

入参

名称	参数类型	详细说明	约束取值范围
defaultImgSrc	const char*	入参指针，默认状态图片路径	有效图片文件路径字符串
triggeredImgSrc	const char*	入参指针，触发状态图片路径	有效图片文件路径字符串

SetImageSrc

void SetImageSrc(const ImageInfo* defaultImgSrc, const ImageInfo* triggeredImgSrc)

功能说明

• 通过 ImageInfo 指针设置按钮的默认图片与触发图片
• 首次调用时自动创建内部 Image 对象
• 设置后图片将在下次绘制时生效

入参

名称	参数类型	详细说明	约束取值范围
defaultImgSrc	const ImageInfo*	入参指针，默认状态图片信息	有效 ImageInfo 对象指针
triggeredImgSrc	const ImageInfo*	入参指针，触发状态图片信息	有效 ImageInfo 对象指针

SetImagePosition

void SetImagePosition(const int16_t x, const int16_t y)

功能说明

• 设置按钮图片在内容区域内的偏移位置
• 坐标相对于按钮内容区域左上角
• 设置后将在下次绘制时生效

入参

名称	参数类型	详细说明	约束取值范围
x	const int16_t	图片 X 坐标偏移	int16_t 范围
y	const int16_t	图片 Y 坐标偏移	int16_t 范围

GetImageX

int16_t GetImageX() const

功能说明

• 获取按钮图片的 X 坐标偏移
• 该方法为 const，不修改对象状态
• 返回值为最近一次 SetImagePosition 设置的 X 坐标

返回值

• 返回类型：int16_t

返回图片 X 坐标偏移

返回值	触发场景
int16_t 值	当前图片 X 坐标偏移

GetImageY

int16_t GetImageY() const

功能说明

• 获取按钮图片的 Y 坐标偏移
• 该方法为 const，不修改对象状态
• 返回值为最近一次 SetImagePosition 设置的 Y 坐标

返回值

• 返回类型：int16_t

返回图片 Y 坐标偏移

返回值	触发场景
int16_t 值	当前图片 Y 坐标偏移

GetCurImageSrc

const Image* GetCurImageSrc() const

功能说明

• 获取当前按钮状态对应的图片资源指针
• 根据当前图片源状态（默认或触发）返回对应 Image 指针
• 该方法为 const，不修改对象状态

返回值

• 返回类型：const Image*

返回当前状态的图片指针

返回值	触发场景
非空指针	当前状态对应的 Image 对象
nullptr	未设置图片或图片源状态异常

GetWidth

int16_t GetWidth() override

功能说明

• 获取按钮内容区域宽度，扣除内边距与边框宽度
• 宽度计算基于当前按钮状态的样式
• 返回值为内容区域实际可用宽度

返回值

• 返回类型：int16_t

返回内容区域宽度

返回值	触发场景
int16_t 值	内容区域宽度（像素）

GetHeight

int16_t GetHeight() override

功能说明

• 获取按钮内容区域高度，扣除内边距与边框宽度
• 高度计算基于当前按钮状态的样式
• 返回值为内容区域实际可用高度

返回值

• 返回类型：int16_t

返回内容区域高度

返回值	触发场景
int16_t 值	内容区域高度（像素）

SetWidth

void SetWidth(int16_t width) override

功能说明

• 设置按钮宽度，同时更新内容宽度与视图宽度
• 宽度值同时应用于内容区域与整体视图
• 设置后自动触发视图重新布局

入参

名称	参数类型	详细说明	约束取值范围
width	int16_t	按钮宽度	int16_t 范围，大于 0

SetHeight

void SetHeight(int16_t height) override

功能说明

• 设置按钮高度，同时更新内容高度与视图高度
• 高度值同时应用于内容区域与整体视图
• 设置后自动触发视图重新布局

入参

名称	参数类型	详细说明	约束取值范围
height	int16_t	按钮高度	int16_t 范围，大于 0

GetContentRect

virtual Rect GetContentRect() override

功能说明

• 获取按钮内容区域的矩形信息，包含坐标与尺寸
• 矩形位置根据内边距和边框宽度偏移计算
• 返回的矩形坐标相对于按钮原始位置

返回值

• 返回类型：Rect

返回内容区域矩形

返回值	触发场景
Rect 对象	内容区域矩形，含坐标与尺寸信息

GetStyle

int64_t GetStyle(uint8_t key) const override

功能说明

• 获取当前样式操作状态下的样式值
• 实际委托 GetStyleForState，使用 styleState_ 确定状态
• 该方法为 const，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值	有效的 Style 键值

返回值

• 返回类型：int64_t

返回样式值

返回值	触发场景
int64_t 值	指定键对应的样式值
0	状态超出有效范围

SetStyle

void SetStyle(uint8_t key, int64_t value) override

功能说明

• 设置当前样式操作状态下的样式值
• 实际委托 SetStyleForState，使用 styleState_ 确定状态
• 首次设置时自动从主题样式拷贝并分配独立样式对象

入参

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

GetStyleForState

int64_t GetStyleForState(uint8_t key, ButtonState state) const

功能说明

• 获取指定按钮状态下的样式值
• 状态值需在有效范围内，否则返回 0
• 该方法为 const，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值	有效的 Style 键值
state	ButtonState	按钮状态	RELEASED(0) / PRESSED(1) / INACTIVE(2)

返回值

• 返回类型：int64_t

返回指定状态的样式值

返回值	触发场景
int64_t 值	指定状态与键对应的样式值
0	state 超出有效范围

SetStyleForState

void SetStyleForState(uint8_t key, int64_t value, ButtonState state)

功能说明

• 设置指定按钮状态下的样式值
• 首次调用时自动从主题样式拷贝并分配独立样式对象
• 设置后自动更新视图矩形信息

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值	有效的 Style 键值
value	int64_t	样式值	与 key 对应的有效值
state	ButtonState	按钮状态	RELEASED(0) / PRESSED(1) / INACTIVE(2)

Disable

void Disable()

功能说明

• 禁用按钮，将按钮状态设为 INACTIVE 并禁止触摸响应
• 禁用后按钮不再响应按压、释放、取消等触摸事件
• 禁用状态下按钮样式切换为 INACTIVE 对应样式

Enable

void Enable()

功能说明

• 启用按钮，将按钮状态恢复为 RELEASED 并恢复触摸响应
• 启用后按钮可正常响应按压、释放、取消等触摸事件
• 启用状态下按钮样式切换为 RELEASED 对应样式

SetStateForStyle

void SetStateForStyle(ButtonState state)

功能说明

• 设置样式操作的目标按钮状态
• 设置后调用 SetStyle 或 GetStyle 将作用于指定状态而非当前实际状态
• 不改变按钮的实际运行状态

入参

名称	参数类型	详细说明	约束取值范围
state	ButtonState	样式操作的目标状态	RELEASED(0) / PRESSED(1) / INACTIVE(2)

EnableButtonAnimation

void EnableButtonAnimation(bool enable)

功能说明

• 启用或禁用按钮按压/释放时的缩放动画效果
• 需在 DEFAULT_ANIMATION 宏开启时才可用
• 动画启用后，按压时按钮缩小至 0.8 倍，释放时恢复原始大小

入参

名称	参数类型	详细说明	约束取值范围
enable	bool	是否启用按钮动画	true(启用) / false(禁用)

Kconfig 配置

配置项	说明	默认值
DEFAULT_ANIMATION	按钮动画功能开关，控制 EnableButtonAnimation 接口与 OnPostDraw 动画绘制是否可用	-

Enumerations

ButtonImageSrc

enum ButtonImageSrc : uint8_t {
    BTN_IMAGE_DEFAULT = 0,
    BTN_IMAGE_TRIGGERED = 1,
    BTN_IMG_NUM = 2,
};

枚举成员	取值	描述
BTN_IMAGE_DEFAULT	0	默认状态图片
BTN_IMAGE_TRIGGERED	1	触发状态图片
BTN_IMG_NUM	2	图片源数量

ButtonState

enum ButtonState : uint8_t {
    RELEASED = 0,
    PRESSED = 1,
    INACTIVE = 2,
    BTN_STATE_NUM = 3,
};

枚举成员	取值	描述
RELEASED	0	释放状态
PRESSED	1	按压状态
INACTIVE	2	不可用状态
BTN_STATE_NUM	3	按钮状态总数