ui_checkbox

ui_checkbox 模块提供复选框组件，支持勾选状态切换与状态变化事件监听。

Class Summary

OHOS::UICheckBox

复选框组件，允许用户进行二选一操作

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取组件类型
  SetOnChangeListener	设置复选框状态变化监听器
  OnPreDraw	绘制前判断是否需要覆盖无效区域
  OnDraw	执行复选框绘制
  OnClickEvent	处理点击事件，切换复选框选中状态
  SetImages	设置复选框选中与未选中状态的图片资源
  GetState	获取复选框当前状态
  SetState	设置复选框状态
  SetSelectedStateColor	设置选中状态的颜色
  GetSelectedStateColor	获取选中状态的颜色

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

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_checkbox.h
• 公有运算符：无
• 继承关系：UIView, AnimatorCallback（DEFAULT_ANIMATION 开启时）；UIView（DEFAULT_ANIMATION 关闭时）
• 嵌套类型：OnChangeListener, UICheckBoxState
• 模板形参：无

OHOS::UICheckBox::OnChangeListener

复选框状态变化监听器抽象类，提供状态变更回调接口

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnChange	复选框状态变更时的纯虚回调函数

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

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

Functions

OHOS::UICheckBox

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前组件的类型标识
• 设计目的：区分 UI 组件类型，供 UI 框架进行组件识别与分发
• 使用场景：UI 框架遍历组件树时识别复选框组件

返回值

• 返回类型：UIViewType

返回组件类型标识

返回值	触发场景
UI_CHECK_BOX	当前组件为复选框

SetOnChangeListener

void SetOnChangeListener(OnChangeListener* onStateChangeListener)

功能说明

• 核心用途：设置复选框状态变化监听器
• 设计目的：当复选框选中状态发生变更时，触发监听器回调通知调用方
• 使用场景：业务逻辑需要响应复选框状态变化的场景

入参

名称	参数类型	详细说明	约束取值范围
onStateChangeListener	OnChangeListener*	入参指针，状态变化监听器对象，可为 nullptr 表示取消监听	nullptr 或有效的 OnChangeListener 派生类实例指针

OnPreDraw

bool OnPreDraw(Rect& invalidatedArea) const override

功能说明

• 核心用途：绘制前判断当前视图是否需要覆盖无效区域
• 设计目的：供渲染管理器决定绘制层级顺序
• 使用场景：UI 框架绘制流程中的预处理阶段

入参

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

返回值

• 返回类型：bool

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

返回值	触发场景
false(0)	复选框不需要覆盖无效区域

OnDraw

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

功能说明

• 核心用途：执行复选框的绘制操作
• 设计目的：根据复选框当前选中状态绘制对应的外观
• 使用场景：UI 框架渲染流程中绘制复选框组件

入参

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

OnClickEvent

bool OnClickEvent(const ClickEvent& event) override

功能说明

• 核心用途：处理复选框的点击事件，切换选中与未选中状态
• 设计目的：用户点击复选框时自动反转选中状态
• 使用场景：用户交互点击复选框时由 UI 框架触发

入参

名称	参数类型	详细说明	约束取值范围
event	const ClickEvent&	入参只读引用，点击事件对象	有效的 ClickEvent 对象引用

返回值

• 返回类型：bool

返回事件是否被消费

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

SetImages

virtual void SetImages(const char* selectedImageSrc, const char* unselectedImageSrc)

功能说明

• 核心用途：通过图片文件路径设置复选框选中与未选中状态的图片资源
• 设计目的：支持自定义复选框外观，替换默认绘制样式
• 使用场景：需要使用自定义图片替代默认复选框外观

入参

名称	参数类型	详细说明	约束取值范围
selectedImageSrc	const char*	入参指针，选中状态的图片文件路径	有效的图片资源路径字符串，可为 nullptr
unselectedImageSrc	const char*	入参指针，未选中状态的图片文件路径	有效的图片资源路径字符串，可为 nullptr

SetImages

virtual void SetImages(const ImageInfo* selectedImageSrc, const ImageInfo* unselectedImageSrc)

功能说明

• 核心用途：通过 ImageInfo 指针设置复选框选中与未选中状态的图片资源
• 设计目的：支持使用内存中的图片信息设置自定义复选框外观
• 使用场景：图片资源已加载到内存中，需通过 ImageInfo 指针引用

入参

名称	参数类型	详细说明	约束取值范围
selectedImageSrc	const ImageInfo*	入参只读指针，选中状态的图片信息	有效的 ImageInfo 对象指针，可为 nullptr
unselectedImageSrc	const ImageInfo*	入参只读指针，未选中状态的图片信息	有效的 ImageInfo 对象指针，可为 nullptr

GetState

UICheckBoxState GetState() const

功能说明

• 核心用途：获取复选框当前的选中状态
• 设计目的：供外部查询复选框状态
• 使用场景：业务逻辑需要读取复选框当前是选中还是未选中

返回值

• 返回类型：UICheckBoxState

返回复选框当前状态

返回值	触发场景
SELECTED(0)	复选框处于选中状态
UNSELECTED(1)	复选框处于未选中状态

SetState

void SetState(UICheckBoxState state, bool needAnimater = false)

功能说明

• 核心用途：设置复选框的选中状态
• 设计目的：支持程序化设置复选框状态，可选择是否启用动画过渡
• 使用场景：业务逻辑需要主动设置复选框状态（非用户点击触发）

入参

名称	参数类型	详细说明	约束取值范围
state	UICheckBoxState	入参，目标选中状态	SELECTED(0), UNSELECTED(1)
needAnimater	bool	入参，是否启用状态切换动画，需 DEFAULT_ANIMATION 为 1 时生效	false(默认), true

SetSelectedStateColor

void SetSelectedStateColor(ColorType color)

功能说明

• 核心用途：设置复选框选中状态的背景颜色
• 设计目的：支持自定义选中状态的视觉外观
• 使用场景：需要修改复选框选中状态的默认颜色

入参

名称	参数类型	详细说明	约束取值范围
color	ColorType	入参，选中状态的颜色值	有效的 ColorType 颜色值

GetSelectedStateColor

ColorType GetSelectedStateColor() const

功能说明

• 核心用途：获取复选框选中状态的背景颜色
• 设计目的：供外部查询当前选中状态颜色的配置
• 使用场景：需要读取复选框选中状态的颜色值

返回值

• 返回类型：ColorType

返回选中状态的颜色值

返回值	触发场景
ColorType	当前选中状态的颜色值

OHOS::UICheckBox::OnChangeListener

OnChange

virtual bool OnChange(UICheckBoxState state) = 0

功能说明

• 核心用途：复选框状态变更时的回调函数，纯虚函数需派生类实现
• 设计目的：当复选框选中状态发生切换时通知监听者
• 使用场景：业务逻辑继承 OnChangeListener 并实现此方法以响应状态变化

入参

名称	参数类型	详细说明	约束取值范围
state	UICheckBoxState	入参，变更后的复选框状态	SELECTED(0), UNSELECTED(1)

返回值

• 返回类型：bool

返回状态变更回调的处理结果

返回值	触发场景
true(1)	状态变更被接受
false(0)	状态变更被拒绝

Enumerations

UICheckBoxState

enum UICheckBoxState : uint8_t {
    SELECTED,
    UNSELECTED,
    MAX_STATUS_NUM,
};

枚举成员	取值	描述
SELECTED	0	选中状态
UNSELECTED	1	未选中状态
MAX_STATUS_NUM	2	状态数量上限，非业务状态值