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