DEV Community: HarmonyOS

The problem of multiple components in HarmonyOS using animateTo animations not being synchronized

HarmonyOS — Fri, 08 May 2026 01:51:00 +0000

Read the original article：The problem of multiple components in HarmonyOS using animateTo animations not being synchronized

Problem Description

In a HarmonyOS application, when using the animateTo method to implement property animations for two Column components, the animations are not executed synchronously.
The problematic code is as follows:

import { display } from '@kit.ArkUI';

const SCREEN_WIDTH = display.getDefaultDisplaySync().width;

@Entry
@Component
struct Index {
  @State translateX: number = SCREEN_WIDTH
  @State lastTranslateX: number = 0

  build() {
    Column() {
      Button('Triggering an animation')
        .onClick(() => this.startAnimation())
        .margin(100)
      Column() {
        Text('B')
          .fontSize(20)
      }
      .width('100%')
      .height(120)
      .backgroundColor('#f1f3f5')
      .opacity(1)
      .translate({ x: this.translateX })
      .alignItems(HorizontalAlign.Center)
      .justifyContent(FlexAlign.Center)

      Column() {
        Text('A')
          .fontSize(20)
      }
      .width('100%')
      .height(120)
      .backgroundColor('#f1f3f5')
      .opacity(1)
      .translate({ x: this.lastTranslateX })
      .alignItems(HorizontalAlign.Center)
      .justifyContent(FlexAlign.Center)
    }

  }

  private startAnimation() {
    this.getUIContext().animateTo({
      duration: 1800,
      curve: Curve.EaseOut
    }, () => {
      this.translateX = 0
      this.lastTranslateX = -SCREEN_WIDTH
    })
  }
}

Background Knowledge

Translate is a general property provided by HarmonyOS for setting the translation of components.
getDefaultDisplaySync is a method provided by the display module to obtain the current default display object. Through this object, you can access screen-related properties such as width.
UIContext provides the animateTo interface to specify transition animations for state changes caused by closure code.
onAreaChange is a component area change event that triggers this callback when the component's area changes. This function only responds to callbacks caused by layout changes that affect the component's size or position.

Problem Analysis

In the animateTo method, all statements are executed in sequence, not synchronously.

Analysis Conclusion

Since the statements in the animateTo method can only be executed sequentially, is it possible to use other callback functions to achieve synchronized animation effects? One approach that comes to mind is using the onAreaChange callback method to synchronize the animations.

Solution

Define the newValue state variable and use the onAreaChange callback method to obtain the real-time width of component A on the screen. Then, set the translation value based on the component's width.

The complete code is shown below:

@Entry
@Component
struct AnimationOutOfSync {
  @State lastTranslateX: number = 0;
  @State newValue: number = 0;
  @State translateX: number = this.newValue;

  build() {
    Column() {
      Button('Triggering an animation')
        .onClick(() => this.startAnimation())
        .margin(100)
      Column() {
        Text('B')
          .fontSize(20)
      }
      .width('100%')
      .height(120)
      .backgroundColor('#f1f3f5')
      .translate({ x: this.translateX })
      .opacity(1)
      // Use onAreaChange to obtain the width of the current component
      .onAreaChange((oldValue: Area, newValue: Area) => {
        this.newValue = newValue.width as number;
        this.translateX = newValue.width as number;
      })
      .alignItems(HorizontalAlign.Center)
      .justifyContent(FlexAlign.Center)

      Column() {
        Text('A')
          .fontSize(20)
      }
      .width('100%')
      .height(120)
      .backgroundColor('#f1f3f5')
      .translate({ x: this.lastTranslateX })
      .alignItems(HorizontalAlign.Center)
      .justifyContent(FlexAlign.Center)
    }
  }

  private startAnimation() {
    this.getUIContext()?.animateTo({
      duration: 1800,
      curve: Curve.EaseOut
    }, () => {
      this.translateX = 0;
      this.lastTranslateX = -this.newValue;
    });
  }
}

Written by Mehmet Emir Ucar

Text Binding Custom Menu

HarmonyOS — Fri, 08 May 2026 01:49:00 +0000

Read the original article：Text Binding Custom Menu

Problem Description

How to achieve the following effect by binding a custom menu to the Text component:

The menu displayed by bindSelectionMenu automatically disappears when the user touches the screen.
Long press to bring up the custom menu; double-tap gesture does not display the default menu.

Background Knowledge

The gesture binding method is used to bind different types of gesture events to a component and set the response methods for these events.
The bindSelectionMenu method can set a custom selection menu for Text. For usage details, please refer to the documentation on binding custom menus to text.

Solution

Add a click event to the outermost component of the page to close the menu, achieving the effect of the menu disappearing when the screen is touched.
The double-tap gesture to bring up the default menu is the system default specification. You can bind a double-tap event to the Text component to override the default behavior.

@Entry
@Component
struct BindMenuPage {
  controller: TextController = new TextController();

