• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# \@Event Decorator: Standardizing Component Output
2
3You can use \@Event, a variable decorator in state management V2, to enable a child component to require the parent component to update the \@Param decorated variables. Using \@Event to decorate the callback method is a standard, indicating that the child component needs to pass in the callback for updating the data source.
4
5
6\@Event works with \@Param to implement two-way data synchronization. Before reading this topic, you are advised to read [\@Param](./arkts-new-param.md).
7
8>**NOTE**
9>
10>The \@Event decorator is supported since API version 12.
11>
12
13## Overview
14
15The variables decorated by \@Param cannot be changed locally. You can use the \@Event decorator to decorate a callback, which is called to change the variables of the data source. You can synchronize the changes to \@Param by using the synchronization mechanism of \@Local. In this way, the variables decorated by \@Param can be updated actively.
16
17When using \@Event to decorate a component:
18
19- You need to determine the parameters and return value in the callback decorated by \@Event.
20
21- Variables of non-callback types decorated by \@Event do not take effect. If \@Event is not initialized, an empty function will be automatically generated as the default callback.
22- If \@Event is not initialized externally but has a default value, the default function will be used for processing.
23
24\@Param indicates the input of a component, and this variable is affected by the parent component. \@Event indicates the output of a component, and the output method affects the parent component. Decorating a callback with \@Event indicates that the callback is the output of the custom component. The parent component needs to determine whether to provide the corresponding method for the child component to change the data source of the \@Param variable.
25
26## Decorator Description
27
28| \@Event Decorator| Description|
29| ------------------- | ------------------------------------------------------------ |
30| Decorator parameters| None.|
31| Allowed variable types| Callback, such as **()=>void** and **(x:number)=>boolean**. You can determine the return value and whether the callback contains parameters.|
32| Allowed function types| Arrow function.|
33
34## Constraints
35
36- \@Event can be used only in custom components decorated by \@ComponentV2. It does not take effect if the decorated variable is not a function.
37
38  ```ts
39  @ComponentV2
40  struct Index {
41    @Event changeFactory: ()=>void = ()=>{}; // Correct usage.
42    @Event message: string = "abcd"; // Incorrect usage. Variable of the non-function type is decorated.
43  }
44  @Component
45  struct Index {
46    @Event changeFactory: ()=>void = ()=>{}; // Incorrect usage. An error is reported during compilation.
47  }
48  ```
49
50
51## Use Scenarios
52
53### Changing Variables in the Parent Component
54
55You can use \@Event to change a variable in the parent component. When the variable is used as the data source of the \@Param variable in the child component, this change will be synchronized accordingly.
56
57```ts
58@Entry
59@ComponentV2
60struct Index {
61  @Local title: string = "Title One";
62  @Local fontColor: Color = Color.Red;
63
64  build() {
65    Column() {
66      Child({
67        title: this.title,
68        fontColor: this.fontColor,
69        changeFactory: (type: number) => {
70          if (type == 1) {
71            this.title = "Title One";
72            this.fontColor = Color.Red;
73          } else if (type == 2) {
74            this.title = "Title Two";
75            this.fontColor = Color.Green;
76          }
77        }
78      })
79    }
80  }
81}
82
83@ComponentV2
84struct Child {
85  @Param title: string = '';
86  @Param fontColor: Color = Color.Black;
87  @Event changeFactory: (x: number) => void = (x: number) => {};
88
89  build() {
90    Column() {
91      Text(`${this.title}`)
92        .fontColor(this.fontColor)
93      Button("change to Title Two")
94        .onClick(() => {
95          this.changeFactory(2);
96        })
97      Button("change to Title One")
98        .onClick(() => {
99          this.changeFactory(1);
100        })
101    }
102  }
103}
104```
105
106Note that using \@Event to change the value of the parent component takes effect immediately. However, the process of synchronizing the change from the parent component to the child component is asynchronous. That is, after the method of \@Event is called, the value of the child component does not change immediately. This is because \@Event passes the actual change capability of the child component value to the parent component for processing. After the parent component determines how to process the value, the final value is synchronized back to the child component before rendering.
107
108```ts
109@ComponentV2
110struct Child {
111  @Param index: number = 0;
112  @Event changeIndex: (val: number) => void;
113
114  build() {
115    Column() {
116      Text(`Child index: ${this.index}`)
117        .onClick(() => {
118          this.changeIndex(20);
119          console.log(`after changeIndex ${this.index}`);
120        })
121    }
122  }
123}
124@Entry
125@ComponentV2
126struct Index {
127  @Local index: number = 0;
128
129  build() {
130  	Column() {
131  	  Child({
132  	    index: this.index,
133  	    changeIndex: (val: number) => {
134  	      this.index = val;
135          console.log(`in changeIndex ${this.index}`);
136  	    }
137  	  })
138  	}
139  }
140}
141```
142
143In the preceding example, clicking the text triggers the \@Event function event to change the value of the child component. The printed log is as follows:
144
145```
146in changeIndex 20
147after changeIndex 0
148```
149
150This indicates that after **changeIndex** is called, the **index** in the parent component has changed, but the one in the child component has not changed yet.
151