DEV Community: HarmonyOS Magician

Hidden Gems in HarmonyOS 5 for Business App Development - Graphic Transformations

HarmonyOS Magician — Fri, 27 Jun 2025 10:14:25 +0000

Hidden Gems in HarmonyOS 5 for Business App Development — Graphic Transformations

1. Introduction

During the development of business applications with HarmonyOS 5, we often encounter subtle yet powerful features buried within the framework. These transformations—such as rotation, translation, and scaling—can significantly enhance UI interactions and animations when used appropriately.

This article aims to explore these transformation capabilities in a concise, developer-oriented way, helping you better understand how to create smooth and dynamic user experiences in your HarmonyOS-based applications.

If you have questions, suggestions, spot any issues, or have a better solution, feel free to leave a comment or reach out via direct message or email. Thank you for your support. 🙏

2. Translate

The translate transformation primarily involves the following parameters:

x: Distance to move along the horizontal axis
y: Distance to move along the vertical axis
z: Distance to move along the depth axis (3D)

In a 2D translation, adjusting x and y allows you to move an element across the plane.

About the `z` Axis:

When z tends toward negative infinity, the component appears to shrink. Once z goes below -250, the object actually enlarges and flips.

This is likely due to a viewpoint positioned around z = -250. The closer a component gets to the viewpoint, the larger it appears—further away, the smaller it looks.

3. Rotate

Compared to translation, rotation comes with more parameters—angle, axis of rotation, transformation center, and perspective depth:

Name	Type	Description
x	number	X coordinate of the rotation axis vector
y	number	Y coordinate of the rotation axis vector
z	number	Z coordinate of the rotation axis vector
angle	number/string	Rotation angle (positive = clockwise, negative = counterclockwise). Can use values like `'90deg'`.
centerX	number/string	X coordinate of the rotation center
centerY	number/string	Y coordinate of the rotation center
centerZ	number	Z coordinate of the 3D rotation center
perspective	number	Distance from the viewpoint to the z=0 plane

The x, y, and z values define the rotation axis. The angle determines how much to rotate, and other parameters define the center and visual depth of the rotation.

3.1 Rotate Around Z Axis (Center Rotation)

{
  "x": 0,
  "y": 0,
  "z": 1,
  "angle": 45,
  "centerX": "50%",
  "centerY": "50%"
}

3.2 Rotate Around Y Axis (Left-Right Flip)

{
  "x": 0,
  "y": 1,
  "z": 0,
  "angle": 45,
  "centerX": "50%",
  "centerY": "50%"
}

3.3 Rotate Around X Axis (Top-Bottom Flip)

{
  "x": 1,
  "y": 0,
  "z": 0,
  "angle": 45,
  "centerX": "50%",
  "centerY": "50%"
}

3.4 centerX / centerY / centerZ (Rotation Anchor)

By default, rotation is performed around the center of the shape. You can customize the pivot point by modifying centerX, centerY, and centerZ, making the effect more flexible and tailored to UI needs.

3.5 perspective (Depth Perception)

Without perspective (perspective = 0): The rotation looks flat with no depth variation—like spinning a card on a table.
With perspective (perspective > 0): Adds a 3D effect where the object appears larger when closer and smaller when further away.

This mimics real-world depth—imagine a straight road that narrows as it vanishes into the distance.

In practice, the effect may not always be visually striking, especially for small rotations or components.

4. Scale

Name	Type	Description
x	number	Scale factor along the X-axis. `x > 1` enlarges, `0 < x < 1` shrinks, `x < 0` flips and scales.
y	number	Same as above, for the Y-axis
z	number	Same as above, for the Z-axis
centerX	number/string	X coordinate of the scaling center
centerY	number/string	Y coordinate of the scaling center

In 2D views, scaling along the Z axis often has no direct visual effect.

5. Coming Up Next

In the next article, we plan to explore matrix transformations—stay tuned!

6. Conclusion

That’s it for now.

If you have any questions, feedback, corrections, or alternative approaches, please feel free to comment, message, or email. Your input is greatly appreciated.

HarmonyOS 5 Business App Tip - OTP Input Component

HarmonyOS Magician — Fri, 27 Jun 2025 10:09:28 +0000

1. Introduction

In many business applications—such as login or payment flows—OTP (one-time password) or short passcode inputs are essential. When implementing an OTP input box in HarmonyOS 5, I encountered several tricky issues worth sharing.

This article walks through common obstacles, including incorrect approaches and best-practice solutions. Sections 2 and 3 show erroneous methods; if you only want the working solution, skip straight to section 4.

Questions, feedback, bug reports, or better ideas are very welcome via comments, DMs, or email. Thank you for your support! 🙏

2. ForEach + TextInput

The first idea: replicate Android's multiple EditText method using HarmonyOS 5’s multiple TextInput. We created a reusable component:

@Component
struct CodeInputView {
  build() {
    TextInput()
      .backgroundColor("#CCFFFFFF")
      .borderRadius(10)
      .maxLength(1)
      .type(InputType.Number)
      .align(Alignment.Center)
  }
}

To handle multiple inputs, we used ForEach inside a Row:

@Preview
@Component
struct CodeInputView {
  @State codeKids: Array<string> = new Array(5).fill('')

  build() {
    Row({ space: 10 }) {
      ForEach(this.codeKids, (item: string, index: number) => {
        TextInput(this.codeKids[index])
          .backgroundColor("#CCFFFFFF")
          .borderRadius(10)
          .maxLength(1)
          .layoutWeight(1)
          .fontSize(25)
          .height("100%")
          .type(InputType.Number)
          .align(Alignment.Center)
      }, (item: string) => item)
    }
    .backgroundColor(Color.Black)
    .height(80)
  }
}

This displays N equal-sized OTP boxes. The preview shows the layout.

Input + Focus Logic

Next, we added onChange to move focus automatically and collect the full OTP:

@Preview
@Component
struct CodeInputView {
  @State codeKids: Array<string> = new Array(5).fill('')
  inputResultCallback: (string) => void

  build() {
    Row({ space: vp(10) }) {
      ForEach(this.codeKids, (item: string, index: number) => {
        TextInput()
          .backgroundColor("#CCFFFFFF")
          .borderRadius(10)
          .maxLength(1)
          .layoutWeight(1)
          .fontSize(25)
          .height("100%")
          .type(InputType.Number)
          .align(Alignment.Center)
          .key(`code${index}`)
          .onChange((value) => {
            if (value.length <= 1) {
              this.codeKids[index] = value
            }
            if (index + 1 < this.codeKids.length) {
              focusControl.requestFocus(`code${index + 1}`)
            } else {
              this.inputResultCallback(this.codeKids.join(""))
            }
          })
      }, (item: string) => item)
    }
    .backgroundColor(Color.Black)
    .height(80)
  }
}

Key points:

inputResultCallback: returns the OTP to the parent.
onChange: stores value and auto-focuses the next box.
key() is needed for focusControl.requestFocus().

3. Odd Issues

3.1 Missing Initial Focus

On first render, no TextInput is focused. Fix by adding:

.defaultFocus(index == 0)

3.2 onChange Doesn’t Fire on Deletion

Surprisingly, deleting a character doesn’t trigger onChange. onKeyEvent wasn't reliable either:

.onKeyEvent((event) => {
  if (event.keyCode == KeyCode.KEYCODE_DEL) {}
})

So we had to look for alternatives.

3.3 Soft Keyboard Hides on Focus Switch

focusControl.requestFocus(nextKey) closes the soft keyboard. We found no clean workaround and suspect limitations in TextInput. Awaiting official fix.

4. Alternative: Single TextInput + Text Display

To avoid focus issues, we used a single hidden TextInput and multiple Text fields to display OTP:

@Preview
@Component
struct CodeInputView {
  @State codeKids: Array<string> = new Array(5).fill('')
  inputResultCallback: (string) => void

