Freerain

Posted on Dec 17

鸿蒙 Next 中 State 的使用方法介绍

在ArkUI框架中，@State装饰器用于管理组件内的状态，使得状态变化能够触发UI的更新。以下将详细介绍@State的使用方法。

一、概述

1. 定义与作用

@State装饰的变量，即状态变量，是私有的，只能在组件内部访问。它是大部分状态变量的数据源，一旦其值发生改变，就可以触发直接绑定UI组件的刷新，从而实现UI与数据状态的同步更新。

2. 支持的版本

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

3. 变量特点

单向/双向数据同步：与子组件中的@Prop装饰变量之间建立单向数据同步，与@Link、@ObjectLink装饰变量之间建立双向数据同步。
生命周期：其生命周期与其所属自定义组件的生命周期相同。

二、装饰器使用规则

1. 装饰器参数

无参数。

2. 同步类型

不与父组件中任何类型的变量同步。

3. 允许装饰的变量类型

Object、class、string、number、boolean、enum类型，以及这些类型的数组。
支持Date类型。
API 11及以上支持Map、Set类型。
支持undefined和null类型（建议显式指定类型）。
支持ArkUI框架定义的联合类型Length、ResourceStr、ResourceColor类型。
API 11及以上支持上述支持类型的联合类型，如string | number、string | undefined或者ClassA | null等。不支持any类型。

4. 被装饰变量的初始值

必须本地初始化，也可选择使用命名参数机制从父组件完成初始化（从父组件初始化将会覆盖本地初始化）。

三、变量的传递/访问规则

1. 从父组件初始化

支持父组件中常规变量（常规变量对@State赋值只是数值初始化，其变化不会触发UI刷新）、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰的变量来初始化子组件的@State。

2. 用于初始化子组件

@State装饰的变量支持初始化子组件的常规变量、@State、@Link、@Prop、@Provide。

3. 是否支持组件外访问

不支持，只能在组件内访问。

四、观察变化和行为表现

1. 观察变化

简单类型（boolean、string、number）：可以观察到数值的变化。例如：

@State count: number = 0;
this.count = 1; // 可观察到变化

class或Object类型：可以观察到自身的赋值变化和其属性赋值的变化（Object.keys(observedObject)返回的所有属性），但嵌套属性的赋值观察不到。例如：

class ClassA {
  public value: string;
  constructor(value: string) {
    this.value = value;
  }
}
class Model {
  public value: string;
  public name: ClassA;
  constructor(value: string, a: ClassA) {
    this.value = value;
    this.name = a;
  }
}
@State title: Model = new Model('Hello', new ClassA('World'));
this.title = new Model('Hi', new ClassA('ArkUI')); // 可观察到变化
this.title.value = 'Hi'; // 可观察到变化
this.title.name.value = 'ArkUI'; // 嵌套属性赋值观察不到

array类型：可以观察到数组本身的赋值和添加、删除、更新数组元素的变化，但数组元素中属性的赋值观察不到。例如：

class Model {
  public value: number;
  constructor(value: number) {
    this.value = value;
  }
}
@State title: Model[] = [new Model(11), new Model(1)];
this.title = [new Model(2)]; // 可观察到变化
this.title[0] = new Model(2); // 可观察到变化
this.title.pop(); // 可观察到变化
this.title.push(new Model(12)); // 可观察到变化
this.title[0].value = 6; // 数组元素属性赋值观察不到

Date类型：可以观察到Date整体的赋值，同时可通过调用Date的接口（如setFullYear、setMonth等）更新Date的属性。
Map类型（API 11及以上）：可以观察到Map整体的赋值，同时可通过调用Map的接口（如set、clear、delete）更新Map的值。
Set类型（API 11及以上）：可以观察到Set整体的赋值，同时可通过调用Set的接口（如add、clear、delete）更新Set的值。

2. 框架行为

当状态变量被改变时，框架会执行以下操作：

查询依赖该状态变量的组件。
执行依赖该状态变量的组件的更新方法，组件更新渲染。
和该状态变量不相关的组件或者UI描述不会发生重新渲染，从而实现页面渲染的按需更新。

五、使用场景

1. 装饰简单类型的变量

示例：

@Entry
@Component
struct MyComponent {
  @State count: number = 0;
  build() {
    Button(`click times: ${this.count}`)
    .onClick(() => {
        this.count += 1;
      })
  }
}

当count改变时，只有关联它的Button组件会刷新。

2. 装饰class对象类型的变量

示例：

