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.