鸿蒙修饰符

一、弁言

在HarmonyOS（鸿蒙）应用开辟中，修饰符（Decorator）是一个极其紧张的概念。它们不光可以或许简化开辟过程，还能提供强盛的功能扩展性。本文将深入探究鸿蒙中的各类修饰符，资助开辟者更好地明白和使用这些工具。本文紧张先容@Styles，@Extend，@Builder，@Component，@BuilderParam，@State，@Prop，@Link，@Provide，@Watch，@Observed等等。
   1.1 什么是修饰符

修饰符是一种特殊的语法元素，用@符号作为标识，可以用来修饰类、方法、属性等代码元素，为其添加额外的举动或特性。在鸿蒙开辟中，修饰符紧张用于以下几个方面：

• UI样式界说和复用
  
• 组件声明和管理
  
• 状态管理和数据同步
  
• 组件间通讯
  

1.2 修饰符在鸿蒙开辟中的紧张性

1.3 修饰符的作用机制

修饰符在编译时会被转换为特定的代码，它们紧张通过以下机制发挥作用：

• 装饰器模式: 在不改变原有代码结构的环境下，动态地给对象添加新的功能
  
• 编译时转换: 将声明式的代码转换为下令式代码
  
• 运行时注入: 在运行时为目的对象注入额外的举动
  

二、UI装饰类修饰符

   2.1 @Styles修饰符

2.1.1 根本概念和使用场景

@Styles修饰符用于界说可复用的样式聚集，类似于Web开辟中的CSS类。它可以：

• 提取共同样式，实现复用
  
• 保持代码整洁
  
• 同一管理样式
  

2.1.2 使用示例

1. // 定义全局样式
2. @Styles function globalStyles() {
3.   .width('100%')
4.   .height(100)
5.   .backgroundColor('#f5f5f5')
6.   .padding(20)
7. }
9. // 使用样式
10. @Entry
11. @Component
12. struct StylesDemo {
13.   build() {
14.     Column() {
15.       Text('Hello')
16.         .fontSize(20)
17.         .globalStyles()
18.       
19.       Text('World')
20.         .fontSize(16)
21.         .globalStyles()
22.     }
23.   }
24. }

复制代码

2.1.3 最佳实践

样式分类管理

1. // 按功能分类样式
2. @Styles function cardStyles() {
3.   .width('100%')
4.   .padding(15)
5.   .borderRadius(8)
6.   .backgroundColor(Color.White)
7. }
9. @Styles function buttonStyles() {
10.   .width(120)
11.   .height(40)
12.   .borderRadius(20)
13.   .backgroundColor('#007DFF')
14. }

复制代码

2.2 @Extend修饰符

2.2.1 根本概念

@Extend用于扩显现有组件的样式和举动，创建具有特定样式的新组件范例。
2.2.2 使用示例

1. // 扩展Text组件
2. @Extend(Text) function primaryText() {
3.     .fontSize(16)
4.     .fontColor('#333333')
5.     .fontWeight(FontWeight.Medium)
6. }
8. // 扩展Button组件
9. @Extend(Button) function primaryButton(color:Color) {
10.     .width(200)
11.    .height(50)
12.    .backgroundColor('#007DFF')
13.    .fontColor(color)
14. }
16. @Entry
17. @Component
18. struct TestCase {
19.    build() {
20.       Column({ space: 20 }) {
21.          Text('这是普通文本')
22.            .primaryText()
24.          Button('点击按钮')
25.           .primaryButton(Color.White)
26.       }
27.    .height('100%')
28.    .width('100%')
29.    }
30. }

复制代码

2.2.3 @Extend vs @Styles 对比

特性@Extend@Styles使用对象特定组件恣意组件复用性只能用于指定的组件范例可以应用于任何组件范例安全更强的范例查抄相对宽松实用场景组件定制化通用样式复用是否能吸收参数是否2.2.4 使用发起

• 选择符合的场景
  
  
  
  • 必要创建特定样式的组件变体时，使用@Extend
    
  • 必要跨组件复用样式时，使用@Styles
    
  
  
• 定名规范
  

1. // 好的命名示例
2. @Extend(Text) function primaryText() {}
3. @Extend(Text) function warningText() {}
4. @Extend(Button) function roundButton() {}
6. // 避免的命名方式
7. @Extend(Text) function txt() {}
8. @Extend(Button) function btn() {}

复制代码

三、组件类修饰符

3.1 @Component修饰符

3.1.1 根本概念

@Component是鸿蒙开辟中最焦点的修饰符之一，用于声明自界说组件。它将一个struct转换为可重用的UI组件，具有以下特点：

• 必须包罗build()方法
  
• 支持组件生命周期
  
• 可以包罗状态变量
  
