HarmonyOS 核心注解及示例代码详解

本文详细解析了HarmonyOS核心注解及其应用场景，涵盖组件开发、状态管理、生命周期和路由导航等关键功能。重点讲解了@Component（自定义组件）、@Entry（入口页面）、@State（组件状态）、@Prop/Link（父子组件通信）、@Provide/Consume（跨组件共享）等高频注解，每个注解均配有可运行的ArkTS示例代码。文章还介绍了纯血鸿蒙新增的@Router路由注解和@Ab

智江鹏

631人浏览 · 2026-02-25 11:31:08

智江鹏 · 2026-02-25 11:31:08 发布

你想了解鸿蒙（HarmonyOS Next/纯血鸿蒙）中核心注解的含义、使用场景，并需要每个注解搭配可运行的示例代码。我会按「高频核心注解」分类讲解，覆盖组件、状态管理、生命周期、路由等核心场景，示例均基于ArkTS/Stage模型，贴合纯血鸿蒙开发规范。

一、注解基础说明

鸿蒙中的注解（Decorator）以 @ 开头，是ArkTS的核心特性，用于修饰类、方法、属性，为代码赋予特定语义（如标记页面、管理状态、声明能力）。注解分为：

内置核心注解：框架提供，如@Entry、@Component；
自定义注解：开发者基于@Decorator自定义（进阶场景）。

本文重点讲解开发中必用的内置注解，每个注解包含「作用+使用场景+完整示例」。

二、核心注解分类讲解（附示例）

1. 组件相关注解（UI开发基础）

（1）`@Component` - 标记自定义组件

作用：声明一个可复用的UI组件，是所有自定义组件的基础注解。
使用场景：封装可复用的UI片段（如按钮、卡片、列表项）。
示例：

// 自定义组件：复用性按钮
@Component
struct CustomButton {
  // 组件属性（外部可传参）
  @Prop text: string = "默认按钮";
  @Prop color: string = "#07C160";

  build() {
    // 组件UI结构（必须实现build方法）
    Button(this.text)
      .backgroundColor(this.color)
      .width(200)
      .height(48)
      .borderRadius(24);
  }
}

// 页面中使用自定义组件
@Entry
@Component
struct Index {
  build() {
    Column() {
      // 传入自定义属性
      CustomButton({ text: "微信登录", color: "#07C160" });
      CustomButton({ text: "取消", color: "#999999" });
    }.justifyContent(FlexAlign.Center).width('100%').height('100%');
  }
}

（2）`@Entry` - 标记应用入口页面

作用：声明当前组件为「应用入口页面」（整个应用的根页面），必须配合@Component使用。
使用场景：应用启动后第一个显示的页面（如登录页、首页）。
示例：

// 入口页面：应用启动后直接显示
@Entry // 标记为入口页面
@Component
struct LoginPage {
  build() {
    Column() {
      Text("春游管理系统")
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .margin(30);
      // 引用自定义组件
      CustomButton({ text: "微信登录" });
    }.justifyContent(FlexAlign.Center).width('100%').height('100%');
  }
}

（3）`@Builder` - 标记UI构建函数

作用：封装可复用的UI片段（比@Component更轻量，无独立生命周期）。
使用场景：同一组件内复用少量UI代码（如标题栏、空数据提示）。
示例：

@Entry
@Component
struct HomePage {
  // 封装复用的标题栏
  @Builder TitleBar(title: string) {
    Row() {
      Text(title)
        .fontSize(22)
        .fontWeight(FontWeight.Bold);
    }
    .width('100%')
    .height(56)
    .padding(16)
    .backgroundColor("#FFFFFF");
  }

  build() {
    Column() {
      // 调用Builder函数
      this.TitleBar("首页");
      Text("春游行程列表")
        .margin(20);
    }.backgroundColor("#F5F5F5").width('100%').height('100%');
  }
}

（4）`@Styles` - 标记样式复用函数

