manifest widgets 浏览器支持

发布于 2026-08-28更新于 2026-10-03作者 Carey Gill · 编辑流程

widgets 是一个 Web App Manifest 成员，微软的 Edge PWA 文档将它描述为“一个可以包含多个小组件定义的数组”。每个定义向操作系统的小组件面板注册一个小组件，随后由 PWA 的 Service Worker 负责渲染和更新它。

浏览器支持

本条目不提供兼容性表格。下面两个来源都没有给出按浏览器划分的支持表格，而猜测出来的表格比没有更糟——所以下面写的只是这两个来源真正记录的内容，不多一个字。

微软 Edge PWA 文档记录了该成员在 Windows 11 上的行为：在 Windows 11 上 “小组件出现在小组件面板（Widgets Board）中，你可以从任务栏左侧打开它”，并且 “在 Windows 11 中，渐进式 Web 应用（PWA）可以定义小组件、更新它们，并处理用户在其中的交互”。文档把 Windows 11 小组件面板称为小组件“目前”面向的宿主，并指出 “未来可能会有其他小组件宿主”。
PWA-driven Widgets 解释文档的状态为“Active”，预期归口为 “W3C Web Incubator Community Group”——也就是说这是一个孵化阶段的提案，而不是已完成的标准。

两个来源都没有记录其他任何浏览器实现了 widgets 成员，也都没有提供按浏览器划分的支持表格。对于微软文档覆盖范围之外的情况，应视为“未记录”，而不是支持或不支持。

如何使用

微软的字段表把 name、description、tag、ms_ac_template 和 screenshots 标为必填，把 short_name、icons、template、data、type、auth、update 和 multiple 标为选填：

{
  "widgets": [
    {
      "name": "PWAmp mini player",
      "description": "widget to control the PWAmp music player",
      "tag": "pwamp",
      "template": "pwamp-template",
      "ms_ac_template": "widgets/mini-player-template.json",
      "data": "widgets/mini-player-data.json",
      "type": "application/json",
      "screenshots": [
        { "src": "./screenshot-widget.png", "sizes": "600x400", "label": "The PWAmp mini-player widget" }
      ],
      "auth": false,
      "update": 86400
    }
  ]
}

同一份指南说明，“目前”只支持通过 ms_ac_template 以 URL 形式提供的自定义 Adaptive Cards 模板；template 字段“目前只是信息性的，并未被使用”。

如何在运行时检测

微软的指南把运行时接口记录为 Service Worker 全局对象（ServiceWorkerGlobalScope）上的 widgets 属性，它暴露了基于 Promise 的方法 getByTag、getByInstanceId、 getByHostId、matchAll、updateByInstanceId 和 updateByTag。指南没有给出特性检测的写法，因此下面检测该属性并提前返回的做法是本条目自己的选择，而非微软文档的推荐：

// 在 Service Worker 中（ServiceWorkerGlobalScope）。
self.addEventListener("widgetinstall", (event) => {
  if (!("widgets" in self)) {
    // 该浏览器没有 widgets API——没有可渲染的内容。
    return;
  }
  event.waitUntil(renderWidget(event.widget));
});

async function renderWidget(widget) {
  const template = await (await fetch(widget.definition.msAcTemplate)).text();
  const data = await (await fetch(widget.definition.data)).text();
  await self.widgets.updateByTag(widget.definition.tag, { template, data });
}

实践清单

清单里有小组件不等于屏幕上有小组件。按微软指南的说法，安装 PWA 会把它的小组件加入面板，但“尚未安装”——只有用户从面板中添加后才算安装，而且即便如此“它也不会被自动渲染”。Service Worker 必须调用 widgets.updateByTag。
update 是以秒为单位的频率，而不是自动刷新：微软的字段表写明“你的 Service Worker 中的代码必须执行更新；小组件不会自动更新”。
你无法直接复用应用自身的界面。指南指出，已有的 PWA“不能原样放进小组件面板”，而且 Windows 11 小组件面板“要求使用 Adaptive Card 模板而不是 HTML 和 JavaScript 来构建小组件”。
本地开发的前置条件不止一个浏览器：指南要求安装 WinAppSDK 1.2 并在 Windows 11 中启用开发者模式，才能在本机开发和测试小组件。
过大的图片会被忽略。按字段表的说明，大于 1024x1024 的小组件 icons “会被忽略”，大于 1024x1024 像素的 screenshots 图片同样如此；截图的 platform 字段支持 Windows 和 any 两个值。
不要只处理安装：文档记录的 Service Worker 事件包括 widgetinstall、 widgetuninstall、widgetresume 和 widgetclick。

下一步

清单 widgets：把 PWA 内容放上操作系统小组件面板 —— 该成员逐字段的完整参考。
manifest: screenshots 支持 —— 小组件必填的 screenshots 数组所类比的顶层成员。
Periodic Background Sync 支持 —— 微软指南用来按 update 间隔刷新小组件的 API。

← 返回兼容性浏览器。