Widget Value
Một con số lớn kèm đơn vị, nhãn và mũi tên xu hướng tùy chọn. Phù hợp nhất cho số đọc từ cảm biến, bộ đếm và mọi thứ gói gọn trong một dòng.
The value template is the plainest of the ten: one number, sized to fill the widget,
with an optional unit after it and a label above. Nothing is required beyond template, which makes it the right first widget to wire up — post a number and it
renders.
Fields
| Field | Type | Notes |
|---|---|---|
template | string | Required. Must be "value" |
value | float | The number rendered large. Must be finite. Absent puts the label in the hero slot instead, which is how you say "no reading yet" without faking a zero |
unit | string | Rendered after the value in a smaller weight (e.g. "°C", "req/s"). Max 32 characters |
min_value, max_value | float | Context bounds, drawn as a Range line on the large family when no stat_rows are set. min_value must be strictly less than max_value when both are sent |
trend | string | up / down / flat. Renders an inline arrow next to the value on the medium family. It is your annotation — the server never derives it |
stat_rows | object[] | Supporting rows below the number on the large family — the first 3 are drawn, and they take the place of the trend badge and Range line. Each is { label (≤32), value (≤32), unit? (≤16) }; the wire cap is 6 |
label, subtitle, icon, accent_color, background_color, text_color | string | Shared content fields — see the API reference |
Example: deploys today
{
"content": {
"template": "value",
"value": 18,
"label": "Deploys",
"subtitle": "Today · 14 prod · 4 staging",
"icon": "shippingbox.fill",
"accent_color": "cyan",
"trend": "up"
}
}Behavior
The number is formatted on device for the user's locale, so send a raw float rather than a
pre-formatted string: send 1234.5, not "1,234.5". Precision narrows as the
value grows — two decimals below 10, one decimal to 100, none to 10,000, then 12.3K and 1.2M above that — which keeps the figure legible at the hero size on every family. If
you need exact characters, a currency symbol, or a fixed number of decimals, use stat_list instead: every value there is a
string you control.
min_value and max_value do not clamp anything on this template — they only give the widget context to draw against. A value outside them is rendered as sent. If you want the reading positioned on a dial between two bounds, that is the gauge template.
Try it on the playground to see how a number sizes across the small, medium, large, and Lock Screen families.