Difference between the HarmonyOS lifecycle methods onPageShow, onPageHide, onForeground, and onBackground

#harmonyos #arkts #lifecycle #uiability

Read the original article：Difference between the HarmonyOS lifecycle methods onPageShow, onPageHide, onForeground, and onBackground

Context

In ArkTS/ArkUI development, there are page-level lifecycle callbacks (onPageShow, onPageHide) and application/Ability-level lifecycle callbacks (onForeground, onBackground). Understanding the difference is essential for managing resources properly and avoiding memory or power consumption issues.

Description

The table below compares when these four callbacks are triggered, their scope, and their typical use cases:

Feature	onPageShow	onPageHide	onForeground	onBackground
Trigger timing	Triggered every time a page is shown: during routing push/back, or when the app returns to the foreground and this page is on top	Triggered every time a page is hidden: navigating away, being covered, or when the app goes to the background	Triggered when the application/Ability moves from background to foreground (once, not tied to a page)	Triggered when the application/Ability moves from foreground to background (once, not tied to a page)
Scope	Applies only to `@Entry`-decorated page components	Same as left	UIAbility lifecycle callback, applies to the entire app (Ability)	Same as left
Use cases	Refresh page-specific data, restore scroll/playback position, re-bind listeners	Save page state, pause animations/timers, unbind listeners	Resume global state, reconnect services/sockets, restart global timers/tasks	Persist global state, disconnect services, stop background tasks, reduce power usage

Key point: Use onPageShow/onPageHide for page switches; use onForeground/onBackground for app foreground/background changes.
During one foreground/background switch, Ability callbacks trigger only once, while page-level callbacks may trigger multiple times depending on routing.

Solution / Approach

UI/data tied to a single page → Use onPageShow/onPageHide
- Example: Fetching page-specific data, restoring scroll position, starting/stopping page animations or timers.
Global resources or cross-page state → Use onForeground/onBackground
- Example: Global IM/Socket connections, foreground location, global analytics sessions, caching.
Avoid duplication
- Don’t start/stop global connections in page callbacks; don’t do page-specific UI updates in global callbacks.
Routing integration
- Navigation triggers onPageShow/onPageHide for every page enter/exit. Use this for light refreshes instead of repeating global re-initializations.

Example Code (ArkTS / ArkUI)

// 1) Page-level: @Entry component
@Entry
@Component
struct DetailPage {
  private timer?: number;

  onPageShow() {
    // Refresh only when this page is shown
    this.fetchDetailOnce();
    this.timer = setInterval(() => this.tick(), 1000);
  }

  onPageHide() {
    // Release page resources
    if (this.timer) clearInterval(this.timer);
    this.saveScrollPos();
    this.unbindPageEvents();
  }

  build() {
    // ...
  }
}

// 2) Application/Ability-level: UIAbility
export default class EntryAbility extends UIAbility {
  onForeground() {
    // App returns to foreground: restore global resources
    GlobalSocket.reconnect();
    Analytics.startSession();
  }

  onBackground() {
    // App goes to background: release/optimize resources
    GlobalSocket.disconnect();
    Analytics.endSession();
    GlobalCache.flush();
  }
}

Key Takeaways

Place short-lived, page-specific logic in onPageShow/onPageHide.
Place global, cross-page logic in onForeground/onBackground.
Page-level callbacks may fire multiple times per navigation; Ability-level callbacks fire only once per foreground/background switch.
Proper separation prevents redundant work, reduces power usage, and avoids resource leaks.