概念
组件内部状态管理 @Local 是专为@ComponentV2 组件设计的装饰器,用于声明组件私有状态。被装饰的变量必须在组件内部初始化,禁止从父组件外部传入初始值(如 Child({count: 10}) 的写法会报错),确保状态封装性。
观测能力
- 支持类型:基本类型(number、string、boolean)、Object、class、Array、Set、Map、Date 等内嵌类型,以及联合类型。
- 变化触发机制:
- 简单类型(如 number):赋值操作触发 UI 刷新(如 this.count++)。
- 对象类型:仅整体赋值时触发(如替换整个对象 this.obj = new MyClass())。
- 数组/集合类型:整体赋值或调用特定 API(如 push()、set())时触发。
与@State 的对比
| 特性 | @Local(V2) | @State(V1) |
|---|---|---|
| 初始化 | 强制内部初始化 | 允许外部传入覆盖初始值 |
| 作用域 | 组件内部私有 | 可跨组件传递 |
| 性能优化 | 更精细的观测,减少不必要刷新 | 可能因外部修改导致过度渲染 |
| 适用版本 | API 12+,ComponentV2 组件 | 旧版本组件体系 |
使用场景
基本状态管理: Button 绑定 local 装饰的变量 count,count 值改变引起 button 刷新。
@Entry@ComponentV2 struct Index {
@Local count:number=1;
build(){
Column(){
Button('点击次数:'+this.count).width('60%').onClick(()=>{
this.count+=1
})
}.height('100%').width().(.)
}
}