• 支持组件间通讯
  

   3.1.2 @Component vs 平凡函数对比

特性@Component平凡函数状态管理支持@State等状态修饰符不支持状态管理生命周期有完备生命周期没有生命周期重渲染机制相应式更新需手动处置惩罚更新使用场景复杂UI组件简单功能封装3.1.3 根本使用示例

1. import { promptAction } from '@kit.ArkUI';
3. @Entry
4. @Component
5. struct TestCase {
6.    // 组件私有状态
7. @State counter: number = 0
8.    // 生命周期函数
9.    aboutToAppear() {
10.       promptAction.showToast({message:'Component is about to appear'})
11.    }
12.    aboutToDisappear() {
13.       promptAction.showToast({message:'Component is about to disappear'})
14.    }
16.    build() {
17.       Column() {
18.          Text(`计数器: ${this.counter}`)
19.            .fontSize(20)
20.            .fontWeight(FontWeight.Bold)
22.          Button('增加')
23.            .onClick(() => {
24.               this.counter++
25.            })
26.            .margin(10)
27.       }
28.    .width('100%')
29.    .padding(20)
30.    }
31. }

复制代码

3.1.4 高级特性

1. 组件参数转达

1. @Component
2. struct AdvancedComponent {
3.   // 从父组件接收的属性
4.   @Prop title: string
5.   @State private description: string = ''
7.   build() {
8.     Column({ space: 10 }) {
9.       Text(this.title)
10.         .fontSize(24)
11.       
12.       TextInput({ placeholder: '请输入描述' })
13.         .onChange((value: string) => {
14.           this.description = value
15.         })
16.     }
17.   }
18. }

复制代码

2. 组件插槽（Slot）

1. @Component
2. struct SlotComponent {
3.   @BuilderParam content: () => void
5.   build() {
6.     Column() {
7.       this.content()
8.     }
9.     .width('100%')
10.     .backgroundColor('#f5f5f5')
11.   }
12. }
14. // 使用组件插槽
15. @Component
16. struct ParentComponent {
17.   build() {
18.     SlotComponent() {
19.       Row() {
20.         Text('自定义内容')
21.         Image('icon.png')
22.       }
23.     }
24.   }
25. }

复制代码

3.1.5 最佳实践

• 组件拆分原则
  

1. // 好的实践：功能单一，职责明确
2. @Component
3. struct UserAvatar {
4.   @Prop userName: string
5.   @Prop avatarUrl: string
7.   build() {
8.     Stack() {
9.       Image(this.avatarUrl)
10.         .width(50)
11.         .height(50)
12.         .borderRadius(25)
13.       
14.       Text(this.userName[0])
15.         .fontSize(20)
16.         .fontColor(Color.White)
17.     }
18.   }
19. }
21. // 使用组件
22. @Component
23. struct UserProfile {
24.   build() {
25.     Row() {
26.       UserAvatar({
27.         userName: "张三",
28.         avatarUrl: "avatar.png"
29.       })
30.       Text("其他信息")
31.     }
32.   }
33. }

复制代码

• 生命周期使用发起
  

1. @Component
2. struct LifecycleComponent {
3.   @State private data: any = {}
5.   aboutToAppear() {
6.     // 初始化数据，订阅事件
7.     this.initData()
8.   }
10.   aboutToDisappear() {
11.     // 清理资源，取消订阅
12.     this.cleanUp()
13.   }
15.   private initData() {
16.     // 数据初始化逻辑
17.   }
19.   private cleanUp() {
20.     // 清理逻辑
21.   }
23.   build() {
24.     // UI渲染
25.   }
26. }

复制代码

3.1.6 性能优化发起

• 状态管理优化
  

1. @Component
2. struct OptimizedComponent {
3.   // 使用私有变量存储不需要响应式更新的数据
4.   private staticData: string = 'static'
5.   
6.   // 只将需要触发更新的数据声明为@State
7.   @State dynamicData: number = 0
9.   build() {
10.     Column() {
11.       // 静态内容
12.       Text(this.staticData)
13.       
14.       // 动态内容
15.       Text(`${this.dynamicData}`)
16.     }
17.   }
18. }

复制代码

• 条件渲染优化
  

1. @Component
2. struct ConditionalComponent {
3.   @State loading: boolean = true
4.   @State data: Array<string> = []
6.   build() {
7.     Column() {
8.       if (this.loading) {
9.         LoadingSpinner()
10.       } else {
11.         ForEach(this.data, (item) => {
12.           DataItem({ content: item })
13.         })
14.       }
15.     }
16.   }
17. }

复制代码

3.2 @BuilderParam修饰符

3.2.1 根本概念

@BuilderParam用于声明自界说构建函数参数，使组件可以或许吸收和渲染自界说内容。
3.2.2 使用场景

