• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# \@Extend Decorator: Defining Extended Component Styles
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @BlYynNe-->
5<!--SE: @lixingchi1-->
6<!--TSE: @TerryTsao-->
7
8Apart from [\@Styles](arkts-style.md) used to reuse styles, ArkUI also provides \@Extend for extending component styles.
9
10
11> **NOTE**
12>
13> This decorator can be used in ArkTS widgets since API version 9.
14>
15> This decorator can be used in atomic services since API version 11.
16
17## How to Use
18
19
20### Syntax
21
22
23```ts
24@Extend(UIComponentName) function functionName { ... }
25```
26
27
28### Usage Rules
29
30- Unlike \@Styles, \@Extend can encapsulate private attributes, private events, and globally defined methods of specific components.
31
32  ```ts
33  // @Extend(Text) supports the private attribute fontColor of the Text component.
34  @Extend(Text)
35  function fancy() {
36    .fontColor(Color.Red)
37  }
38
39  // superFancyText can call the predefined method fancy.
40  @Extend(Text)
41  function superFancyText(size: number) {
42    .fontSize(size)
43    .fancy()
44  }
45  ```
46
47
48- Unlike \@Styles, \@Extend enables decorated methods to accept parameters. When calling these methods, you pass parameters following standard TypeScript parameter passing conventions.
49
50  ```ts
51  // xxx.ets
52  @Extend(Text)
53  function fancy(fontSize: number) {
54    .fontColor(Color.Red)
55    .fontSize(fontSize)
56  }
57
58  @Entry
59  @Component
60  struct FancyUse {
61    build() {
62      Row({ space: 10 }) {
63        Text('Fancy')
64          .fancy(16)
65        Text('Fancy')
66          .fancy(24)
67      }
68    }
69  }
70  ```
71
72- Parameters passed into \@Extend decorated methods can be functions serving as event handlers.
73
74  ```ts
75  @Extend(Text)
76  function makeMeClick(onClick: () => void) {
77    .backgroundColor(Color.Blue)
78    .onClick(onClick)
79  }
80
81  @Entry
82  @Component
83  struct FancyUse {
84    @State label: string = 'Hello World';
85
86    onClickHandler() {
87      this.label = 'Hello ArkUI';
88    }
89
90    build() {
91      Row({ space: 10 }) {
92        Text(`${this.label}`)
93          .makeMeClick(() => {
94            this.onClickHandler();
95          })
96      }
97    }
98  }
99  ```
100
101- Parameters passed into \@Extend decorated methods can also be [state variables](arkts-state-management-overview.md). Changes to these state variables cause the UI to re-render.
102
103  ```ts
104  @Extend(Text)
105  function fancy(fontSize: number) {
106    .fontColor(Color.Red)
107    .fontSize(fontSize)
108  }
109
110  @Entry
111  @Component
112  struct FancyUse {
113    @State fontSizeValue: number = 20
114
115    build() {
116      Row({ space: 10 }) {
117        Text('Fancy')
118          .fancy(this.fontSizeValue)
119          .onClick(() => {
120            this.fontSizeValue = 30
121          })
122      }
123    }
124  }
125  ```
126
127
128## Constraints
129
130- Unlike \@Styles, \@Extend must be defined globally, outside of any component declaration.
131
132> **NOTE**
133>
134> Styles defined using \@Extend can be used only in the file where they are declared and cannot be exported to other files.
135>
136> For styles requiring cross-file reuse, you are advised to use [AttributeModifier](../../ui/arkts-user-defined-extension-attributeModifier.md).
137
138**Incorrect Usage**
139
140```ts
141@Entry
142@Component
143struct FancyUse {
144  // Incorrect. @Extend must be defined globally, outside of any component declaration.
145  @Extend(Text) function fancy (fontSize: number) {
146    .fontSize(fontSize)
147  }
148
149  build() {
150    Row({ space: 10 }) {
151      Text('Fancy')
152        .fancy(16)
153    }
154  }
155}
156```
157
158**Correct Usage**
159
160```ts
161// Correct usage.
162@Extend(Text)
163function fancy(fontSize: number) {
164  .fontSize(fontSize)
165}
166
167@Entry
168@Component
169struct FancyUse {
170  build() {
171    Row({ space: 10 }) {
172      Text('Fancy')
173        .fancy(16)
174    }
175  }
176}
177```
178
179
180## Use Cases
181
182The following example demonstrates how to use \@Extend for style reuse.<br>Original implementation, where three **Text** components are declared with individual **fontStyle**, **fontWeight**, and **backgroundColor** style settings:
183
184
185```ts
186@Entry
187@Component
188struct FancyUse {
189  @State label: string = 'Hello World';
190
191  build() {
192    Row({ space: 10 }) {
193      Text(`${this.label}`)
194        .fontStyle(FontStyle.Italic)
195        .fontWeight(100)
196        .backgroundColor(Color.Blue)
197      Text(`${this.label}`)
198        .fontStyle(FontStyle.Italic)
199        .fontWeight(200)
200        .backgroundColor(Color.Pink)
201      Text(`${this.label}`)
202        .fontStyle(FontStyle.Italic)
203        .fontWeight(300)
204        .backgroundColor(Color.Orange)
205    }.margin('20%')
206  }
207}
208```
209
210Using \@Extend for style composition and reuse:
211
212
213```ts
214@Extend(Text)
215function fancyText(weightValue: number, color: Color) {
216  .fontStyle(FontStyle.Italic)
217  .fontWeight(weightValue)
218  .backgroundColor(color)
219}
220```
221
222Simplified code with the use of \@Extend:
223
224
225```ts
226@Entry
227@Component
228struct FancyUse {
229  @State label: string = 'Hello World';
230
231  build() {
232    Row({ space: 10 }) {
233      Text(`${this.label}`)
234        .fancyText(100, Color.Blue)
235      Text(`${this.label}`)
236        .fancyText(200, Color.Pink)
237      Text(`${this.label}`)
238        .fancyText(300, Color.Orange)
239    }.margin('20%')
240  }
241}
242```
243