Descripción general de la gestión de estado

En la descripción anterior, la mayoría de las páginas que creamos eran interfaces estáticas. Si desea crear una interfaz dinámica e interactiva, debe introducir el concepto de "estado".

Representación de la figura 1

En el ejemplo anterior, la interacción del usuario con la aplicación desencadena un cambio de estado del texto, lo que hace que la interfaz de usuario se represente, cambiando la interfaz de usuario de "Hello World" a "Hello ArkUI".

En el marco de programación de la interfaz de usuario declarativa, la interfaz de usuario es el resultado de ejecución del estado del programa y el usuario crea un modelo de interfaz de usuario, en el que el estado de tiempo de ejecución de la aplicación es un parámetro. Cuando se cambian los parámetros, la interfaz de usuario también realizará los cambios correspondientes como resultado devuelto. La nueva representación de la interfaz de usuario provocada por estos cambios de estado en tiempo de ejecución se conoce colectivamente como el mecanismo de administración de estado en ArkUI.

Los componentes personalizados tienen variables, y las variables deben decorarse con decoradores para convertirse en variables de estado. Los cambios en las variables de estado harán que se actualice la representación de la interfaz de usuario. Si no usa variables de estado, la interfaz de usuario solo se puede representar durante la inicialización y no se actualizará más adelante. La siguiente figura muestra la relación entre Estado y Vista (UI).

Vista (IU): representación de la IU, generalmente se refiere a la descripción de la IU en el método de construcción del componente personalizado y el método decorado por @Builder.
Estado: Estado, generalmente se refiere a los datos decorados por el decorador. El usuario cambia los datos de estado activando el método de evento del componente. Un cambio en los datos de estado hace que la interfaz de usuario se vuelva a procesar.

concepto basico

Variables de estado: variables decoradas por decoradores de estado, los cambios provocarán actualizaciones de representación de la interfaz de usuario.
Variables regulares: Variables sin estado, generalmente utilizadas para cálculos auxiliares. Sus cambios nunca provocan una actualización de la interfaz de usuario.
Fuente de datos/fuente de sincronización: la fuente original de las variables de estado, que se pueden sincronizar con diferentes datos de estado. Por lo general, significa los datos que se pasan del componente principal al componente secundario.
Mecanismo de parámetro con nombre: el componente principal pasa el parámetro especificado a la variable de estado del componente secundario, que es el medio principal para pasar parámetros de sincronización para el principal y el secundario. Ejemplo: CompA: ({ aProp: this.aProp }).
Inicialización desde el componente principal: el componente principal utiliza el mecanismo de parámetros con nombre para pasar los parámetros especificados al componente secundario. El valor predeterminado de la inicialización local se sobrescribirá cuando se pase un valor del componente principal. Ejemplo:

@Component
struct MyComponent {
  @State count: number = 0;
  private increaseBy: number = 1;

  build() {
  }
}

@Component
struct Parent {
  build() {
    Column() {
      // 从父组件初始化，覆盖本地定义的默认值
      MyComponent({ count: 1, increaseBy: 2 })
    }
  }
}

Inicializar subnodos: las variables de estado del componente se pueden pasar a los subcomponentes para inicializar las variables de estado correspondientes a los subcomponentes. Mismo ejemplo que el anterior.
Inicialización local: cuando se declara la variable, se le asigna un valor como valor predeterminado para la inicialización. Ejemplo: @State cuenta: número = 0.

Resumen de decoradores

ArkUI proporciona una variedad de decoradores. Mediante el uso de estos decoradores, las variables de estado no solo pueden observar cambios dentro de los componentes, sino que también se pueden pasar entre diferentes niveles de componentes, como componentes padre-hijo, niveles de componentes cruzados y cambios globales. . De acuerdo con el alcance de la influencia de las variables de estado, todos los decoradores se pueden dividir aproximadamente en:

El decorador que gestiona el estado del componente: la gestión de estado a nivel de componente puede observar cambios en el componente y cambios en diferentes niveles de componente, pero solo necesita observar el mismo árbol de componentes, es decir, la misma página.
Decorator que administra el estado de la aplicación: administración de estado a nivel de aplicación, que puede observar los cambios de estado de diferentes páginas o incluso diferentes capacidades de UIA, y es una administración de estado global dentro de la aplicación.

