We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
GuidesApplication FrameworkArkUIUI Development (ArkTS-based Declarative Development Paradigm)Basic Syntax of UI ParadigmsComponent Encapsulation

Component Encapsulation

Last updated: 2026-09-10 06:21
Content overview
Expand

Description

In ArkUI app development, you may need to encapsulate UI components or styles. This encapsulation enables the reuse of identical or similar code functionality, thereby improving development efficiency while also facilitating project maintenance and team collaboration.

Typical component encapsulation scenarios include:

Common Component Style Encapsulation

Description

When developing different service features, you may need to use components with the same style. For example, the login button on the sign-in page and the checkout button on the shopping page—both within the same app and representing confirmation actions—may share the same UI style. In such cases, you can extract the common styles of the Button component, encapsulate them, and enable global reuse. The figure below shows a Button component in two different states: default and pressed.

How to Implement

The common style of a component is implemented by setting the attributes of the component. In ArkUI, you can use the AttributeModifier to encapsulate the attributes in the same AttributeModifier implementation class and apply the AttributeModifier instance object to the component whose style needs to be reused.

How to Develop

  1. The provider defines an implementation class for the AttributeModifier API to encapsulate common style attributes.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. export class MyButtonModifier implements AttributeModifier<ButtonAttribute> {
    2.   private buttonType: ButtonType = ButtonType.Normal;
    3. 

    4.   constructor() {
    5.   }
    6. 

    7.   applyNormalAttribute(instance: ButtonAttribute): void {
    8.     instance.type(this.buttonType);
    9.     instance.width(200);
    10.     instance.height(50);
    11.     instance.fontSize(20);
    12.     instance.fontColor('#0A59F7')
    13.     instance.backgroundColor('#0D000000')
    14.   }
    15. 

    16.   applyPressedAttribute(instance: ButtonAttribute): void {
    17.     instance.fontColor('#0A59F7')
    18.     instance.backgroundColor('#26000000')
    19.   }
    20. 

    21.   type(type: ButtonType): MyButtonModifier {
    22.     this.buttonType = type;
    23.     return this;
    24.   }
    25. }
    AttributeStylePage.ets

  2. The consumer creates an AttributeModifier instance and passes it as a parameter to the attributeModifier() method of the system component. The encapsulated styles are then applied to that component.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Entry
    2. @Component
    3. struct AttributeStylePage {
    4.   modifier = new MyButtonModifier()
    5.     .type(ButtonType.Capsule)
    6. 

    7.   build() {
    8.     NavDestination() {
    9.       Column() {
    10.         Button('Capsule Button')
    11.           .attributeModifier(this.modifier)
    12.       }
    13.       .margin({ top: $r('app.float.margin_top') })
    14.       .justifyContent(FlexAlign.Start)
    15.       .alignItems(HorizontalAlign.Center)
    16.       .width('100%')
    17.       .height('100%')
    18.     }
    19.     .title(getResourceString($r('app.string.common_style_extract'), this))
    20.   }
    21. }
    NOTE

    AttributeModifier applies only to system components. Attributes of custom components cannot be modified.

    AttributeModifier instances can be exported and reused across files, supporting modification of attributes and events for components in various states.

    For details, see AttributeModifier Usage.

Custom Component Encapsulation

Description

In app development, beyond UI styles, layouts and logic may also require reuse. In such cases, consider encapsulating UI content with the same functionality or style into a custom component. For example, the figure below shows a custom component containing an image and text, implemented through a vertical arrangement of an Image component and a Text component. The styles of the Image and Text components can be modified by the consumer.

How to Implement

Use @Component to create a custom component, encapsulate the static part in the component, and provide the variable part as parameters.

In this scenario, variables are added to set the attributeModifier() method of the child components. External consumers can then pass AttributeModifier instances via parameters, thereby enabling style modifications of the internal child components.