  build() {
    Column() {
      Text(undefined, { controller: this.controller }) {
        Span('Hello World');
        ImageSpan($r('app.media.startIcon')) // Image resources need to be replaced by yourself.
          .width('100px').height('100px');
      }
      .parallelGesture(
        // Rewrite the double-tap gesture event to close the menu.
        TapGesture({ count: 2 })
          .onAction(() => {
            this.controller.closeSelectionMenu();
          }), GestureMask.Normal)
      .copyOption(CopyOptions.InApp)
      // Set TextResponseType.LONG_PRESS to display a custom menu by long-pressing.
      .bindSelectionMenu(TextSpanType.DEFAULT, this.LongPressImageCustomMenu, TextResponseType.LONG_PRESS);
    }.width('100%').height('100%')
    .justifyContent(FlexAlign.Center)
    .onClick(() => {
      // Set a click event on the root node of the page to close the menu.
      this.controller.closeSelectionMenu(); // Close Menu
    });
  }

  @Builder
  LongPressImageCustomMenu() {
    Scroll() {
      Menu() {
        MenuItemGroup() {
          // Image resources need to be replaced by yourself.
          MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Long Press Image Menu 1', labelInfo: '' });
          MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Long Press Image Menu 2', labelInfo: '' });
          MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Long Press Image Menu 3', labelInfo: '' });
        };
      }
      .backgroundColor('#F0F0F0');
    };
  }
}

Verification Result

If change the content as "Menu 1":

Written by Mehmet Emir Ucar

Progress component to implement a clock-style progress bar

HarmonyOS — Fri, 08 May 2026 01:24:00 +0000

Read the original article：Progress component to implement a clock-style progress bar

Requirement Description

How can I create a 360-degree circular dial and add a white dashed line that follows the rotation around the circumference (similar to a clock hand)?

Background Knowledge

Progress Bar (Progress): Progress is a progress bar display component that typically shows the current progress of a target operation. For specific usage, please refer to Progress.

Implementation Steps

The circular progress bar refers to the progress bar in the official documentation. The dashed lines are set using the Divider() component, and the rotation angle follows the progress of the progress bar.

Code Snippet / Configuration

@Entry
@Component
struct Index {
  @State rotateAngle: number = 0
  uiContext: UIContext | undefined = undefined;

  aboutToAppear() {
    this.uiContext = this.getUIContext();
    if (!this.uiContext) {
      console.warn('no uiContext');
      return;
    }
  }

  build() {
    Column() {
      Column() {
        Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).width(100).height(100)
          .backgroundColor(Color.Black)
          .style({ scaleCount: 20, scaleWidth: 5 })

        Divider()
          .height(40)
          .width(0)
          .borderWidth(2)
          .margin({ top: -90 })
          // Set the rotation center using centerX and centerY
          .rotate({
            centerX: '100%',
            centerY: '100%',
            angle: this.rotateAngle
          })
          .onAppear(() => {
            this.uiContext?.animateTo({
              duration: 3000,
              curve: Curve.Linear,
              iterations: -1, // Setting -1 indicates that the animation loops indefinitely
            }, () => {
              this.rotateAngle = 360 * 20 / 150
            })
          })
      }.width('100%').height('100%')
    }
  }
}

Limitations or Considerations

This example supports API Version 19 Release and later versions.
This example supports HarmonyOS 5.1.1 Release SDK and later versions.
This example requires DevEco Studio 5.1.1 Release or later for building and running.

Written by Mehmet Emir Ucar

Passing parameters from a struct decorated with @ComponentV2 to a custom dialog decorated with @CustomDialog fails

HarmonyOS — Thu, 07 May 2026 01:21:00 +0000

Read the original article：Passing parameters from a struct decorated with @ComponentV2 to a custom dialog decorated with @CustomDialog fails

Problem Description

In the @ComponentV2 component, data cannot be directly passed to the @CustomDialog component.
The problematic code is as follows:

@ComponentV2
export struct Page {
  @Local selectIndex: number = 0;
  dialogController: CustomDialogController | null = new CustomDialogController({
    builder: AccountSafeDialog({
      selectIndex：this.selectIndex,
    }),
  })
  // ...
}
// Define pop-up window
@CustomDialog
export struct AccountSafeDialog {
  controller?: CustomDialogController;
  @Link selectIndex: number;
  // ...
}

Background Knowledge

The @ComponentV2 decorator is a custom component decorator used in conjunction with V2 state variables. Variables decorated with the @Link decorator share the same value as the data source in their parent component. The custom dialog CustomDialog is displayed through the CustomDialogController class, and both are only used in state management V1.
A pop-up window can be implemented by using the Dialog mode of NavDestination. In this case, the entire NavDestination area is transparent by default, with no component occupying the space.

Troubleshooting Process

Running the code results in an error:

error message:undefined 'selectIndex'[-21]
<@Component 'AccountSafeDialog'[375]>:
constructor: source variable in parent/ancestor @Component must be defined. Application error!

The error message indicates that the variable selectIndex cannot be found. In the code, selectIndex is decorated with @Local, which means this variable is passed from the parent component. Upon checking the parent component, it was found to be decorated with @ComponentV2, indicating a different state management version compared to the @CustomDialog decorator used in the child component.

Analysis Conclusion

There is a state management version incompatibility between components decorated with @ComponentV2 and custom dialog components decorated with @CustomDialog, which prevents data from being correctly passed to the custom dialog components decorated with @CustomDialog.

Solution

You can replace @CustomDialog with a Page using @ComponentV2 and implement the pop-up dialog using the DIALOG mode of Navigation.
Example code is as follows:

In Index.ets, use the pushPathByName method to push the specified NavDestination page information onto the stack.

@Entry
@ComponentV2
struct NavigationExample {
  pageInfos: NavPathStack = new NavPathStack();
  @Local selectIndex: number = 10