• 自界说列表项渲染
  

2. @Component
3. struct MainPage {
4. @State items: string[] = ['项目1', '项目2', '项目3']
5. @Builder myItemBuilder(item: string):void{}
6. @BuilderParam itemBuilder: (item: string) => void =  this.myItemBuilder
7.    build() {
8.       List() {
9.          ForEach(this.items, (item:string,idx:number) => {
10.             ListItem() {
11.                this.itemBuilder(item)
12.             }
13.          })
14.       }
15.    }
16. }
18. // 使用示例
19. @Entry
20. @Component
21. struct TestCase {
22.    build() {
23.       Column(){
24.          MainPage({
25.             itemBuilder: (item:string) => {
26.                Row() {
27.                   Text(item).width('100%')
28.                     .height('100%')
29.                     .backgroundColor(Color.Pink)
30.                }
31.             }
32.          })
33.       }}
34. }

复制代码

• 可定制化容器组件
  

1. @Component
2. struct Container {
3.   @BuilderParam header?: () => void
4.   @BuilderParam content: () => void
5.   @BuilderParam footer?: () => void
7.   build() {
8.     Column() {
9.       if (this.header) {
10.         this.header()
11.       }
12.       
13.       this.content()
14.       
15.       if (this.footer) {
16.         this.footer()
17.       }
18.     }
19.   }
20. }

复制代码

3.2.3 注意事项与最佳实践

• 参数定名规范
  

1. // 推荐的命名方式
2. @BuilderParam headerBuilder: () => void
3. @BuilderParam contentBuilder: () => void
4. @BuilderParam footerBuilder: () => void
6. // 不推荐的命名方式
7. @BuilderParam hdr: () => void
8. @BuilderParam cnt: () => void

复制代码

• 性能思量
  

1. @Component
2. struct PerformanceOptimizedList {
3.    // 使用私有变量缓存不常变化的构建函数
5. @Builder myStaticBuilder() :void{
6.       Text('Static Content')
7. }
9. @BuilderParam private staticBuilder:()=>void = this.myStaticBuilder
11. @BuilderParam dynamicBuilder: () => void
13.   build() {
14.       Column() {
15.          // 静态内容
16.          this.staticBuilder()
18.          // 动态内容
19.          this.dynamicBuilder()
20.       }
21.    }
22. }

复制代码

四、状态管理类修饰符

4.1 @State修饰符

4.1.1 根本概念

@State是鸿蒙应用中最根本的状态管理修饰符，用于组件内部状态管理。当@State装饰的变量发生变革时，框架会主动重新渲染相干UI。
   4.1.2 使用规则

• 根本语法
  

1. interface IUser{
2.    name: string,
3.    age: number
4. }
6. // 使用示例
7. @Entry
8. @Component
9. struct TestCase {
10.    // 基础类型
11.    @State count: number = 0
12.    // 对象类型
13.    @State user: IUser  = {
14.       name: 'tata',
15.       age: 25
16.    }
17.       // 数组类型
18.    @State list: string[] = ['item1', 'item2']
19.    build() {
20.       Column({ space: 20 }) {
21.          // 使用状态变量
22.          Text(`Count: ${this.count}`)
23.          Button('Add')
24.            .onClick(() => {
25.               this.count++
26.            })
28.          Text(`User: ${this.user.name}, ${this.user.age}`)
29.          Button('Update User')
30.            .onClick(() => {
31.               // 对象更新要使用新对象
32.               this.user = {
33.                  name:this.user.name,
34.                  age: this.user.age + 1
35.               }
36.            })
37.       }
38.    }
39. }

复制代码

4.1.3 @State注意事项和最佳实践

• 状态初始化
  

1. @Component
2. struct StateInitDemo {
3.   // ✅ 推荐：直接初始化
4.   @State counter1: number = 0
5.   
6.   // ⚠️ 不推荐：延迟初始化可能导致问题
7.   @State counter2: number
9.   aboutToAppear() {
10.     // 延迟初始化可能导致首次渲染问题
11.     this.counter2 = 0
12.   }
13. }

复制代码

• 状态粒度控制
  

1. @Component
2. struct StateGranularityDemo {
3.   // ❌ 错误：粒度过大
4.   @State entirePage: {
5.     header: object,
6.     content: object,
7.     footer: object
8.   }
10.   // ✅ 正确：适当的状态粒度
11.   @State headerConfig: object
12.   @State contentList: array
13.   @State footerVisible: boolean
15.   build() {
16.     Column() {
17.       // UI实现
18.     }
19.   }
20. }

复制代码

4.2 @Prop修饰符

4.2.1 根本概念

