Fortschritts-Widget

Wie weit etwas fortgeschritten ist, als Balken gezeichnet. Ideal für Rollouts, Backups, Kontingente und jede Aufgabe mit bekanntem Ziel.

The progress template renders a fraction as a percentage and a bar. Send value as a fraction between 0 and 1 — not a percentage — and the widget does the arithmetic and the formatting.

Fields

Field	Type	Notes
`template`	string	Required. Must be `"progress"`
`value`	float	Required (see the self-advancing note below for the one exception). A fraction in `0.0 – 1.0`; `0.42` renders as 42%. Out-of-range values are rejected with `422`
`trend`	string	`up` / `down` / `flat`. Drawn as a badge under the bar on the large family, when no `stat_rows` are set
`stat_rows`	object[]	Supporting rows under the bar on the large family — the first 3 are drawn, in place of the trend badge. Each is `{ label (≤32), value (≤32), unit? (≤16) }`; the wire cap is 6
`label`, `subtitle`, `icon`, `accent_color`, `background_color`, `text_color`	string	Shared content fields — see the API reference

Example: incident acknowledgements

PATCH /widgets/oncall-pages

{
  "content": {
    "template": "progress",
    "value": 0.6,
    "label": "Pages",
    "subtitle": "6 of 10 acked · INC-2841",
    "icon": "checklist",
    "accent_color": "green",
    "stat_rows": [
      { "label": "Acked",    "value": "6" },
      { "label": "Total",    "value": "10" },
      { "label": "Severity", "value": "SEV-2" }
    ]
  }
}

Behavior

The percentage shown above the bar is derived from value, so the number and the fill can never disagree. There is no "indeterminate" state: a job whose progress you cannot measure is better modelled as a status widget than as a bar stuck at some arbitrary fraction.

Bars do not animate between pushes — each update paints the new fill immediately. For something that should keep moving on its own, use the date pair below, or reach for a Live Activity, which is the right surface for work that is happening right now and will end.

Kommt in App-Version 1.6

Dieser Abschnitt beschreibt eine Funktion in einem App-Update, das derzeit vom App Store geprüft wird. Er wird hier automatisch freigeschaltet, sobald das Update verfügbar ist.

Self-advancing progress

Sending start_date and end_date together makes the bar advance on device across that window with no further pushes — useful for anything whose progress is purely a function of the clock: a maintenance window, a lease, a rendering job with a known finish time.

Field	Type	Notes
`start_date`	string	RFC 3339. Must be after 2000-01-01, no more than 366 days ahead, and strictly before `end_date`
`end_date`	string	RFC 3339, same bounds. With both dates set, `value` becomes optional

A two-hour maintenance window

{
  "content": {
    "template": "progress",
    "label": "Maintenance",
    "subtitle": "db-primary · read-only",
    "icon": "wrench.and.screwdriver.fill",
    "accent_color": "orange",
    "start_date": "2027-05-10T22:00:00Z",
    "end_date": "2027-05-11T00:00:00Z",
    "value": 0.0
  }
}

ℹ Info

Send value as well whenever you can, as the example does. Builds released before 1.6 ignore the dates and render value, so it is what keeps the widget honest on an older phone. Builds that understand the pair prefer the dates: they advance the bar from the window, and a window whose end_date has passed reads 100% no matter what value says.

Drag the value and open a window on the playground to see both modes across the small, medium, large, and Lock Screen families.