鸿蒙 @Event装饰器：函数传递

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、核心概述

@Event是ArkUI状态管理V2中用于规范组件输出的特殊装饰器，专门处理子组件向父组件传递事件和数据的场景。它与@Param装饰器配合使用，实现数据的双向同步和组件间的规范通信。

核心特性：

• 输出规范化：明确标识组件对外输出的方法
• 回调机制：通过回调函数实现父子组件通信
• 双向同步支持：与@Param配合实现数据双向流动
• 类型安全：支持 TypeScript 类型约束

二、装饰器说明

2.1 基本属性

属性	说明
装饰器参数	无
允许装饰的变量类型	回调方法：()=>void、(param: Type)=>ReturnType 等
允许传入的函数类型	箭头函数、方法引用
使用条件	必须用在 @ComponentV2 装饰的自定义组件中

2.2 版本支持

• 从API version 12开始支持
• 支持在元服务中使用
• 需要配合 @ComponentV2 使用

三、工作原理

3.1 与@Param的协同机制

@Event装饰器主要解决@Param装饰变量的更新问题：

• @Param变量不能在组件内部直接修改
• @Event提供规范的回调机制来更新数据源
• 通过@Local的同步机制将修改同步回@Param变量

3.2 通信流程

子组件 @Event 回调 → 父组件处理方法 → 更新数据源 → 同步到 @Param 变量

四、使用示例

4.1 基本用法

@ComponentV2
struct UserInputComponent {
  // 定义事件回调
  @Event onUsernameChange: (newName: string) => void = (newName: string) => {};
  @Event onSaveRequest: () => boolean = () => false;
  
  @Local private tempUsername: string = '';
  
  build() {
    Column() {
      TextInput({ text: this.tempUsername })
        .onChange((value) => {
          this.tempUsername = value;
          // 触发事件回调
          this.onUsernameChange(value);
        })
      
      Button('保存')
        .onClick(() => {
          const result = this.onSaveRequest();
          if (result) {
            // 保存成功处理
          }
        })
    }
  }
}

4.2 父组件中使用

@Entry
@Component
struct ParentComponent {
  @State userData: UserProfile = new UserProfile('初始用户');
  
  // 处理用户名变更 - 使用箭头函数
  private handleUsernameChange = (newName: string): void => {
    this.userData.username = newName;
    console.log(`用户名更新为: ${newName}`);
  }
  
  // 处理保存请求 - 使用箭头函数
  private handleSaveRequest = (): boolean => {
    if (this.userData.isValid()) {
      this.userData.saveToDatabase();
      return true;
    }
    return false;
  }
  
  build() {
    Column() {
      UserInputComponent({
        onUsernameChange: this.handleUsernameChange, 
        onSaveRequest: this.handleSaveRequest        
      })
      
      Text(`当前用户名: ${this.userData.username}`)
        .fontSize(20)
        .margin(10)
    }
  }
}

五、注意事项

• 只能在 @ComponentV2 装饰的组件中使用
• 只能装饰回调函数类型的变量
• 需要与父组件的方法签名严格匹配
• 当@Event没有初始化时，会自动生成一个空的函数作为默认回调
• 使用@Event修改父组件的值是立刻生效的，从父组件将变化同步回子组件的过程是异步的