Desde la perspectiva del formulario de transferencia de datos y el tipo de sincronización, los decoradores también se pueden dividir en:

pase unidireccional de solo lectura;
Transferencia bidireccional cambiable.

El diagrama es el siguiente: Para la introducción de decoradores específicos, consulte el estado propiedad del componente de gestión y el estado propiedad de la aplicación de gestión. Los desarrolladores pueden usar estas capacidades de manera flexible para realizar el vínculo entre los datos y la interfaz de usuario.

En la figura anterior, el decorador en la parte Componentes es la administración de estado a nivel de componente y la parte Aplicación es la administración de estado de la aplicación. Los desarrolladores pueden usar @StorageLink/@LocalStorageLink y @StorageProp/@LocalStorageProp para realizar una sincronización bidireccional y unidireccional de los estados de las aplicaciones y los componentes. La dirección de la flecha en la figura es la dirección de sincronización de datos, la flecha simple es la sincronización unidireccional y la flecha doble es la sincronización bidireccional.

El estado propiedad del componente de gestión, es decir, la gestión del estado a nivel de Componentes en la figura:

@State: la variable decorada por @State tiene el estado del componente al que pertenece y se puede utilizar como fuente de datos para la sincronización unidireccional y bidireccional de sus subcomponentes. Cuando su valor cambia, provocará la actualización de representación de los componentes relacionados.
@Prop: las variables decoradas con @Prop pueden establecer una relación de sincronización unidireccional con el componente principal. Las variables decoradas con @Prop son mutables, pero la modificación no se sincronizará con el componente principal.
@Link: La variable decorada por @Link y la variable de estado del componente principal crean una relación de sincronización bidireccional. El componente principal aceptará la sincronización de la modificación de la variable decorada por @Link y la actualización del componente principal. también se sincronizará con la variable decorada por @Link.
@Provide/@Consume: las variables decoradas con @Provide/@Consume se utilizan para sincronizar variables de estado entre niveles de componentes (componentes multicapa) y se pueden vincular a través de alias (alias) o nombre de propiedad sin pasar por el mecanismo de nomenclatura de parámetros.
@Observado: @Observado decora la clase, y la clase que necesita observar escenas anidadas de varias capas debe decorarse con @Observado. Usar @Observed solo no tiene ningún efecto y debe usarse junto con @ObjectLink y @Prop.
@ObjectLink: la variable decorada con @ObjectLink recibe una instancia de la clase decorada con @Observed, que se usa para observar escenas anidadas de varias capas y crear una sincronización bidireccional con la fuente de datos del componente principal.

ilustrar

Solo @Observed/@ObjectLink puede observar escenas anidadas, y otras variables de estado solo pueden observar la primera capa. Para obtener más detalles, consulte la sección "Observación de cambios y comportamientos" de cada capítulo del decorador.

Administre el estado propiedad de la aplicación, es decir, la administración del estado a nivel de la aplicación en la figura:

AppStorage es un objeto LocalStorage único especial en la aplicación. Es una base de datos de nivel de aplicación y está vinculada al proceso. Se puede vincular con componentes a través de los decoradores @StorageProp y @StorageLink.
AppStorage es el "centro" del estado de la aplicación. Los datos que deben interactuar con los componentes (IU) se almacenan en AppStorage, como los datos persistentes PersistentStorage y las variables de entorno Environment. Luego, la interfaz de usuario accede a estos datos a través del decorador o la interfaz API proporcionada por AppStorage;
El marco también proporciona LocalStorage y AppStorage es un singleton especial de LocalStorage. LocalStorage es la "base de datos" en memoria del estado de la aplicación declarado por la aplicación. Por lo general, se usa para compartir el estado a nivel de página. Los decoradores @LocalStorageProp y @LocalStorageLink se pueden vincular con la interfaz de usuario.

Otras funciones de gestión estatal

@Watch se utiliza para monitorear los cambios en las variables de estado.

Operador $$: proporcione una referencia a la variable TS para el componente integrado, de modo que la variable TS y el estado interno del componente integrado se mantengan sincronizados.

Administrar el estado propiedad de los componentes

