배터리 위젯
최대 8개 기기의 충전 상태를 링으로 보여줍니다. 스마트홈 배터리, 센서 등 방전되면 곤란한 모든 것에 가장 적합합니다.
이 섹션은 App Store 심사를 기다리고 있는 앱 업데이트의 기능을 설명합니다. 업데이트가 출시되면 여기에서 자동으로 잠금 해제됩니다.
The battery template renders one ring per device, in the same idiom as Apple's own
Batteries widget. It is the right shape for any set of things that each have a percentage and a
name — smart-home batteries, sensor nodes, UPS units, tool packs.
Fields
| Field | Type | Notes |
|---|---|---|
template | string | Required. Must be "battery" |
devices | object[] | Required. Between 1 and 8 device objects, rendered in the order you send them |
devices[].name | string | Required. Must not be empty. Max 32 characters |
devices[].level | float | Required. Charge percentage, 0 to 100 |
devices[].charging | boolean | Overlays a charging bolt on the ring |
devices[].icon | string | SF Symbol shown inside the ring, or an MDI icon prefixed with mdi:. Max 128 characters |
devices[].color | string | Ring color — named color or hex (see Colors). Default is green, switching to red at or below 20% |
label, subtitle, icon, accent_color, background_color, text_color | string | Shared content fields — see the API reference |
Example: household devices
{
"content": {
"template": "battery",
"label": "Devices",
"icon": "battery.75percent",
"accent_color": "green",
"devices": [
{ "name": "Vacuum", "level": 68, "icon": "fan.fill" },
{ "name": "Front lock", "level": 45, "icon": "lock.fill", "charging": true },
{ "name": "Doorbell", "level": 18, "icon": "video.fill" },
{ "name": "Sensor hub", "level": 92, "icon": "sensor.fill" }
]
}
}Behavior
Each ring fills to its level and is tinted by its own color, falling back
to green — and to red at or below 20%, so a device that needs attention stands out without you
computing the color. charging: true adds the bolt overlay. Large Home Screen widgets
list all eight devices; smaller families render as many as fit, taking them from the front of the
array, so put the devices you care most about first.
The devices array is replaced wholesale by a merge patch, not merged element by element. Send the full roster on every update, including devices whose level has not changed — a patch carrying one device leaves the widget showing exactly that one device.
Add and reorder devices interactively on the playground to see how many rings each widget size shows.