Виджет Gauge

Значение на шкале между фиксированными минимумом и максимумом. Лучше всего для SLO, бюджетов ошибок, температур и ёмкости.

The gauge template draws a value on an arc between two bounds you choose. It answers "how close to the limit is this?", which a bare number cannot: 2.4 means nothing until you know the ceiling is 5.

Fields

Field	Type	Notes
`template`	string	Required. Must be `"gauge"`
`value`	float	Required. Must be finite and fall within `min_value` – `max_value`; outside that range the request is rejected with `422`
`min_value`	float	Required. Start of the arc. Must be strictly less than `max_value`
`max_value`	float	Required. End of the arc
`unit`	string	Appended to the value and to the MIN / MAX end labels. Max 32 characters
`trend`	string	`up` / `down` / `flat`. Accepted by the server; the current iOS gauge does not draw an arrow, so treat it as forward-looking metadata rather than something users will see
`label`, `subtitle`, `icon`, `accent_color`, `background_color`, `text_color`	string	Shared content fields — see the API reference

Example: error rate against an SLO

PATCH /widgets/error-rate

{
  "content": {
    "template": "gauge",
    "value": 2.4,
    "min_value": 0,
    "max_value": 5,
    "unit": "%",
    "label": "Errors",
    "subtitle": "api-gateway · last 5m · SLO 1.0%",
    "icon": "chart.line.uptrend.xyaxis",
    "accent_color": "red"
  }
}

Behavior

Pick bounds once and keep them fixed. The arc's meaning comes entirely from where the needle sits between them, so a max_value that tracks the current peak makes every update look the same and hides exactly the trend you built the widget to see. Choose the number that means "this is the limit" — the SLO, the disk size, the tank capacity — and leave it alone.

Because the server rejects a value outside the bounds, a metric that can legitimately overshoot needs headroom in max_value rather than a clamp at the sender. Set the ceiling above the worst case you expect, or keep sending the raw number to a value widget and let the subtitle carry the threshold.

ℹ Инфо

The MIN and MAX end labels take the same unit as the value, so a unit that reads well next to a big number ("%", "°C") also has to read well in MAX 5%. Long words ("requests per second") are better placed in label or subtitle.

For a fraction that is already a percentage of a known whole, progress says the same thing with less configuration.

Появится в версии приложения 1.6

В этом разделе описана функция из обновления приложения, ожидающего проверки в App Store. Она автоматически разблокируется здесь, как только обновление станет доступным.

Set the bounds and drag the needle on the playground to see the arc across the small, medium, large, and Lock Screen families.