  build() {
    Stack() {
      Row({ space: vp(10) }) {
        ForEach(this.codeKids, (item: string, index: number) => {
          Text(item)
            .backgroundColor($r('app.color.white_80'))
            .height(match())
            .layoutWeight(1)
            .fontSize(fp(25))
            .textAlign(TextAlign.Center)
            .align(Alignment.Center)
            .borderRadius(vp(15))
            .focusable(false)
            .defaultFocus(false)
            .focusOnTouch(false)
        }, (item: string) => item)
      }
      .height(match())
      .width(match())

      TextInput()
        .maxLength(this.viewSize)
        .fontSize(fp(25))
        .borderRadius(vp(15))
        .type(InputType.Number)
        .key(this.inputKey)
        .onChange((value) => {
          let a = value.split('')
          this.codeKids.forEach((_, index) => {
            this.codeKids[index] = a[index] || ''
          })
          if (a.length >= this.viewSize) {
            this.inputResultCallback(value)
          }
          this.showCaret = (a.length == 0)
        })
        .copyOption(CopyOptions.None)
        .caretColor(this.showCaret ? Color.Black : Color.Transparent)
        .fontColor(Color.Transparent)
        .backgroundColor(Color.Transparent)
        .height(match())
        .width(match())
    }
    .height(vp(80))
  }
}

Key Details

Transparent TextInput handles all input.
Text fields instantly reflect each character.
caretColor toggles visibility.
OTP completion triggers inputResultCallback.

Usage:

CodeInputView({ inputResultCallback: (code) => {
  // handle OTP code
}})

Preview of the effect shows a clean input experience.

5. Final Version

Below is the complete, configurable component:

@Preview
@Component
export struct CodeInputView {
  @State viewSize: number = 4
  inputResultCallback: (string) => void
  @Link codeKids: Array<string>
  @State showCaret: boolean = true
  private inputKey = "code_input"

  aboutToAppear() {
    if (this.codeKids == null) {
      this.codeKids = new Array(this.viewSize).fill('');
    }
  }

  build() {
    Stack() {
      if (this.codeKids != null) {
        Row({ space: vp(10) }) {
          ForEach(this.codeKids, (item: string, index: number) => {
            Text(item)
              .backgroundColor($r('app.color.white_80'))
              .height(match())
              .layoutWeight(1)
              .fontSize(fp(25))
              .textAlign(TextAlign.Center)
              .align(Alignment.Center)
              .borderRadius(vp(15))
              .focusable(false)
              .defaultFocus(false)
              .focusOnTouch(false)
              .onClick(() => {
                focusControl.requestFocus(this.inputKey)
              })
          }, (item: string) => item)
        }
        .height(match())
        .width(match())

        TextInput()
          .maxLength(this.viewSize)
          .fontSize(fp(25))
          .borderRadius(vp(15))
          .type(InputType.Number)
          .key(this.inputKey)
          .onChange((value) => {
            let a = value.split('')
            this.codeKids.forEach((_, idx) => {
              this.codeKids[idx] = a[idx] || ''
            })
            if (a.length >= this.viewSize) {
              this.inputResultCallback(value)
            }
            this.showCaret = (a.length == 0)
          })
          .copyOption(CopyOptions.None)
          .caretColor(this.showCaret ? Color.Black : Color.Transparent)
          .fontColor(Color.Transparent)
          .backgroundColor(Color.Transparent)
          // TODO: Pressed styles won’t work with transparent backgrounds
          .height(match())
          .width(match())
      }
    }
    .height(vp(80))
  }
}

6. Conclusion

That wraps up this OTP input component walkthrough. Feel free to suggest additional features or improvements in the comments.

HarmonyOS 5 ArkUI still lacks comprehensive documentation, and many patterns from Android don’t translate well. This blog aims to help navigate some of the quirks. Let’s adapt together! Amituofo.

HarmonyOS 5: In-App Notification with SubWindow — A Coffee-Break Implementation

HarmonyOS Magician — Fri, 27 Jun 2025 09:57:02 +0000

1. Introduction

While HarmonyOS 5 supports system-level notifications, business apps often require in-app notices—such as updates, alerts, or marketing messages—especially when users deny system-level notification permissions.

This article walks through how to implement an in-app floating notification banner using SubWindow in a single-Ability Stage-based app architecture, inspired by Android's DecorView overlay. The notification appears at the top of the screen and supports animation and interactivity—ideal for alerting users without interrupting their current workflow.

Questions or suggestions? Feel free to leave a comment or contact me directly. 🙏

2. WindowStage & SubWindow

HarmonyOS 5 Stage model uses @ohos.window for window management. The two core APIs are:

WindowStage: Manages window units.
Window: Represents each window instance, including subwindows.

We use WindowStage.createSubWindow() to display a custom notification banner.

Example: Creating and Displaying a SubWindow

let mainWindowStage: window.WindowStage = null;
let subWindow: window.Window = null;

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage) {
    mainWindowStage = windowStage;
    this.showSubWindow();
  }

  showSubWindow() {
    mainWindowStage.createSubWindow("NoticeSubWindow", (err, data) => {
      if (err.code) return;

      subWindow = data;
      subWindow.moveWindowTo(0, 0);

      let mainWidth = mainWindowStage.getMainWindowSync()
                          .getWindowProperties().windowRect.width;
      subWindow.resize(mainWidth, 500);

      subWindow.setUIContent("pages/SubWindowNotice", (err) => {
        if (err.code) return;
        subWindow.setWindowBackgroundColor("#00FFFFFF");  // Transparent window
        subWindow.showWindow();
      });
    });
  }

  destroySubWindow() {
    subWindow?.destroyWindow();
  }
}

SubWindow Lifecycle Steps

Create subwindow using createSubWindow.
Configure size/position with resize and moveWindowTo.
Inject content via setUIContent.
Show or destroy as needed.

This approach gives us an overlay-like notification that's completely decoupled from the current page.

3. SubWindow UI — Notification Banner

We define a reusable notification component within a dedicated page (pages/SubWindowNotice), structured as:

@Entry
@Preview
@Component
struct SubWindowNotice {
  mHeight: number = vp(40)

  build() {
    Row({ space: vp(3) }) {
      Image($r("app.media.icon_default"))
        .autoResize(true)
        .margin({ top: vp(5), bottom: vp(5) })
        .width(vp(25))

      Column() {
        Text("Notification Title")
        Text("This is a brief description.")
      }
      .alignItems(HorizontalAlign.Start)
      .layoutWeight(1)

      Button("Action").fontSize("10fp")
    }
    .height(this.mHeight)
    .padding({ left: vp(5), right: vp(5), bottom: vp(3), top: vp(3) })
    .border({ radius: vp(10) })
    .margin({ left: vp(5), right: vp(5) })
    .backgroundColor(0x33000000)
  }
}

This banner includes:

Icon
Title + Description
Optional action button

4. Display & Animation Logic

To manage display and animation, we introduce two states:

@State isShow: boolean = false  // Toggle visibility

Use conditional rendering:

if (this.isShow) {
  Row(...) {
    ...
  }
  .transition({
    type: TransitionType.All,
    opacity: 1,
    translate: { x: 0, y: -this.mHeight }
  })
}

Animation Trigger

We toggle isShow via animateTo, with entry and exit after delay:

onPageShow() {
  setTimeout(() => {
    this.toggleAnimation();
    setTimeout(() => {
      this.toggleAnimation();
    }, 3000);  // Visible for 3s
  }, 300);     // Delay start
}

toggleAnimation() {
  animateTo({ duration: 1000 }, () => {
    this.isShow = !this.isShow;
  });
}

5. Full Component Code

@Entry
@Preview
@Component
struct SubWindowNotice {
  @State isShow: boolean = false
  @State isRunning: boolean = false
  mHeight: number = vp(40)
  textValue: string = "textValue"

