【鸿蒙开发】ArkTS 装饰器全解析：从 @Entry 到 @Observed 的全面指南

本文将带你系统理解鸿蒙应用开发中 ArkTS 装饰器（Decorator） 的用法和关系。无论你是刚接触 HarmonyOS 的新手，还是准备深入掌握 ArkUI 框架的开发者，都可以通过这篇文章梳理一遍思路。

---

一、ArkTS 简介

HarmonyOS（鸿蒙）是华为面向全场景的操作系统，而 ArkTS（Ark TypeScript）是它的官方应用开发语言。ArkTS 基于 TypeScript 扩展而来，具备以下特性：

• 声明式 UI：UI 由状态驱动，类似 React、Vue。
• 装饰器语法：通过 @Entry、@State 等装饰器，标记组件和状态。
• 原生系统能力：直接调用鸿蒙设备 API（相机、蓝牙、传感器等）。

你可以把 ArkTS 看成「TypeScript + 鸿蒙专用语法」。

---

二、为什么需要装饰器？

在 ArkTS 中，装饰器（Decorator）承担了 声明 UI 组件、管理状态、传递数据 等关键作用。它们让开发者通过简洁的标记，告诉框架某个变量、组件应该如何运行和渲染。

如果说 ArkTS 的灵魂是声明式 UI，那么 装饰器就是驱动 UI 的引擎。

---

三、常见装饰器详解

1. 组件相关

• @Entry

  • 定义应用的入口页面，全局唯一。
  • 相当于「main 函数」。

• @Component

  • 声明一个 UI 组件，可被复用或被引用。
  • 相当于 React 的函数组件。

@Entry
@Component
struct Index {build() {Column() {Text("Hello ArkTS")}}
}

2. 状态管理相关

• @State
  定义组件内部状态，变化时会触发 UI 自动刷新。

@State count: number = 0;

• @Prop
  父组件传入的属性，子组件只读。

@Prop title: string;

• @Link
  父子组件之间的双向绑定，子组件可修改并影响父组件。

@Link count: number;

• @Provide / @Consume
  用于跨层级共享数据，类似 React Context。

@Provide theme: string = "dark";
@Consume theme: string;

• @Observed
  将类对象变为响应式，属性更新时 UI 自动刷新。
• @ObjectLink
  子组件对 @ObjectLink 对象的双向绑定。

3. 存储相关

• @StorageProp：全局存储，组件只读。

• @StorageLink：全局存储，组件可读写。

• @LocalStorageProp：局部存储（只读）。

• @LocalStorageLink：局部存储（读写）。

这些装饰器适合存储用户 ID、语言偏好、主题模式等全局配置。

4. 样式与开发辅助

• @Styles：定义可复用样式。

• @Extend：扩展已有组件。

• @Preview：在 DevEco Studio 中预览页面。

四、典型的数据流动

入口组件 → 子组件 → 全局存储 → 响应式对象

数据在 ArkTS 中呈现 自上而下传递，状态驱动 UI，响应式刷新的模式。

五、完整示例：计数器 App

// 入口组件
@Entry
@Component
struct Index {@State count: number = 0;build() {Column() {Text(`计数：${this.count}`).fontSize(20)MyButton({ value: $count }) // 使用 @Link 传递状态}}
}// 子组件
@Component
struct MyButton {@Link value: number;build() {Button(`点击 +1 (${this.value})`).onClick(() => {this.value += 1; // 会影响父组件的 count})}
}

六、ArkTS vs React/Vue 对比

特性	React	Vue	ArkTS
UI 声明	JSX	模板 + 指令	ArkTS 装饰器
状态管理	Hooks	响应式 data	@State / @Link
跨层级传递	Context API	Provide/Inject	@Provide / @Consume
存储支持	依赖第三方库	Vuex/Pinia	内置 StorageProp/Link
系统能力	依赖原生桥接	依赖插件	原生支持 HarmonyOS API

七、总结

1. ArkTS 装饰器是 HarmonyOS 应用开发的核心语法。

2. @Entry 定义入口，@Component 定义 UI 单元。

3. @State、@Prop、@Link 负责父子关系的数据传递。

4. @Storage* 与 @Provide/@Consume 扩展到全局/跨层级共享。

5. @Observed / @ObjectLink 让复杂对象也具备响应式能力。

「ArkTS 装饰器速查表」（Cheat Sheet）

装饰器	作用	使用场景
@Entry	声明应用入口组件（全局唯一）	应用启动页
@Component	声明一个 UI 组件	普通页面或自定义组件
@State	组件内部状态，变更触发 UI 更新	计数器、开关等局部状态
@Prop	父组件传入的属性（只读）	父传子单向数据
@Link	父子组件双向绑定	父子共享、可修改状态
@Provide	祖先组件提供数据	主题、语言等全局上下文
@Consume	后代组件消费数据	获取祖先组件提供的值
@Observed	定义响应式类对象，属性变化自动刷新	用户对象、数据模型
@ObjectLink	子组件双向绑定响应式对象	操作父组件传入的对象
@StorageProp	从全局存储读取只读属性	用户 ID、配置常量
@StorageLink	从全局存储读写共享数据	登录状态、语言选择
@LocalStorageProp	局部存储只读属性	页面内局部状态共享
@LocalStorageLink	局部存储可读写数据	页面内共享变量
@Styles	定义复用样式	统一 UI 风格
@Extend	扩展已有组件	定制化样式组件
@Preview	IDE 预览页面	DevEco Studio UI 调试

---

Tips

1. 最常用组合：@State（局部状态） + @Link（父子双向绑定）。
2. 跨组件通信：用 @Provide / @Consume 替代繁琐的层层传参。
3. 全局数据：用 @StorageLink 直接挂载到全局存储，避免重复管理。
4. 复杂对象：用 @Observed + @ObjectLink，让对象也能响应式更新。