进度小组件

某件事进行到哪一步，以进度条呈现。最适合灰度发布、备份、配额，以及任何终点明确的任务。

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.

将在应用版本 1.6 中推出

本节介绍的功能来自一个正在等待 App Store 审核的应用更新。更新上线后，此处会自动解锁。

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
  }
}

ℹ 信息

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.