从 Qt 角度理解 ArkUI 的控件方法

ArkUI组件回调函数属性详解

本文档从 Qt 开发者的角度详细介绍 ArkUI 中组件回调函数属性的使用方法，通过对比分析帮助 Qt 开发者快速理解 ArkUI 的组件开发模式。

Qt vs ArkUI 深度对比

从 Qt 开发者的角度来理解 @ComponentV2，可以把它类比为 Qt 中的 QWidget 或 QObject 的概念：

1. 组件声明对比

Qt 中的自定义 Widget：

class MyWidget : public QWidget {
    Q_OBJECT
public:
    explicit MyWidget(QWidget *parent = nullptr);
};

ArkUI 中的自定义组件：

@ComponentV2
export struct Init {
    @Param onPresentMainPage?: () => void = undefined;
}

2. 功能对应关系

Qt概念	ArkUI概念	作用
Q_OBJECT	@ComponentV2	启用框架特性
Q_PROPERTY	@Param/@State	属性声明
signals/slots	回调函数	事件通信
paintEvent()	build()	渲染方法
构造函数	aboutToAppear()	初始化

3. 具体类比

Qt 的 Q_OBJECT 宏：

• 启用信号槽机制
• 提供运行时类型信息(RTTI)
• 支持属性系统和反射
• 启用元对象编译器(MOC)

ArkUI 的 @ComponentV2 装饰器：

• 启用组件生命周期管理
• 提供状态管理和数据绑定
• 支持参数传递和事件处理
• 启用ArkUI编译器优化

4. 参数传递对比

Qt 属性系统：

class MyWidget : public QWidget {
    Q_OBJECT
    Q_PROPERTY(QString title READ title WRITE setTitle)
public:
    QString title() const { return m_title; }
    void setTitle(const QString &title) { m_title = title; }
private:
    QString m_title;
};

ArkUI 参数系统：

@ComponentV2
export struct Init {
    @Param onPresentMainPage?: () => void = undefined;
    @Param onPresentUserPrivacyPage?: (version: number) => void = undefined;
}

5. 生命周期对比

Qt Widget 生命周期：

• 构造函数 → showEvent() → paintEvent() → closeEvent() → 析构函数

ArkUI 组件生命周期：

• 创建 → aboutToAppear() → build() → aboutToDisappear() → 销毁

6. 实际使用场景

就像在 Qt 中你需要继承 QWidget 并添加 Q_OBJECT 宏来创建自定义控件一样，在 ArkUI 中你需要使用 @ComponentV2 装饰器来创建自定义组件。

核心理解：

• @ComponentV2 = Qt 的 Q_OBJECT 宏
• 都是告诉框架"这是一个特殊的类，请启用框架的高级特性"
• 都提供了属性系统、事件处理和生命周期管理
• 都是各自框架中创建可复用UI组件的标准方式

简单来说，@ComponentV2 就是 ArkUI 版本的 Q_OBJECT，它让普通的 struct 变成了具有完整框架支持的 UI 组件。

ArkUI 组件回调函数属性详解

基于上述对比理解，我们以 Init 组件为例详细说明 ArkUI 中 @Param 装饰器的应用。

概述

onPresentUserPrivacyPage 和 onPresentMainPage 是 Init 组件的回调函数属性，使用 @Param 装饰器声明。

属性定义

@Param onPresentMainPage?: () => void = undefined;
@Param onPresentUserPrivacyPage?: (version: number) => void = undefined;

属性特性

1. @Param 装饰器

• 组件参数：由父组件传入的回调函数
• 可选属性：使用?标记，可以不传入
• 默认值：初始值为undefined

2. 函数签名

onPresentMainPage

• 类型：() => void
• 作用：无参数的回调函数
• 用途：通知父组件跳转到主页面

onPresentUserPrivacyPage

• 类型：(version: number) => void
• 作用：接收版本号参数的回调函数
• 用途：通知父组件显示隐私政策页面

实际使用场景

在aboutToAppear()生命周期中：

aboutToAppear(): void {
  executeInitializeTasks(context).then(() => {
    if (this.upstreamPrivacyVersion !== undefined) {
      // 调用隐私页面回调，传入版本号
      this.onPresentUserPrivacyPage?.(this.upstreamPrivacyVersion);
    } else {
      // 调用主页面回调
      this.onPresentMainPage?.();
    }
  });
}

设计模式

这是典型的回调模式(Callback Pattern)：

• 解耦合：Init 组件不直接处理页面跳转逻辑
• 职责分离：Init 负责初始化，父组件负责导航
• 灵活性：父组件可以自定义跳转行为

类比理解

类似于 Qt 中的信号槽机制：

• Init 组件发出"初始化完成"信号
• 父组件接收信号并执行相应的槽函数
• 实现了组件间的松耦合通信

总结

这两个属性本质上是事件处理器，让 Init 组件能够通知父组件执行不同的页面跳转操作。通过回调函数的方式，实现了组件间的优雅通信和职责分离。