class Model {
  public value: string;
  constructor(value: string) {
    this.value = value;
  }
}
@Entry
@Component
struct EntryComponent {
  build() {
    Column() {
      MyComponent({ count: 1, increaseBy: 2 })
      .width(300)
      MyComponent({ title: new Model('Hello World 2'), count: 7 })
    }
  }
}
@Component
struct MyComponent {
  @State title: Model = new Model('Hello World');
  @State count: number = 0;
  private increaseBy: number = 1;
  build() {
    Column() {
      Text(`${this.title.value}`)
      .margin(10)
      Button(`Click to change title`)
      .onClick(() => {
          this.title.value = this.title.value === 'Hello ArkUI'? 'Hello World' : 'Hello ArkUI';
        })
      .width(300)
      .margin(10)
      Button(`Click to increase count = ${this.count}`)
      .onClick(() => {
          this.count += this.increaseBy;
        })
      .width(300)
      .margin(10)
    }
  }
}

如果count或title的值发生变化，会查询MyComponent中使用该状态变量的UI组件并重新渲染。

3. 装饰Map类型变量（API 11及以上）

示例：

@Entry
@Component
struct MapSample {
  @State message: Map<number, string> = new Map([[0, "a"], [1, "b"], [3, "c"]]);
  build() {
    Row() {
      Column() {
        ForEach(Array.from(this.message.entries()), (item: [number, string]) => {
          Text(`${item[0]}`).fontSize(30)
          Text(`${item[1]}`).fontSize(30)
          Divider()
        })
        Button('init map').onClick(() => {
          this.message = new Map([[0, "a"], [1, "b"], [3, "c"]]);
        })
        Button('set new one').onClick(() => {
          this.message.set(4, "d");
        })
        Button('clear').onClick(() => {
          this.message.clear();
        })
        Button('replace the first one').onClick(() => {
          this.message.set(0, "aa");
        })
        Button('delete the first one').onClick(() => {
          this.message.delete(0);
        })
      }
    .width('100%')
    }
  .height('100%')
  }
}

点击按钮改变message的值，视图会随之刷新。

4. 装饰Set类型变量（API 11及以上）

示例：

@Entry
@Component
struct SetSample {
  @State message: Set<number> = new Set([0, 1, 2, 3, 4]);
  build() {
    Row() {
      Column() {
        ForEach(Array.from(this.message.entries()), (item: [number]) => {
          Text(`${item[0]}`).fontSize(30)
          Divider()
        })
        Button('init set').onClick(() => {
          this.message = new Set([0, 1, 2, 3, 4]);
        })
        Button('set new one').onClick(() => {
          this.message.add(5);
        })
        Button('clear').onClick(() => {
          this.message.clear();
        })
        Button('delete the first one').onClick(() => {
          this.message.delete(0);
        })
      }
    .width('100%')
    }
  .height('100%')
  }
}

点击按钮改变message的值，视图会随之刷新。

5. State支持联合类型实例

示例：

@Entry
@Component
struct EntryComponent {
  build() {
    Column() {
      MyComponent()
    }
  }
}
@Component
struct MyComponent {
  @State count: number | undefined = 0;
  build() {
    Column() {
      Text(`count(${this.count})`)
      Button('change')
      .onClick(() => {
          this.count = undefined;
        })
    }
  }
}

点击按钮改变count的属性或者类型，视图会随之刷新。

六、常见问题及解决方法

1. 使用箭头函数改变状态变量未生效

原因：箭头函数体内的this对象指向定义该函数时所在的作用域，而不是使用时所在的作用域。

解决方法：将当前this传入，调用代理状态变量的属性赋值。

2. 状态变量的修改放在构造函数内未生效

原因：在状态管理中，类会被一层“代理”包装。在构造函数中修改状态变量时，this指向未被代理封装的原始对象，后续触发事件无法响应变化。

解决方法：将状态变量的修改放在类的普通方法中，在对象初始化和代理封装完成后进行修改。

3. 状态变量只能影响其直接绑定的UI组件的刷新

示例说明：

简单类型值拷贝情况（如string），改变父组件中简单类型状态变量的值，不会影响子组件中同名但不同引用的简单类型状态变量。
对于对象类型，当在组件间传递对象引用时，改变对象的一层属性会触发相关组件刷新，但改变嵌套属性（观测能力仅有一层）时，可能无法触发某些组件的刷新。

理解这些@State的使用方法和特点，有助于在ArkUI开发中更好地管理组件状态，构建出响应式的用户界面。同时，注意常见问题的避免和解决，能够提高开发效率和代码质量。

DEV Community