  build() {
    Navigation(this.pageInfos) {
      Column() {
        Button('pushPath', { stateEffect: true, type: ButtonType.Capsule })
          .width('80%')
          .height(40)
          .margin(20)
          .onClick(() => {
            this.pageInfos.pushPathByName('pageOne', this.selectIndex, () => {
            }, false); // Push the NavDestination page information specified by name onto the stack
          })
      }
    }.title('NavIndex')
  }
}

2.Create PageOne.ets as a pop-up page and set the mode of NavDestination to DIALOG mode.

@Builder
export function PageOneBuilder(name: string, param: Object) {
  PageOne()
}

@ComponentV2
export struct PageOne {
  pageInfos: NavPathStack = new NavPathStack();
  @Local selectIndex: number = 0

  build() {
    NavDestination() {
      Column() {
        Text(this.selectIndex.toString())
      }
    }
    .onReady(context => {
      this.selectIndex = context.pathInfo.param as number;
    })
    .position({ left: 50, top: 200 })
    .backgroundColor(Color.Pink)
    .width(300)
    .height(300)
    .mode(NavDestinationMode.DIALOG)
    .hideBackButton(true)
  }
}

3.In the module.json5 configuration file under the src/main directory, configure the routerMap field in the module section as "routerMap": "$profile:router_map", and add a new router_map.json file in the src/main/resources/base/profile directory. An example of router_map.json is as follows:

{
  "routerMap": [
    {
      "name": "pageOne",
      "pageSourceFile": "src/main/ets/pages/PageOne.ets",
      "buildFunction": "PageOneBuilder",
      "data": {
        "description": "this is pageOne"
      }
    }
  ]
}

Limitations or Considerations

This example supports API Version 19 Release and later versions.
This example supports HarmonyOS 5.1.1 Release SDK and later versions.
This example requires DevEco Studio 5.1.1 Release or later for building and running.

Written by Mehmet Emir Ucar

How to implement the effect of switching images by sliding the Slider

HarmonyOS — Thu, 07 May 2026 01:15:00 +0000

Read the original article：How to implement the effect of switching images by sliding the Slider

How to implement the effect of switching images by sliding the Slider

Context

This guide explains how to implement image switching functionality using the Slider component, where images are displayed on the left side and change as the slider is moved.

Description

How to display images on the left side of a Slider component and switch images accordingly when sliding.

The Slider component is typically used for quickly adjusting setting values, such as volume or brightness control.
- onChange: Event callback triggered when the Slider is dragged or clicked.
- blockStyle: Sets the slider block shape parameters.
overlay: Can set a floating layer for components.

Solution

To implement image switching with Slider, first bind images to the Slider, then listen for value changes through the onChange event. Steps are as follows:

Bind images to the Slider using overlay:

@Builder
OverlayNode() {
  Column() {
    Image($r(this.icon)) // Resources can be cited according to actual circumstances.
  }.width(40).height(40).alignItems(HorizontalAlign.Center).margin({ left: 10 })
};Copy codeCopy code
Slider({ style: SliderStyle.NONE, value: 20 })
  .overlay(this.OverlayNode(), { align: Alignment.Start })

Listen to the onChange event to switch different images based on the value:

.onChange(value => {
  if (value < 20) {
    this.icon = this.iconList[0];
  } else if (value >= 20 && value <= 30) {
    this.icon = this.iconList[1];
  } else if (value > 30 && value <= 40) {
    this.icon = this.iconList[2];
  } else if (value > 40 && value <= 50) {
    this.icon = this.iconList[3];
  } else if (value > 50 && value <= 60) {
    this.icon = this.iconList[4];
  } else if (value > 60 && value <= 70) {
    this.icon = this.iconList[5];
  } else {
    this.icon = this.iconList[6];
  };
});

Complete code:

