Preface
In the previous section we introduced the @Styles decorator: defining component reuse styles, which can use @Styles for style extension. Today I will explain another decorator based on @Styles - @Extend decoration Container, which is also used to extend native component styles.
Note⚠️: Starting from API version 9, this decorator supports use in ArkTS cards.
@Extend decorator usage instructions
Next, I will introduce the specific usage instructions of the @Extend decorator in terms of syntax and usage rules.
1: Use syntax
@Extend(UIComponentName) function functionName {
... }
2:Usage rules
- Unlike @Styles, @Extend can only be defined globally and not within components.
- Unlike @Styles, @Extend supports encapsulating private properties and private events of specified components and predefining @Extend methods of the same component.
// @Extend(Text)可以支持Text的私有属性fontColor
@Extend(Text) function fancy () {
.fontColor(Color.Red)
}
// superFancyText可以调用预定义的fancy
@Extend(Text) function superFancyText(size:number) {
.fontSize(size)
.fancy()
}
- Unlike @Styles, methods decorated with @Extend support parameters. Developers can pass parameters when calling, and the call follows the TS method pass-by-value call.
// xxx.ets
@Extend(Text) function fancy (fontSize: number) {
.fontColor(Color.Red)
.fontSize(fontSize)
}
@Entry
@Component
struct FancyUse {
build() {
Row({
space: 10 }) {
Text('Fancy')
.fancy(16)
Text('Fancy')
.fancy(24)
}
}
}
- The parameter of the @Extend decorated method can be a function, which serves as the handle of the Event event.
@Extend(Text) function makeMeClick(onClick: () => void) {
.backgroundColor(Color.Blue)
.onClick(onClick)
}
@Entry
@Component
struct FancyUse {
@State label: string = 'Hello World';
onClickHandler() {
this.label = 'Hello ArkUI';
}
build() {
Row({
space: 10 }) {
Text(`${
this.label}`)
.makeMeClick(this.onClickHandler.bind(this))
}
}
}
- The parameters of @Extend can bestate variables. When the state variables change, the UI can be refreshed and rendered normally.
@Extend(Text) function fancy (fontSize: number) {
.fontColor(Color.Red)
.fontSize(fontSize)
}
@Entry
@Component
struct FancyUse {
@State fontSizeValue: number = 20
build() {
Row({
space: 10 }) {
Text('Fancy')
.fancy(this.fontSizeValue)
.onClick(() => {
this.fontSizeValue = 30
})
}
}
}
@Extend decorator usage scenarios
The following example declares three Text components, each of which has its fontStyle, fontWeight, and backgroundColor styles set.
@Entry
@Component
struct FancyUse {
@State label: string = 'Hello World'
build() {
Row({
space: 10 }) {
Text(`${
this.label}`)
.fontStyle(FontStyle.Italic)
.fontWeight(100)
.backgroundColor(Color.Blue)
Text(`${
this.label}`)
.fontStyle(FontStyle.Italic)
.fontWeight(200)
.backgroundColor(Color.Pink)
Text(`${
this.label}`)
.fontStyle(FontStyle.Italic)
.fontWeight(300)
.backgroundColor(Color.Orange)
}.margin('20%')
}
}
@Extend reuses style combinations. Examples are as follows.
@Extend(Text) function fancyText(weightValue: number, color: Color) {
.fontStyle(FontStyle.Italic)
.fontWeight(weightValue)
.backgroundColor(color)
}
Combining styles through @Extend makes the code more concise and enhances readability.
@Entry
@Component
struct FancyUse {
@State label: string = 'Hello World'
build() {
Row({
space: 10 }) {
Text(`${
this.label}`)
.fancyText(100, Color.Blue)
Text(`${
this.label}`)
.fancyText(200, Color.Pink)
Text(`${
this.label}`)
.fancyText(300, Color.Orange)
}.margin('20%')
}
}
Summarize
The @Extend decorator and the @Styles decorator both belong to the extended component style, thereby achieving the effect of taking the style. However, there are obvious differences between the two. We can use more specific usage scenarios and flexibly choose to use them based on the differences between the two.
- @Extend is used to extend native component styles based on @Styles.
- Unlike @Styles, @Extend can only be defined globally and not within components.
- Unlike @Styles, @Extend supports encapsulating private properties and private events of specified components and predefining @Extend methods of the same component.
- Unlike @Styles, methods decorated with @Extend support parameters. Developers can pass parameters when calling, and the call follows the TS method pass-by-value call.
- The parameter of the @Extend decorated method can be a function, which serves as the handle of the Event event. It can also be a state variable. When the state variable changes, the UI can be refreshed and rendered normally.