面向一切会说 HTTP 的事物的 iOS 小组件 API

PushWard 是一个面向 Apple iOS 小组件的 API：声明一次小组件，然后用简单的 HTTP 请求驱动 iPhone 的主屏幕、锁定屏幕和待机显示。每次更新都会触发一次推送驱动的 WidgetKit 刷新 — 无需轮询，无需 WidgetKit 代码，无需 Xcode，您这边也无需 App Store 审核。

什么是 iOS 主屏幕小组件？

小组件是 Apple 的一目了然式展示面：iPhone 主屏幕、锁定屏幕和待机显示中始终可见的小卡片，无需打开应用即可展示信息。它们由 Apple 的设备端框架 WidgetKit 构建，通常每一个都隶属于一款您必须亲自开发、签名并发布的应用。PushWard 的小组件不同：由 PushWard 应用渲染，内容来自您的 API 调用 — 传感器读数、服务器健康检查、部署计数器，任何能以 JSON 发送的数据。

API 的工作方式

用 POST 注册一个小组件，再用 PATCH 更新它 — 整个循环就是这样。每次更新都会通过 Apple Push Notification service 发送一个轻量推送，通知 WidgetKit 重新加载小组件的时间线，新值无需小组件轮询就会出现。可选的按小组件推送节流会把突发的数据源合并处理。

通过 HTTP 注册并更新小组件

# 1. Register a widget
curl -X POST https://api.pushward.app/widgets \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "cpu-load", "name": "CPU Load", "content": {
    "template": "progress", "value": 0.42,
    "label": "load avg", "icon": "cpu", "accent_color": "cyan"
  } }'

# 2. Update it - WidgetKit refreshes the widget
curl -X PATCH https://api.pushward.app/widgets/cpu-load \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{ "content": { "value": 0.78, "accent_color": "orange" } }'

十种小组件模板

选择契合数据的布局：单个数值、进度条、状态指示灯、仪表盘、统计列表、趋势迷你图、倒计时、电池电量、日程或端点之间的流向。每个模板都由 PushWard 应用原生渲染，您的数据无需任何设计工作就能落入精致的布局。

浏览小组件模板 →

会行动的交互式小组件

小组件最多可携带三个轻点操作：不离开主屏幕就触发静默 webhook、深层链接到另一个应用，或打开一个 URL。直接在小组件上重启服务器、触发快捷指令或确认警报 — PushWard 应用完全不必打开。

与您的技术栈协作

用您已在运行的工具喂给小组件数据：Grafana 警报切换状态指示灯，Home Assistant 自动化更新温度，GitHub Actions 任务递增部署计数器，cron 脚本上报备份的时长。只要能发送 HTTP 请求，就能拥有一个小组件。

查看所有集成 →

小组件与实时活动并用

小组件与实时活动互为补充：小组件是持久的环境化状态，会一直留在主屏幕上直到被移除；实时活动则是一个有始有终的任务，运行期间固定在锁定屏幕和灵动岛上。PushWard 通过同一个 REST API 和同一个集成密钥驱动两者。

了解实时活动 API →

常见问题

这是 Apple 官方的 WidgetKit API 吗？

不是。WidgetKit 是 Apple 的设备端框架，直接使用它意味着构建并发布带有小组件扩展的自有 iOS 应用。PushWard 是一个独立的 iOS 小组件 API：PushWard 应用自带 WidgetKit 扩展，您的 HTTP 请求决定它展示什么。

小组件的更新有多快？

每个 PATCH 都会触发一个轻量推送，通知 WidgetKit 重新加载小组件，因此更新通常在几秒内生效。按小组件的推送节流（1 秒到 1 小时）会合并突发的数据源，让刷新保持在 iOS 授予扩展的预算之内。

小组件能在锁定屏幕和待机显示中使用吗？

能。PushWard 小组件可以添加到 iPhone 的主屏幕、锁定屏幕和待机显示。锁定屏幕的紧凑配件槽位会渲染精简布局，轻点即可打开配置好的轻点操作。

接收者需要安装应用吗？

需要 — 免费的 PushWard iOS 应用（iOS 26 或更高版本）负责渲染小组件，并将它们注册到 iOS 小组件选择器中。您无需构建或向 App Store 提交任何东西。

试用 iOS 小组件 API

在 playground 中构建小组件载荷，观看它在模拟 iPhone 上渲染，或阅读入门指南，几分钟内用 curl 注册您的第一个小组件。