게이지 위젯

고정된 최솟값과 최댓값 사이의 다이얼에 값을 표시합니다. 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.