Manifest 中的清单成员
widgets 清单成员
发布于 更新于
清单成员 widgets 定义一组小组件,让已安装的 PWA 向操作系统的小组件界面提供内容。每项定义包含
Adaptive Cards 模板,以及可选的 JSON 数据 URL。卡片由小组件宿主(目前是 Windows 11 小组件面板)绘制;即使没有打开页面,Service Worker 也能响应
小组件生命周期事件,填充和刷新内容。
Windows 11 上的 Microsoft Edge 是微软文档记载的实现,宿主是 Windows 11 小组件面板 (Microsoft Edge 文档,“Display a PWA widget in the Windows Widgets Board”)。这个成员由微软的说明文档定义,文档把 WICG 列为预期孵化场所, 目前尚无 W3C 或 WICG 草案。没有其他浏览器记载过支持,不认识该成员的浏览器会直接忽略它。
| 属性 | 值 |
|---|---|
| 类型 | 小组件定义对象数组。Edge 中的必填键:name、description、tag(Service Worker 用来指代该小组件的字符串)、ms_ac_template(Adaptive Cards 模板的 URL)与 screenshots。可选键:short_name、data(模板绑定的 JSON 的 URL,提供时必须返回有效 JSON)、template(在 Edge 中仅供参考;微软的字段表把它列为可选,模板一节却称其必填)、type(数据的 MIME 类型)、icons、auth(布尔值)、multiple(布尔值,默认 true)与 update(刷新周期,单位为秒)。 |
| 默认值 | 缺省。没有该成员,应用不会在小组件面板提供任何内容。 |
| 示例值 | [{ "name": "待办任务", "description": "你的待办任务", "tag": "tasks", "ms_ac_template": "/widgets/tasks.json", "data": "/widgets/tasks-data.json", "screenshots": [{ "src": "/widgets/tasks.png", "sizes": "600x400" }] }]。 |
安装应用只是把它的小组件列进面板的 Add widgets 选择器。用户添加后小组件才激活,此时 Service Worker
收到 widgetinstall 事件;Worker 随后调用 self.widgets.updateByTag(tag, { template, data }) 完成渲染。
其余事件有 widgetuninstall、widgetresume(面板重新可见)与 widgetclick(用户触发了 Adaptive Cards
动作,动作名在 event.action 上)。同一个对象还提供 self.widgets.getByTag()、getByInstanceId() 与
matchAll() 用于枚举已安装的小组件。
示例描述从 https://tasks.example/ 安装的应用上的一个任务列表小组件。
声明小组件及其模板、数据与刷新周期
链接到“声明小组件及其模板、数据与刷新周期”一节Service Worker 用 tag 定位小组件,发布新版本时应保持这个值不变。update: 900 声明十五分钟的刷新周期(单位为秒)。Edge 不会自行刷新小组件,
更新要由 Service Worker 完成,例如在 periodicsync 事件里。
{ "widgets": [ { "name": "待办任务", "short_name": "任务", "description": "一眼看到你的待办任务", "tag": "open-tasks", "template": "open-tasks", "ms_ac_template": "/widgets/open-tasks.ac.json", "data": "/widgets/open-tasks-data.json", "type": "application/json", "update": 900, "icons": [{ "src": "/widgets/icon-96.png", "sizes": "96x96" }], "screenshots": [ { "src": "/widgets/open-tasks-wide.png", "sizes": "600x400", "label": "列出三个任务的待办任务小组件" } ] } ]}选择器显示的是 screenshots。这里应使用渲染后的卡片截图,不要用应用截图。
安装时渲染,恢复时刷新
链接到“安装时渲染,恢复时刷新”一节Service Worker 拉取小组件定义中指明的模板与数据,把两者交给 updateByTag()。同一个函数也在
widgetresume 时运行,这是面板隐藏期间数据过期后的刷新时机。
async function renderWidget(widget) { const definition = widget.definition; const template = await (await fetch(definition.msAcTemplate)).text(); const data = await (await fetch(definition.data)).text(); await self.widgets.updateByTag(definition.tag, { template, data });}
self.addEventListener('widgetinstall', (event) => { event.waitUntil(renderWidget(event.widget));});
self.addEventListener('widgetresume', (event) => { event.waitUntil(renderWidget(event.widget));});Edge 在 event.widget.definition 上暴露定义,其中 ms_ac_template 读作 msAcTemplate。
检测 API 并处理卡片动作
链接到“检测 API 并处理卡片动作”一节self.widgets 只存在于实现了小组件的浏览器,跨浏览器共用的 Service Worker 应先检测,再调用。
widgetclick 处理函数收到 Adaptive Cards 模板中声明的动作名,可以就地更新卡片。
if ('widgets' in self) { self.addEventListener('widgetclick', (event) => { if (event.action !== 'complete-task') return; event.waitUntil( fetch('/api/tasks/complete', { method: 'POST', body: JSON.stringify(event.data) }) .then(() => renderWidget(event.widget)), ); });} else { // 此浏览器没有小组件界面;应用只保留页内的任务列表。}没有 self.widgets 的环境会执行 else 分支,Worker 不注册监听器。
另请参阅
链接到“另请参阅”一节- widgets 浏览器支持
- Microsoft Edge 上的 PWA(侧边栏、应用商店)
- Windows 上的 PWA
- icons 清单成员
- screenshots 清单成员
- Display a PWA widget in the Windows Widgets Board(learn.microsoft.com)
- PWA-driven Widgets explainer(microsoftedge.github.io)
规范
| 规范 | 状态 |
|---|---|
| PWA-driven Widgets explainer | 社区草案 |