作用：封装可复用的组件样式（如字体、颜色、边距），减少重复代码。
使用场景：统一页面内多个组件的样式（如所有文本的字体大小、颜色）。
示例：

@Entry
@Component
struct StyleDemo {
  // 封装文本样式
  @Styles TextNormal() {
    fontSize(16);
    color("#333333");
    margin(8);
  }

  // 封装按钮样式
  @Styles ButtonPrimary() {
    width(280);
    height(48);
    borderRadius(24);
    backgroundColor("#07C160");
  }

  build() {
    Column() {
      Text("春游注意事项")
        .TextNormal(); // 应用文本样式
      Text("1. 全程跟随队伍")
        .TextNormal();
      Button("确认已阅读")
        .ButtonPrimary(); // 应用按钮样式
    }.justifyContent(FlexAlign.Center);
  }
}

2. 状态管理注解（响应式核心）

状态注解是实现「数据驱动UI」的关键，数据变化时UI自动刷新。

（1）`@State` - 组件内私有状态

作用：声明组件内部的响应式状态，仅当前组件可修改，数据变化触发UI刷新。
使用场景：组件内的临时状态（如开关状态、输入框内容）。
示例：

@Entry
@Component
struct StateDemo {
  // 组件内私有状态：是否勾选同意协议
  @State isAgree: boolean = false;
  // 组件内私有状态：输入框内容
  @State inputText: string = "";

  build() {
    Column() {
      Input({ placeholder: "请输入姓名", text: this.inputText })
        .onChange((value) => {
          this.inputText = value; // 修改状态，UI自动刷新
        })
        .margin(10);

      Checkbox()
        .select(this.isAgree)
        .onChange((checked) => {
          this.isAgree = checked; // 修改状态
        })
      Text("同意春游协议")
        .fontSize(14);

      // 状态联动：勾选后按钮可用
      Button("提交")
        .disabled(!this.isAgree)
        .backgroundColor(this.isAgree ? "#07C160" : "#CCCCCC");
    }.padding(20);
  }
}

（2）`@Prop` - 父子组件单向传值

作用：子组件接收父组件的状态，仅能读取、不能修改（单向数据流）。
使用场景：父组件向子组件传递静态/动态数据（如按钮文本、卡片标题）。
示例：

// 子组件：接收父组件传值
@Component
struct ChildCard {
  @Prop title: string; // 单向接收父组件数据
  @Prop count: number;

  build() {
    Column() {
      Text(`标题：${this.title}`)
        .fontSize(18);
      Text(`人数：${this.count}`)
        .fontSize(14);
    }.padding(10).border({ width: 1, color: "#EEEEEE" }).margin(10);
  }
}

// 父组件：传递数据给子组件
@Entry
@Component
struct ParentPage {
  @State tourCount: number = 20; // 父组件状态

  build() {
    Column() {
      // 子组件接收父组件的状态
      ChildCard({ title: "春游报名", count: this.tourCount });

      // 父组件修改状态，子组件UI自动刷新
      Button("增加人数")
        .onClick(() => {
          this.tourCount++;
        });
    }
  }
}

（3）`@Link` - 父子组件双向绑定

作用：子组件与父组件共享状态，子组件可修改父组件的状态（双向数据流）。
使用场景：子组件需要修改父组件的状态（如弹窗的关闭状态、筛选条件）。
示例：

// 子组件：修改父组件状态
@Component
struct ChildDialog {
  @Link isShow: boolean; // 双向绑定父组件状态

  build() {
    if (this.isShow) {
      Dialog() {
        Column() {
          Text("确认取消报名吗？")
            .margin(20);
          Button("取消")
            .onClick(() => {
              this.isShow = false; // 子组件修改父组件状态
            });
        }
      }.show();
    }
  }
}

// 父组件
@Entry
@Component
struct ParentPage {
  @State isDialogShow: boolean = false;

