배터리 위젯

최대 8개 기기의 충전 상태를 링으로 보여줍니다. 스마트홈 배터리, 센서 등 방전되면 곤란한 모든 것에 가장 적합합니다.

앱 버전 1.6에서 제공 예정

이 섹션은 App Store 심사를 기다리고 있는 앱 업데이트의 기능을 설명합니다. 업데이트가 출시되면 여기에서 자동으로 잠금 해제됩니다.

The battery template renders one ring per device, in the same idiom as Apple's own Batteries widget.

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. Replaced wholesale on PATCH — re-send the full roster, unchanged devices included (why)
`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%
`device_sort`	object[]	Up to 2 sort keys applied to `devices` before they are stored, so the smaller families show the devices you care about. Omit to keep the order you send
`device_sort[].field`	string	Required. `level` or `name`. Names compare case-insensitively
`device_sort[].direction`	string	`asc` (default) or `desc`
`label`, `subtitle`, `icon`, `accent_color`, `background_color`, `text_color`	string	Shared content fields — see the API reference

Example: household devices

PATCH /widgets/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

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.

Once you track more than two devices that ordering matters, because the small family shows only the first two and the medium family the first four. Send "device_sort": [{ "field": "level" }] and the server reorders devices for you on every update, so the emptiest devices are the ones that stay visible as levels drift.

Keys apply in order and the first one that separates two devices wins, so a second key is a tie-break. With one key, devices sharing a level keep the order you sent them in; add { "field": "name" } after the level key and those ties resolve alphabetically instead. The same field may not appear in both keys.

Lowest battery first, then alphabetical

{
  "content": {
    "template": "battery",
    "device_sort": [
      { "field": "level", "direction": "asc" },
      { "field": "name",  "direction": "asc" }
    ],
    "devices": [
      { "name": "Vacuum",     "level": 68 },
      { "name": "Front lock", "level": 45 },
      { "name": "Doorbell",   "level": 45 },
      { "name": "Sensor hub", "level": 92 }
    ]
  }
}

The server stores the sorted array, so every response and later GET return it reordered — and because the reordering happens on write rather than on the device, it works on every version of the app already installed.