zepp-os-navigation-lifecycle

name	zepp-os-navigation-lifecycle
description	Use when navigating between Zepp OS device-app pages, passing data between pages, wiring App()/Page() lifecycle hooks, launching or exiting the app, or controlling page scroll/swipe.

Zepp OS Navigation & Lifecycle

Context: Device App (Mini Program). Watchfaces have no pages — see zepp-os-watchface. API_LEVEL: 2.0+. Prereq: registering pages in app.json — see zepp-os-fundamentals.

Overview

A Mini Program is App() + one or more Page() instances. You move between pages with @zos/router and hook behavior into the lifecycle. There is no virtual DOM — build() draws the UI imperatively (see zepp-os-ui).

Lifecycle order

App onCreate(params)   // init globalData; NO UI yet (page not loaded)
  → Page onInit(params)  // params from push/replace (a string)
    → Page build()        // draw widgets here
    → Page onDestroy()
App onDestroy()

// app.js
App({ globalData: { user: null }, onCreate(params) {}, onDestroy() {} })

// page/.../index.page.js
Page({
  state: { n: 0 },
  onInit(params) { /* params is a STRING from push() */ },
  build() { /* createWidget(...) */ },
  onDestroy() {},
})

Get instances: getApp() (app), getCurrentPage() (current page). Access global data via getApp()._options.globalData (documented accessor, API_LEVEL 2.0+) or this.globalData inside lifecycle hooks.

Router (@zos/router)

Method	Use
push({ url, params })	go to a page, keep history (back returns)
replace({ url, params })	go to a page, replace current (no back)
back()	return to previous page — cannot pass params
home()	exit the Mini Program back to the watchface
exit()	quit the Mini Program
launchApp({ appId, params })	launch another Mini Program / system app
getAppIdByName [≥3.6], checkSystemApp [≥3.0], setLaunchAppTimeout / clearLaunchAppTimeout	app-launch helpers

import { push } from '@zos/router'
push({ url: 'page/detail/index', params: { id: '0', type: 'normal' } })

Passing data between pages

Three mechanisms (pick by direction):

1. Forward (A→B): push({ params }). In B's onInit(params) the value arrives as a string — JSON.parse(params). One-way only.
2. Back (B→A) / shared: the global app object — getApp()._options.globalData (documented accessor, API_LEVEL 2.0+). back() can't carry params, so use this.
3. Persisted across pages: @zos/storage sessionStorage (key-value for the session). See zepp-os-settings-storage.

Router docs for replace mention onCreate, while the Page lifecycle reference and samples use onInit(params) for page params; treat push/replace params as data for the target page onInit.

Page scroll/swipe (@zos/page)

getScrollTop, scrollTo, setScrollMode, setScrollLock, swipeToIndex, getSwiperIndex — control vertical scroll and swiper pages. Full API: references/page-scroll.md.

Common Mistakes

• Drawing UI in App onCreate or Page onInit → the page isn't ready; draw only in build().
• Expecting onInit(params) to be an object → it's a string; JSON.parse it.
• Trying to pass data through back() → it doesn't carry params; use globalData or sessionStorage.
• Forgetting to register the page path in app.json targets[].module.page.pages → navigation fails (see zepp-os-fundamentals).
• Using push when you don't want a back step → use replace.

Page registration + navigation checklist

Progress:

• Register the page path in app.json → targets[].module.page.pages.
• Navigate with push({ url, params }) (keeps history) or replace({ url, params }) (no back step).
• Receive in the target's onInit(params) — params is a string; JSON.parse it.
• Draw UI only in build(), never in onInit/onCreate.
• Returning data? back() can't carry params — use getApp()._options.globalData or sessionStorage.

Reference

• references/router.md — every router method + options
• references/lifecycle.md · cross-page-communication.md · page-scroll.md
• Example: examples/navigate-and-pass-data.md
• Signatures: npm @zeppos/device-types