  build() {
    if (this.isShow) {
      Row({ space: vp(3) }) {
        Image($r("app.media.icon_default"))
          .autoResize(true)
          .margin({ top: vp(5), bottom: vp(5) })
          .width(vp(25))

        Column() {
          Text("Title")
          Text("This is a notification message")
        }
        .alignItems(HorizontalAlign.Start)
        .layoutWeight(1)

        Button("Close").fontSize("10fp")
      }
      .transition({
        type: TransitionType.All,
        opacity: 1,
        translate: { x: 0, y: -this.mHeight }
      })
      .height(this.mHeight)
      .padding({ left: vp(5), right: vp(5), bottom: vp(3), top: vp(3) })
      .border({ radius: vp(10) })
      .margin({ left: vp(5), right: vp(5) })
      .backgroundColor(0x33000000)
    }
  }

  onPageShow() {
    setTimeout(() => {
      this.toggleAnimation()
      setTimeout(() => {
        this.toggleAnimation()
      }, 3000)
    }, 300)
  }

  toggleAnimation() {
    animateTo({ duration: 1000 }, () => {
      this.isShow = !this.isShow
    })
  }
}

6. Conclusion

In a single-Ability HarmonyOS 5 Stage application, SubWindow provides a convenient way to overlay global notices across all pages.

This approach is well-suited for:

In-app alerts
Persistent banners
Floating global widgets

Limitations:

No public APIs for custom SubWindow animation (must be handled within page UI)
@Extend cannot be used across files (a minor annoyance)

Still, this workaround delivers a robust, elegant notification UX suitable for business apps.

Feedback, corrections, and ideas are always welcome.

HarmonyOS 5 Business App Development Insights - In-Depth State Management

HarmonyOS Magician — Fri, 27 Jun 2025 09:51:53 +0000

HarmonyOS 5 Business App Development Insights — In-Depth State Management

1. Introduction

In building real-world business applications on HarmonyOS 5, state management is one of the most critical aspects of ArkUI development. It directly impacts UI responsiveness, interaction accuracy, and data consistency across components.

This article dives into state management mechanisms introduced in HarmonyOS 5 API version 11+, including frequently encountered challenges and practical solutions. We’ll cover decorators like @State, @Prop, @Link, and @Watch—key tools for managing component communication, reactivity, and rendering control in large-scale apps.

If you have any questions, suggestions, or corrections, feel free to comment, message, or email. Your support is greatly appreciated. 🙏

2. @State

1. Initialization Behavior

When a component initializes, @State can only accept a value once from its parent. Changes made to the parent state afterward won’t affect the child. This is why it's known as internal component state.

@Entry
@Component
export struct ExpComponent {
  @State title: string = "Title"

  build() {
    Column() {
      ExpChildComponent({
        childTitle: this.title
      })
      Button(this.title)
        .onClick(() => {
          this.title = "Click"
        })
    }
  }
}

@Component
export struct ExpChildComponent {
  @State childTitle: string = "????"

  build() {
    Text(this.childTitle)
  }
}

In this example, ExpChildComponent won’t update after onClick.

2. Too Many @State Variables

For complex pages, declaring multiple @State variables can clutter your code. A better approach is wrapping state in a class:

@Component
export struct ExpComponent {
  @State uiState: ExpUIState = new ExpUIState()

  build() {
    Text(this.uiState.title)
  }
}

class ExpUIState {
  title: string = ""
}

This keeps your components clean and organized.

3. Arrays

@State supports arrays and observes changes like:

@State title: Model[] = [new Model(1), new Model(2)];

this.title = [new Model(2)];
this.title[0] = new Model(2);
this.title.pop();
this.title.push(new Model(12));

However, nested property updates are not observed:

this.title[0].value = 6;

Updates to object properties inside arrays will not trigger reactivity.

4. Scope Effects

Due to JavaScript’s closure behavior, arrow functions inherit this from the context in which they are defined—not from the execution context.

@Component
export struct ExpComponent {
  @State uiState: ExpUIState = new ExpUIState()

  build() {
    Column() {
      Text(this.uiState.title)
      Button("Click").onClick(() => {
        this.uiState.autoRefreshTitle()
      })
    }
  }
}

class ExpUIState {
  title: string = "??"
  autoRefreshTitle = () => {
    this.title = "AutoRefreshTitle"
  }
}

The above won't trigger a UI update. Use this pattern instead:

@Component
export struct ExpComponent {
  @State uiState: ExpUIState = new ExpUIState()

  build() {
    Column() {
      Text(this.uiState.title)
      Button("Click").onClick(() => {
        let ref = this.uiState
        this.uiState.autoRefreshTitle(ref)
      })
    }
  }
}

class ExpUIState {
  title: string = "??"
  autoRefreshTitle = (st: ExpUIState) => {
    st.title = "AutoRefreshTitle"
  }
}

5. Nested Objects

When @State decorates an object that contains sub-objects or arrays:

class ExpUIState {
  childs: ExpChild[] = []
  firstChild: ExpChild = new ExpChild()
}

Only the top-level reference is reactive. Updating inner fields (e.g. uiState.firstChild.subTitle = "") will not update the UI.

Solution: avoid using @State for deeply nested structures.

3. @prop

1. Initialization Behavior

Similar to @State, but @Prop values are updated from parent components. However, changes made within the child will not reflect back to the parent.

2. Prop Chaining

Using @Prop across multiple nested components can get messy. Consider switching to @Provide.

3. @Require

@Prop can be combined with @Require to enforce required properties:

@Require @Prop index: number

4. @Observed

To observe changes in nested objects passed via @Prop, use @Observed.

@Component
export struct ExpComponent {
  @State uiState: ExpUIState = new ExpUIState()

  build() {
    Column() {
      ExpChildComponent({
        child: this.uiState.firstChild
      })
      Button("Click").onClick(() => {
        this.uiState.firstChild.subTitle = "????"
      })
    }
  }
}

@Component
export struct ExpChildComponent {
  @Require @Prop child: ExpChild

  build() {
    Text(this.child.subTitle)
  }
}

@Observed
class ExpUIState {
  childs: ExpChild[] = []
  firstChild: ExpChild = new ExpChild()
}

@Observed
class ExpChild {
  subTitle: string = "啊"
}

Every layer must be marked with @Observed and received via @Prop.

4. @link

1. Initialization Behavior

@Link creates two-way bindings between parent and child:

Comp({ aLink: this.aState })  // since API 9
Comp({ aLink: $aState })      // also supported

2. Used in Dialogs

@Link works well for synchronizing data within dialog components:

@CustomDialog
struct CustomDialog01 {
  @Link inputValue: string;
  controller: CustomDialogController;

  build() {
    Column() {
      Text('Change text')
        .fontSize(20)
        .margin({ top: 10, bottom: 10 })

      TextInput({ placeholder: '', text: this.inputValue })
        .height(60)
        .width('90%')
        .onChange((value: string) => {
          this.inputValue = value;
        })
    }
  }
}

@Entry
@Component
struct DialogDemo01 {
  @State inputValue: string = 'click me';
  dialogController: CustomDialogController = new CustomDialogController({
    builder: CustomDialog01({
      inputValue: $inputValue
    })
  })

  build() {
    Column() {
      Button(this.inputValue)
        .onClick(() => {
          this.dialogController.open();
        })
        .backgroundColor(0x317aff)
    }
    .width('100%')
    .margin({ top: 5 })
  }
}

You can also pass in a function if needed.

3. Deeply Nested @link

Like @Prop, using deeply nested @Link structures is discouraged. Use @Provide/@Consume instead.

5. @Watch

@Watch is a direct way to observe changes to state variables.

1. Avoid Mutating Watched Variables Inside Watchers

@State @Watch("onUiStateChange") uiState: ExpUIState = new ExpUIState()

onUiStateChange() {
  this.uiState.firstChild = new ExpChild()  // Infinite loop!
}

2. Event Propagation from Child to Parent

You can use @Link or @Provide/@Consume to sync data between components, and use @Watch for observation.

3. Not Sticky

