zepp-os-watchface

name

zepp-os-watchface

description

Use whenever the project is a Zepp OS watchface, watch face, clock face, or dial rather than a regular Mini Program app - configuring appType "watchface" and module.watchface.path in app.json, the WatchFace() entry (one render surface, no pages, no router), drawing the current time / date / seconds, building a digital or analog clock that redraws on tick, adding complications (heart rate, battery, weather), AOD / Always-On Display, edit mode so users can customize widgets, the lockscreen flag, or choosing Watchface Maker (no-code) vs a coded watchface project. Use even when the user says just "clock face", "dial", or "lockscreen" - watchface is a distinct appType, not a regular app. Do not use for normal pages-with-navigation apps (zepp-os-fundamentals + zepp-os-navigation-lifecycle).

Zepp OS Watchface

Context: Watchface (a distinct appType, not a Mini Program app). API_LEVEL: 1.0+ (legacy hm* globals on 1.0; @zos/* on 2.0+). Prereq: project structure & app.json — see zepp-os-fundamentals. Widgets — see zepp-os-ui. Data — see zepp-os-sensors.

Overview

A watchface is not an app: appType is "watchface", there are no pages, and the entry is WatchFace({ … }) (one render surface, not Page/App navigation). Two ways to make one: the visual Watchface Maker (no code) or a coded project via Zeus CLI (this skill).

app.json — the watchface module

{
  "app": { "appType": "watchface", /* … */ },
  "targets": {
    "gtr-3-pro": {
      "module": {
        "watchface": {
          "path": "watchface/gtr-3-pro/index",   // the WatchFace() entry
          "main": 1,        // this is the primary/preview face
          "editable": 1,    // user can customize widgets in edit mode
          "lockscreen": 1   // usable as lock screen
        }
      },
      "platforms": [{ "st": "r" }],
      "designWidth": 480
    }
  }
}

Use module.watchface (not module.page). appType must be "watchface".

The WatchFace entry

// watchface/<target>/index.js
import ui from '@zos/ui'                       // modern; 2.0+
import { getScene, SCENE_AOD } from '@zos/app'

WatchFace({
  initView() {
    // create widgets once: time, date, step complication, etc. (createWidget)
  },
  build() {
    this.initView()
  },
  onInit() {},
  onDestroy() {},
})

• Build the face with the same @zos/ui widgets as a device app (zepp-os-ui) — TEXT, IMG, ARC, plus watchface-specific time/data widgets.
• Read complications (steps, heart rate, battery) via @zos/sensor (zepp-os-sensors).

Always-On Display (AOD)

Watches dim into a low-power AOD scene. Detect it and render a simpler, lower-power face:

import { getScene, SCENE_AOD } from '@zos/app'
if (getScene() === SCENE_AOD) {
  // draw a minimal AOD layout (fewer pixels, no animation)
}

Ignoring AOD drains battery and may look wrong when dimmed.

Legacy vs modern API

	Watchface API
Zepp OS 1.0	global hmUI, hmSensor, hmFS, hmSetting, hmBle (no import)
Zepp OS 2.0+	import from @zos/ui, @zos/sensor, @zos/fs, … (same modules as apps)

Target 2.0+ and use @zos/* for new work; only touch hm* when maintaining a 1.0 face.

Common Mistakes

• Using module.page / appType: "app" for a watchface → it must be module.watchface + appType: "watchface".
• Expecting pages/router → a watchface is a single render surface; there's no navigation.
• Not handling SCENE_AOD → battery drain and broken dimmed appearance.
• Mixing hmUI (1.0) with @zos/ui (2.0+) in new code → pick the modern modules; see zepp-os-ui.
• Forgetting editable/main/lockscreen flags → the face won't be customizable / primary / usable as lock screen.

Watchface setup checklist

Progress:

• app.json: appType: "watchface" + module.watchface (path, main, editable, lockscreen), platforms[].st, designWidth.
• Entry: WatchFace({ initView, build, onInit, onDestroy }) — no Page/router.
• Create widgets once in initView() with @zos/ui; read complications (steps, HR, battery) via @zos/sensor.
• Branch on getScene() === SCENE_AOD to draw a minimal, low-power layout.
• Set editable / main / lockscreen flags as needed.

Reference

• references/specification.md — design spec (time, complications, layout)
• references/quick-start.md — Maker vs CLI
• Example: examples/watchface-entry.md
• Widgets: zepp-os-ui · Data: zepp-os-sensors · app.json: zepp-os-fundamentals