// Start solution1
@Entry
@Component
struct SliderDemo {
  @State icon: string = 'sys.media.AI_phone';
  iconList: Array<string> = ['sys.media.AI_translate', 'sys.media.AI_circle_viewfinder', 'sys.media.AI_retouch',
    'sys.media.battery_bolt_fill', 'sys.media.AI_phone', 'sys.media.calendar_badge_play', 'sys.media.battery_bolt_fill'];
  // Start solution2
  @Builder
  OverlayNode() {
    Column() {
      Image($r(this.icon)) // Resources can be cited according to actual circumstances.
    }.width(40).height(40).alignItems(HorizontalAlign.Center).margin({ left: 10 })
  };
  // End solution2
  build() {
    Column() {
      // Start solution3
      Slider({ style: SliderStyle.NONE, value: 20 })
        .overlay(this.OverlayNode(), { align: Alignment.Start })
        // End solution3
        .trackThickness(60)
        .trackColor('#e0e0e0')
        .selectedColor(Color.White)
        .width('90%')
        .margin({ left: '5%', top: '40%' })
        .blockStyle({ type: SliderBlockType.IMAGE, image: $r(this.icon) }) // Resources can be cited according to actual circumstances.
        // Start solution4
        .onChange(value => {
          if (value < 20) {
            this.icon = this.iconList[0];
          } else if (value >= 20 && value <= 30) {
            this.icon = this.iconList[1];
          } else if (value > 30 && value <= 40) {
            this.icon = this.iconList[2];
          } else if (value > 40 && value <= 50) {
            this.icon = this.iconList[3];
          } else if (value > 50 && value <= 60) {
            this.icon = this.iconList[4];
          } else if (value > 60 && value <= 70) {
            this.icon = this.iconList[5];
          } else {
            this.icon = this.iconList[6];
          };
        });
      // End solution4
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#ffececec')
  }
}
// End solution1

Implementation effect:

Limitations or Considerations

This example supports API Version 19 Release and above
Requires HarmonyOS 5.1.1 Release SDK or later
Must use DevEco Studio 5.1.1 Release or newer for compilation and execution

Key Takeaways

Use the overlay attribute to position images relative to the Slider component
Implement onChange event handler to detect slider value changes
Bind different images to different slider values for visual feedback
This implementation requires API Version 19 Release or higher
Compatible with HarmonyOS 5.1.1 Release SDK and above
Requires DevEco Studio 5.1.1 Release or newer for compilation

Written by Mehmet Emir Ucar

How to Exit Slide-Out Mode When Clicking on a Blank Area

HarmonyOS — Thu, 07 May 2026 01:11:00 +0000

Read the original article：How to Exit Slide-Out Mode When Clicking on a Blank Area

Context

When the type of the SideBarContainer component is set to Overlay, how can we implement exiting the slide-out state by clicking on the blank area?

Background Check

SidebarContainer: Create a sidebar container that can toggle visibility, where the first child component is the sidebar and the second is the content area.
Component Transition(transition):The transition within components is primarily configured through the transition property, which displays transitional animations when components are inserted or removed. This is mainly used for enhancing user experience when subcomponents are inserted or removed within container components.

Solution / Approach

Set up two buttons to open and close the sidebar respectively. Use transition and timers to customize the sidebar's entrance and exit animations. Control the visibility of the sidebar through the showSideBar property of the SideBarContainer component. To achieve this, add the click event for closing the sidebar to a blank area. A complete example is as follows:

@Entry
@Component
struct SideBarContainerDemo {
  @State arr: number[] = [1, 2, 3]
  @State current: number = 1
  @State showSideBar: boolean = false
  @State showFlag: Visibility = Visibility.Hidden;

  // Delay closing the sidebar to allow custom entrance animations to display.
  cancel() {
    this.showFlag = Visibility.Hidden
    setTimeout(() => {
      this.showSideBar = !this.showSideBar
    }, 1000)
  }

  build() {
    // Set the type of SideBarContainer to Overlay. 
    SideBarContainer(SideBarContainerType.Overlay) {
      Column() {
        ForEach(this.arr, (item: number) => {
          Column({ space: 5 }) {
            Text('Index0' + item)
              .fontSize(25)
              .fontColor(this.current === item ? '#0A59F7' : '#999')
              .fontFamily('source-sans-pro,cursive,sans-serif')
          }
          .onClick(() => {
            this.current = item
          })
        }, (item: string) => item)
      }
      .visibility(this.showFlag)
      // Customize entrance animations through transition 
      .transition(TransitionEffect.OPACITY
        .animation({ duration: 1000 })
        .combine(TransitionEffect.translate({ x: 100 })))
      .width('100%')
      .justifyContent(FlexAlign.SpaceEvenly)
      .backgroundColor('#ffa2cdff')

      Column() {
        Button('Open the sidebar').onClick(() => {
          this.showFlag = Visibility.Visible
          this.showSideBar = true
        })
          .margin({ top: 16, bottom: 16 })
        Button('Close the sidebar').onClick(() => {
          this.cancel()
        })
      }.height('100%')
      // Click on a blank area to exit the slide-out state.
      .onClick(() => {
        this.cancel()
      })
    }
    .divider(null)
    .sideBarPosition(SideBarPosition.End)
    // Whether to display the sidebar
    .showSideBar(this.showSideBar)
    .showControlButton(false)
    .sideBarWidth(150)
    .minSideBarWidth(50)
    .maxSideBarWidth(300)
    .minContentWidth(0)
    .onChange((value: boolean) => {
      console.info('status:' + value)
    })
  }
}

Limitations or Considerations

This example supports API Version 19 Release and above.
This example supports HarmonyOS 5.1.1 Release SDK and above.
This example requires DevEco Studio 5.1.1 Release and above for compilation and execution.

Written by Mehmet Emir Ucar

After the properties of an array object change, the UI rendering cannot be triggered to refresh

HarmonyOS — Wed, 06 May 2026 01:42:00 +0000

Read the original article：After the properties of an array object change, the UI rendering cannot be triggered to refresh

Problem Description

Define the Item class and decorate it with @Observed to make it a deeply observable class. In the parent component, define items as an array of Item objects and render them using a ForEach loop. In the child component, use the @ObjectLink decorator. However, after the properties of the array objects change, the UI rendering does not refresh. The problematic code is as follows:

@Observed
class Item {
  name: string = '';
  num: number = 0;
}

@Component
@Entry
struct Index {
  @State items: Item[] = [
    { name: 'Zhang San', num: 18 },
    { name: 'Li Si', num: 20 },
  ]

  build() {
    Column() {
      ForEach(this.items, (item: Item) => {
        MyItem({ item: item })
      })
    }
  }
}

@Component
struct MyItem {
  @ObjectLink item: Item