@Watch doesn’t trigger on initial assignment—only on changes.

4. Logging Use Case

@Watch is great for logging state changes.

6. Coming Soon

Next post may continue exploring:
@State, @Prop, @Provide, @ObjectLink, @ObjectLinkV2, @Link, @Watch, and @Track (tentative)

7. Conclusion

That’s it!

If you have any questions, suggestions, or feedback, feel free to comment, message, or email. Thank you for reading 🙏

HarmonyOS 5 Building a Draggable Floating View Component in Your Application

HarmonyOS Magician — Fri, 27 Jun 2025 09:45:21 +0000

Introduction

In HarmonyOS development, implementing a floating draggable UI component (DragView) can greatly improve user experience. This is particularly useful for creating floating entries, quick access widgets, or contextual helpers. This article introduces a reusable DragView component that supports smooth dragging, edge constraint, magnetic snapping, and customizable initial alignment.

Design Concept

HarmonyOS provides built-in gesture support, such as PanGesture, which makes it straightforward to implement draggable interactions. The idea is simple:

Track drag offset using PanGesture.
Dynamically update the UI's .position() with the calculated offset.
After the drag ends, trigger a smooth snapping animation (animateTo) to snap the view to the nearest edge or position.

DragView Container

We start by defining the DragView component using .position(this.curPosition) to place it on the screen, and accept a builder function dragContentBuilder to support flexible content injection.

@State private curPosition: Position = { x: 0, y: 0 };

build() {
  Stack() {
    if (this.dragContentBuilder) {
      this.dragContentBuilder()
    } else {
      this.defDragView()
    }
  }
  .position(this.curPosition)
  .onClick(this.onClickListener)
}

Edge Constraints

To ensure the drag stays within a desired area, we define a BoundArea object to encapsulate the bounding logic.

export class BoundArea {
  constructor(start: number, top: number, end: number, bottom: number) {
    this.start = start
    this.top = top
    this.end = end
    this.bottom = bottom
    this.width = end - start
    this.height = bottom - top
    this.centerX = this.width / 2 + start
    this.centerY = this.height / 2 + top
  }
  // ... other fields
}

By default, the bounding area is set to the full screen.

Measuring View Dimensions

Since the DragView content is dynamic, we calculate its width and height using .onAreaChange.

.onAreaChange((oldValue: Area, newValue: Area) => {
  if (newValue.width && newValue.height) {
    this.dragWidth = newValue.width
    this.dragHeight = newValue.height
  }
})

Implementing Drag Interaction

We use PanGesture with PanDirection.All to allow free dragging in all directions.

PanGesture({ direction: PanDirection.All })
  .onActionStart(event => this.changePosition(event.offsetX, event.offsetY))
  .onActionUpdate(event => this.changePosition(event.offsetX, event.offsetY))
  .onActionEnd(() => this.adsorbToEnd(this.curPosition.x, this.curPosition.y))

The actual dragging logic applies clamping to keep the view within bounds:

private changePosition(offsetX: number, offsetY: number) {
  let targetX = clamp(this.endPosition.x + offsetX, this.boundArea.start, this.boundArea.end - this.dragHeight);
  let targetY = clamp(this.endPosition.y + offsetY, this.boundArea.top, this.boundArea.bottom - this.dragWidth);
  this.curPosition = { x: targetX, y: targetY };
}

Magnetic Snapping Animation

After the drag ends, the component snaps to the closest horizontal edge and clamps vertically within bounds:

private adsorbToEnd(startX: number, startY: number) {
  let targetX = (startX <= this.boundArea.centerX)
    ? this.boundArea.start + this.dragMargin.left
    : this.boundArea.end - this.dragWidth - this.dragMargin.right;

  let targetY = clamp(
    startY,
    this.boundArea.top + this.dragMargin.top,
    this.boundArea.bottom - this.dragWidth - this.dragMargin.bottom
  );

  this.startMoveAnimateTo(targetX, targetY);
}

Customizing Initial Alignment

To improve usability, we allow customizing the initial position using dragAlign and dragMargin:

dragAlign: Alignment = Alignment.BottomStart;
dragMargin: Margin = {};

The position is calculated once after the component's dimensions are known:

private initAlign() {
  switch (this.dragAlign) {
    case Alignment.BottomEnd:
      this.curPosition = {
        x: this.boundArea.end - this.dragWidth - this.dragMargin.right,
        y: this.boundArea.bottom - this.dragHeight - this.dragMargin.bottom
      };
      break;
    // ... other alignments
  }
  this.endPosition = this.curPosition;
}

Example Usage

A simple usage example:

DragView({
  dragAlign: Alignment.Center,
  dragMargin: bothway(10),
  dragContentBuilder: this.defDragView()
})

@Builder
defDragView() {
  Stack() {
    Text("Drag Me")
      .width(50).height(50)
      .fontSize(15)
  }
  .shadow({ radius: 1.5, color: "#80000000", offsetX: 0, offsetY: 1 })
  .padding(18)
  .borderRadius(30)
  .backgroundColor(Color.White)
  .animation({ duration: 200, curve: Curve.Smooth })
}

Conclusion

With this DragView component, you can easily implement reusable floating views inside HarmonyOS applications. It supports customizable boundaries, snapping logic, initial placement, and dynamic UI content.

If you're building a system-wide floating assistant or cross-page notice, consider combining this approach with SubWindow, as discussed in the in-app notice article.

Unit and Integration Testing in HarmonyOS 5

HarmonyOS Magician — Fri, 27 Jun 2025 08:20:32 +0000

Testing and debugging are essential steps to ensure the quality and stability of any application. For HarmonyOS 5 development, unit testing and integration testing are two key approaches to validate the independence and collaboration of modules. This article walks through how to conduct both types of tests effectively in HarmonyOS.

1. Unit Testing

1.1 Purpose

Unit testing verifies the smallest testable parts of an application (such as functions or methods). It allows early detection of bugs and ensures correctness. The objectives are:

Ensure individual module functionality;
Detect and fix logical issues early;
Support refactoring with automated regression checks.

1.2 Tools

HarmonyOS supports various mainstream testing frameworks:

GTest (Google Test): C++ unit test framework with rich assertion support;
Mockito: Mocking framework for Java unit testing;
JUnit: Standard framework for Java-based unit tests, also applicable for HarmonyOS Java modules.

1.3 Example

A sample test for an addition function using GTest:

#include <gtest/gtest.h>
#include "calculator.h"

TEST(CalculatorTest, AddFunction) {
    Calculator calc;
    EXPECT_EQ(calc.add(2, 3), 5);
    EXPECT_EQ(calc.add(-1, 1), 0);
    EXPECT_EQ(calc.add(0, 0), 0);
}

1.4 Execution

Use the following command to execute tests:

./calculator_test

The output shows test results. If a test fails, review the assertion messages, update the code, and rerun the tests.

2. Integration Testing

2.1 Purpose

Integration testing ensures that modules work together as expected. It checks interface calls, data transfer, and business workflows. It helps to:

Validate inter-module communication;
Confirm correctness of API calls;
Ensure end-to-end process consistency.

2.2 Tools

Common tools for integration testing in HarmonyOS:

Unity: Lightweight C testing framework, supports cross-platform;
Postman: For API simulation and response verification;
TestRunner: Official test runner for HarmonyOS, supports CI/CD integration.

2.3 Example

Testing a weather app's integration from frontend to backend:

it('should get weather based on user location', async () => {
    const location = getUserLocationMock();
    const weather = await getWeatherFromServer(location);
    expect(weather.status).toBe(200);
    expect(weather.data).toHaveProperty('temperature');
});

2.4 Debugging Tips

Due to complexity, common debugging strategies include:

Logging: Track input/output across modules;
Mocking: Replace external dependencies with mocks;
API debugging tools: Use Postman to validate API interactions.

3. Conclusion

