@Track装饰器：class对象属性级更新
======================

@Track应用于class对象的属性级更新。@Track装饰的属性变化时，只会触发该属性关联的UI更新。

在阅读本文档之前，建议开发者对状态管理基本观察能力有基本的了解。建议提前阅读：[@State](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-state)。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cf/v3/b7uA9RdYRT-5tAO-WXkcUg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132250Z&HW-CC-Expire=86400&HW-CC-Sign=67688CE38648D32C28A9726E099B4D53344988B7BAE583C05C7B77A18517943F)

从API version 11开始，该装饰器支持在ArkTS卡片中使用。

从API version 12开始，该装饰器支持在元服务中使用。

#### 概述

@Track是class对象的属性装饰器。当一个class对象是状态变量时，@Track装饰的属性发生变化，只会触发该属性关联的UI更新；如果class类中使用了@Track装饰器，则未被@Track装饰器装饰的属性不能在UI中使用，如果使用，会发生运行时报错。

#### class属性级更新说明

状态管理V1中@State等装饰器默认支持观察第一层属性的变化，第一层属性的变化虽然可以触发更新，但无法做到类属性级的观察，下面的例子就展示了这一限制：

import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN\_NUMBER: number = 0XFF00;
const TAG: string = '\[Sample\_StateTrack\]';
class Info {
  public name: string = 'Jack';
  public age: number = 12;
}

@Entry
@Component
struct Index {
  @State info: Info = new Info();