  build() {
    Row() {
      Text(this.item.name)
      Row() {
        Button('+').onClick(() => {
          this.item.num++
        })
        Row() {
          Text(`${this.item.num}`)
        }
        .width(50)
        .justifyContent(FlexAlign.Center)

        Button('-').onClick(() => {
          this.item.num--
        })
      }
    }
    .margin({
      top: 20
    })
    .justifyContent(FlexAlign.SpaceAround)
    .width('100%')
  }
}

Background Knowledge

@Observed/@ObjectLink: Used for observing nested scenarios, such as two-dimensional arrays, object arrays, and nested class scenarios, where deep property changes need to be observed. @Observed and @ObjectLink must be used together.
makeV1Observed: Wraps an unobservable object into a state-managed V1 observable object, with capabilities equivalent to @Observed, and allows initialization of @ObjectLink.

Troubleshooting Process

For the issue where state variables do not trigger UI updates, you can generally consider the following aspects (other special scenarios require special considerations):
1.The rules governing the decorator's behavior. For @Observed/@ObjectLink, according to the official documentation, a class needs to meet the following conditions to be observable:

The declared state variables must be created using the new character.
If this class is a deeply nested class, you need to ensure that the deep-level class containing the observed property is also decorated with @Observed.
In child components, use @Prop to receive state variables. However, if you modify these variables within the child component, it will not trigger a refresh in the parent component. Instead, you should use @ObjectLink to receive state variables.

2.Summarize the rules for parameter passing. When passing state variables, if subcomponents use @Builder or @LocalBuilder, it is also important to consider the issues of value passing versus reference passing.

Based on the considerations above, the following checks are made:

1.Verify whether the source data has changed: Print logs after clicking the button to check if the data itself has changed. By comparing the logs, it was found that the data had indeed changed, but it did not trigger a UI rendering refresh.

09-26 10:23:51.944   1748-1748     A03d00/JSAPP                    com.example.test19    I     Zhang San：19
09-26 10:23:52.837   1748-1748     A03d00/JSAPP                    com.example.test19    I     Zhang San：20
09-26 10:23:54.827   1748-1748     A03d00/JSAPP                    com.example.test19    I     Li Si：21
09-26 10:23:55.430   1748-1748     A03d00/JSAPP                    com.example.test19    I     Li Si：22

2.According to the rules of decorator usage, check whether it is used correctly:

The state variable items is an array object, and the objects within the array are declared using literal notation rather than being created with the new operator, which does not conform to the intended usage rules.
Object arrays also fall under a type of deep nesting. The class of the property being modified is decorated with @Observed, which complies with the rules.
In the problem code, there is no modification of child components involved, and the parent component's display behavior is observed. The child component uses @ObjectLink to receive parameters passed from the parent component, which complies with the rules.

3.The custom builder function @Builder or @LocalBuilder does not exist in the problem code, so this check is ignored.

Analysis Conclusion

In summary, the issue of the UI not refreshing in the code is due to the fact that the new operator was not used when declaring the state variable, causing the UI to fail to update when the data changes.

Solution

Option 1: Modify the method of creating objects originally done through literals to use the new keyword instead. This task can be implemented in the aboutToAppear callback. The parent component's code is modified as follows:

aboutToAppear(): void {
  this.items = this.items.map((item) => {
    let cur = new Item()
    cur.name = item.name
    cur.num = item.num
    return cur
  })
}

Map each item in the this.items array to a new Item instance, copying the name and num properties of the original item to the new instance. Finally, this.items is updated to this new array.

Option 2: In state management, to address the issue where certain classes in third-party packages cannot be decorated by the state management decorator, leading to UI not being refreshed, the makeV1Observed interface was introduced in version 1 of the state management system to enable deep listening for regular variables. Import UIUtils and modify the code as follows:

@State items: Item[] = [
  UIUtils.makeV1Observed({ name: 'Zhang San', num: 18 }),
  UIUtils.makeV1Observed({ name: 'Li Si', num: 20 })
]

Limitations or Considerations

This example supports API Version 19 Release and later versions.
This example supports HarmonyOS 5.1.1 Release SDK and later versions.
This example requires DevEco Studio 5.1.1 Release or later for compilation and running.

Written by Mehmet Emir Ucar

Wear Engine setFingerprint() 206 Error

HarmonyOS — Wed, 06 May 2026 01:19:00 +0000

Read the original article：Wear Engine setFingerprint() 206 Error

Problem Description

When calling setFingerprint() in Huawei Wear Engine, a 206 error is encountered. The root cause lies in incorrect fingerprint value formatting, particularly with the public key used in the certificate.

Background Knowledge

The fingerprint must be the public key (in base64 format) derived from a valid certificate file (.cer). The correct method involves extracting the last certificate block and encoding the public key.

Troubleshooting Process

Open the .cer file, and copy the last paragraph (from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----) into a new .cer file.
Open this new .cer file, click Details, and select Public Key to obtain the pubKey.
Convert the pubKey into Base64 format. You may use a third-party tool such as tomeko.net.
Example Base64 encoded string: BC5Z9/29Yn93xSa9XkQ2HN5GikugmXjor9se0VwnOENK9t4uFK4VlRpOHv4B3lphjIa7P6Sh61CFRsT0MZNhuV8=
Construct the fingerprint using the format: <App Package Name>_<Base64EncodedPubKey>
Example: com.huawei.wearengine_BC5Z9/29Yn93xSa9XkQ2HN5GikugmXjor9se0VwnOENK9t4uFK4VlRpOHv4B3lphjIa7P6Sh61CFRsT0MZNhuV8=

Analysis Conclusion

The 206 error is caused by an improperly formed fingerprint string. The fingerprint must follow the structure defined above, ensuring it matches the base64-encoded public key of the .cer certificate used.

Solution

·Extract the correct certificate section

·Obtain the public key

·Encode it properly in Base64

·Concatenate with the app package name to form the correct fingerprint

Verification Result

After correcting the fingerprint format using the described method, the setFingerprint() function executes successfully without error 206.

Written by Mehmet Algul

How to create an onboard screen?

HarmonyOS — Wed, 06 May 2026 01:07:00 +0000

Read the original article：How to create an onboard screen?

Context

The onboard screen can be used to introduce the app or a functionality to first-time users.

Description

User wants to create an onboard screen using the Swiper component. The swiper should be controllable with the crown. The user wants to close the app with the swipe left action on the first page.

Solution

To create an onboard screen, you can use the Swiper.

Step 1: Create a local storage variable to store the onboard status. Modify EntryAbility.ets

onWindowStageCreate(windowStage: window.WindowStage): void {
  // Main window is created, set main page for this ability
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (err) => {
    if (err.code) {
      hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
      return;
    }
    hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');

    // Add this line
    PersistentStorage.persistProp('onboard', false)
  });
}

