| name | zepp-os-ui |
| description | Use for creating, drawing, showing, or laying out any on-watch UI in a Zepp OS device app page or watchface - widgets via createWidget(widget.TYPE, ...), widget.TEXT / BUTTON / IMG / ARC / CIRCLE / CANVAS / GRADIENT_POLYGON / SCROLL_LIST / PAGE_SCROLL, showing text / labels / buttons / images, scrollable lists, arcs and progress rings, canvas custom drawing (lines, shapes, paths), handling tap / click / long-press / drag / swipe / move events on widgets, reading or updating widget properties, or px() screen adaptation. Use even when the task sounds like generic UI ("show an image", "make a scrollable list", "handle a tap on a button", "respond to swipe") - Zepp OS uses imperative @zos/ui createWidget, not JSX or HTML. |
Zepp OS UI
Context: Device App (watch) + Watchface — UI exists only on the watch, never in the side service / settings app.
API_LEVEL: 2.0+ (direct property accessors are [≥4.0]).
Prereq: runtime contexts & designWidth — see zepp-os-fundamentals.
Overview
All on-screen UI is built imperatively: createWidget(widget.TYPE, optionsObject) returns a widget instance you then read/update via properties and events. There is no JSX/HTML. Lay out with absolute coordinates and adapt across screen shapes with px().
import { createWidget, widget, prop, event, align, text_style } from '@zos/ui'
import { px } from '@zos/utils'
const title = createWidget(widget.TEXT, {
x: px(96), y: px(120), w: px(288), h: px(80),
color: 0xffffff, text_size: px(36),
align_h: align.CENTER_H, align_v: align.CENTER_V,
text: 'Hello',
})
Reading & setting properties
| API_LEVEL | Read | Write |
|---|
| 2.0 – 3.x | w.getProperty(prop.X) | w.setProperty(prop.X, value) |
[≥4.0] | w.text (direct getter) | w.text = 'new' (direct setter) |
Set several at once: w.setProperty(prop.MORE, { x, y, w, h, text }).
Common widgets
widget.* | Use |
|---|
TEXT | text label |
BUTTON | tappable button (click_func in options) |
IMG / IMG_ANIM | static image / frame animation |
FILL_RECT STROKE_RECT CIRCLE ARC | drawn shapes |
GROUP / VIEW_CONTAINER | group child widgets, move/show them together |
SCROLL_LIST / CYCLE_LIST | scrollable lists |
CANVAS [≥3.0] | freeform drawing |
QRCODE | QR code |
PAGE_INDICATOR SLIDE_SWITCH RADIO_GROUP CHECKBOX_GROUP STATE_BUTTON | interactive controls |
DIALOG (discontinued; prefer @zos/interaction createModal) KEYBOARD [≥3.0] PICK_DATE | dialogs & input |
Full list + every option: references/ui-widget-basic.md, ui-widget-form.md, ui-widget-layout.md.
Events
- Quick tap: pass
click_func: (w) => {...} in the widget options (buttons).
- General:
w.addEventListener(event.CLICK_DOWN, (info) => { info.x, info.y }). Events: CLICK_DOWN, CLICK_UP, MOVE, MOVE_IN, MOVE_OUT. Remove with removeEventListener. Page-level helpers (toast, dialog, gestures): references/ui-methods.md.
Screen adaptation (the part people skip)
Zepp OS v3 abstracts screens into three shapes; code once per shape, not per device:
- Design benchmarks: round
480×480, square 390×450, band 194×368.
platforms[].st in app.json: r round, s square, b band (sr adds a sub-resolution).px(n) scales a value from the target's designWidth to the actual screen — wrap every coordinate/size in px().- Keep style in per-shape layout files (e.g.
index.page.r.layout.js / .s.layout.js), behavior in index.page.js. Per-shape assets live in assets/<target>.<st>/.
Full spec: references/screen-adaptation.md. Grouping patterns: references/widget-group.md. Animations: references/ui-animations.md.
Common Mistakes
- Calling
@zos/ui from the side service or settings app → UI only exists on the watch (see zepp-os-fundamentals).
- Hard-coded pixels → wrap in
px() or the layout breaks on other screen shapes.
- Using direct
w.text = … accessors below 4.0 → they're [≥4.0]; use getProperty/setProperty for older levels.
- Recreating a widget to update it → keep the instance and
setProperty; don't createWidget again each refresh.
- Confusing watchface
hmUI with @zos/ui → watchfaces may use the legacy hmUI namespace; see zepp-os-watchface.
Screen adaptation checklist
Progress:
Reference