@Prop用于父子组件间的单向数据转达，子组件通过@Prop吸收父组件转达的数据。
4.2.2 使用示例

1. // 子组件
2. @Component
3. struct ChildComponent {
4.   @Prop count: number  // 接收父组件传递的数值
5.   @Prop message: string  // 接收父组件传递的字符串
7.   build() {
8.     Column() {
9.       Text(`Count: ${this.count}`)
10.       Text(`Message: ${this.message}`)
11.     }
12.   }
13. }
15. // 父组件
16. @Component
17. struct ParentComponent {
18.   @State parentCount: number = 0
19.   @State parentMessage: string = 'Hello'
21.   build() {
22.     Column() {
23.       // 传递属性给子组件
24.       ChildComponent({
25.         count: this.parentCount,
26.         message: this.parentMessage
27.       })
29.       Button('Update Parent')
30.         .onClick(() => {
31.           this.parentCount++
32.           this.parentMessage = 'Updated'
33.         })
34.     }
35.   }
36. }

复制代码

4.2.3 @Prop vs 平凡变量对比

1. @Component
2. struct PropComparisonDemo {
3.   // @Prop装饰的变量
4.   @Prop propValue: number
5.   
6.   // 普通变量
7.   normalValue: number
9.   build() {
10.     Column() {
11.       // @Prop变量会响应父组件的更新
12.       Text(`Prop Value: ${this.propValue}`)
13.       
14.       // 普通变量不会响应更新
15.       Text(`Normal Value: ${this.normalValue}`)
16.     }
17.   }
18. }

复制代码

特性@Prop变量平凡变量数据流向单向（父到子）无数据流相应更新主动相应不相应可修改性当地可修改但不影响父组件可以自由修改使用场景父子组件通讯组件内部数据4.2.4 @Prop的高级用法

• 默认值处置惩罚
  

1. @Component
2. struct PropDefaultDemo {
3.   // 使用装饰器提供默认值
4.   @Prop defaultValue: number = 100
6.   build() {
7.     Column() {
8.       Text(`Value: ${this.defaultValue}`)
9.     }
10.   }
11. }

复制代码

• 属性监听与处置惩罚
  

1. @Component
2. struct PropWatchDemo {
3.   @Prop @Watch('onCountChange') count: number
4.   @State localCount: number = 0
6.   onCountChange() {
7.     // 当@Prop值变化时执行
8.     this.localCount = this.count * 2
9.   }
11.   build() {
12.     Column() {
13.       Text(`Prop Count: ${this.count}`)
14.       Text(`Local Count: ${this.localCount}`)
15.     }
16.   }
17. }

复制代码

4.2.5 最佳实践

• 属性定名规范
  

1. @Component
2. struct PropNamingDemo {
3.   // ✅ 推荐：语义化命名
4.   @Prop isVisible: boolean
5.   @Prop userName: string
6.   @Prop itemCount: number
8.   // ❌ 避免：模糊的命名
9.   @Prop flag: boolean
10.   @Prop str: string
11.   @Prop num: number
12. }

复制代码

• 范例安全
  

1. @Component
2. struct PropTypeDemo {
3.   // ✅ 推荐：明确的类型定义
4.   @Prop items: Array<{
5.     id: number,
6.     name: string
7.   }>
9.   // ❌ 避免：使用any类型
10.   @Prop data: any
11. }

复制代码

4.3 @Link修饰符

4.3.1 根本概念

@Link修饰符用于实现父子组件间的双向数据绑定。与@Prop差别，@Link装饰的变量在子组件中的修改会同步回父组件。
   4.3.2 使用示例

1. // 子组件
2. @Component
3. struct LinkChildComponent {
4.   @Link countValue: number  // 双向绑定数据
6.   build() {
7.     Column() {
8.       Text(`Count: ${this.countValue}`)
9.       Button('在子组件中修改')
10.         .onClick(() => {
11.           this.countValue++  // 修改会影响父组件
12.         })
13.     }
14.   }
15. }
17. // 父组件
18. @Entry
19. @Component
20. struct TestCase {
21.   @State parentCount: number = 0
23.   build() {
24.     Column() {
25.       Text(`Parent Count: ${this.parentCount}`)
26.       LinkChildComponent({ countValue: $parentCount })
27.       Button('在父组件中修改')
28.         .onClick(() => {
29.           this.parentCount++
30.         })
31.     }
32.   }
33. }

复制代码

4.3.3 @Link vs @Prop 对比

特性@Link@Prop数据流向双向单向（父到子）子组件修改直接影响父组件不影响父组件使用场景必要子组件修改父组件状态只必要展示父组件数据语法标志变量名变量名4.3.4 @Link最佳实践

• 公道使用场景
  