  build() {
    Column() {
      Button("取消报名")
        .onClick(() => {
          this.isDialogShow = true; // 父组件修改状态
        });
      // 子组件双向绑定
      ChildDialog({ isShow: $isDialogShow }); // 注意：Link需要加$符号
    }
  }
}

（4）`@Provide` / `@Consume` - 跨组件状态共享

作用：跨层级组件（爷孙/远亲）共享状态，无需逐层传值（替代多层@Prop/@Link）。
使用场景：全局状态（如用户登录状态、主题色）。
示例：

// 根组件：提供状态（Provide）
@Entry
@Component
struct RootPage {
  @Provide("userName") userName: string = "未登录"; // 提供全局状态

  build() {
    Column() {
      Text(`当前用户：${this.userName}`)
        .margin(20);
      // 子组件（无需传值）
      MiddleComponent();
      // 修改全局状态
      Button("登录")
        .onClick(() => {
          this.userName = "小明";
        });
    }
  }
}

// 中间组件（无需处理状态）
@Component
struct MiddleComponent {
  build() {
    // 孙组件
    ChildComponent();
  }
}

// 孙组件：消费状态（Consume）
@Component
struct ChildComponent {
  @Consume("userName") userName: string; // 消费全局状态

  build() {
    Text(`欢迎${this.userName}参加春游`)
      .fontSize(16);
  }
}

3. 生命周期注解

（1）`@OnLifecycle` - 组件生命周期监听

作用：监听组件的生命周期（如aboutToAppear、onPageShow），替代直接写生命周期方法（更灵活）。
使用场景：拆分生命周期逻辑，提高代码可读性。
示例：

@Entry
@Component
struct LifeCycleDemo {
  // 监听页面即将显示
  @OnLifecycle(LifecycleConst.aboutToAppear)
  onAboutToAppear() {
    console.log("页面即将显示：初始化数据");
  }

  // 监听页面显示
  @OnLifecycle(LifecycleConst.onPageShow)
  onPageShow() {
    console.log("页面显示：刷新数据");
  }

  // 监听页面即将销毁
  @OnLifecycle(LifecycleConst.aboutToDisappear)
  onAboutToDisappear() {
    console.log("页面即将销毁：释放资源");
  }

  build() {
    Column() {
      Text("生命周期示例")
        .fontSize(20);
    }.justifyContent(FlexAlign.Center);
  }
}

4. 路由/导航注解

（1）`@Router` - 路由页面配置（纯血鸿蒙新增）

作用：声明页面的路由信息（路径、参数），简化路由跳转。
使用场景：配置页面路由，支持参数传递/接收。
示例：

// 页面1：配置路由并传递参数
@Entry
@Component
@Router({ path: "/pages/LoginPage" }) // 声明路由路径
struct LoginPage {
  build() {
    Column() {
      Button("跳转到首页")
        .onClick(() => {
          // 跳转并传递参数
          router.pushUrl({
            url: "/pages/HomePage",
            params: { userName: "小明", tourId: 1001 }
          });
        });
    }
  }
}

// 页面2：接收路由参数
@Entry
@Component
@Router({ path: "/pages/HomePage" })
struct HomePage {
  // 接收路由参数（纯血鸿蒙支持@State自动绑定）
  @State userName: string = "";
  @State tourId: number = 0;

  // 页面显示时读取参数
  onPageShow() {
    // 获取路由参数
    const params = router.getParams();
    this.userName = params.userName as string;
    this.tourId = params.tourId as number;
    console.log(`接收参数：${this.userName}，${this.tourId}`);
  }

  build() {
    Column() {
      Text(`欢迎${this.userName}，当前行程ID：${this.tourId}`)
        .fontSize(20);
    }
  }
}

5. 能力/服务注解（Stage模型）

（1）`@Ability` - 标记UIAbility