How to Develop

  1. The provider encapsulates default attribute styles: implementing the AttributeModifier API classes for the Image and Text components separately to provide methods to set customizable attributes such as width and height.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. export class CustomImageModifier implements AttributeModifier<ImageAttribute> {
    2.   private imageWidth: Length = 0;
    3.   private imageHeight: Length = 0;
    4. 

    5.   constructor(width: Length, height: Length) {
    6.     this.imageWidth = width;
    7.     this.imageHeight = height;
    8.   }
    9. 

    10.   width(width: Length) {
    11.     this.imageWidth = width;
    12.     return this;
    13.   }
    14. 

    15.   height(height: Length) {
    16.     this.imageHeight = height;
    17.     return this;
    18.   }
    19. 

    20.   applyNormalAttribute(instance: ImageAttribute): void {
    21.     instance.width(this.imageWidth);
    22.     instance.height(this.imageHeight);
    23.     instance.borderRadius($r('app.float.border_radius'))
    24. 

    25.   }
    26. }
    27. 

    28. export class CustomTextModifier implements AttributeModifier<TextAttribute> {
    29.   constructor() {
    30.   }
    31. 

    32.   applyNormalAttribute(instance: TextAttribute): void {
    33.     instance.fontSize($r('app.float.font_size_l'));
    34.   }
    35. }

  2. The provider encapsulates the custom component CustomImageText by adding relevant variables and applying default AttributeModifier objects to configure the Image and Text components.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Component
    2. export struct CustomImageText {
    3.   @Prop imageAttribute: AttributeModifier<ImageAttribute> = new CustomImageModifier(100, 100);
    4.   @Prop textAttribute: AttributeModifier<TextAttribute> = new CustomTextModifier();
    5.   @Prop imageSrc: PixelMap | ResourceStr | DrawableDescriptor;
    6.   @Prop text: string;
    7.   onClickEvent?: () => void;
    8. 

    9.   build() {
    10.     Column({ space: 12 }) {
    11.       Image(this.imageSrc)
    12.         .attributeModifier(this.imageAttribute)
    13.       Text(this.text)
    14.         .attributeModifier(this.textAttribute)
    15.     }.onClick(() => {
    16.       if (this.onClickEvent !== undefined) {
    17.         this.onClickEvent();
    18.       }
    19.     })
    20.   }
    21. }

  3. The consumer adds the CustomImageText component to their layout. They have the option to create implementation class instances of the AttributeModifier API for the Image and Text components and pass them as parameters to the CustomImageText component to modify its attribute styles.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Component
    2. struct CommonComponent {
    3.   imageAttribute: CustomImageModifier = new CustomImageModifier(330, 330);
    4. 

    5.   build() {
    6.     NavDestination() {
    7.       Column() {
    8.         CustomImageText({
    9.           imageAttribute: this.imageAttribute,
    10.           imageSrc: $r('app.media.image'),
    11.           text: 'Scenery',
    12.           onClickEvent: () => {
    13.             this.getUIContext().getPromptAction().showToast({ message: 'Clicked' })
    14.           }
    15.         })
    16.       }
    17.       .margin({ top: $r('app.float.margin_top') })
    18.       .justifyContent(FlexAlign.Start)
    19.       .alignItems(HorizontalAlign.Center)
    20.       .width('100%')
    21.       .height('100%')
    22.     }
    23.     .title(getResourceString($r('app.string.common'), this))
    24.   }
    25. }

Component Factory Class Encapsulation

Description

As shown in the figure below, team A has implemented a component factory class that encapsulates multiple components. In different development scenarios, team B wants to retrieve corresponding components from the factory class instance by using the component names. For instance, by passing the parameter TextInput or Radio to the instance, team B can obtain the TextInput or Radio component template, respectively.

How to Implement

The system provides the @Builder decorator, whose decorated methods comply with the syntax rules of the custom component build() function. After the method decorated by @Builder is passed to wrapBuilder, the WrappedBuilder object is returned. This object can be assigned and transferred.

With the wrapBuilder function, the component factory can store various components using a Map structure, where the key is the component name and the value is a WrappedBuilder object. During use, the corresponding component can be retrieved by its key value.