1. @Component
2. struct FormComponent {
3.   // ✅ 适合使用@Link的场景：表单数据
4.   @Link formData: {
5.     username: string,
6.     password: string
7.   }
9.   build() {
10.     Column() {
11.       TextInput({ placeholder: '用户名' })
12.         .onChange((value) => {
13.           this.formData.username = value
14.         })
15.       
16.       TextInput({ placeholder: '密码' })
17.         .type(InputType.Password)
18.         .onChange((value) => {
19.           this.formData.password = value
20.         })
21.     }
22.   }
23. }

复制代码

• 制止过分使用
  

1. @Component
2. struct OptimizedComponent {
3.   // ✅ 只对需要双向绑定的数据使用@Link
4.   @Link editableData: string
5.   
6.   // ✅ 只读数据使用@Prop
7.   @Prop readOnlyData: string
8.   
9.   // ✅ 组件内部状态使用@State
10.   @State localState: number = 0
12.   build() {
13.     Column() {
14.       // 实现UI
15.     }
16.   }
17. }

复制代码

4.4 @Provide/@Consume修饰符

4.4.1 根本概念

@Provide和@Consume用于实现跨组件层级的数据共享，制止多层props转达（即"prop drilling"标题）。
4.4.2 根本用法

2. interface IUser{
3.   name:string,
4.   role:string
5. }
6. // 顶层组件
7. @Entry
8. @Component
9. struct TestCase {
10.   @Provide('theme') theme: string = 'light'
11.   @Provide('user') userInfo:IUser  = {
12.     name: 'tata',
13.     role: 'admin'
14.   }
16.   build() {
17.     Column() {
18.       ConsumerComponent()
19.     }
20.   }
21. }
23. // 消费组件（可以是任意层级的子组件）
24. @Component
25. struct ConsumerComponent {
26.   @Consume('theme') theme: string
27.   @Consume('user') userInfo: IUser
29.   build() {
30.     Column() {
31.       Text(`Current Theme: ${this.theme}`)
32.       Text(`User: ${this.userInfo.name}`)
33.     }
34.   }
35. }

复制代码

4.4.3 高级特性

• 使用别名
  

1. @Component
2. struct AdvancedProvider {
3.   @Provide('systemTheme') theme: string = 'light'
4. }
6. @Component
7. struct AdvancedConsumer {
8.   // 使用别名访问共享数据
9.   @Consume('systemTheme') currentTheme: string
11.   build() {
12.     Column() {
13.       Text(`Theme: ${this.currentTheme}`)
14.     }
15.   }
16. }

复制代码

• 多层级数据共享
  

1. @Component
2. struct AppRoot {
3.   @Provide('globalState') userInfo:IUser = {
4.     name:'tata',
5.     role:'admin'
6.   }
8.   build() {
9.     Column() {
10.       // 可以被任意深度的子组件访问
11.       DeepNestedComponent()
12.     }
13.   }
14. }

复制代码

4.4.4 使用发起与最佳实践

• 公道的数据粒度
  

1. // ✅ 推荐：适当的粒度
2. @Component
3. struct GoodProvider {
4.   @Provide('userSettings') settings: UserSettings
5.   @Provide('appTheme') theme: Theme
6. }
8. // ❌ 避免：过大的共享范围
9. @Component
10. struct BadProvider {
11.   @Provide('entireAppState') state: AppState
12. }

复制代码

• 性能优化
  

1. @Component
2. struct OptimizedProvider {
3.   // 将频繁变化的数据和稳定数据分开
4.   @Provide('staticConfig') staticConfig: Config // 稳定数据
5.   @Provide('dynamicState') dynamicState: State // 变化数据
7.   build() {
8.     Column() {
9.       // 实现UI
10.     }
11.   }
12. }

复制代码

• 错误处置惩罚
  

1. @Component
2. struct SafeConsumer {
3.   @Consume('data') data?: DataType  // 使用可选类型
4.   
5.   build() {
6.     Column() {
7.       if (this.data) {
8.         // 安全地使用数据
9.         Text(this.data.toString())
10.       } else {
11.         // 提供后备UI
12.         Text('数据未就绪')
13.       }
14.     }
15.   }
16. }

复制代码

4.5 @Watch修饰符

4.5.1 根本概念

@Watch用于监听状态变量的变革，当被监听的状态发生改变时，会触发相应的回调函数。
   4.5.2 根本用法

1. // 顶层组件
2. @Entry
3. @Component
4. struct TestCase {
5.   @State @Watch('onCountChange') count: number = 0
6.   @State message: string = ''
8.   onCountChange() {
9.     this.message = `计数变为 ${this.count.toString()}`
10.   }
12.   build() {
13.     Column({ space: 20 }) {
14.       Text(`Current count: ${this.count}`)
15.       Text(this.message)
17.       Button('Increment')
18.         .onClick(() => {
19.           this.count++
20.         })
21.     }
22.   }
23. }

