鸿蒙开发中所有自定义装饰器的完整案例解析--涵盖 16 个核心装饰器的详细用法和实战场景

以下是鸿蒙开发中 所有自定义装饰器的完整案例解析 和 终极总结指南，涵盖 16 个核心装饰器的详细用法和实战场景：

---

一、终极总结表：16大装饰器全景图

装饰器	类别	V1	V2	核心作用	典型场景
@Component	组件定义	✅	❌	创建标准组件	业务UI组件
@ComponentV2	组件定义	❌	✅	创建可继承组件	UI框架基类
@State	状态管理	✅	✅	组件私有状态	计数器、开关状态
@Local	状态管理	❌	✅	V2组件状态（可继承）	可继承的基类状态
@Prop	状态管理	✅	✅	父→子单向同步	接收父组件数据
@Param	状态管理	❌	✅	V2父→子传参（可继承）	可继承的组件参数
@Link	状态管理	✅	✅	父子双向绑定	表单控件
@Provide	状态管理	✅	✅	跨层级提供数据	主题、配置下发
@Consume	状态管理	✅	✅	跨层级消费数据	获取祖先数据
@Builder	UI构建	✅	✅	定义UI片段	复用UI组合
@BuilderParam	UI构建	✅	✅	声明动态插槽	可配置布局容器
@Styles	UI构建	✅	✅	复用样式集	统一按钮/卡片样式
@Extend	UI构建	✅	✅	扩展原生组件样式	定制系统组件
@Reusable	性能优化	✅	❌	V1组件实例复用	弹窗/高频切换组件
@ReusableV2	性能优化	❌	✅	V2组件实例复用	长列表项
@Watch	辅助	✅	✅	监听状态变化	数据变化回调
@Computed	辅助(V2专属)	❌	✅	声明计算属性	购物车总价

---

二、组件定义装饰器

1. @Component (标准组件)

@Component
struct UserCard {
@Prop name: string = "张三"

build() {
Column() {
Text(this.name).fontSize(18)
Text("前端开发工程师")
}
}
}

作用：定义可复用的 UI 组件单元

---

2. @ComponentV2 (实验性组件)

// @ts-nocheck
@ComponentV2
export struct BaseDialog {
@Local title: string = "系统提示" // V2专属状态

build() {
Column() {
Text(this.title).fontColor(Color.Red)
this.DialogContent() // 抽象插槽
}
}

@BuilderParam DialogContent: () => void = () => Text("默认内容")
}

// 继承基类
@Component
struct ConfirmDialog extends BaseDialog {
@Param message: string // V2专属传参

@BuilderParam override DialogContent: () => void = () => {
Text(this.message)
Button("确认")
}
}

突破能力：组件继承、状态继承、方法重写

---

三、状态管理装饰器

3. @State (组件私有状态)

@State count: number = 0

Button(`点击 ${this.count}`)
.onClick(() => this.count++) // 触发UI更新

4. @Local (V2 组件状态)

@ComponentV2
struct Counter {
@Local value: number = 0 // 可被子组件继承

build() { ... }
}

5. @Prop (父→子单向同步)

// 子组件
@Component
struct Child {
@Prop data: string // 接收父组件数据
}

// 父组件
Parent() {
Child({ data: parentData }) // 传递数据
}

6. @Param (V2 单向传参)

@ComponentV2
struct ChildV2 {
@Param message: string // 支持继承
}

7. @Link (父子双向绑定)

// 子组件
@Component
struct Toggle {
@Link isOn: boolean // 双向绑定
}

// 父组件
@State switchState: boolean = false
Toggle({ isOn: $switchState }) // $表示双向绑定

8. @Provide/@Consume (跨层级通信)

// 祖先组件
@Component
struct GrandParent {
@Provide theme: string = "dark"
}

// 子孙组件（跳过中间层）
@Component
struct Child {
@Consume theme: string // 直接获取祖先数据
}

---

四、UI构建装饰器

9. @Builder (UI片段复用)

@Builder function fancyButton(text: string) {
Button(text)
.backgroundColor('#6200EE')
.fontColor(Color.White)
}

