鸿蒙 ArkTS 高频装饰器速查表（含场景 + 代码模板）[2026-06-07]

这份表按「使用频率 + 功能」分类，附直接可复制的代码模板，覆盖你项目里 99% 的场景。

一、组件 / 页面基础定义（必用）

1.1 @Component

使用案例

@Component
struct MyButton {
 build () {  
    Button ("确认").width (100) 
   }
}

1.2 @Entry

使用案例

@Entry
@Component
struct NearLinkPage {
  build() { Column() { Text("页面") } }
}

1.3 @CustomDialog

使用案例

@CustomDialog
struct MyDialog {
  controller: CustomDialogController
  build() { Column() { Text("弹窗") } }
}

二、状态管理（你当前最常用，按场景排序）

2.1 @State

使用案例

// 定义nearLinkFlag
@State nearLinkFlag: boolean = false;

// 修改后自动刷新Text
this.nearLinkFlag = true;

2.2 @Watch

使用案例

@State nearLinkState: number = 0;
@Watch('nearLinkState')
onStateChange() {
  if (this.nearLinkState === 2) {
    AlertDialog.show({ title: "已连接" })
  }
}

2.3 @Prop

使用案例

// 子组件
@Component
struct Child {
  @Prop title: string; // 单向接收
}

// 父组件
Child({ title: "NearLink设置" })

2.4 @Link

使用案例

// 子组件
@Component
struct Child {
  @Link switchState: boolean;
}

// 父组件（必须用$传递）
Child({ switchState: $this.nearLinkFlag })

2.5 @Provide / @Consume

使用案例

// 祖先组件
@Provide nearLinkGlobalState: boolean = false;

// 任意后代组件
@Consume nearLinkGlobalState: boolean;

2.6 @Observed + @ObjectLink

使用案例

// 1. 标记对象为可观察
@Observed
class NearLinkDevice {
  name: string = "";
  connected: boolean = false;
}

// 2. 子组件接收
@Component
struct DeviceItem {
  @ObjectLink device: NearLinkDevice;
}

三、UI 复用与样式（提升开发效率）

3.1 @Builder

使用案例

@Builder
StatusText(flag: boolean) {
  Text(flag ? "已开启" : "已关闭")
    .fontColor(flag ? "#0088ff" : "#ff0000")
}

// 使用：直接在build里调用
this.StatusText(this.nearLinkFlag)

3.2 @Styles

使用案例

@Styles
commonButton() {
  .width(120)
  .height(44)
  .borderRadius(8)
  .backgroundColor("#0088ff")
}

// 使用：直接链式调用
Button("确认").commonButton()

3.3 @Styles

使用案例

// 子组件
@Component
struct Card {
  @BuilderParam content: () => void;
  build() { Column() { this.content() } }
}

// 父组件使用
Card() {
  Text("自定义内容").fontSize(20)
}

3.4 @Extend

使用案例

@Extend(Button)
function primaryBtn() {
  .width(100)
  .backgroundColor("#0088ff")
}

// 使用：直接调用扩展方法
Button("提交").primaryBtn()

四、全局/页面级存储（跨组件共享数据）

4.1 @StorageLink

使用案例

// 全局存储，读写
@StorageLink('isDarkMode') isDark: boolean = false;

// 修改后所有使用该key的组件同步更新
this.isDark = true;

4.2 @StorageProp

使用案例

@StorageProp('appVersion') version: string = "1.0.0";

4.3 @LocalStorageLink

使用案例

// 页面根组件初始化
let pageStorage: LocalStorage = new LocalStorage();

// 页面内组件
@LocalStorageLink('pageState') pageState: number = 0;

五、其他高频辅助装饰器

5.1 @Preview

使用案例

@Preview
@Entry
@Component
struct IndexPage { ... }

5.2 @Reusable

使用案例

@Reusable
@Component
struct ListItem { ... }

总结

快速选型指南（帮你选对装饰器）

1. 组件内用：优先 @State + @Watch
2. 父子传值：只读用 @Prop，需要双向修改用 @Link
3. 跨多层组件共享：用 @Provide / @Consume
4. 对象/数组状态：用 @Observed + @ObjectLink
5. 重复UI/样式：用 @Builder / @Styles