复制代码

4.5.3 高级用法

• 监听多个属性
  

1. @Component
2. struct MultiWatchDemo {
4.   @State @Watch('onScoreChange') score: number = 0
5.   @State @Watch('onScoreChange') bonus: number = 0
7.   // 监听多个数值变化
8.   onScoreChange() {
9.     console.info(`Total: ${this.score + this.bonus}`)
10.   }
12.   build() {
13.     Column() {
14.       // UI实现
15.     }
16.   }
17. }

复制代码

• 条件监听
  

1. @Component
2. struct ConditionalWatchDemo {
3.   @State @Watch('onValueChange') value: number = 0
4.   @State isEnabled: boolean = true
6.   onValueChange(newValue: number, oldValue: number) {
7.     if (this.isEnabled) {
8.       // 只在启用状态下处理变化
9.       this.handleValueChange(newValue, oldValue)
10.     }
11.   }
13.   private handleValueChange(newVal: number, oldVal: number) {
14.     // 处理逻辑
15.   }
17.   build() {
18.     Column() {
19.       Switch()
20.         .checked(this.isEnabled)
21.         .onChange((value: boolean) => {
22.           this.isEnabled = value
23.         })
24.     }
25.   }
26. }

复制代码

4.5.4 @Watch使用场景

• 表单验证
  

1. @Component
2. struct FormValidationDemo {
3.   @State @Watch('validateEmail') email: string = ''
4.   @State emailError: string = ''
6.   validateEmail(newValue: string) {
7.     const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
8.     if (!emailRegex.test(newValue)) {
9.       this.emailError = '请输入有效的邮箱地址'
10.     } else {
11.       this.emailError = ''
12.     }
13.   }
15.   build() {
16.     Column({ space: 10 }) {
17.       TextInput({ placeholder: '请输入邮箱' })
18.         .onChange((value: string) => {
19.           this.email = value
20.         })
21.       
22.       if (this.emailError) {
23.         Text(this.emailError)
24.           .fontSize(12)
25.           .fontColor(Color.Red)
26.       }
27.     }
28.   }
29. }

复制代码

• 数据同步
  

1. @Component
2. struct DataSyncDemo {
3.   @State @Watch('syncToServer') localData: IUser = {}
5.   async syncToServer(newValue: IUser) {
6.     try {
7.       await this.saveToServer(newValue)
8.       console.info('Data synced successfully')
9.     } catch (error) {
10.       console.error('Sync failed:', error)
11.     }
12.   }
14.   private async saveToServer(data: object) {
15.     // 实现服务器同步逻辑
16.   }
18.   build() {
19.     Column() {
20.       // UI实现
21.     }
22.   }
23. }

复制代码

4.5.5 最佳实践

• 性能优化
  

2. @Component
3. struct WatchOptimizationDemo {
4.   @State @Watch('onDataChange') data: IUser = {
5.     name:'tata',
6.     role:'admin'
7.   }
9.   // ✅ 优化：添加防抖处理
10.   private debounceTimer: number = -1
12.   onDataChange() {
13.     if (this.debounceTimer !== -1) {
14.       clearTimeout(this.debounceTimer)
15.     }
17.     this.debounceTimer = setTimeout(() => {
18.       this.processDataChange(this.data)
19.       this.debounceTimer = -1
20.     }, 300)
21.   }
23.   private processDataChange(data: IUser) {
24.     // 处理数据变化
25.   }
27.   build() {
28.     Column() {
29.       // UI实现
30.     }
31.   }
32. }

复制代码

• 错误处置惩罚
  

1. @Component
2. struct WatchErrorHandlingDemo {
3.   @State @Watch('onDataChange') data: IUser = {
4.     name:'tata',
5.     role:'admin'
6.   }
8.   onDataChange() {
9.     try {
10.       // 数据验证
11.       if (!this.isValidData(this.data)) {
12.         throw new Error('Invalid data format')
13.       }
15.       // 处理数据
16.       this.processData(this.data)
17.     } catch (error) {
18.       console.error('Error in watch handler:', error)
19.       // 恢复到之前的值
20.       // 显示错误提示
21.       this.showError(error.message)
22.     }
23.   }
25.   private isValidData(data: IUser): boolean {
26.     // 实现数据验证逻辑
27.     return true
28.   }
30.   private processData(data: IUser) {
31.     // 处理数据
32.   }
34.   private showError(message: string) {
35.     // 显示错误提示
36.   }
38.   build() {
39.     Column() {
40.       // UI实现
41.     }
42.   }
43. }

复制代码

4.5.6 @Watch注意事项

• 制止无穷循环
  