How to Develop

  1. On the component factory implementation side, encapsulate the components targeted for factory processing via global @Builder methods.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Builder
    2. function myRadio() {
    3.   Text($r('app.string.radio'))
    4.     .width('100%')
    5.     .fontColor($r('sys.color.mask_secondary'))
    6.   Row() {
    7.     Radio({ value: '1', group: 'radioGroup' })
    8.       .margin({ right: $r('app.float.margin_right') })
    9.     Text('man')
    10.   }
    11.   .width('100%')
    12. 

    13.   Row() {
    14.     Radio({ value: '0', group: 'radioGroup' })
    15.       .margin({ right: $r('app.float.margin_right') })
    16.     Text('woman')
    17.   }
    18.   .width('100%')
    19. }
    20. 

    21. @Builder
    22. function myCheckBox() {
    23.   Text($r('app.string.checkbox'))
    24.     .width('100%')
    25.     .fontColor($r('sys.color.mask_secondary'))
    26.   Row() {
    27.     CheckboxGroup({ group: 'checkboxGroup' })
    28.       .checkboxShape(CheckBoxShape.ROUNDED_SQUARE)
    29.     Text('all')
    30.       .margin({ left: $r('app.float.margin_right') })
    31.   }
    32.   .width('100%')
    33. 

    34.   Row() {
    35.     Checkbox({ name: '1', group: 'checkboxGroup' })
    36.       .shape(CheckBoxShape.ROUNDED_SQUARE)
    37.       .margin({ right: $r('app.float.margin_right') })
    38.     Text('text1')
    39.   }
    40.   .width('100%')
    41. 

    42.   Row() {
    43.     Checkbox({ name: '0', group: 'checkboxGroup' })
    44.       .shape(CheckBoxShape.ROUNDED_SQUARE)
    45.       .margin({ right: $r('app.float.margin_right') })
    46.     Text('text2')
    47.   }
    48.   .width('100%')
    49. }

  2. On the component factory implementation side, use the wrapBuilder function to wrap the encapsulated global @Builder methods and store the return values as values in the component factory Map. After all components are stored, export the component factory for external use.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. let factoryMap: Map<string, object> = new Map();
    2. 

    3. factoryMap.set('Radio', wrapBuilder(myRadio));
    4. factoryMap.set('Checkbox', wrapBuilder(myCheckBox));
    5. 

    6. export { factoryMap };

  3. The consumer imports the component factory and obtains the corresponding WrappedBuilder object based on a key value.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. import { factoryMap } from '../view/FactoryMap';
    2. // ...
    3. let myRadio: WrappedBuilder<[]> = factoryMap.get('Radio') as WrappedBuilder<[]>;
    4. let myCheckbox: WrappedBuilder<[]> = factoryMap.get('Checkbox') as WrappedBuilder<[]>;

  4. The consumer applies the specific component by calling the build() method of the WrappedBuilder object within the build() function.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Component
    2. struct ComponentFactory {
    3.   build() {
    4.     NavDestination() {
    5.       Column({ space: 12 }) {
    6.         myRadio.builder();
    7.         myCheckbox.builder();
    8.       }
    9.       .width('100%')
    10.       .padding($r('app.float.padding'))
    11.     }
    12.     .title(getResourceString($r('app.string.factory'), this))
    13.   }
    14. }
NOTE

The wrapBuilder method has the following constraints:

  1. The wrapBuilder method supports only the global @Builder method.
  2. As for the WrappedBuilder object returned by wrapBuilder, its builder attribute method can be used only inside the struct.

FAQs

How Do I Call Methods in Child Components?

Main approaches include:

  • Method 1: Using the Controller class

    1. Define the Controller class and add a method variable.
    2. Encapsulate a specific method in the child component, add the Controller variable, and assign the method value when the aboutToAppear() method is called.
    3. Create a Controller instance in the parent component and pass it to the child component. When the parent component executes the method in the Controller instance, it indirectly calls the method in the child component.
    Collapse
    Word wrap
    Dark theme
    Copy code
    1.     export class Controller {
    2.       action = () => {
    3.       };
    4.     }
    5.     
    6.     @Component
    7.     export struct ChildComponent {
    8.       @State bgColor: ResourceColor = Color.White;
    9.       controller: Controller | undefined = undefined;
    10.       private switchColor = () => {
    11.         if (this.bgColor === Color.White) {
    12.           this.bgColor = Color.Red;
    13.         } else {
    14.           this.bgColor = Color.White;
    15.         }
    16.       }
    17.     
    18.       aboutToAppear(): void {
    19.         if (this.controller) {
    20.           this.controller.action = this.switchColor;
    21.         }
    22.       }
    23.     
    24.       build() {
    25.         Column() {
    26.           Text('Child Component')
    27.         }.backgroundColor(this.bgColor).borderWidth(1)
    28.       }
    29.     }
    30.     
    31.     @Entry
    32.     @Component
    33.     struct Index {
    34.       private childRef = new Controller();
    35.     
    36.       build() {
    37.         Column() {
    38.           ChildComponent({ controller: this.childRef })
    39.     
    40.           Button('Switch Color')
    41.             .onClick(() => {
    42.               this.childRef.action();
    43.             })
    44.             .margin({ top: 16 })
    45.         }
    46.         .width('100%')
    47.         .alignItems(HorizontalAlign.Center)
    48.       }
    49.     }

  • Method 2: Using @Watch

    Use @Watch to listen to the state variable. When the parent component modifies the variable, the callback of @Watch is executed, that is, the method in the child component is called.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Component
    2. export struct ChildComponent {
    3.   @State bgColor: ResourceColor = Color.White;
    4.   @Link @Watch('switchColor') checkFlag: boolean;
    5. 

    6.   private switchColor() {
    7.     if (this.checkFlag) {
    8.       this.bgColor = Color.Red;
    9.     } else {
    10.       this.bgColor = Color.White;
    11.     }
    12.   }
    13. 

    14.   build() {
    15.     Column() {
    16.       Text('Child Component')
    17.     }.backgroundColor(this.bgColor)
    18.     .borderWidth(1)
    19.   }
    20. }
    21. 

    22. @Entry
    23. @Component
    24. struct Index {
    25.   @State childCheckFlag: boolean = false;
    26. 

    27.   build() {
    28.     Column() {
    29.       ChildComponent({ checkFlag: this.childCheckFlag })
    30. 

    31.       Button('Switch Color')
    32.         .onClick(() => {
    33.           this.childCheckFlag = !this.childCheckFlag;
    34.         })
    35.         .margin({ top: 16 })
    36.     }
    37.     .width('100%')
    38.     .alignItems(HorizontalAlign.Center)
    39.   }
    40. }

  • Approach 3: using Emitter

    The Emitter communication mechanism is used. An event listener is added to the child component, and the parent component emits the corresponding event. When the event is listened to, the method in the child component is called.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. @Component
    2. export struct ChildComponent {
    3.   public static readonly EVENT_ID_SWITCH_COLOR = 'SWITCH_COLOR';
    4.   @State bgColor: ResourceColor = Color.White;
    5.   private switchColor = () => {
    6.     if (this.bgColor === Color.White) {
    7.       this.bgColor = Color.Red;
    8.     } else {
    9.       this.bgColor = Color.White;
    10.     }
    11.   }
    12. 

    13.   aboutToAppear(): void {
    14.     emitter.on(ChildComponent.EVENT_ID_SWITCH_COLOR, this.switchColor);
    15.   }
    16. 

    17.   aboutToDisappear(): void {
    18.     emitter.off(ChildComponent.EVENT_ID_SWITCH_COLOR, this.switchColor);
    19.   }
    20. 

    21.   build() {
    22.     Column() {
    23.       Text('Child Component')
    24.     }.backgroundColor(this.bgColor)
    25.     .borderWidth(1)
    26.   }
    27. }
    28. 

    29. @Entry
    30. @Component
    31. struct Index {
    32.   build() {
    33.     Column() {
    34.       ChildComponent()
    35. 

    36.       Button('Switch Color')
    37.         .onClick(() => {
    38.           emitter.emit(ChildComponent.EVENT_ID_SWITCH_COLOR);
    39.         })
    40.         .margin({ top: 16 })
    41.     }
    42.     .width('100%')
    43.     .alignItems(HorizontalAlign.Center)
    44.   }
    45. }

How Do I Call Methods in Parent Components?

Add a callback method in the child component. When the parent component uses the child component, pass the method of the parent component as a parameter.

Collapse
Word wrap
Dark theme
Copy code
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { hilog } from '@kit.PerformanceAnalysisKit';
  3. 

  4. @Component
  5. export struct ChildComponent {
  6.   call = () => {
  7.   };
  8. 

  9.   build() {
  10.     Column() {
  11.       Button('Child Component')
  12.         .onClick(() => {
  13.           this.call();
  14.         })
  15.     }
  16.   }
  17. }
  18. 

  19. @Entry
  20. @Component
  21. struct Index {
  22.   parentAction() {
  23.     try {
  24.       this.getUIContext().getPromptAction().showToast({ message: 'Parent Action' });
  25.     } catch (error) {
  26.       let err = error as BusinessError;
  27.       hilog.warn(0x000, 'testTag', `showToast failed, code=${err.code}, message=${err.message}`);
  28.     }
  29.   }
  30. 

  31.   build() {
  32.     Column() {
  33.       ChildComponent({ call: this.parentAction })
  34.     }
  35.     .width('100%')
  36.     .alignItems(HorizontalAlign.Center)
  37.   }
  38. }

How Do I Extract Variable UI Content to Implement Slot-like Functionality?

Use the @BuilderParam parameter or @BuilderParam trailing closure method to expose the variable UI content as a variable in the encapsulated child component. When the parent component applies the child component, the specific UI content is implemented.

Collapse
Word wrap
Dark theme
Copy code
  1. @Component
  2. export struct ChildComponent {
  3.   @Builder
  4.   customBuilder() {
  5.   }
  6. 

  7.   @BuilderParam customBuilderParam: () => void = this.customBuilder;
  8. 

  9.   build() {
  10.     Column() {
  11.       Text('Text in Child')
  12.       this.customBuilderParam();
  13.     }
  14.   }
  15. }
  16. 

  17. @Entry
  18. @Component
  19. struct Index {
  20.   @Builder
  21.   componentBuilder() {
  22.     Text(`Parent builder`)
  23.   }
  24. 

  25.   build() {
  26.     Column() {
  27.       ChildComponent() {
  28.         this.componentBuilder();
  29.       }
  30.     }
  31.     .width('100%')
  32.     .alignItems(HorizontalAlign.Center)
  33.   }
  34. }

How Do I Pass a UI Component Array for ForEach Loop Rendering?

You can pack UI components into global @Builder, and then use wrapBuilder to encapsulate each @Builder in sequence. The obtained WrappedBuilder object or array can be used to pass parameters, and ForEach can be used to render the passed array.

For details, see Assigning a Value to a Variable by the @Builder Method to Use the Variable in UI Syntax.

Sample Code

Freezing a Custom Component (V2)
Component Extension
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice