跳转到内容

安装中的概念

增强安装界面

发布于

Chrome 的增强安装界面(richer install UI)是较大的安装对话框,显示应用名称、图标,以及 manifest 中的 description 和 screenshots。填入这两个成员,就能扩展只显示名称和图标的默认对话框。Android 上的 Chrome 94 在 manifest 具有 description 且至少一张截图时以底部面板显示它;桌面端 Chrome 108 在至少一张截图带有 form_factor: "wide" 时显示它。

浏览器自带入口和 BeforeInstallPromptEvent.prompt() 都在发起提示时决定使用哪种对话框。Chrome 读取可安装性检查时已经抓取的 manifest,按当前设备形态过滤 screenshots,过滤后为空则回退到默认对话框。页面的 JavaScript 无法请求、也无法检测出现的是哪种对话框;两种情况下 userChoice 的兑现方式相同。

Chrome 在计入每张截图之前都会执行这些规则:

  • 宽和高都在 320 px 到 3840 px 之间。
  • 长边最多为短边的 2.3 倍。
  • 一起显示的所有截图必须共享同一宽高比;第一张截图决定比例,Chrome 会丢弃不匹配的截图。
  • 桌面端只使用 form_factor: "wide" 的截图;Android 使用 form_factor: "narrow" 或未设置 form_factor 的截图。
  • 存在 sizes 与 type 时会读取;Chrome 会跳过加载失败的截图。

Chrome 还限制显示的截图数量,桌面端可能截断过长的 description,所以第一句话必须把意思说完。这两个成员是声明式的:已安装应用在运行时不读取它们,修改它们只会改变下一次的安装对话框(以及在 Chrome 周期性更新 manifest 之后应用的商店式详情页)。

为两种设备形态提供截图,部署前就检查 manifest,避免等到 DevTools 读取已部署文件时才发现问题。

一份同时满足 Android 与桌面端对话框的 manifest

链接到“一份同时满足 Android 与桌面端对话框的 manifest”一节

Android 使用的 narrow 截图都是 9:16;桌面端使用 wide 截图。每张都带 sizes,Chrome 不必解码图片就能应用比例规则。

{
"name": "Meal Planner",
"description": "Plan a week of meals, build the shopping list, and cook offline.",
"screenshots": [
{ "src": "/screenshots/week.png", "sizes": "1080x1920", "type": "image/png",
"form_factor": "narrow", "label": "Weekly plan" },
{ "src": "/screenshots/list.png", "sizes": "1080x1920", "type": "image/png",
"form_factor": "narrow", "label": "Shopping list" },
{ "src": "/screenshots/desktop.png", "sizes": "1920x1080", "type": "image/png",
"form_factor": "wide", "label": "Weekly plan on a large screen" }
]
}

去掉 wide 那一项,Android 面板保留,桌面端用户则悄悄回到默认对话框;把 1080×1920 与 1080×2340 的 narrow 截图混在一起,Chrome 只保留与第一项比例一致的截图。

没有运行时 API 能检测增强对话框。部署前可以用脚本按 Chrome 的条件检查 manifest。用 Node 对构建产物中的 manifest 运行它,不需要浏览器。

import { readFile } from 'node:fs/promises';
const manifest = JSON.parse(await readFile('dist/manifest.webmanifest', 'utf8'));
const shots = manifest.screenshots ?? [];
const problems = [];
if (!manifest.description) problems.push('缺少 description:Android 将显示默认对话框');
if (!shots.some((s) => s.form_factor === 'wide')) problems.push('没有 wide 截图:桌面端将显示默认对话框');
for (const s of shots) {
const [w, h] = (s.sizes ?? '').split('x').map(Number);
if (!w || !h) { problems.push(`${s.src}:请补充 sizes 以便检查比例规则`); continue; }
if (w < 320 || h < 320 || w > 3840 || h > 3840) problems.push(`${s.src}:${w}x${h} 超出 320-3840`);
if (Math.max(w, h) / Math.min(w, h) > 2.3) problems.push(`${s.src}:宽高比超过 2.3`);
}
console.log(problems.length ? problems.join('\n') : '截图通过增强安装界面规则');

通过了这个脚本的 manifest,仍可能因为某张图片在提示时返回非图片响应而回退到默认对话框,所以截图 URL 应与 manifest 放在同一次部署里。

规范

规范状态
无。