// 使用
fancyButton("提交")

10. @BuilderParam (动态插槽)

@Component
struct Card {
@BuilderParam header: () => void

build() {
Column() {
this.header() // 动态渲染传入的UI
}
}
}

// 注入内容
Card({ header: () => Text("标题").fontSize(20) })

11. @Styles (样式复用)

@Styles function warningStyle() {
.backgroundColor('#FFF8E1')
.borderColor('#FFD740')
}

Text("警告信息")
.warningStyle() // 应用样式集

12. @Extend (扩展原生样式)

@Extend(Text) function titleStyle() {
.fontSize(24)
.fontWeight(FontWeight.Bold)
}

Text("章节标题")
.titleStyle() // 扩展原生组件

---

五、缓存复用装饰器

13. @Reusable (V1组件缓存)

@Reusable
@Component
struct ExpensiveComponent {
aboutToReuse(params: Object) {
console.log("复用实例", params)
}
}

// 使用
ExpensiveComponent().reuseId("comp-1")

14. @ReusableV2 (V2组件缓存)

@ReusableV2
@ComponentV2
struct V2Component {
aboutToReuse() { /* 无参数 */ }
aboutToRecycle() { /* 回收回调 */ }
}

// 必须指定reuseId
V2Component().reuse({ reuseId: () => 'v2-comp' })

---

六、辅助装饰器

15. @Watch (状态监听)

@State counter: number = 0

@Watch('counter')
onCountChange(newValue: number, oldValue: number) {
console.log(`值变化：${oldValue} → ${newValue}`)
}

16. @Computed (计算属性-V2专属)

@ComponentV2
struct Cart {
@State items: Item[] = []

@Computed
get totalPrice(): number {
return this.items.reduce((sum, item) => sum + item.price, 0)
}
}

---

七、三大黄金实践法则

法则1：装饰器选型决策树

graph TD A[开发组件类型] --> B{是否需继承？} B -->|是| C[用@ComponentV2+@Local] B -->|否| D[用@Component] D --> E{是否高频创建？} E -->|是| F[添加@Reusable] E -->|否| G[标准实现] C --> H{是否需缓存？} H -->|是| I[添加@ReusableV2]

法则2：状态管理三原则

1. 数据流向：

• 单向数据流：父 → @Prop → 子
• 双向同步：父 ↔ @Link ↔ 子

2. 层级穿透：

• 跨层级：祖先 @Provide → 子孙 @Consume

3. V2优先：

• 继承场景：@Local > @State，@Param > @Prop

法则3：性能优化组合拳

场景	优化方案	效果提升
长列表	@ReusableV2 + LazyForEach	滚动帧率提升 300%
高频显示/隐藏	@Reusable + reuseId	切换耗时降低 80%
复杂计算	@Computed + 缓存策略	计算耗时减少 70%
样式复用	@Styles + @Extend	代码量减少 60%

---

八、避坑指南（血泪经验）

1. TS兼容问题：

// 在V2组件文件顶部添加
// @ts-nocheck

2. 装饰器冲突：

• ❌ 禁止混用 @State 和 @Local
• ❌ 避免同时使用 @Prop 和 @Param

3. 缓存陷阱：

// 错误！每次创建新ID导致无法复用
.reuse({ reuseId: () => Date.now().toString() })

// 正确：相同类型组件使用固定ID
.reuse({ reuseId: () => 'user-card' })

4. V2组件限制：

• 不可在 @ComponentV2 中使用 @StorageProp
• 禁止跨 V1/V2 组件继承

---

九、演进路线图（2025）

1. Q1：

• @ComponentV2 结束实验阶段
• @Computed 支持 V1 组件

2. Q2：

• 新增 @Mixin 混入装饰器
• 推出 @Animate 动画装饰器

3. Q3：

• 统一 V1/V2 状态管理模型
• 废弃 @Local 和 @Param

官方资源：

• ArkUI 装饰器文档

掌握这些装饰器组合用法，可大幅提升鸿蒙开发效率和性能表现。建议从 @Component + @Prop + @Builder 基础组合起步，逐步探索高级用法。