作用：声明一个UIAbility（应用的基本运行单元），纯血鸿蒙Stage模型核心注解。
使用场景：配置应用的能力（如入口Ability、后台Ability）。
示例：

// EntryAbility.ets
@Ability // 标记为UIAbility
export default class EntryAbility extends UIAbility {
  // Ability创建时触发
  onCreate(want, launchParam) {
    console.log("Ability创建：初始化应用");
  }

  // 窗口创建时触发
  onWindowStageCreate(windowStage) {
    // 加载入口页面
    windowStage.loadContent("pages/LoginPage");
  }

  // Ability销毁时触发
  onDestroy() {
    console.log("Ability销毁：释放全局资源");
  }
}

（2）`@Background` - 标记后台任务

作用：声明后台任务（如数据同步、消息推送），纯血鸿蒙新增。
使用场景：应用退到后台后仍需执行的任务（如春游行程提醒）。
示例：

// BackgroundTask.ets
@Background // 标记为后台任务
export default class TourReminderTask extends BackgroundTask {
  // 后台任务执行逻辑
  onStart() {
    console.log("后台任务启动：检查春游提醒");
    // 定时提醒逻辑
    setInterval(() => {
      console.log("提醒：明天9点春游集合");
    }, 3600000);
  }

  // 后台任务停止
  onStop() {
    console.log("后台任务停止");
  }
}

三、核心注解总结

注解	核心作用	关键特点
`@Component`	标记自定义组件	必须实现build方法，可复用
`@Entry`	标记入口页面	配合@Component，应用启动页
`@State`	组件内私有状态	数据驱动UI，仅当前组件可用
`@Prop`	父子单向传值	子组件只读，父组件修改
`@Link`	父子双向绑定	子组件可修改父组件状态（加$）
`@Provide/@Consume`	跨组件状态共享	无需逐层传值，全局共享
`@OnLifecycle`	生命周期监听	拆分生命周期逻辑，更灵活
`@Router`	路由页面配置	纯血鸿蒙新增，简化路由跳转
`@Ability`	标记UIAbility	Stage模型核心，应用运行单元

关键注意事项

状态注解（@State/@Prop/@Link）仅能修饰基本类型（string/number/boolean） 或可观察对象（如class实例）；
@Entry 只能修饰一个组件（应用唯一入口）；
纯血鸿蒙中@Router需配合main_pages.json路由配置使用；
注解的参数（如@Provide("userName")）需保持唯一，避免冲突。

如果需要针对「春游管理系统」场景（如微信登录页、行程列表页）定制注解使用示例，我可以补充更贴合业务的代码。

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

开源鸿蒙栏完整开发指南Flutter 实战｜自定义底部导航

人工智能6S服务平台

鸿蒙应用开发UI基础第三十九节：触摸事件与手势交互全解 - 从基础解析到实战演示

本文摘要：本文系统讲解了鸿蒙应用开发中的手势交互机制，主要内容包括：触摸事件底层原理，解析Down/Move/Up/Cancel事件流及其核心属性事件分发与冒泡机制，演示onTouch回调与stopPropagation拦截方法 6种基础手势的使用场景和触发规则 3种手势绑定方式的优先级差异及冲突解决方案组合手势实现复杂交互的方法手势异常问题的排查思路文章通过TouchBaseDemo

人工智能6S服务平台

鸿蒙NEXT原生AI智能家庭助手开发方案

本方案基于鸿蒙NEXT开发一款全场景智能家庭助手，实现以用户为中心的多设备协同交互。应用集成华为盘古大模型能力，通过鸿蒙智能体框架（HMAF）实现设备间的智能联动与任务调度，支持手机、智能手表、智慧屏、车载设备等多终端无缝协同，为用户提供自然、高效、智能的家庭生活体验。核心功能：语音交互、设备控制、场景管理、多设备协同技术亮点：鸿蒙智能体框架（HMAF）、盘古大模型端云协同、分布式软总线通信用户体