Step 2: Use the Swiper and create the onboard screen. Create Onboard.ets

import { common } from '@kit.AbilityKit'

@Component
export default struct Onboard {
  @State swiperIndex: number = 0
  total: number = 0
  sc: SwiperController = new SwiperController()

  build() {
    Column() {
      Swiper(this.sc) {
        Column() {
          Text('Page 1')
        }.padding({ left: '10%', right: '10%' })

        Column() {
          Text('Page 2')
        }.padding({ left: '10%', right: '10%' })

        Column() {
          Text('Page 3')
        }.padding({ left: '10%', right: '10%' })

        Column() {
          Text('Page 4')
        }.padding({ left: '10%', right: '10%' })
      }
      .loop(false)
      .effectMode(EdgeEffect.None)
      .defaultFocus(true)
      .onDigitalCrown((event) => {
        if (event.action === CrownAction.BEGIN) {
          this.total = event.degree
        } else {
          this.total += event.degree
        }

        if (this.total > 50) {
          this.sc.showPrevious()
          this.total = 0
        } else if (this.total < -50) {
          this.sc.showNext()
          this.total = 0
        }
      })
      .onChange((index: number) => {
        this.swiperIndex = index
      })
      .size({ width: '100%', height: '60%' })
      .margin({ top: '20%' })

      if (this.swiperIndex !== 0) {
        Button('Finish')
          .fontColor(Color.Blue)
          .backgroundColor(Color.Transparent)
          .onClick(() => {
            AppStorage.set('onboard', true)
          })
      }
    }
    .size({ width: '100%', height: '100%' })
    .parallelGesture(
      PanGesture({ direction: PanDirection.Right })
        .onActionUpdate((event) => {
          const horizontalDistance = event.offsetX;

          if (this.swiperIndex === 0 && horizontalDistance > 50) {
            (this.getUIContext().getHostContext() as common.UIAbilityContext).moveAbilityToBackground()
          }
        })
    )
  }
}

Swipe to close

.parallelGesture(
  PanGesture({ direction: PanDirection.Right })
    .onActionUpdate((event) => {
      const horizontalDistance = event.offsetX;

      if (this.swiperIndex === 0 && horizontalDistance > 50) {
        (this.getUIContext().getHostContext() as common.UIAbilityContext).moveAbilityToBackground()
      }
    })
)

Use crown to change