Unit and integration testing are essential for ensuring stability and reliability in HarmonyOS 5 apps. By designing and executing tests properly, developers can catch issues early and maintain high-quality code. Combining these with CI/CD tools enables automation and boosts overall development efficiency.

Hypium: The Unit Testing Framework for HarmonyOS 5

HarmonyOS Magician — Fri, 27 Jun 2025 08:15:43 +0000

1. Overview

Hypium is the official unit testing framework for HarmonyOS 5. It supports writing test cases, executing them, and viewing results within DevEco Studio.

Feature	Description
Case Writing	Mocha-style syntax (`describe`, `it`)
Execution	Package, suite, and method-level testing
Mock Support	Supported from version 1.0.1
Data-Driven Tests	Supported from version 1.0.2

2. Installation

Add the following dependency in your project's package.json:

"dependencies": {
  "@ohos/hypium": "1.0.6"
}

Use npm view @ohos/hypium version to check the latest version.

Import Hypium APIs:

import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium';

3. Feature Guide

3.1 Basic Flow

Use describe to group test cases and it for each test:

describe('ExampleTest', () => {
  it('should do something', 0, () => {
    // Your logic here
  });
});

3.2 Assertions

Hypium provides rich assertion methods for verifying expected outcomes.

Method	Description
`assertEqual`	Checks for equality
`assertContain`	Checks if a substring is present
`assertUndefined`	Checks if value is `undefined`

Example:

import { describe, it, expect } from '@ohos/hypium';
export default function abilityTest() {
  describe('ActsAbilityTest', function () {
    it('assertContain', 0, function () {
      let a = 'abc';
      let b = 'b';
      expect(a).assertContain(b);
      expect(a).assertEqual(a);
    });
  });
}

3.3 Mock Support

Starting from v1.0.1, Hypium supports mocking of class methods.

import { describe, expect, it, MockKit, when } from '@ohos/hypium';

export default function ActsAbilityTest() {
  describe('ActsAbilityTest', function () {
    it('testMockfunc', 0, function () {
      let mocker = new MockKit();

      class ClassName {
        method_1(arg) { return '888888'; }
        method_2(arg) { return '999999'; }
      }

      let claser = new ClassName();
      let mockfunc = mocker.mockFunc(claser, claser.method_1);
      when(mockfunc)('test').afterReturnNothing();

      expect(claser.method_1('test')).assertUndefined();
    });
  });
}

3.4 Data-Driven Testing

From version 1.0.2, Hypium supports parameterized and stress testing based on a data.json file.

Sample data.json:

{
  "suites": [
    {
      "describe": ["actsAbilityTest"],
      "stress": 2,
      "params": {
        "suiteParams1": "suiteParams001",
        "suiteParams2": "suiteParams002"
      },
      "items": [
        {
          "it": "testDataDriverAsync",
          "stress": 2,
          "params": [
            { "name": "tom", "value": 5 },
            { "name": "jerry", "value": 4 }
          ]
        },
        {
          "it": "testDataDriver",
          "stress": 3
        }
      ]
    }
  ]
}

Run with parameters:

import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry';
import { Hypium } from '@ohos/hypium';
import testsuite from '../test/List.test';
import data from '../test/data.json';

Hypium.setData(data);
Hypium.hypiumTest(abilityDelegator, abilityDelegatorArguments, testsuite);

4. Running Tests

You can run tests in DevEco Studio via:

Package Level: Run all test cases in a package
Suite Level: Run all tests within a describe block
Method Level: Run an individual test (it block)

How to Test HarmonyOS 5 Apps: Must-Have Toolkit for Developers

HarmonyOS Magician — Fri, 27 Jun 2025 08:09:23 +0000

With over 4,000 applications now integrated into the HarmonyOS ecosystem, Huawei has made remarkable progress in the native development of HarmonyOS NEXT. The ecosystem offers developers a comprehensive suite of tools including DevEco Studio, DevEco Testing, and the Hypium automation testing framework. This blog introduces key tools and services essential for HarmonyOS development and testing.

HarmonyOS Development Toolkit Overview

Huawei provides developers with a rich set of tools and services for HarmonyOS application development, debugging, and testing. These include:

1. AppGallery Connect (AGC)

A one-stop service platform for app ideation, development, distribution, operation, and monetization.

AGC Portal

2. DevEco Studio

An integrated development platform that supports distributed development across multiple devices.

Features: smart code editing, low-code development, bidirectional preview, lightweight build tool DevEco Hvigor, and local emulator.
DevEco Studio

3. DevEco Testing

Provides comprehensive HarmonyOS application and device testing solutions.

4. HarmonyOS Design

A continually updated design resource library with icons, colors, typography, sounds, components, and templates.

HarmonyOS Design

5. ArkTS

HarmonyOS's official application development language, built on TypeScript with stricter static typing and UI/state management capabilities.

ArkTS Documentation

6. ArkUI

A declarative UI development framework optimized for building distributed app interfaces.

ArkUI Overview

7. ArkCompiler

Huawei's unified programming platform that supports cross-device compilation and execution.

ArkCompiler

Automated Testing Frameworks

ArkxTest: HarmonyOS Automation Framework

Huawei offers a robust automation testing framework that supports JS/TS-based unit and UI testing for HarmonyOS.

Key Components:

Unit Testing Framework: For validating application APIs and logic.
UI Testing Framework: For end-to-end testing using UI interactions.

Note: The UI framework is supported from HarmonyOS 3.0 onwards.

Full guidelines: ArkxTest Documentation

Hypium: Next-Gen Automated Testing for HarmonyOS

"Hypium" = "Hyper Automation + ium"
A new plugin-based framework for DevEco Studio that simplifies test case creation and execution during the development cycle.

Key Modules:

HJsUnit: Unit testing interface for logic validation.
HUiTest: Simple API to test UI elements and user interactions.

By integrating into DevEco Studio, Hypium auto-generates test directories, classes, and templates, reducing the setup time and increasing test productivity.

Learn more:

Hypium Overview

HarmonyOS Special-Purpose Testing Services

To deliver a smooth, secure, and responsive user experience, apps must undergo rigorous testing phases:

Testing Lifecycle:

Development Testing: Basic validation of usability.
Functional Testing: Ensure feature completeness.
Specialized Testing: Validate security, performance, power consumption, and stability.
Pre-launch Review: Final compliance checks based on HarmonyOS testing standards.

Why Specialized Testing?

Conventional teams often lack resources for advanced testing. Different scenarios demand different skills and environments. Huawei addresses this gap with DevEco Testing, a professional, simplified, and intelligent testing service.

DevEco Testing Capabilities:

Stability Testing
Network Availability (Dial Testing)
Performance Profiling
Security Audits
Standard Compliance Validation

These services streamline the entire testing pipeline, allowing both developers and testers to validate HarmonyOS apps efficiently.

Full article: Mastering HarmonyOS Specialized Testing

Leveraging HarmonyOS 5 Service Cards in Business Applications

HarmonyOS Magician — Thu, 26 Jun 2025 08:01:14 +0000

1. ArkTS Card-Related Modules

1.1 form_config.json

The form_config.json file under the resources/base/profile/ directory is used to configure card layout, scheduled updates, dynamic/static settings, etc.

Refer to the official documentation for full field definitions: form_config.json Field Reference

This file is an array structure that allows multiple card configurations of different dimensions. The src field specifies the layout file path.

{
"forms": [
 {
   "name": "widget1",
   "displayName": "$string:widget_display_name",
   "description": "$string:widget_desc",
   "src": "./ets/widget/pages/WidgetCard.ets",
   "uiSyntax": "arkts",
   "window": {
     "designWidth": 720,
     "autoDesignWidth": true
   },
   "colorMode": "auto",
   "isDynamic": false,
   "isDefault": true,
   "updateEnabled": false,
   "scheduledUpdateTime": "10:30",
   "updateDuration": 1,
   "defaultDimension": "2*4",
   "supportDimensions": ["2*4"]
 },
 {
   "name": "widget2",
   "displayName": "$string:widget_display_name",
   "description": "$string:widget_desc",
   "src": "./ets/widget/pages/WidgetCard.ets",
   "uiSyntax": "arkts",
   "window": {
     "designWidth": 720,
     "autoDesignWidth": true
   },
   "colorMode": "auto",
   "isDynamic": false,
   "isDefault": false,
   "updateEnabled": false,
   "scheduledUpdateTime": "10:30",
   "updateDuration": 1,
   "defaultDimension": "4*4",
   "supportDimensions": ["4*4"]
 }
]
}

