倒计时小组件

倒计时到某个日期，两次推送之间也会在设备上持续走时。加上开始日期，它就会自行填充进度条。

将在应用版本 1.6 中推出

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

The countdown template renders the time remaining until a date. WidgetKit redraws the number itself, so one push sets the target and the widget stays correct for as long as it is pinned — you only send another update when the target moves.

Fields

Field	Type	Notes
`template`	string	Required. Must be `"countdown"`
`end_date`	string	Required. RFC 3339 timestamp of the target. Must be after 2000-01-01 and no more than 366 days in the future. A date already in the past counts up instead of down
`start_date`	string	RFC 3339 timestamp the countdown started from. Must be strictly before `end_date`. Adds a progress bar that advances on device
`expired_text`	string	Shown in place of the countdown once `end_date` passes. Max 64 characters. Absent means the widget keeps counting, showing time elapsed since the target
`label`, `subtitle`, `icon`, `accent_color`, `background_color`, `text_color`	string	Shared content fields — see the API reference

Example: certificate renewal

PATCH /widgets/cert-renewal

{
  "content": {
    "template": "countdown",
    "end_date": "2027-05-10T16:13:00Z",
    "start_date": "2027-05-10T13:00:00Z",
    "expired_text": "Renewing",
    "label": "Cert renewal",
    "subtitle": "api.pushward.app",
    "icon": "lock.shield.fill",
    "accent_color": "indigo"
  }
}

Behavior

With only end_date the widget is a bare countdown. Add start_date and it also draws a bar that fills from the start to the target, advancing between pushes without any further requests — the widget knows both ends of the window, so it can interpolate. That makes the template cheap to drive: a maintenance window, a lease expiry, or a release date costs one PATCH when it is scheduled and one when it changes.

After the target passes, expired_text takes over if you set it ("Renewing", "Out now", "Overdue"). If you did not, the widget flips to counting the time elapsed since end_date, which is the right default for a deadline you want to keep staring at.

ℹ 信息

Dates are bounded on both sides: anything before 2000-01-01 is rejected outright (it catches milliseconds accidentally sent as seconds, which land in 1970), and anything more than 366 days ahead is rejected too. The bounds are re-checked on every PATCH against the merged content, so a widget whose end_date has aged into the past stays patchable.

Pick a target and watch it tick on the playground before wiring it to a real schedule.