  // 借助getFontSize的日志打印，可以分辨哪个组件触发了渲染
  getFontSize(id: number): number {
    hilog.info(DOMAIN\_NUMBER, TAG, \`Component ${id} render\`);
    return 30;
  }

  build() {
    Column() {
      Text(\`name: ${this.info.name}\`)
        .fontSize(this.getFontSize(1))
      Text(\`age: ${this.info.age}\`)
        .fontSize(this.getFontSize(2))

      // 点击当前Button，可以发现当前虽然仅改变了name属性
      // 但是依旧会触发两个Text的刷新
      // Text(\`age: ${this.info.age}\`)是冗余刷新
      Button('change name').onClick(() => {
        this.info.name = 'Jane';
      })

      // 点击当前Button，可以发现当前虽然仅改变了age属性
      // 但是依旧会触发两个Text的刷新
      // Text(\`name: ${this.info.name}\`)是冗余刷新
      Button('change age').onClick(() => {
        this.info.age++;
      })
    }
    .height('100%')
    .width('100%')
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6a/v3/TQ3BCDRiR5eTTkoKBEoauA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132250Z&HW-CC-Expire=86400&HW-CC-Sign=A12B726B179EDEAD535E5B03979881714FBBE6A9149512E30E6BA9724097A922)

当UI刷新时，会执行组件的属性设置方法，利用这一机制可以通过观察getFontSize方法是否被调用来判断当前组件是否刷新。

*   UI首次渲染完成，观察到输出如下日志：
    
    Component 1 render
    Component 2 render
    
*   当点击Button('change name')时，即使只修改了info.name，观察日志发现两个Text组件仍会重新渲染。组件Text(\`age: ${this.info.age}\`)并未使用name属性，但仍因为info.name的改变而刷新，因此这次刷新是冗余的。日志输出如下：
    
    Component 1 render
    Component 2 render
    
*   同理，点击Button('change age')，也会触发Text(\`name: ${this.info.name}\`)的刷新。日志输出如下：
    
    Component 1 render
    Component 2 render
    

造成上述冗余刷新的根本原因是：状态管理V1中@State等装饰器无法精准观察类属性的访问与变更。为了实现类对象属性的精准观察，引入@Track装饰器。

#### 装饰器说明

| @Track变量装饰器 | 说明 |
| :-- | :-- |
| 装饰器参数 | 无 |
| 可装饰的变量 | class对象的非静态成员属性。@Track不支持观察Function类型的数据变化，修改@Track装饰的Function类型的数据，UI不会刷新。 |

#### 观察变化和行为表现

当一个class对象是状态变量时，@Track装饰的属性发生变化，该属性关联的UI触发更新。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cc/v3/GOw7U774T3-xgxZ4yF3OPw/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132250Z&HW-CC-Expire=86400&HW-CC-Sign=064DC8F01159B3D71F147169D4A712B9A8E8F5ED9468AC2FD352D75126BAAAC4)

当class对象中没有一个属性被标记@Track，行为与原先保持不变。@Track没有深度观测的功能。

使用@Track装饰器可以避免冗余刷新。

import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN\_NUMBER: number = 0XFF00;
const TAG: string = '\[Sample\_StateTrack\]';

class LogTrack {
  @Track public str1: string;
  @Track public str2: string;

  constructor(str1: string) {
    this.str1 = str1;
    this.str2 = 'World';
  }
}

class LogNotTrack {
  public str1: string;
  public str2: string;

  constructor(str1: string) {
    this.str1 = str1;
    this.str2 = 'World';
  }
}

@Entry
@Component
struct AddLog {
  @State logTrack: LogTrack = new LogTrack('Hello');
  @State logNotTrack: LogNotTrack = new LogNotTrack('Hello');

  isRender(index: number): number {
    hilog.info(DOMAIN\_NUMBER, TAG, \`Text ${index} is rendered\`);
    return 50;
  }

  build() {
    Row() {
      Column() {
        Text(this.logTrack.str1) // Text1
          .id('str1')
          .fontSize(this.isRender(1))
          .fontWeight(FontWeight.Bold)
        Text(this.logTrack.str2) // Text2
          .fontSize(this.isRender(2))
          .fontWeight(FontWeight.Bold)
        Button('change logTrack.str1')
          .id('str2')
          .onClick(() => {
            this.logTrack.str1 = 'Bye';
          })
        Text(this.logNotTrack.str1) // Text3
          .fontSize(this.isRender(3))
          .fontWeight(FontWeight.Bold)
        Text(this.logNotTrack.str2) // Text4
          .fontSize(this.isRender(4))
          .fontWeight(FontWeight.Bold)
        Button('change logNotTrack.str1')
          .onClick(() => {
            this.logNotTrack.str1 = 'Bye';
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

在上面的示例中：

1.  类LogTrack中的属性均被@Track装饰器装饰，点击按钮"change logTrack.str1"，此时Text1刷新，Text2不刷新，只有一条日志输出，避免了冗余刷新。
    
    Text 1 is rendered
    
2.  类LogNotTrack中的属性均未被@Track装饰器装饰，点击按钮"change logNotTrack.str1"，此时Text3、Text4均会刷新，有两条日志输出，存在冗余刷新。
    
    Text 3 is rendered
    Text 4 is rendered
    

#### 限制条件

*   如果class类中使用了@Track装饰器，那么该class类中非@Track装饰的属性不能在@Component UI中使用，包括不能绑定在组件上、不能用于初始化子组件，错误的使用将导致运行时报错，从API version 23开始，将返回错误码[140110](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-statemanagement#section140110-在ui中使用非track装饰的属性发生运行时报错)，详见[在UI中使用非@Track装饰的属性发生运行时报错](#在ui中使用非track装饰的属性发生运行时报错)；可以在非UI中使用非@Track装饰的属性，如事件回调函数中、生命周期函数中等。
    
*   API version 19及以后，@Track使用在[@ComponentV2](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-custom-components#componentv2)的UI中，不会引起运行时报错，但依旧不会刷新，详见[@Observed+@Track装饰的class（V1->V2）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-v1-v2-mixusage#传递class类型v1-v2)、[@Observed+@Track装饰的class（V2->V1）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-v1-v2-mixusage#传递class类型v2-v1)。
    
*   建议开发者不要混用包含@Track的class对象和不包含@Track的class对象，如联合类型中、类继承中等，容易在UI中误用非@Track装饰的属性，导致运行时报错。
    

#### 使用场景

#### \[h2\]@Track和自定义组件更新

以下示例展示组件更新和@Track的处理步骤。对象log是@State装饰的状态变量，logInfo是@Track装饰的成员属性，其余成员属性都是非@Track装饰的，而且也不准备在UI中更新它们的值。

import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN\_NUMBER: number = 0XFF00;
const TAG: string = '\[Sample\_StateTrack\]';
class Log {
  @Track public logInfo: string;
  public owner: string;
  public id: number;
  public time: Date;
  public location: string;
  public reason: string;

  constructor(logInfo: string) {
    this.logInfo = logInfo;
    this.owner = 'OH';
    this.id = 0;
    this.time = new Date();
    this.location = 'CN';
    this.reason = 'NULL';
  }
}

@Entry
@Component
struct AddLog {
  @State log: Log = new Log('origin info.');

  build() {
    Row() {
      Column() {
        Text(this.log.logInfo)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            // 没有被@Track装饰的属性可以在点击事件中使用。
            hilog.info(DOMAIN\_NUMBER, TAG, 'owner: ' + this.log.owner +
              ' id: ' + this.log.id +
              ' time: ' + this.log.time +
              ' location: ' + this.log.location +
              ' reason: ' + this.log.reason);
            this.log.time = new Date();
            this.log.id++;
            this.log.logInfo += ' info.';
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

处理步骤：

1.  AddLog自定义组件的Text.onClick点击事件自增字符串' info.'。
    
2.  由于@State log变量的@Track属性logInfo更改，Text重新渲染。
    

#### 常见问题

#### \[h2\]在UI中使用非@Track装饰的属性发生运行时报错

在UI中使用非@Track装饰的属性，运行时会报错，从API version 23开始，将返回错误码140110。需要给age也添加@Track装饰器。

class Person {
  // id被@Track装饰
  @Track id: number;
  // age未被@Track装饰
  age: number;

  constructor(id: number, age: number) {
    this.id = id;
    this.age = age;
  }
}

@Entry
@Component
struct Parent {
  @State parent: Person = new Person(2, 30);

  build() {
    // 没有被@Track装饰的属性不可以在UI中使用，运行时会报错
    Text(\`Parent id is: ${this.parent.id} and Parent age is: ${this.parent.age}\`)
  }
}