1.2 EntryFormAbility

Implement lifecycle methods of FormExtensionAbility in EntryFormAbility.ets:

import { formBindingData, FormExtensionAbility, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';

export default class EntryFormAbility extends FormExtensionAbility {
onAddForm(want: Want) {
 let formData = '';
 return formBindingData.createFormBindingData(formData);
}
onCastToNormalForm(formId: string) {}
onUpdateForm(formId: string) {}
onFormEvent(formId: string, message: string) {}
onRemoveForm(formId: string) {}
onAcquireFormState(want: Want) {
 return formInfo.FormState.READY;
}
};

1.3 Saving Card IDs Including Temporary Ones

onAddForm can be called multiple times.
onRemoveForm should remove IDs for non-pinned cards.

import { preferences } from '@kit.ArkData';

private saveServiceCardId(want: Want): void { ... }
private deleteServiceCardId(formId: string): void { ... }

The core logic saves all card IDs in onAddForm, and filters them in onRemoveForm.

1.4 Getting IDs of Pinned Cards

The app provider can read the IDs of cards pinned to the home screen like this:

private getFormIds(): void {
  let options = { name: 'CloudPhoneCard' };
  preferences.removePreferencesFromCacheSync(getContext(this), options);
  let formIds = preferences.getPreferencesSync(getContext(this), options);
  Logger.debug(`EntryAbility getFormIds: ${formIds.getSync('formIds', '[]')}`);
}

1.5 Updating Network Images in Cards

Only dynamic cards support image updates. Network images must be downloaded to local storage first, and accessed using the memory:// prefix.

private async updateNetImg(formId: string, src: string): Promise<void> {
  let fileName = 'file' + Date.now();
  let tmpFile = this.context.getApplicationContext().tempDir + '/' + fileName;
  let imgMap: Record<string, number> = {};

  class FormDataClass {
    updateImg: string = fileName;
    formImages: Record<string, number> = imgMap;
  }

  let httpRequest = http.createHttp();
  let data = await httpRequest.request(src);

  if (data?.responseCode == http.ResponseCode.OK) {
    try {
      let imgFile = fileIo.openSync(tmpFile, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
      imgMap[fileName] = imgFile.fd;
      let writeLen = await fileIo.write(imgFile.fd, data.result as ArrayBuffer);
      let formData = new FormDataClass();
      let formInfo = formBindingData.createFormBindingData(formData);
      await formProvider.updateForm(formId, formInfo);
      fileIo.closeSync(imgFile);
    } catch (error) {
      Logger.debug(`Failed to write image: ${JSON.stringify(error)}`);
    }
  }
  httpRequest.destroy();
}

Official reference: Image Update Guide

HarmonyOS 5 DES Encryption and Decryption

HarmonyOS Magician — Thu, 26 Jun 2025 07:52:23 +0000

1. Introduction to harmony

harmony is a powerful yet easy-to-use utility library for HarmonyOS, designed to help developers quickly build HarmonyOS applications. It encapsulates a variety of commonly used utilities, including but not limited to:

System & Device: App info, device info, screen adaptation
User Interaction: Dialogs, toasts, notifications, camera, QR code scanning
Storage & Data Processing: User preferences, file operations, JSON, string manipulation, collections, encryption/decryption
Security: DES/AES encryption and decryption, biometric authentication, exception capturing
Others: Thread communication, logging, random number generation, Base64 encoding/decoding, etc.

Additionally, picker_utils is a sub-library extracted from harmony, which contains utilities such as PickerUtil, PhotoHelper, and ScanUtil.

Installation

ohpm i @pura/harmony
ohpm i @pura/picker_utils

Initialize the library globally in the onCreate method of your UIAbility:

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  AppUtil.init(this.context);
}

2. Introduction to DES Algorithm

DES (Data Encryption Standard) is the first standardized symmetric block cipher algorithm released by the United States in 1977. It features:

64-bit data blocks
56-bit effective key (plus 8 parity bits totaling 64 bits)
16-round Feistel network structure

The encryption involves expansion permutation, nonlinear S-box transformation, and P-box permutation to enhance confusion and diffusion.

Main drawbacks:

Small key space of only 2562^{56}, vulnerable to brute-force attacks
Existence of weak keys (e.g., all-zero key)
Poor resistance to differential and linear cryptanalysis

Therefore, DES has been replaced by AES for modern cryptography, but it remains a classic teaching example and a milestone in cryptographic standardization.

3. Using DES APIs in harmony

3.1 Generate Symmetric Key

let symKey1 = await DES.generateSymKey();
let symKeyStr1 = CryptoHelper.dataBlobToStr(symKey1.getEncoded(), 'hex');
LogUtil.error(`Symmetric Key 1: ${symKeyStr1}`);

let symKey2 = DES.generateSymKeySync();
let symKeyStr2 = CryptoHelper.dataBlobToStr(symKey2.getEncoded(), 'base64');
LogUtil.error(`Symmetric Key 2: ${symKeyStr2}`);

3.2 ECB Mode Encryption & Decryption

Encryption

let plaintext = "HarmonyOS Tech Exchange QQ Group: 1029219059";
let base64Key = "bZen8i4KBFVMlomHBNWeExvFydWEXspO";
let symKey = CryptoUtil.getConvertSymKeySync('3DES192', base64Key, 'base64');
let dataBlob = CryptoHelper.strToDataBlob(plaintext, 'utf-8');

let encryptedBlob = await DES.encryptECB(dataBlob, symKey);
let encryptedStr = CryptoHelper.dataBlobToStr(encryptedBlob, 'utf-8');
LogUtil.error(`Encrypted (ECB, async): ${encryptedStr}`);

Decryption

let decryptedBlob = await DES.decryptECB(encryptedBlob, symKey);
let decryptedStr = CryptoHelper.dataBlobToStr(decryptedBlob, 'utf-8');
LogUtil.error(`Decrypted (ECB, async): ${decryptedStr}`);

Synchronous versions available as DES.encryptECBSync() and DES.decryptECBSync().

3.3 CBC Mode Encryption & Decryption (Supports IV)

Encryption

let ivParams = CryptoUtil.generateIvParamsSpec();
let plaintext = "harmony, a highly efficient HarmonyOS toolkit.";
let base64Key = "bZen8i4KBFVMlomHBNWeExvFydWEXspO";
let symKey = CryptoUtil.getConvertSymKeySync('3DES192', base64Key, 'base64');
let dataBlob = CryptoHelper.strToDataBlob(plaintext, 'utf-8');

let encryptedBlob = await DES.encryptCBC(dataBlob, symKey, ivParams);
let encryptedStr = CryptoHelper.dataBlobToStr(encryptedBlob, 'utf-8');
LogUtil.error(`Encrypted (CBC, async): ${encryptedStr}`);

Decryption

let decryptedBlob = await DES.decryptCBC(encryptedBlob, symKey, ivParams);
let decryptedStr = CryptoHelper.dataBlobToStr(decryptedBlob, 'utf-8');
LogUtil.error(`Decrypted (CBC, async): ${decryptedStr}`);

3.4 Custom Encryption Modes (e.g., OFB, PKCS7)

Encryption (OFB Mode)

let ivParams = CryptoUtil.generateIvParamsSpec();
let hexKey = "f1f8d34a21fd62ffb128b1ada4fd8f0758123e7d442b6273";
let symKey = await CryptoUtil.getConvertSymKey('3DES192', hexKey, 'hex');
let dataBlob = CryptoHelper.strToDataBlob("HarmonyOS Tech Exchange QQ Group: 1029219059", 'utf-8');

let encryptedBlob = await DES.encrypt(dataBlob, symKey, ivParams, '3DES192|OFB|PKCS7');
let encryptedStr = CryptoHelper.dataBlobToStr(encryptedBlob, 'utf-8');
LogUtil.error(`Encrypted (OFB mode, async): ${encryptedStr}`);

Decryption (OFB Mode)

let decryptedBlob = await DES.decrypt(encryptedBlob, symKey, ivParams, '3DES192|OFB|PKCS7');
let decryptedStr = CryptoHelper.dataBlobToStr(decryptedBlob, 'utf-8');
LogUtil.error(`Decrypted (OFB mode, async): ${decryptedStr}`);

4. Summary

harmony provides comprehensive support for symmetric encryption and decryption, including multiple DES modes (ECB, CBC, OFB, etc.) with both synchronous and asynchronous APIs.
With CryptoUtil and CryptoHelper, converting between strings and binary data is straightforward.
For production use, CBC or higher-security algorithms (e.g., AES) are recommended instead of ECB.

HarmonyOS 5: A Complete Guide to Releasing a HarmonyOS App or Atomic Service

HarmonyOS Magician — Thu, 26 Jun 2025 07:35:37 +0000

Given the lack of comprehensive official documentation on releasing an atomic service, this guide walks you through the complete process from start to finish. It is based on real experience preparing to release a HarmonyOS atomic service.

Overview

The process is divided into the following steps:

Create the Project
AppGallery Setup
Development
Build and Package
Release

Let's begin.

Step 1: Create an Atomic Service Project

Creating an atomic service project is slightly different from a standard HarmonyOS app.

In DevEco Studio, go to File > New > Create Project, then select "Atomic Service". Choose a template (default: Empty Ability) and click Next.
The wizard will check your login status. If not logged in, you will be redirected to log in on the web.
After logging in, return to DevEco Studio and select your App ID from the dropdown. If none exist, click "Register App ID" to create one.
On the web page, fill in details such as App Name, App Type, etc.
After submitting, you will be prompted with a success message. You can view the project details in the console, although it's optional at this point.
Back in DevEco Studio, select your newly created project from the dropdown and click Next.
Provide basic project info such as Project Name, Save Location, etc., and click Finish.

Project creation is now complete.

Step 2: AppGallery Setup

This step is mostly covered in Step 1. You create the App ID and can check the project info in AppGallery Connect.

Step 3: Development

Now develop the actual features of your atomic service. Refer to the HarmonyOS documentation for specific development guidance.

Step 4: Build and Package

Before packaging, additional AppGallery configuration is needed.

AppGallery Configuration Overview

HarmonyOS requires a digital certificate and Profile file for signing atomic services before they can be released.

4.1 Generate Key and CSR File

In DevEco Studio, go to Build > Generate Key and CSR.
In the dialog, fill in basic info. If this is your first time, click New to create a .p12 key store file:
- Key store file: Path and custom name.
- Password: Set and remember it.
- Confirm Password: Same as above.

Click OK to return. The .p12 file path and password should now be auto-filled.

Alias: Key alias (any memorable name).
Password: Auto-filled, same as keystore password.
Validity: Recommended 25+ years.
Certificate Info: Organization, region, country code, etc.

Click Next, then choose CSR file path and name. Click Finish. You now have a .p12 and a .csr file on your computer.

4.2 Apply for a Release Certificate

Log in to AppGallery Connect.
Go to Certificates, App IDs & Profiles.
Under the Certificates tab, click New Certificate.
Fill in:
- Certificate Name: Any name under 100 characters.
- Type: Choose Release Certificate.
- CSR File: Upload the .csr file you just generated.

Click Submit to generate the certificate. Download the .cer file afterward.

4.3 Apply for a Release Profile

Profiles (.p7b) are required for packaging. On the Profile tab:

App Name: Select from dropdown.
Package Name: Auto-filled.
Profile Name: Custom name (match atomic service name recommended).
Type: Choose Release.
Certificate: Select the one created earlier.
Permission Request: Apply only if your app requires special permissions (optional).

Click Add, then download the .p7b profile file.

Configure Signing Info for Build

Before building, configure the signing setup:

Open the build-profile.json5 file. Note that signingConfigs may initially be empty.
In DevEco Studio, go to File > Project Structure, open the Signing Configs tab.
Uncheck Auto Sign.
Fill in:
- Store File: Path to .p12 file.
- Store Password
- Key Alias
- Key Password
- Sign Algorithm: SHA256withECDSA
- Profile File: Path to .p7b file.
- CertPath File: Path to downloaded .cer file.

Click OK. Reopen build-profile.json5 to confirm signingConfigs has been populated.

Build and Package the App

In DevEco Studio, go to Build > Build Hap(s)/APP(s) > Build APP(s).
The compiled and signed output will appear under: build/output/app/release/

Example: HistoryToday-default-signed.app — ready for publishing.

Step 5: Publish to AppGallery

Log in to AppGallery Connect and navigate to My Atomic Services.
Select the HarmonyOS tab, search for your service name, and click Edit.

Fill in required info:

Release Country/Region
Basic Info
Privacy Policy: Add a link or create one.
User Agreement: Provide a link.
Filing Info: Choose appropriate filing type (e.g., standalone app).
Listing Schedule: Choose immediate or scheduled release.
App Icon: Must be 216x216. See icon guidelines.

Upload Package

Upload the package you built (e.g., HistoryToday-default-signed.app). Set Usage Scenario to Testing and Official Release.

Click Submit for Review and wait for approval.

After submission, your service will show status: Pre-reviewing.

Note: Review times can be slow — please be patient.

HarmonyOS 5 Demo Example of Bidirectional Communication between HarmonyOS Web Components and Embedded Web Pages

HarmonyOS Magician — Wed, 25 Jun 2025 03:13:56 +0000

I. Preface

In ArkUI development, the Web component (Web) allows developers to embed web pages within an application, enabling hybrid development scenarios.
This article will elaborate on how to achieve bidirectional communication between ArkUI and embedded web pages through a complete demo, covering core technical points such as ArkUI calling web JS and web pages calling ArkUI objects via WebviewController.

II. Principles of Bidirectional Communication Implementation

1. Concept of Bidirectional Communication

Web to ArkUI (reverse communication): Register the ArkUI object to the window object of the web page through registerJavaScriptProxy, allowing the web page to call the methods exposed by ArkUI via window.xxx.
ArkUI to Web (forward communication): Execute web JS code through runJavaScript, supporting callbacks to obtain return values and enabling native code to call web functions.

2. Flowchart of Bidirectional Communication

ArkUI Web
┌──────────────┐ ┌──────────────┐
│ registerJS ├─────────────▶ window.objName │
│ (Reverse Registration) │ ├──────────────┤
├──────────────┤ │ call test() │
│ runJavaScript├─────────────▶ execute JS code │
│ (Forward Call) │ ├──────────────┤
└──────────────┘ └──────────────┘

III. Steps to Implement Bidirectional Communication

1. ArkUI Defines Objects Callable by Web Pages

Create a TestObj class and declare methods allowed to be called by web pages (whitelist mechanism):

class TestObj {
  // Method 1 callable by web pages: returns a string
  test(): string {
    return "ArkUI Web Component";
  }

  // Method 2 callable by web pages: prints logs
  toString(): void {
    console.log('Web Component toString');
  }

  // Method 3 callable by web pages: receives messages from web pages
  receiveMessageFromWeb(message: string): void {
    console.log(`Received from web: ${message}`);
  }
}

2. Core Code of ArkUI Components

Initialize the controller and state:

@Entry
@Component
struct WebComponent {
  // Webview controller
  controller: webview.WebviewController = new webview.WebviewController();
  // ArkUI object registered to the web page
  @State testObj: TestObj = new TestObj();
  // Registration name (web page accesses via window.[name])
  @State regName: string = 'objName';
  // Receives data returned by the web page
  @State webResult: string = '';

  build() { /* Component layout and interaction logic */ }
}

Layout and interaction buttons, adding three core function buttons:

Column() {
  // Displays data returned by the web page
  Text(`Web Returned Data: ${this.webResult}`).fontSize(16).margin(10);

  // 1. Register the ArkUI object to the web page
  Button('Register to Window')
    .onClick(() => {
      this.controller.registerJavaScriptProxy(
        this.testObj,  // ArkUI object
        this.regName,  // Web page access name
        ["test", "toString", "receiveMessageFromWeb"]  // Whitelist of allowed methods
      );
    })

  // 2. ArkUI calls web JS
  Button('Call Web Function')
    .onClick(() => {
      this.controller.runJavaScript(
        'webFunction("Hello from ArkUI!")',  // Execute web JS code
        (error, result) => {  // Callback to process return value
          if (!error) this.webResult = result || 'No return value';
        }
      );
    })

  // 3. Web component loading
  Web({ src: $rawfile('index.html'), controller: this.controller })
    .javaScriptAccess(true)  // Enable JS interaction permission
    .onPageEnd(() => {  // Triggered when page loading is complete
      // Automatically call the web test function after page loading
      this.controller.runJavaScript('initWebData()');
    })
}

3. The actual role of `registerJavaScriptProxy` is to bind the ArkUI object to the web page window, achieving reverse communication.

registerJavaScriptProxy(
  obj: Object,        // Object defined in ArkUI
  name: string,       // Name for web page access (e.g., window.name)
  methods: string[]   // Whitelist of allowed methods (strictly matches method names)
);

Source Code Example

The complete code has been uploaded to the Gitee repository. Welcome to download and debug! If you have any questions, feel free to leave a message in the comment section for communication~

Project Structure

├── xxx.ets # ArkUI component code
└── index.html # Embedded web page file

WebViewPage.ets

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

class TestObj {
  constructor() {
  }

  test(): string {
    return "ArkUI Web Component";
  }

  toString(): void {
    console.log('Web Component toString');
  }

  receiveMessageFromWeb(message: string): void {
    console.log(`Received message from web: ${message}`);
  }
}

@Entry
@Component
struct WebViewPage {
  controller: webview.WebviewController = new webview.WebviewController();
  @State testObjtest: TestObj = new TestObj();
  @State name: string = 'objName';
  @State webResult: string = '';

  build() {
    Column() {
      Text(this.webResult).fontSize(20)
      Button('refresh')
        .onClick(() => {
          try {
            this.controller.refresh();
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Button('Register JavaScript To Window')
        .onClick(() => {
          try {
            this.controller.registerJavaScriptProxy(this.testObjtest, this.name, ["test", "toString", "receiveMessageFromWeb"]);
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Button('deleteJavaScriptRegister')
        .onClick(() => {
          try {
            this.controller.deleteJavaScriptRegister(this.name);
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Button('Send message to web')
        .onClick(() => {
          try {
            this.controller.runJavaScript(
              'receiveMessageFromArkUI("Hello from ArkUI!")',
              (error, result) => {
                if (error) {
                  console.error(`run JavaScript error, ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
                  return;
                }
                console.info(`Message sent to web result: ${result}`);
              }
            );
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Button('Get data from web')
        .onClick(() => {
          try {
            this.controller.runJavaScript(
              'getWebPageData()',
              (error, result) => {
                if (error) {
                  console.error(`run JavaScript error, ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
                  return;
                }
                if (result) {
                  this.webResult = result;
                  console.info(`Data from web: ${result}`);
                }
              }
            );
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: $rawfile('index.html'), controller: this.controller })
        .javaScriptAccess(true)
        .onPageEnd(e => {
          try {
            this.controller.runJavaScript(
              'test()',
              (error, result) => {
                if (error) {
                  console.error(`run JavaScript error, ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
                  return;
                }
                if (result) {
                  this.webResult = result;
                  console.info(`The test() return value is: ${result}`);
                }
              }
            );
            if (e) {
              console.info('url: ', e.url);
            }
          } catch (error) {
            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
        .width("100%")
        .height("50%")
    }
    .width("100%")
    .height("100%")
    .backgroundColor(Color.Black)
  }
}

index.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Web Communication</title>
</head>

<body>
<button onclick="callArkUIMethod()">Call ArkUI Method</button>
<button onclick="sendMessageToArkUI()">Send message to ArkUI</button>
<div id="messageFromArkUI"></div>
<script>
    function callArkUIMethod() {
        const result = window.objName.test();
        console.log("Result from ArkUI: ", result);
    }

    function sendMessageToArkUI() {
        window.objName.receiveMessageFromWeb('Hello from web!');
    }

    function receiveMessageFromArkUI(message) {
        const messageDiv = document.getElementById('messageFromArkUI');
        messageDiv.textContent = `Received message from ArkUI: ${message}`;
    }

    function getWebPageData() {
        return "Data from web page";
    }

    function test() {
        return "Test function result from web";
    }
</script>
</body>

</html>

Notes

Call deleteJavaScriptRegister(name) when the component is destroyed to cancel registration and avoid memory leaks:

onDestroy() {
  this.controller.deleteJavaScriptRegister(this.regName);
}

DEV Community: HarmonyOS Magician

Hidden Gems in HarmonyOS 5 for Business App Development - Graphic Transformations

Hidden Gems in HarmonyOS 5 for Business App Development — Graphic Transformations

1. Introduction

2. Translate

About the z Axis:

3. Rotate

3.1 Rotate Around Z Axis (Center Rotation)

3.2 Rotate Around Y Axis (Left-Right Flip)

3.3 Rotate Around X Axis (Top-Bottom Flip)

3.4 centerX / centerY / centerZ (Rotation Anchor)

3.5 perspective (Depth Perception)

4. Scale

5. Coming Up Next

6. Conclusion

HarmonyOS 5 Business App Tip - OTP Input Component

1. Introduction

2. ForEach + TextInput

Input + Focus Logic

3. Odd Issues

3.1 Missing Initial Focus

3.2 onChange Doesn’t Fire on Deletion

3.3 Soft Keyboard Hides on Focus Switch

4. Alternative: Single TextInput + Text Display

Key Details

5. Final Version

6. Conclusion

HarmonyOS 5: In-App Notification with SubWindow — A Coffee-Break Implementation

1. Introduction

2. WindowStage & SubWindow

Example: Creating and Displaying a SubWindow

SubWindow Lifecycle Steps

3. SubWindow UI — Notification Banner

4. Display & Animation Logic

Animation Trigger

5. Full Component Code

6. Conclusion

HarmonyOS 5 Business App Development Insights - In-Depth State Management

HarmonyOS 5 Business App Development Insights — In-Depth State Management

1. Introduction

2. @State

1. Initialization Behavior

2. Too Many @State Variables

3. Arrays

4. Scope Effects

5. Nested Objects

3. @prop

1. Initialization Behavior

2. Prop Chaining

3. @Require

4. @Observed

4. @link

1. Initialization Behavior

2. Used in Dialogs

3. Deeply Nested @link

5. @Watch

1. Avoid Mutating Watched Variables Inside Watchers

2. Event Propagation from Child to Parent

3. Not Sticky

4. Logging Use Case

6. Coming Soon

7. Conclusion

HarmonyOS 5 Building a Draggable Floating View Component in Your Application

Introduction

Design Concept

DragView Container

Edge Constraints

Measuring View Dimensions

Implementing Drag Interaction

Magnetic Snapping Animation

Customizing Initial Alignment

Example Usage

Conclusion

Unit and Integration Testing in HarmonyOS 5

1. Unit Testing

1.1 Purpose

1.2 Tools

1.3 Example

1.4 Execution

2. Integration Testing

About the `z` Axis: