# screenshots 清单成员

> screenshots 成员列出标记为 wide 或 narrow 的图片，Android 上的 Chrome 94 与桌面端的 Chrome 105 在增强安装对话框中展示它们；Safari 与 Firefox 忽略该成员。

`screenshots` 是一个图片资源数组，展示应用使用中的样子。具备增强安装对话框的浏览器把它们渲染成
`description` 旁边的轮播；为 Web 应用打包上架的应用商店则把它们复制进商店列表。没有该成员时，
安装提示是只含图标、名称与来源的紧凑版本。

Android 上的 Chrome 94 与桌面端的 Chrome 105（以及 Edge 105 与 Samsung Internet 17.0）读取该
成员，并在至少有一张截图适合当前设备时切换到增强对话框（BCD `html.manifest.screenshots`）。iOS
与 macOS 上的 Safari 27 解析这个数组，但在"添加到主屏幕"或"添加到程序坞"流程中不使用其中任何
内容；桌面端 Firefox 157 不从清单安装 Web 应用。

## 成员

- **类型**：图片资源对象数组。每个对象有 `src`（相对于清单解析的 URL）、`sizes`（以像素计的
  `宽x高`）、可选的 `type`（`image/png`、`image/jpeg`、`image/webp`）、可选的 `form_factor`
  （`"wide"` 用于桌面与横屏平板，`"narrow"` 用于手机）、供辅助技术朗读的可选 `label`，以及给
  商店的可选 `platform` 提示。
- **默认值**：空数组；浏览器显示紧凑版安装提示。
- **示例值**：`[{ "src": "/shots/home.png", "sizes": "1080x1920", "type": "image/png", "form_factor": "narrow", "label": "Today's tasks" }]`。

Chromium 按设备形态施加限制。桌面端对话框取标记为 `wide` 的截图，最多 8 张；Android 对话框取
标记为 `narrow` 或未标记的截图，最多 5 张；每张截图每条边必须在 320 到 3840 像素之间，并与同一
`form_factor` 的第一张截图保持相同宽高比，否则被跳过。`sizes` 与解码后图片不符的也会被跳过。
桌面端对话框只在存在 `wide` 截图时出现，所以只有手机截图的清单在 Windows 与 macOS 上仍是紧凑
提示。

截图在安装对话框打开时才抓取，不在页面加载时抓取，所以它们的体积不影响页面加载指标；但它们需要
和图标一样的缓存纪律，因为 Chrome 在下一次清单更新之前不会重新抓取。

:::observed
Chrome 155（macOS 26，英文界面）的 DevTools > Application > Manifest，清单里的截图全部带
`"form_factor": "narrow"` 时：**Screenshots** 一节列出它们，**Errors and warnings** 一节显示
`Richer PWA Install UI won't be available on desktop. Please add at least one screenshot with the form_factor set to wide.`。
加入一张 1280×800 的 `wide` 截图并重新加载后，这一行消失，地址栏安装对话框出现轮播。
:::

## 示例

前两个示例是清单；第三个展示页面想复用同一组图片时能对安装提示做些什么。

### 同时服务桌面端与手机对话框

一张 `wide` 加两张 `narrow` 截图就能满足 Chromium 的两种对话框。`wide` 图保持 16:10，两张
`narrow` 图共用 9:19.5，这就是按设备形态分别适用的同比例规则。

```json
{
  "screenshots": [
    {
      "src": "/shots/desktop-overview.png",
      "sizes": "1280x800",
      "type": "image/png",
      "form_factor": "wide",
      "label": "Dashboard with the week's totals and a chart of spending by category"
    },
    {
      "src": "/shots/phone-today.png",
      "sizes": "1080x2340",
      "type": "image/png",
      "form_factor": "narrow",
      "label": "Today view listing three open tasks"
    },
    {
      "src": "/shots/phone-add.png",
      "sizes": "1080x2340",
      "type": "image/png",
      "form_factor": "narrow",
      "label": "Add-task sheet with amount and category fields"
    }
  ]
}
```

同一形态内的顺序有意义：第一项确定其余各项必须匹配的宽高比，也是用户滚动之前看到的那一张。

### 写出能替代图片的 label

`label` 是屏幕阅读器从截图里得到的唯一文字，商店也把它复用为图注。描述屏幕上显示的内容，而不是
"这是一张截图"这件事。

```json
{
  "screenshots": [
    {
      "src": "/shots/phone-map.webp",
      "sizes": "1170x2532",
      "type": "image/webp",
      "form_factor": "narrow",
      "label": "Map of the route from Oslo to Bergen with the next stop highlighted"
    }
  ]
}
```

`"Screenshot 1"` 这样的 label 能通过校验，却什么也没告诉用户；Chrome 会原样朗读这个字符串。

### 在自定义安装按钮里复用这些截图

运行时没有任何信号报告浏览器是否渲染了增强对话框。页面能做的是用 `beforeinstallprompt` 推迟
提示，用同一组图片展示自己的预览，再调用 `prompt()` 让浏览器的对话框（增强版或紧凑版）接着
出现。没有该事件的浏览器走回退分支，什么也不显示。

```js
let deferredPrompt = null;

window.addEventListener('beforeinstallprompt', (event) => {
  event.preventDefault();
  deferredPrompt = event;
  document.querySelector('#install').hidden = false; // 按钮展示同一组 /shots/ 图片
});

document.querySelector('#install').addEventListener('click', async () => {
  if (!deferredPrompt) return; // Safari、Firefox：没有可显示的提示，按钮保持隐藏
  deferredPrompt.prompt();
  const { outcome } = await deferredPrompt.userChoice;
  deferredPrompt = null;
  console.log(`install ${outcome}`); // "accepted" 或 "dismissed"
});
```

按钮预览直接复用清单里的 `/shots/` 文件，而不是另做一套，这样预览与浏览器对话框永远不会对不上。

## 另请参阅

- [description 清单成员](/zh/reference/manifest/description/)
- [icons 清单成员](/zh/reference/manifest/icons/)
- [更丰富的安装 UI：用描述和截图增强安装提示](/zh/reference/installation/richer-install-ui/)
- [beforeinstallprompt 与自定义安装提示](/zh/reference/installation/install-prompt/)
- [Web App Manifest - Application Information: screenshots member](https://www.w3.org/TR/manifest-app-info/#screenshots-member)（w3.org）
- [Richer install UI available for desktop](https://developer.chrome.com/blog/richer-install-ui-desktop)（developer.chrome.com）
- [screenshots](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/screenshots)（developer.mozilla.org）