• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# \@Extend装饰器：定义扩展组件样式
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @BlYynNe-->
5<!--Designer: @lixingchi1-->
6<!--Tester: @TerryTsao-->
7<!--Adviser: @zhang_yixin13-->
8
9在前文的示例中，可以使用[\@Styles](arkts-style.md)用于样式的重用，在\@Styles的基础上，我们提供了\@Extend，用于扩展组件样式。
10
11
12> **说明：**
13>
14> 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
15>
16> 从API version 11开始，该装饰器支持在原子化服务中使用。
17
18## 装饰器使用说明
19
20
21### 语法
22
23
24```ts
25@Extend(UIComponentName) function functionName { ... }
26```
27
28
29### 使用规则
30
31- 和\@Styles不同，\@Extend支持封装指定组件的私有属性、私有事件和自身定义的全局方法。
32
33  ```ts
34  // @Extend(Text)可以支持Text的私有属性fontColor
35  @Extend(Text)
36  function fancy() {
37    .fontColor(Color.Red)
38  }
39
40  // superFancyText可以调用预定义的fancy
41  @Extend(Text)
42  function superFancyText(size: number) {
43    .fontSize(size)
44    .fancy()
45  }
46  ```
47
48
49- 和\@Styles不同，\@Extend装饰的方法支持参数，开发者可以在调用时传递参数，调用遵循TS方法传值调用。
50
51  ```ts
52  // xxx.ets
53  @Extend(Text)
54  function fancy(fontSize: number) {
55    .fontColor(Color.Red)
56    .fontSize(fontSize)
57  }
58
59  @Entry
60  @Component
61  struct FancyUse {
62    build() {
63      Row({ space: 10 }) {
64        Text('Fancy')
65          .fancy(16)
66        Text('Fancy')
67          .fancy(24)
68      }
69    }
70  }
71  ```
72
73- \@Extend装饰的方法的参数可以为function，作为Event事件的句柄。
74
75  ```ts
76  @Extend(Text)
77  function makeMeClick(onClick: () => void) {
78    .backgroundColor(Color.Blue)
79    .onClick(onClick)
80  }
81
82  @Entry
83  @Component
84  struct FancyUse {
85    @State label: string = 'Hello World';
86
87    onClickHandler() {
88      this.label = 'Hello ArkUI';
89    }
90
91    build() {
92      Row({ space: 10 }) {
93        Text(`${this.label}`)
94          .makeMeClick(() => {
95            this.onClickHandler();
96          })
97      }
98    }
99  }
100  ```
101
102- \@Extend的参数可以为[状态变量](arkts-state-management-overview.md)，当状态变量改变时，UI可以正常的被刷新渲染。
103
104  ```ts
105  @Extend(Text)
106  function fancy(fontSize: number) {
107    .fontColor(Color.Red)
108    .fontSize(fontSize)
109  }
110
111  @Entry
112  @Component
113  struct FancyUse {
114    @State fontSizeValue: number = 20;
115
116    build() {
117      Row({ space: 10 }) {
118        Text('Fancy')
119          .fancy(this.fontSizeValue)
120          .onClick(() => {
121            this.fontSizeValue = 30;
122          })
123      }
124    }
125  }
126  ```
127
128
129## 限制条件
130
131- 和\@Styles不同，\@Extend仅支持在全局定义，不支持在组件内部定义。
132
133> **说明：**
134>
135> 仅限在当前文件内使用，不支持导出。
136>
137> 如果要实现export功能，推荐使用[AttributeModifier](../../ui/arkts-user-defined-extension-attributeModifier.md)。
138
139【反例】
140
141```ts
142@Entry
143@Component
144struct FancyUse {
145  // 错误写法，@Extend仅支持在全局定义，不支持在组件内部定义
146  @Extend(Text) function fancy (fontSize: number) {
147    .fontSize(fontSize)
148  }
149
150  build() {
151    Row({ space: 10 }) {
152      Text('Fancy')
153        .fancy(16)
154    }
155  }
156}
157```
158
159【正例】
160
161```ts
162// 正确写法
163@Extend(Text)
164function fancy(fontSize: number) {
165  .fontSize(fontSize)
166}
167
168@Entry
169@Component
170struct FancyUse {
171  build() {
172    Row({ space: 10 }) {
173      Text('Fancy')
174        .fancy(16)
175    }
176  }
177}
178```
179
180
181## 使用场景
182
183以下示例声明了3个Text组件，每个Text组件均设置了fontStyle、fontWeight和backgroundColor样式。
184
185
186```ts
187@Entry
188@Component
189struct FancyUse {
190  @State label: string = 'Hello World';
191
192  build() {
193    Row({ space: 10 }) {
194      Text(`${this.label}`)
195        .fontStyle(FontStyle.Italic)
196        .fontWeight(100)
197        .backgroundColor(Color.Blue)
198      Text(`${this.label}`)
199        .fontStyle(FontStyle.Italic)
200        .fontWeight(200)
201        .backgroundColor(Color.Pink)
202      Text(`${this.label}`)
203        .fontStyle(FontStyle.Italic)
204        .fontWeight(300)
205        .backgroundColor(Color.Orange)
206    }.margin('20%')
207  }
208}
209```
210
211使用@Extend将样式组合复用，示例如下。
212
213
214```ts
215@Extend(Text)
216function fancyText(weightValue: number, color: Color) {
217  .fontStyle(FontStyle.Italic)
218  .fontWeight(weightValue)
219  .backgroundColor(color)
220}
221```
222
223通过\@Extend组合样式后，使得代码更加简洁，增强可读性。
224
225
226```ts
227@Entry
228@Component
229struct FancyUse {
230  @State label: string = 'Hello World';
231
232  build() {
233    Row({ space: 10 }) {
234      Text(`${this.label}`)
235        .fancyText(100, Color.Blue)
236      Text(`${this.label}`)
237        .fancyText(200, Color.Pink)
238      Text(`${this.label}`)
239        .fancyText(300, Color.Orange)
240    }.margin('20%')
241  }
242}
243```
244