1. @Component
2. struct WatchCycleDemo {
3.   @State @Watch('onValueChange') value1: number = 0
4.   @State @Watch('onValue2Change') value2: number = 0
6.   // ❌ 错误：可能导致无限循环
7.   onValueChange() {
8.     this.value2++ // 触发value2的watch
9.   }
11.   onValue2Change() {
12.     this.value1++ // 触发value1的watch
13.   }
15.   // ✅ 正确：添加循环保护
16.   private updateCount: number = 0
17.   private readonly MAX_UPDATES: number = 3
19.   onSafeValueChange() {
20.     if (this.updateCount < this.MAX_UPDATES) {
21.       this.updateCount++
22.       this.value2++
23.     } else {
24.       this.updateCount = 0
25.     }
26.   }
27. }

复制代码

• 同步与异步处置惩罚
  

1. @Component
2. struct WatchAsyncDemo {
3.   @State @Watch('onDataChange') data: object = {}
5.   // ✅ 处理异步操作
6.   async onDataChange(newValue: object) {
7.     try {
8.       await this.validateData(newValue)
9.       await this.saveData(newValue)
10.     } catch (error) {
11.       console.error('Async operation failed:', error)
12.     }
13.   }
15.   private async validateData(data: object): Promise<void> {
16.     // 异步数据验证
17.   }
19.   private async saveData(data: object): Promise<void> {
20.     // 异步保存数据
21.   }
23.   build() {
24.     Column() {
25.       // UI实现
26.     }
27.   }
28. }

复制代码

  

• @Watch 回调函数现实上不支持有用的参数转达
  
• 回调函数中第一个参数是被监听属性的名称字符串
  

  4.6 @Observed/@ObjectLink修饰符

4.6.1 根本概念

@Observed和@ObjectLink是用于对象范例数据的相应式管理修饰符：

• @Observed：将一个类标志为可观察对象
  
• @ObjectLink：用于在组件间创建对象的引用关系，实现对象级别的双向同步
  

   4.6.2 根本用法

1. // 定义可观察类
2. @Observed
3. class Student {
4.   name: string
5.   age: number
6.   scores: number[]
8.   constructor(name: string, age: number) {
9.     this.name = name
10.     this.age = age
11.     this.scores = []
12.   }
13. }
15. // 父组件
16. @Component
17. struct ParentComponent {
18.   // 创建可观察对象实例
19.   @State student: Student = new Student('tata', 18)
21.   build() {
22.     Column() {
23.       // 传递给子组件
24.       StudentCard({ studentInfo: this.student })
25.       
26.       Button('修改信息')
27.         .onClick(() => {
28.           this.student.age++
29.           this.student.scores.push(100)
30.         })
31.     }
32.   }
33. }
35. // 子组件
36. @Component
37. struct StudentCard {
38.   // 使用ObjectLink引用父组件的对象
39.   @ObjectLink studentInfo: Student
41.   build() {
42.     Column() {
43.       Text(`姓名: ${this.studentInfo.name}`)
44.       Text(`年龄: ${this.studentInfo.age}`)
45.       ForEach(this.studentInfo.scores, (score:number) => {
46.         Text(`分数: ${score}`)
47.       })
48.     }
49.   }
50. }

复制代码

4.6.3 关键点

• 类级别装饰器
  

1. // ✅ 正确：整个类使用 @Observed
2. @Observed
3. class Model {
4.   property1: string
5.   property2: number
6. }
8. // ❌ 错误：不能装饰属性
9. class WrongModel {
10.   @Observed property: string  // 这是错误的用法
11. }

复制代码

• 嵌套对象处置惩罚
  

1. @Observed
2. class Parent {
3.   child: Child  // 如果 Child 需要观察，Child 类也需要使用 @Observed 装饰器
4. }
6. @Observed
7. class Child {
8.   name: string
9. }

复制代码

• 数组处置惩罚
  

1. @Observed
2. class TodoList {
3.   items: Array<TodoItem>  // TodoItem 类需要使用 @Observed
5.   addItem(item: TodoItem) {
6.     this.items.push(item)
7.   }
8. }
10. @Observed
11. class TodoItem {
12.   content: string
13.   completed: boolean
14. }

复制代码

4.6.4 现实应用示例

