HarmonyOS Development in Practice: A Comprehensive Analysis of the Popup Component

The Perfect Fusion of Flexible Interaction and Dynamic Effects

In HarmonyOS application development, the popup (Popup) is a core component for user guidance and information reminders. It provides a lightweight, non-intrusive interactive experience through pop-up windows, suitable for scenarios such as screen recording prompts, operation guides, and status feedback. This article, based on official documentation, offers an in-depth analysis of the core features and practical techniques of Popups.

1. Two Types of Popups and Modal Control

Popups are divided into two categories to meet different scenario requirements:

System Popup (PopupOptions)

• Built-in standardized layout; directly displays text information via the message property.
• Supports adding button interactions: primaryButton (main button) and secondaryButton (secondary button), both can bind click events.

bindPopup(this.handlePopup, {
  message: 'Operation Confirmation',
  primaryButton: { value: 'Confirm', action: () => { ... } },
  secondaryButton: { value: 'Cancel', action: () => { ... } }
})

Custom Popup (CustomPopupOptions)

• Fully customizable UI using the @Builder constructor, supporting mixed graphics and text as well as complex layouts.

@Builder popupBuilder() {
  Row() {
    Image($r("app.media.icon")).width(24)
    Text('Custom Content').fontSize(15)
  }
}

Modal Control:

• When mask: true (or a color value), a background overlay locks user operations (modal window).
• When mask: false, users can interact with elements behind the popup (non-modal window).

2. Dynamic Interaction and Event Listening

State Binding and Triggering

Control display state via @State variables (e.g., show: boolean). For example, toggle by clicking a button:

Button('Show Popup').onClick(() => { this.handlePopup = !this.handlePopup; })

Event Callback

Use onStateChange to listen for popup state changes (such as automatically resetting state when closed):

onStateChange: (e) => {
  if (!e.isVisible) this.handlePopup = false;
}

3. Advanced Features: Animation and Style Customization

Animation Effects

Combine multiple animations using the transition property:

transition: TransitionEffect.scale({ x:1, y:0 })
  .animation({ duration: 500, curve: Curve.Ease })

Supports combined animations (e.g., opacity + translation):

TransitionEffect.OPACITY.combine(TransitionEffect.translate({ x:50, y:50 }))

Deep Style Customization

• Background color: popupColor: Color.Red
• Mask: mask: { color: '#33d9d9d9' }
• Position & size:
  • placement: Placement.Top (pop up from top)
  • width: 200 (fixed width)
• Remove default blur background: backgroundBlurStyle: BlurStyle.NONE

4. Avoiding Soft Keyboard Overlap and Best Practices

Prevent Obstruction Issues

Set keyboardAvoidMode: KeyboardAvoidMode.DEFAULT so that the popup will automatically avoid being covered by the soft keyboard.

Usage Scenario Recommendations

• Text Prompt: For non-interactive scenarios, use only the message to convey information.
• Action Confirmation: Use popups with buttons to handle user decisions.
• Guided Tips: Combine custom popups with precise placement (e.g., below a button).

Conclusion

The Popup component achieves powerful interaction capabilities through a simple API. Its flexible customization (animations, styles, modal control) and event response mechanisms significantly enhance the user experience of HarmonyOS applications. Developers should focus on:

• Choosing between modal/non-modal modes to balance user interruption,
• Using animations to enhance visual feedback,
• Leveraging @Builder for branded design.

Mastering these techniques allows you to easily address prompt needs in complex scenarios and create more professional HarmonyOS applications.