@Estado decorador: estado dentro del componente

Las variables decoradas con @State, o variables de estado, están vinculadas a la representación del componente personalizado una vez que la variable tiene una propiedad de estado. Cuando el estado cambia, la interfaz de usuario tendrá un cambio de representación correspondiente.

Entre los decoradores relacionados con variables de estado, @State es el más básico, un decorador que permite que las variables tengan atributos de estado y también es la fuente de datos para la mayoría de las variables de estado.

descripción general

Las variables decoradas @State, al igual que otras variables decoradas en el paradigma declarativo, son privadas y solo se puede acceder a ellas desde dentro del componente, y deben especificar su tipo e inicialización local al declarar. La inicialización también se puede realizar opcionalmente desde el componente principal mediante el mecanismo de parámetro con nombre.

Las variables decoradas con @State tienen las siguientes características:

La sincronización de datos unidireccional o bidireccional se establece entre las variables decoradas @State y las variables decoradas @Prop, @Link u @ObjectLink en los subcomponentes.
El ciclo de vida variable de la decoración @State es el mismo que el ciclo de vida del componente personalizado al que pertenece.

Descripción de las reglas de uso del decorador

Decorador de variables @State	ilustrar
parámetros del decorador	ninguno
Tipo de sincronización	No sincronizado con variables de ningún tipo en el componente padre.
Tipos variables que permiten la decoración	Objeto, clase, cadena, número, booleano, tipos de enumeración y matrices de estos tipos. Se debe especificar el tipo. No se admite ninguno, los tipos de unión de tipos simples y tipos complejos no se admiten, y no se permiten valores indefinidos y nulos. ilustrar Se recomienda no decorar el tipo Fecha, ya que la aplicación puede producir un comportamiento anormal. Los tipos Longitud, ResourceStr y ResourceColor no se admiten, y Longitud, ResourceStr y ResourceColor son tipos de unión de tipos simples y tipos complejos.
El valor inicial de la variable decorada.	debe especificarse.

Explicación de las reglas de acceso/transferencia de variables

pase/acceso	ilustrar
Inicializar desde el componente principal	Opcional, inicialice desde el componente principal o localmente. Admite variables regulares en componentes principales, @State, @Link, @Prop, @Provide, @Consume, @ObjectLink, @StorageLink, @StorageProp, @LocalStorageLink y @LocalStorageProp variables decoradas e inicializa @State de componentes secundarios.
Se utiliza para inicializar componentes secundarios	Las variables decoradas con @State admiten la inicialización de variables regulares de subcomponentes, @State, @Link, @Prop, @Provide.
Ya sea para admitir el acceso fuera del componente	No compatible, solo accesible dentro de los componentes.

pase/acceso

ilustrar

Inicializar desde el componente principal

Opcional, inicialice desde el componente principal o localmente.

Admite variables regulares en componentes principales, @State, @Link, @Prop, @Provide, @Consume, @ObjectLink, @StorageLink, @StorageProp, @LocalStorageLink y @LocalStorageProp variables decoradas e inicializa @State de componentes secundarios.

Se utiliza para inicializar componentes secundarios

Las variables decoradas con @State admiten la inicialización de variables regulares de subcomponentes, @State, @Link, @Prop, @Provide.

Ya sea para admitir el acceso fuera del componente

No compatible, solo accesible dentro de los componentes.

Figura 1 Ilustración de las reglas de inicialización

Observar los cambios y el comportamiento.

No todos los cambios en las variables de estado harán que la interfaz de usuario se actualice, solo las modificaciones que el marco pueda observar harán que la interfaz de usuario se actualice. Esta sección presenta qué tipo de modificación se puede observar y cómo el marco hace que la interfaz de usuario se actualice después de observar el cambio, es decir, cuál es el comportamiento del marco.

observar cambios

Cuando el tipo de datos decorado es booleano, cadena, tipo de número, puede observar el cambio del valor.

// for simple type
@State count: number = 0;
// value changing can be observed
this.count = 1;

Cuando el tipo de datos decorado es clase u Objeto, puede observar el cambio de su propia asignación y el cambio de su asignación de atributos, es decir, todos los atributos devueltos por Object.keys(observedObject). Los ejemplos son los siguientes.

Declare las clases ClassA y Model.

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;
  }
}

El tipo de decoración @State es Modelo

// class类型
@State title: Model = new Model('Hello', new ClassA('World'));

Asignación a variables decoradas @State.

// class类型赋值
this.title = new Model('Hi', new ClassA('ArkUI'));

Asigne valores a las propiedades de las variables decoradas @State.

// class属性的赋值
this.title.value = 'Hi'

No se observan las asignaciones a propiedades anidadas.

// 嵌套的属性赋值观察不到
this.title.name.value = 'ArkUI'

Cuando el objeto decorado es una matriz, puede observar la asignación de la propia matriz y los cambios al agregar, eliminar y actualizar la matriz. Los ejemplos son los siguientes.

Declare las clases ClassA y Model.

class Model {
  public value: number;
  constructor(value: number) {
    this.value = value;
  }
}

Cuando el objeto decorado por @State es una matriz de tipo Model.

@State title: Model[] = [new Model(11), new Model(1)]

La asignación de la matriz en sí es observable.

this.title = [new Model(2)]

Se puede observar la asignación de los elementos de la matriz.

this.title[0] = new Model(2)

Se puede observar la eliminación de un elemento de matriz.

this.title.pop()

Se pueden observar elementos de matriz agregados.

this.title.push(new Model(12))

comportamiento del marco

Cuando se cambia la variable de estado, consulta los componentes que dependen de la variable de estado;
Ejecute el método de actualización del componente que depende de la variable de estado y el componente actualiza la representación;
Los componentes o las descripciones de la interfaz de usuario que no están relacionados con esta variable de estado no se volverán a representar, por lo que la representación de la página se puede actualizar a pedido.

Escenas a utilizar

Decoración de variables de tipos simples

El siguiente ejemplo es un tipo simple de decoración @State, el recuento está decorado por @State como una variable de estado y el cambio de recuento hace que el componente del botón se actualice:

Cuando cambia el conteo de la variable de estado, se encuentra que solo el componente Button está asociado con él;
Ejecute el método de actualización del componente Botón para realizar una actualización a pedido.

@Entry
@Component
struct MyComponent {
  @State count: number = 0;

  build() {
    Button(`click times: ${this.count}`)
      .onClick(() => {
        this.count += 1;
      })
  }
}

Decorar variables de tipo de objeto de clase

El componente personalizado MyComponent define el recuento de variables de estado y el título decorado por @State, donde el tipo de título es el modelo de clase personalizado. Si el valor de recuento o título cambia, consulta el componente de la interfaz de usuario mediante la variable de estado en MyComponent y vuelve a renderizar.
Hay varias instancias del componente MyComponent en EntryComponent y los cambios en el estado interno del primer MyComponent no afectarán al segundo MyComponent.

class Model {
  public value: string;

  constructor(value: string) {
    this.value = value;
  }
}

@Entry
@Component
struct EntryComponent {
  build() {
    Column() {
      // 此处指定的参数都将在初始渲染时覆盖本地定义的默认值，并不是所有的参数都需要从父组件初始化
      MyComponent({ count: 1, increaseBy: 2 })
      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}`)
      Button(`Click to change title`).onClick(() => {
        // @State变量的更新将触发上面的Text组件内容更新
        this.title.value = this.title.value === 'Hello ArkUI' ? 'Hello World' : 'Hello ArkUI';
      })

      Button(`Click to increase count=${this.count}`).onClick(() => {
        // @State变量的更新将触发该Button组件的内容更新
        this.count += this.increaseBy;
      })
    }
  }
}

A partir de este ejemplo, podemos entender el proceso de inicialización de la primera representación de la variable @State:

Utilice la inicialización local predeterminada:

@State title: Model = new Model('Hello World');
@State count: number = 0;

Para @State, el valor pasado por el mecanismo de parámetro con nombre no es obligatorio. Si no hay un valor pasado de parámetro con nombre, se usa el valor predeterminado de la inicialización local.

MyComponent({ count: 1, increaseBy: 2 })

Marco de desarrollo de HarmonyOS Learning Road Ark: aprendizaje del lenguaje ArkTS (Administración de estado 1)