.defaultFocus(true)
.onDigitalCrown((event) => {
  if (event.action === CrownAction.BEGIN) {
    this.total = event.degree
  } else {
    this.total += event.degree
  }

  if (this.total > 50) {
    this.sc.showPrevious()
    this.total = 0
  } else if (this.total < -50) {
    this.sc.showNext()
    this.total = 0
  }
}

Step 3: Finally, modify the Index.ets to use the Onboard Page.

import Onboard from '../components/Onboard';

@Entry
@Component
struct Index {
  @StorageProp('onboard') onboard: boolean = false;

  build() {
    Stack() {
      if (!this.onboard) {
        Onboard()
      } else {
        Text('Main App')
      }
    }
    .height('100%')
    .width('100%')
  }
}

Key Takeaways

Use Swiper to create an onboard screen.
Use moveAbilityToBackground to close the app.

Written by Mehmet Karaaslan

The device cannot receive offline messages manually pushed by the server.

HarmonyOS — Tue, 05 May 2026 01:57:00 +0000

Read the original article：The device cannot receive offline messages manually pushed by the server

Problem Description

When the server pushes offline messages, if the mobile application process does not exist, the messages cannot be received. Even after starting the application and the process exists, the messages still cannot be received. How to locate and handle this issue?

Scenario:

The category selected for the push is MARKETING.

The token has been obtained.

Background Knowledge

Offline Push: Offline push refers to the process where, if the device is offline, Push Kit will cache the messages and push them to the device once it comes online. For more details, refer to: Push Kit Introduction.

Offline means the device is in an offline state, i.e., powered off or without network connectivity, and is not related to whether the APP is in the process.

If the device has network connectivity, it can receive push messages regardless of whether the APP is in the process.

If the device is already offline, developers can control the time the message is cached on the Push server through the ttl parameter in the request body. If the user's device comes online within the message cache time, the message will be delivered; otherwise, the message will be discarded after the cache time.

Troubleshooting Process

Notification Authorization:

You can determine whether the user has authorized by checking the error code returned from requestEnableNotification. If the returned error code is 1600004, it indicates that the authorization was denied. Below is an example code for the development steps. Please refer to it:

import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

class MyAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    hilog.info(0x0000, 'testTag', '%{public}s','Ability onWindowStageCreate');
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', err);
        return;
      }
      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', data);
      notificationManager.requestEnableNotification(this.context).then(() => {
        hilog.info(0x0000, 'testTag', `[ANS] requestEnableNotification success`);
      }).catch((err: BusinessError) => {
        hilog.error(0x0000, 'testTag',
          `[ANS] requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);
      });
    });
  }
}

Message Type and Configuration:

Confirm that the type and configuration of the message to be sent are correct. For instance, it is necessary to set appropriate category and push-type to ensure the message is processed correctly. Additionally, check if testMessage is set to true, as test messages have specific sending restrictions:

When testMessage is true, a single project can push up to 1000 test messages, with no more than 10 Tokens carried per push. When pushing authorized subscription messages and card refresh messages, only one Token can be carried per push.

If the self-classification rights for notification messages have not been applied for, the pushed notification messages will default to the information marketing category (with category value set to MARKETING). If only information marketing messages need to be sent, there is no need to apply for the self-classification rights for notification messages.

PushToken:

Confirm that the application has successfully obtained and uploaded the PushToken.

The PushToken identifies each application on every device. Developers call the getToken() interface to request the PushToken from the PushKit server, and use the PushToken to send push messages after obtaining it.

The PushToken generally does not change, except in the following scenarios where the PushToken may change:

Uninstall the application and then reinstall it.
Reset the device to factory settings.
After the application explicitly calls the deleteToken() interface, call the getToken() interface again.
After the application explicitly calls the deleteAAID() interface, call the getToken() interface again.
When the device (only Wearable devices) is taken to other countries or regions overseas, the system will update the device's Token. The updated Token is returned through the callback of the pushService.on('tokenUpdate') interface.

Therefore, it is recommended to call the getToken() interface when the application starts. If the device's PushToken changes, it should be promptly reported to the application server to update the PushToken.

Below is a reference example code:

  // Import the pushService module and related common modules.
  import { pushService } from '@kit.PushKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';
  import { BusinessError } from '@kit.BasicServicesKit';

  // It is recommended to call the `getToken()` interface in the `onCreate()` method of the UIAbility (such as EntryAbility) to obtain the PushToken and report it to the server, facilitating the server to push messages to the terminal.
  try {
    pushService.getToken().then((data: string) => {
      hilog.info(0x0000, 'testTag', 'Succeeded in getting push token.');
    }).catch((err: BusinessError) => {
        hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', err.code, err.message);
    });
  } catch (err) {
    let e: BusinessError = err as BusinessError;
      hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', e.code, e.message);
  }

Configuration Issues with the module.json5 File:

Under the skills tag in the module.json5 file, multiple skill objects can coexist, each corresponding to a specific capability. If you need to set up both push message redirection capabilities and other redirection capabilities (such as NFC redirection, browser redirection, etc.) simultaneously, you should create different skill objects within the skills array, each mapping to the corresponding capability. It is not recommended to configure multiple actions within a single skill, as this may result in the inability to match the intended scenarios.

Analysis Conclusion

There is an issue with the configuration of the module.json5 file, which requires the creation of different skill objects within the skills array.

Solution

If you need to set up both push message redirection capabilities and other redirection capabilities (such as NFC redirection, browser redirection, etc.), you should create different skill objects within the skills array, each mapping to the corresponding capability.

Example of skills tag configuration:

"abilities": [
  {
    "name": "PushMessageAbility",
    "srcEntry": "./ets/abilities/PushMessageAbility.ets",
    "launchType": "singleton",
    "startWindowIcon": "$media:startIcon",
    "startWindowBackground": "$color:start_window_background",
    "exported": false,
    "skills": [
      {
        "actions": [
          "action.ohos.push.listener"
        ]
      }
    ]
  }
]

It is not recommended to configure multiple actions within a single skill, as this may result in failure to match the intended scenarios.

Written by Mehmet Karaaslan

SoundPool does not play the audio.

HarmonyOS — Tue, 05 May 2026 01:54:00 +0000

Read the original article：SoundPool does not play the audio

SoundPool does not play the audio.

Problem Description

SoundPool does not play the audio.

Background Knowledge

SoundPool provides functionalities such as loading, playing, setting volume, looping, stopping playback, and unloading resources for short audio files. The SoundPool.unload method is used to unload audio that has already been loaded.

Troubleshooting Process

Search for the keyword "SoundPool::Play" in the hilog logs to identify the audio ID played at the time the issue occurred. Record the audio ID and the playback time.

04-29 18:02:32.140 SoundPool::Play soundID::74,priority:0

Then search for the keyword "SoundPool::Unload soundID: audio ID" in the log to check the time when the audio was unloaded.

04-29 18:02:30.235 SoundPool::Unload soundID::74

Analysis Conclusion

If the audio unload time is earlier than the audio playback time, it indicates that the application unloaded the audio before the playback was completed, resulting in the audio not being played.

Solution

Listen to the 'playFinished' event of SoundPool, and unload the audio in the callback function.

import { BusinessError } from '@kit.BasicServicesKit';

// Create a soundPool instance.
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`);
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`);
    soundPool.on('playFinished', () => {
      console.info('Succeeded in playFinished');
      // Execute the audio unload method here.
    });
  }
});

Verification Result

Works at API level 18 and later.

Written by Mehmet Karaaslan

How to execute a custom method when dragging down after scrolling to the top and dragging up after scrolling to the bottom?

HarmonyOS — Tue, 05 May 2026 01:50:00 +0000

Read the original article：How to execute a custom method when dragging down after scrolling to the top and dragging up after scrolling to the bottom?

Requirement Description

How to execute a custom method when dragging down after scrolling to the top and dragging up after scrolling to the bottom?

Background Knowledge

Scroll is a scrollable container component that allows content to scroll when the layout size of its child components exceeds the size of the parent component.
- currentOffset retrieves the current offset of the Scroll.
- isAtEnd checks whether the Scroll has reached the bottom.
PanGesture can bind swipe gesture events to components, where the event.offsetY in the gesture callback is positive when swiping from top to bottom, and negative when swiping in the opposite direction.

Implementation Steps

Use PanGesture to bind the pan event to the Scroll, and determine the Scroll position in onActionEnd to perform corresponding processing.

Determine if the Scroll has reached the top and continues to drag down:

Call currentOffset to get the current position of the Scroll. If the Y direction is less than or equal to 0, it has reached the top.
Determine whether to continue dragging down through the event in onActionEnd. If event.offsetY is greater than 0, it indicates continuing to drag down, then perform custom operations.

Determine if the Scroll has reached the bottom and continues to drag up:

Call isAtEnd to determine if the Scroll has reached the bottom.
Determine whether to continue dragging up through the event in onActionEnd. If event.offsetY is less than 0, it indicates continuing to drag up, then perform custom operations.

Code Snippet / Configuration

@Entry
@Component
struct ScrollDemo {
  private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Vertical })
  private scrollerForScroll: Scroller = new Scroller()

  build() {
    Column() {
      Scroll(this.scrollerForScroll) {
        Image($r('app.media.layered_image'))
          .size({ width: 400, height: 1050 })
      }
      .width('100%')
      .height('100%')
      .edgeEffect(EdgeEffect.Spring)
      .parallelGesture(
        PanGesture(this.panOption)
          .onActionStart((event: GestureEvent) => {
            console.info('Pan start')
          })
          .onActionUpdate((event: GestureEvent) => {
            // This method will be continuously triggered during the sliding process.
          })
          .onActionEnd((event: GestureEvent) => {
            console.info('Pan end')
            // Scroll to the bottom and continue scrolling.
            if (this.scrollerForScroll.isAtEnd() && event.offsetY < 0) {
              console.info("Perform Custom Operation 1")
            }
            // Swipe to the top and continue swiping.
            const offsetRes = this.scrollerForScroll.currentOffset() // Get the current position of Scroll
            if (offsetRes.yOffset <= 0 && event.offsetY > 0) {
              console.info("Perform Custom Operation 2")
            }
          }), GestureMask.Normal)
    }
  }
}

DEV Community: HarmonyOS

The problem of multiple components in HarmonyOS using animateTo animations not being synchronized

Problem Description

Background Knowledge

Problem Analysis

Analysis Conclusion

Solution

Written by Mehmet Emir Ucar

Text Binding Custom Menu

Problem Description

Background Knowledge

Solution

Verification Result

Written by Mehmet Emir Ucar

Progress component to implement a clock-style progress bar

Requirement Description

Background Knowledge

Implementation Steps

Code Snippet / Configuration

Limitations or Considerations

Written by Mehmet Emir Ucar

Passing parameters from a struct decorated with @ComponentV2 to a custom dialog decorated with @CustomDialog fails

Problem Description

Background Knowledge

Troubleshooting Process

Analysis Conclusion

Solution

Limitations or Considerations

Written by Mehmet Emir Ucar

How to implement the effect of switching images by sliding the Slider

How to implement the effect of switching images by sliding the Slider

Context

Description

Solution

Key Takeaways

Written by Mehmet Emir Ucar

How to Exit Slide-Out Mode When Clicking on a Blank Area

Context

Background Check

Solution / Approach

Limitations or Considerations

Written by Mehmet Emir Ucar

After the properties of an array object change, the UI rendering cannot be triggered to refresh

Problem Description

Background Knowledge

Troubleshooting Process

Analysis Conclusion

Solution

Limitations or Considerations

Written by Mehmet Emir Ucar

Wear Engine setFingerprint() 206 Error

Problem Description

Background Knowledge

Troubleshooting Process

Analysis Conclusion

Solution

Verification Result

Related Documents or Links

Written by Mehmet Algul

How to create an onboard screen?

Context

Description

Solution

Key Takeaways

Written by Mehmet Karaaslan

The device cannot receive offline messages manually pushed by the server.

Problem Description

Background Knowledge

Troubleshooting Process

Analysis Conclusion

Solution

Written by Mehmet Karaaslan

SoundPool does not play the audio.

SoundPool does not play the audio.

Problem Description

Background Knowledge

Troubleshooting Process

Analysis Conclusion

Solution

Verification Result