1# \@Observed和\@ObjectLink：嵌套类对象属性变化 2 3 4上文所述的装饰器仅能观察到第一层的变化，但是在实际应用开发中，应用会根据开发需要，封装自己的数据模型。对于多层嵌套的情况，比如二维数组，或者数组项class，或者class的属性是class，他们的第二层的属性变化是无法观察到的。这就引出了\@Observed/\@ObjectLink装饰器。 5 6 7> **说明：** 8> 9> 从API version 9开始，这两个装饰器支持在ArkTS卡片中使用。 10 11 12## 概述 13 14\@ObjectLink和\@Observed类装饰器用于在涉及嵌套对象或数组的场景中进行双向数据同步： 15 16- 被\@Observed装饰的类，可以被观察到属性的变化； 17 18- 子组件中\@ObjectLink装饰器装饰的状态变量用于接收\@Observed装饰的类的实例，和父组件中对应的状态变量建立双向数据绑定。这个实例可以是数组中的被\@Observed装饰的项，或者是class object中是属性，这个属性同样也需要被\@Observed装饰。 19 20- 单独使用\@Observed是没有任何作用的，需要搭配\@ObjectLink或者[\@Prop](arkts-prop.md)使用。 21 22 23## 限制条件 24 25使用\@Observed装饰class会改变class原始的原型链，\@Observed和其他类装饰器装饰同一个class可能会带来问题。 26 27## 装饰器说明 28 29| \@Observed类装饰器 | 说明 | 30| -------------- | --------------------------------- | 31| 装饰器参数 | 无 | 32| 类装饰器 | 装饰class。需要放在class的定义前，使用new创建类对象。 | 33 34| \@ObjectLink变量装饰器 | 说明 | 35| ----------------- | ---------------------------------------- | 36| 装饰器参数 | 无 | 37| 同步类型 | 不与父组件中的任何类型同步变量。 | 38| 允许装饰的变量类型 | 必须为被\@Observed装饰的class实例，必须指定类型。<br/>不支持简单类型，可以使用[\@Prop](arkts-prop.md)。<br/>\@ObjectLink的属性是可以改变的，但是变量的分配是不允许的，也就是说这个装饰器装饰变量是只读的，不能被改变。 | 39| 被装饰变量的初始值 | 不允许。 | 40 41\@ObjectLink装饰的数据为可读示例。 42 43 44```ts 45// 允许@ObjectLink装饰的数据属性赋值 46this.objLink.a= ... 47// 不允许@ObjectLink装饰的数据自身赋值 48this.objLink= ... 49``` 50 51> **说明：** 52> 53> \@ObjectLink装饰的变量不能被赋值，如果要使用赋值操作，请使用[@Prop](arkts-prop.md)。 54> 55> - \@Prop装饰的变量和数据源的关系是是单向同步，\@Prop装饰的变量在本地拷贝了数据源，所以它允许本地更改，如果父组件中的数据源有更新，\@Prop装饰的变量本地的修改将被覆盖； 56> 57> - \@ObjectLink装饰的变量和数据源的关系是双向同步，\@ObjectLink装饰的变量相当于指向数据源的指针。如果一旦发生\@ObjectLink装饰的变量的赋值，则同步链将被打断。 58 59 60## 变量的传递/访问规则说明 61 62| \@ObjectLink传递/访问 | 说明 | 63| ----------------- | ---------------------------------------- | 64| 从父组件初始化 | 必须指定。<br/>初始化\@ObjectLink装饰的变量必须同时满足以下场景：<br/>- 类型必须是\@Observed装饰的class。<br/>- 初始化的数值需要是数组项，或者class的属性。<br/>- 同步源的class或者数组必须是\@State，\@Link，\@Provide，\@Consume或者\@ObjectLink装饰的数据。<br/>同步源是数组项的示例请参考[对象数组](#对象数组)。初始化的class的示例请参考[嵌套对象](#嵌套对象)。 | 65| 与源对象同步 | 双向。 | 66| 可以初始化子组件 | 允许，可用于初始化常规变量、\@State、\@Link、\@Prop、\@Provide | 67 68 69 **图1** 初始化规则图示 70 71 72 73 74 75## 观察变化和行为表现 76 77 78### 观察的变化 79 80\@Observed装饰的类，如果其属性为非简单类型，比如class、Object或者数组，也需要被\@Observed装饰，否则将观察不到其属性的变化。 81 82 83```ts 84class ClassA { 85 public c: number; 86 87 constructor(c: number) { 88 this.c = c; 89 } 90} 91 92@Observed 93class ClassB { 94 public a: ClassA; 95 public b: number; 96 97 constructor(a: ClassA, b: number) { 98 this.a = a; 99 this.b = b; 100 } 101} 102``` 103 104以上示例中，ClassB被\@Observed装饰，其成员变量的赋值的变化是可以被观察到的，但对于ClassA，没有被\@Observed装饰，其属性的修改不能被观察到。 105 106 107```ts 108@ObjectLink b: ClassB 109 110// 赋值变化可以被观察到 111this.b.a = new ClassA(5) 112this.b.b = 5 113 114// ClassA没有被@Observed装饰，其属性的变化观察不到 115this.b.a.c = 5 116``` 117 118\@ObjectLink：\@ObjectLink只能接收被\@Observed装饰class的实例，可以观察到： 119 120- 其属性的数值的变化，其中属性是指Object.keys(observedObject)返回的所有属性，示例请参考[嵌套对象](#嵌套对象)。 121 122- 如果数据源是数组，则可以观察到数组item的替换，如果数据源是class，可观察到class的属性的变化，示例请参考[对象数组](#对象数组)。 123 124 125### 框架行为 126 1271. 初始渲染： 128 1. \@Observed装饰的class的实例会被不透明的代理对象包装，代理了class上的属性的setter和getter方法 129 2. 子组件中\@ObjectLink装饰的从父组件初始化，接收被\@Observed装饰的class的实例，\@ObjectLink的包装类会将自己注册给\@Observed class。 130 1312. 属性更新：当\@Observed装饰的class属性改变时，会走到代理的setter和getter，然后遍历依赖它的\@ObjectLink包装类，通知数据更新。 132 133 134## 使用场景 135 136 137### 嵌套对象 138 139以下是嵌套类对象的数据结构。 140 141 142```ts 143// objectLinkNestedObjects.ets 144let NextID: number = 1; 145 146@Observed 147class ClassA { 148 public id: number; 149 public c: number; 150 151 constructor(c: number) { 152 this.id = NextID++; 153 this.c = c; 154 } 155} 156 157@Observed 158class ClassB { 159 public a: ClassA; 160 161 constructor(a: ClassA) { 162 this.a = a; 163 } 164} 165``` 166 167 168 以下组件层次结构呈现的是此数据结构 169 170```ts 171@Component 172struct ViewA { 173 label: string = 'ViewA1'; 174 @ObjectLink a: ClassA; 175 176 build() { 177 Row() { 178 Button(`ViewA [${this.label}] this.a.c=${this.a.c} +1`) 179 .onClick(() => { 180 this.a.c += 1; 181 }) 182 } 183 } 184} 185 186@Entry 187@Component 188struct ViewB { 189 @State b: ClassB = new ClassB(new ClassA(0)); 190 191 build() { 192 Column() { 193 ViewA({ label: 'ViewA #1', a: this.b.a }) 194 ViewA({ label: 'ViewA #2', a: this.b.a }) 195 196 Button(`ViewB: this.b.a.c+= 1`) 197 .onClick(() => { 198 this.b.a.c += 1; 199 }) 200 Button(`ViewB: this.b.a = new ClassA(0)`) 201 .onClick(() => { 202 this.b.a = new ClassA(0); 203 }) 204 Button(`ViewB: this.b = new ClassB(ClassA(0))`) 205 .onClick(() => { 206 this.b = new ClassB(new ClassA(0)); 207 }) 208 } 209 } 210} 211``` 212 213 214ViewB中的事件句柄： 215 216 217- this.b.a = new ClassA(0) 和this.b = new ClassB(new ClassA(0))： 对\@State装饰的变量b和其属性的修改。 218 219- this.b.a.c = ... ：该变化属于第二次的变化，[@State](arkts-state.md#观察变化)无法观察到第二层的变化，但是ClassA被\@Observed装饰，ClassA的属性c的变化可以被\@ObjectLink观察到。 220 221 222ViewA中的事件句柄： 223 224 225- this.a.c += 1：对\@ObjectLink变量a的修改，将触发Button组件的刷新。\@ObjectLink和\@Prop不同，\@ObjectLink不拷贝来自父组件的数据源，而是在本地构建了指向其数据源的引用。 226 227- \@ObjectLink变量是只读的，this.a = new ClassA(...)是不允许的，因为一旦赋值操作发生，指向数据源的引用将被重置，同步将被打断。 228 229 230### 对象数组 231 232对象数组是一种常用的数据结构。以下示例展示了数组对象的用法。 233 234 235```ts 236@Component 237struct ViewA { 238 // 子组件ViewA的@ObjectLink的类型是ClassA 239 @ObjectLink a: ClassA; 240 label: string = 'ViewA1'; 241 242 build() { 243 Row() { 244 Button(`ViewA [${this.label}] this.a.c = ${this.a.c} +1`) 245 .onClick(() => { 246 this.a.c += 1; 247 }) 248 } 249 } 250} 251 252@Entry 253@Component 254struct ViewB { 255 // ViewB中有@State装饰的ClassA[] 256 @State arrA: ClassA[] = [new ClassA(0), new ClassA(0)]; 257 258 build() { 259 Column() { 260 ForEach(this.arrA, 261 (item) => { 262 ViewA({ label: `#${item.id}`, a: item }) 263 }, 264 (item) => item.id.toString() 265 ) 266 // 使用@State装饰的数组的数组项初始化@ObjectLink，其中数组项是被@Observed装饰的ClassA的实例 267 ViewA({ label: `ViewA this.arrA[first]`, a: this.arrA[0] }) 268 ViewA({ label: `ViewA this.arrA[last]`, a: this.arrA[this.arrA.length-1] }) 269 270 Button(`ViewB: reset array`) 271 .onClick(() => { 272 this.arrA = [new ClassA(0), new ClassA(0)]; 273 }) 274 Button(`ViewB: push`) 275 .onClick(() => { 276 this.arrA.push(new ClassA(0)) 277 }) 278 Button(`ViewB: shift`) 279 .onClick(() => { 280 this.arrA.shift() 281 }) 282 Button(`ViewB: chg item property in middle`) 283 .onClick(() => { 284 this.arrA[Math.floor(this.arrA.length / 2)].c = 10; 285 }) 286 Button(`ViewB: chg item property in middle`) 287 .onClick(() => { 288 this.arrA[Math.floor(this.arrA.length / 2)] = new ClassA(11); 289 }) 290 } 291 } 292} 293``` 294 295- this.arrA[Math.floor(this.arrA.length/2)] = new ClassA(..) ：该状态变量的改变触发2次更新： 296 1. ForEach：数组项的赋值导致ForEach的[itemGenerator](arkts-rendering-control-foreach.md#接口描述)被修改，因此数组项被识别为有更改，ForEach的item builder将执行，创建新的ViewA组件实例。 297 2. ViewA({ label: `ViewA this.arrA[first]`, a: this.arrA[0] })：上述更改改变了数组中第一个元素，所以绑定this.arrA[0]的ViewA将被更新； 298 299- this.arrA.push(new ClassA(0)) ： 将触发2次不同效果的更新： 300 1. ForEach：新添加的ClassA对象对于ForEach是未知的[itemGenerator](arkts-rendering-control-foreach.md#接口描述)，ForEach的item builder将执行，创建新的ViewA组件实例。 301 2. ViewA({ label: `ViewA this.arrA[last]`, a: this.arrA[this.arrA.length-1] })：数组的最后一项有更改，因此引起第二个ViewA的实例的更改。对于ViewA({ label: `ViewA this.arrA[first]`, a: this.arrA[0] })，数组的更改并没有触发一个数组项更改的改变，所以第一个ViewA不会刷新。 302 303- this.arrA[Math.floor(this.arrA.length/2)].c：[@State](arkts-state.md#观察变化)无法观察到第二层的变化，但是ClassA被\@Observed装饰，ClassA的属性的变化将被\@ObjectLink观察到。 304 305 306### 二维数组 307 308使用\@Observed观察二维数组的变化。可以声明一个被\@Observed装饰的继承Array的子类。 309 310 311```ts 312@Observed 313class StringArray extends Array<String> { 314} 315``` 316 317使用new StringArray()来构造StringArray的实例，new运算符使得\@Observed生效，\@Observed观察到StringArray的属性变化。 318 319声明一个从Array扩展的类class StringArray extends Array<String> {}，并创建StringArray的实例。\@Observed装饰的类需要使用new运算符来构建class实例。 320 321 322```ts 323@Observed 324class StringArray extends Array<String> { 325} 326 327@Component 328struct ItemPage { 329 @ObjectLink itemArr: StringArray; 330 331 build() { 332 Row() { 333 Text('ItemPage') 334 .width(100).height(100) 335 336 ForEach(this.itemArr, 337 item => { 338 Text(item) 339 .width(100).height(100) 340 }, 341 item => item 342 ) 343 } 344 } 345} 346 347@Entry 348@Component 349struct IndexPage { 350 @State arr: Array<StringArray> = [new StringArray(), new StringArray(), new StringArray()]; 351 352 build() { 353 Column() { 354 ItemPage({ itemArr: this.arr[0] }) 355 ItemPage({ itemArr: this.arr[1] }) 356 ItemPage({ itemArr: this.arr[2] }) 357 358 Divider() 359 360 ForEach(this.arr, 361 itemArr => { 362 ItemPage({ itemArr: itemArr }) 363 }, 364 itemArr => itemArr[0] 365 ) 366 367 Divider() 368 369 Button('update') 370 .onClick(() => { 371 console.error('Update all items in arr'); 372 if (this.arr[0][0] !== undefined) { 373 // 正常情况下需要有一个真实的ID来与ForEach一起使用，但此处没有 374 // 因此需要确保推送的字符串是唯一的。 375 this.arr[0].push(`${this.arr[0].slice(-1).pop()}${this.arr[0].slice(-1).pop()}`); 376 this.arr[1].push(`${this.arr[1].slice(-1).pop()}${this.arr[1].slice(-1).pop()}`); 377 this.arr[2].push(`${this.arr[2].slice(-1).pop()}${this.arr[2].slice(-1).pop()}`); 378 } else { 379 this.arr[0].push('Hello'); 380 this.arr[1].push('World'); 381 this.arr[2].push('!'); 382 } 383 }) 384 } 385 } 386} 387``` 388