1. // 定义观察类
2. @Observed
3. class Profile {
4.   name: string
5.   age: number
7.   constructor(name: string, age: number) {
8.     this.name = name
9.     this.age = age
10.   }
11. }
13. // 父组件
14. @Component
15. struct ProfileManager {
16.   @State profile: Profile = new Profile('tata', 25)
18.   build() {
19.     Column() {
20.       // 传递给子组件
21.       ProfileEditor({ userProfile: this.profile })
22.       ProfileDisplay({ userProfile: this.profile })
23.     }
24.   }
25. }
27. // 编辑组件
28. @Component
29. struct ProfileEditor {
30.   @ObjectLink userProfile: Profile
32.   build() {
33.     Column() {
34.       Button('修改年龄')
35.         .onClick(() => {
36.           this.userProfile.age++  // 直接修改将触发更新
37.         })
38.     }
39.   }
40. }
42. // 显示组件
43. @Component
44. struct ProfileDisplay {
45.   @ObjectLink userProfile: Profile
47.   build() {
48.     Column() {
49.       Text(`姓名: ${this.userProfile.name}`)
50.       Text(`年龄: ${this.userProfile.age}`)
51.     }
52.   }
53. }

复制代码

4.6.5 注意事项

• @Observed 只能用于类声明
  
• 不能用于装饰类的属性
  
• 嵌套对象如需相应式，必要分别使用 @Observed 装饰器
  
• 共同 @ObjectLink 使用来实现组件间的数据同步
  
• 观察对象的属性修改会主动触发相干组件的更新
  

对比

让我详细对比这些修饰符的区别：
   1. 使用场景对比

修饰符使用对象数据流向使用场景@State根本范例/对象/数组组件内部管理组件内部状态@Prop根本范例/对象/数组父 -> 子父组件向子组件转达数据@Link根本范例/对象/数组双向父子组件双向数据同步@Observed/@ObjectLink类实例多组件共享复杂对象的相应式管理2. 详细示例对比

1. // @State：组件内部状态管理
2. @Component
3. struct StateExample {
4.   @State count: number = 0  // 组件内部状态
6.   build() {
7.     Column() {
8.       Text(`Count: ${this.count}`)
9.       Button('Add').onClick(() => this.count++)
10.     }
11.   }
12. }
14. // @Prop：单向数据流
15. @Component
16. struct PropExample {
17.   @Prop title: string  // 从父组件接收数据
18.   
19.   build() {
20.     Text(this.title)
21.   }
22. }
24. // @Link：双向数据绑定
25. @Component
26. struct LinkExample {
27.   @Link message: string  // 与父组件双向绑定
28.   
29.   build() {
30.     TextInput({ text: this.message })
31.       .onChange((value: string) => {
32.         this.message = value  // 修改会影响父组件
33.       })
34.   }
35. }
37. // @Observed：对象响应式
38. @Observed
39. class User {
40.   name: string
41.   age: number
43.   constructor(name: string, age: number) {
44.     this.name = name
45.     this.age = age
46.   }
47. }
49. @Component
50. struct ObservedExample {
51.   @State user: User = new User('tata', 25)
53.   build() {
54.     Column() {
55.       UserCard({ userInfo: this.user })  // 传递给子组件
56.     }
57.   }
58. }
60. @Component
61. struct UserCard {
62.   @ObjectLink userInfo: User  // 引用观察对象
64.   build() {
65.     Column() {
66.       Text(`Name: ${this.userInfo.name}`)
67.       Button('Age++')
68.         .onClick(() => {
69.           this.userInfo.age++  // 直接修改对象属性
70.         })
71.     }
72.   }
73. }

复制代码

3. 特点对比

@State

• 用于组件内部状态管理
  
• 值变革会触发组件重新渲染
  
• 可以管理任何范例的数据
  

1. @State count: number = 0
2. @State user: Object = {}
3. @State list: string[] = []

复制代码

@Prop

• 实现单向数据流
  
• 子组件不能直接修改父组件数据
  
• 父组件数据变革会更新子组件
  

1. // 父组件
2. @State title: string = 'Hello'
3. // 子组件使用
4. @Prop title: string

复制代码

@Link

• 实现双向数据绑定
  
• 子组件可以直接修改数据
  
• 数据变革双向同步
  

1. // 父组件
2. @State message: string = ''
3. // 子组件使用
4. @Link message: string

复制代码

@Observed/@ObjectLink

• 用于复杂对象的相应式管理
  
• 主动跟踪对象属性变革
  
• 支持多组件共享和同步
  

1. @Observed
2. class Model {
3.   // 整个类的属性都会被观察
4. }
6. @ObjectLink model: Model  // 引用观察对象

复制代码

4. 数据同步方式对比

1. // @State：组件内直接修改
2. @State value: number = 0
3. this.value = 1  // 直接赋值
5. // @Prop：不能直接修改
6. @Prop title: string
7. this.title = 'new'  // ❌ 错误
9. // @Link：双向同步
10. @Link count: number
11. this.count++  // ✅ 会同步到父组件
13. // @Observed：对象属性修改
14. @ObjectLink user: User
15. this.user.name = 'new name'  // ✅ 自动触发更新

复制代码

---