진행률 위젯
어디까지 진행됐는지를 막대로 그립니다. 롤아웃, 백업, 할당량 등 끝이 정해진 작업에 가장 적합합니다.
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
{
"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.
이 섹션은 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 |
{
"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.