• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# \@Extend Decorator: Extension of Built-in Components
2
3
4Apart from\@Styles used to extend styles, ArkUI also provides \@Extend, which allows you to add a new attribute feature to a built-in component.
5
6
7> **NOTE**
8> Since API version 9, this decorator is supported in ArkTS widgets.
9
10
11## Rules of Use
12
13
14### Syntax
15
16
17```ts
18@Extend(UIComponentName) function functionName { ... }
19```
20
21
22### Rules of Use
23
24- Unlike \@Styles, \@Extend can be defined only globally, that is, outside a component declaration.
25
26> **NOTE**
27> This decorator can be used only in the current file and cannot be exported.
28
29- Unlike \@Styles, \@Extend can encapsulate private attributes and events of specified components and predefine \@Extend decorated methods of the same component.
30
31  ```ts
32  // @Extend(Text) supports the private attribute fontColor of the <Text> component.
33  @Extend(Text) function fancy () {
34    .fontColor(Color.Red)
35  }
36  // superFancyText can call the predefined method fancy.
37  @Extend(Text) function superFancyText(size:number) {
38      .fontSize(size)
39      .fancy()
40  }
41  ```
42
43
44- Unlike \@Styles, \@Extend decorated methods support parameters. You can pass in parameters when calling such methods. Regular TypeScript provisions for method parameters apply.
45
46  ```ts
47  // xxx.ets
48  @Extend(Text) function fancy (fontSize: number) {
49    .fontColor(Color.Red)
50    .fontSize(fontSize)
51  }
52
53  @Entry
54  @Component
55  struct FancyUse {
56    build() {
57      Row({ space: 10 }) {
58        Text('Fancy')
59          .fancy(16)
60        Text('Fancy')
61          .fancy(24)
62      }
63    }
64  }
65  ```
66
67- A function can be passed as a parameter in an \@Extend decorated method. The function is used as the handler of an event.
68
69  ```ts
70  @Extend(Text) function makeMeClick(onClick: () => void) {
71    .backgroundColor(Color.Blue)
72    .onClick(onClick)
73  }
74
75  @Entry
76  @Component
77  struct FancyUse {
78    @State label: string = 'Hello World';
79
80    onClickHandler() {
81      this.label = 'Hello ArkUI';
82    }
83
84    build() {
85      Row({ space: 10 }) {
86        Text(`${this.label}`)
87          .makeMeClick(() => {this.onClickHandler()})
88      }
89    }
90  }
91  ```
92
93- A [state variable](arkts-state-management-overview.md) can be passed as a parameter in an \@Extend decorated method. When the state variable changes, the UI is re-rendered.
94
95  ```ts
96  @Extend(Text) function fancy (fontSize: number) {
97    .fontColor(Color.Red)
98    .fontSize(fontSize)
99  }
100
101  @Entry
102  @Component
103  struct FancyUse {
104    @State fontSizeValue: number = 20
105    build() {
106      Row({ space: 10 }) {
107        Text('Fancy')
108          .fancy(this.fontSizeValue)
109          .onClick(() => {
110            this.fontSizeValue = 30
111          })
112      }
113    }
114  }
115  ```
116
117
118## Use Scenarios
119
120The following example declares three **\<Text>** components. The **fontStyle**, **fontWeight**, and **backgroundColor** styles are set for each **\<Text>** component.
121
122
123```ts
124@Entry
125@Component
126struct FancyUse {
127  @State label: string = 'Hello World'
128
129  build() {
130    Row({ space: 10 }) {
131      Text(`${this.label}`)
132        .fontStyle(FontStyle.Italic)
133        .fontWeight(100)
134        .backgroundColor(Color.Blue)
135      Text(`${this.label}`)
136        .fontStyle(FontStyle.Italic)
137        .fontWeight(200)
138        .backgroundColor(Color.Pink)
139      Text(`${this.label}`)
140        .fontStyle(FontStyle.Italic)
141        .fontWeight(300)
142        .backgroundColor(Color.Orange)
143    }.margin('20%')
144  }
145}
146```
147
148\@Extend combines and reuses styles. The following is an example:
149
150
151```ts
152@Extend(Text) function fancyText(weightValue: number, color: Color) {
153  .fontStyle(FontStyle.Italic)
154  .fontWeight(weightValue)
155  .backgroundColor(color)
156}
157```
158
159With the use of \@Extend, the code readability is enhanced.
160
161
162```ts
163@Entry
164@Component
165struct FancyUse {
166  @State label: string = 'Hello World'
167
168  build() {
169    Row({ space: 10 }) {
170      Text(`${this.label}`)
171        .fancyText(100, Color.Blue)
172      Text(`${this.label}`)
173        .fancyText(200, Color.Pink)
174      Text(`${this.label}`)
175        .fancyText(300, Color.Orange)
176    }.margin('20%')
177  }
178}
179```
180