CycleTracker：清单和图标

PWA 清单文件是一个 JSON 文件，它提供有关应用功能的信息，以便在用户设备上安装时，该应用看起来和行为都像原生应用。清单包含应用的元数据，包括其名称、图标和显示指令。

虽然根据规范，所有清单键（或成员）都是可选的，但某些浏览器、操作系统和应用分发商对于 Web 应用要成为 PWA 都有特定的必需成员。通过包含名称或短名称、起始 URL、满足最低要求的图标以及 PWA 应该查看的应用视口类型，您的应用将满足 PWA 的清单要求。

我们经期追踪应用的极简主义清单文件可能如下所示

json

{
  "short_name": "CT",
  "start_url": "/",
  "icons": [
    {
      "src": "icon-512.png",
      "sizes": "512x512"
    }
  ],
  "display": "standalone"
}

在保存清单文件并从我们的 HTML 文件链接到它之前，我们可以开发一个仍然简短但信息量更大的 JSON 对象来定义 PWA 的身份、呈现和图标。是的，上面会起作用，但让我们讨论此示例中的成员以及其他几个使清单文件能够更好地定义 CycleTracker PWA 外观的成员。

应用身份

为了标识您的 PWA，JSON 必须包含 name 或 short_name 成员，或两者兼有，以定义 PWA 名称。它还可以包含 description。

name: PWA 的名称。这是操作系统列出应用程序、应用程序图标旁边的标签等时使用的名称。
short_name: 如果空间不足以显示 name，则向用户显示的 PWA 名称。它用作手机屏幕上图标的标签，包括 iOS 上的“添加到主屏幕”对话框。

当 name 和 short_name 都存在时，name 在大多数情况下使用，而 short_name 在显示应用程序名称的空间有限时使用。

description: 解释应用程序功能。它提供了应用程序目的和功能的可访问描述。

任务

编写清单文件的前几行。您可以使用下面的文本，或更谨慎或更具描述性的值，以及您选择的描述。

示例解决方案

json

{
  "name": "CycleTracker: Period Tracking app",
  "short_name": "CT",
  "description": "Securely and confidentially track your menstrual cycle. Enter the start and end dates of your periods, saving your private data to your browser on your device, without sharing it with the rest of the world."
}

应用呈现

PWA 已安装和离线体验的外观（或呈现）在清单中定义。呈现清单成员包括 start_url 和 display，以及可用于自定义应用颜色的成员，包括 theme_color 和 background_color。

start_url: 用户启动 PWA 时的起始页面。
display: 控制应用的显示模式，包括 fullscreen、standalone（将 PWA 显示为独立应用）、minimal-ui（类似于独立视图但带有控制导航的 UI 元素）和 browser（在常规浏览器视图中打开应用）。

还有一个orientation 成员，它将 PWA 的默认方向定义为 portrait 或 landscape。由于我们的应用在这两种方向上都能很好地工作，我们将省略此成员。

颜色

theme_color: 操作系统和浏览器 UI 元素（例如某些移动体验上的状态栏和桌面操作系统上的应用程序标题栏）的默认颜色。
background_color: 在 CSS 加载之前作为应用背景显示的占位符颜色。为了在应用启动和加载之间创建平滑过渡，建议使用声明为应用background-color颜色的 <color>。

示例解决方案

由于示例应用程序是单页，我们可以使用 "/" 作为 start_url，或者完全省略该成员。出于同样的原因，我们可以通过将 display 设置为 standalone 来显示没有浏览器 UI 的应用程序。

在我们的 CSS 中，background-color: #eeffee; 设置在 body 元素选择器上。我们使用 #eeffee 来确保从占位符外观到应用程序加载的平滑过渡。

json

{
  "name": "...",
  "short_name": "...",
  "description": "...",
  "start_url": "/",
  "theme_color": "#eeffee",
  "background_color": "#eeffee",
  "display": "standalone"
}

应用图标

PWA 图标可帮助用户识别您的应用，使其更具视觉吸引力，并提高可发现性。PWA 应用图标会出现在主屏幕、应用启动器或应用商店搜索结果中。渲染图标的大小和文件要求因显示位置和显示者而异。清单是您定义图像的地方。

在清单 JSON 对象中，icons 成员指定了一个或多个用于不同上下文的图标对象数组，每个对象都有一个 src 和 sizes 成员，以及可选的 type 和 purpose 成员。每个图标对象的 src 列出单个图像文件的来源。sizes 成员提供了一个空格分隔的大小列表，该特定图像应该用于或关键字 any；该值与 <link> 元素的 sizes 属性相同。type 成员列出图像的 MIME 类型。

json

{
  "name": "MyApp",
  "icons": [
    {
      "src": "icons/tiny.webp",
      "sizes": "48x48"
    },
    {
      "src": "icons/small.png",
      "sizes": "72x72 96x96 128x128 256x256",
      "purpose": "maskable"
    },
    {
      "src": "icons/large.png",
      "sizes": "512x512"
    },
    {
      "src": "icons/scalable.svg",
      "sizes": "any"
    }
  ]
}

所有图标都应该具有相同的外观和感觉，以确保用户识别您的 PWA，但图标越大，它包含的细节就越多。虽然所有图标文件都是正方形的，但某些操作系统会渲染不同的形状，切掉部分或“遮盖”图标以适应 UI，如果图标不可遮盖，则会缩小并居中图标并带有背景。安全区，即如果图标被遮盖成圆形，仍能正常渲染的区域，是图像文件内部的 80%。图标通过 purpose 成员标记为可安全遮盖，当设置为 maskable 时，它将图标定义为自适应。

在 Safari 中，因此对于 iOS 和 iPadOS，如果您通过 <link> 在 HTML 文档的 <head> 中包含非标准的 apple-touch-icon，它们将优先于清单中声明的图标。

任务

将图标添加到您一直在构建的清单文件中。

玩转 CycleTracker 的“周期”和“月经”词语以及我们选择的绿色主题颜色，我们的图标图像都可以是带有绿色圆圈的浅绿色正方形。我们最小尺寸的 circle.ico，一个只代表句点标点符号和应用程序主题颜色的图标文件，以及我们的中间图像 circle.svg、tire.svg 和 wheel.svg，随着尺寸的增大，从普通圆圈到轮胎添加更多细节，我们最大的图标是带有辐条和阴影的详细轮子。也就是说，设计图标超出了本教程的范围。

<div>
  <img alt="a green circle" src="circle.svg" role="img" />
  <img alt="a simple wheel" src="tire.svg" role="img" />
  <img alt="a detailed wheel" src="wheel.svg" role="img" />
</div>

div {
  display: flex;
  gap: 5px;
}
img {
  width: 33%;
}

示例解决方案

json

{
  "name": "...",
  "short_name": "...",
  "description": "...",
  "start_url": "...",
  "theme_color": "...",
  "background_color": "...",
  "display": "...",
  "icons": [
    {
      "src": "circle.ico",
      "sizes": "48x48"
    },
    {
      "src": "icons/circle.svg",
      "sizes": "72x72 96x96",
      "purpose": "maskable"
    },
    {
      "src": "icons/tire.svg",
      "sizes": "128x128 256x256"
    },
    {
      "src": "icons/wheel.svg",
      "sizes": "512x512"
    }
  ]
}

将清单添加到应用

您现在有一个完全可用的清单文件。是时候保存它并从我们的 HTML 文件中链接到它了。

清单文件扩展名可以是规范建议的 .webappmanifest。但是，由于它是 JSON 文件，因此最常使用浏览器支持的 .json 扩展名保存。

PWA 需要从应用的 HTML 文档中链接清单文件。我们有一个功能齐全的应用，但它还不是 PWA，因为它尚未链接到我们的外部清单 JSON 文件。要包含外部 JSON 资源，我们使用带有 rel="manifest" 属性的 <link> 元素，并将 href 属性设置为资源的位置。

html

<link rel="manifest" href="cycletracker.json" />

<link> 元素最常用于链接样式表，对于 PWA，则用于链接必需的清单文件，但它也用于建立站点图标（包括“favicon”风格图标以及移动设备上的主屏幕和应用图标）等。

html

<link rel="icon" href="icons/circle.svg" />

当使用 .webmanifest 扩展名时，如果您的服务器不支持该 MIME 类型，请设置 type="application/manifest+json"。

任务

保存您在上述步骤中创建的清单文件，然后从 index.html 文件中链接到它。

可选地，也可以从您的 HTML 链接一个快捷方式图标。

示例解决方案

index.html 的 <head> 现在可能看起来类似于

html

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width" />
  <title>Cycle Tracker</title>
  <link rel="stylesheet" href="style.css" />
  <link rel="manifest" href="cycletracker.json" />
  <link rel="icon" href="icons/circle.svg" />
</head>

在 GitHub 上查看 cycletracker.json 文件并查看项目源代码。

有了清单文件，并且从 https:// URL（或 localhost）加载时，大多数浏览器会识别您的网站为 PWA，有些还会提示安装它。为了使我们的 PWA 离线工作，我们仍然需要添加一个 Service Worker。

调试清单文件

一些浏览器开发工具提供了对应用程序清单的洞察。在 Edge、Firefox 和 Chrome 开发工具中，清单成员及其值在“应用程序”面板下可见。

In the developer tools, the left panel includes links to the manifest. The right side reads App Manifest, with the file name as a link to the JSON file.

清单应用窗格提供了清单文件的名称作为链接，以及身份、呈现和图标部分。

The identity and presentation manifest members along with values, if present.

支持的清单成员会显示，以及所有包含的值。在此屏幕截图中，虽然我们没有包含 orientation 或 id 成员，但它们被列出。应用程序面板可用于查看清单成员甚至进行学习：在此示例中，我们学习到要指定与当前身份匹配的应用程序 ID，请将 id 字段设置为“/”。

Chrome 和 Edge 还提供错误和警告、协议处理程序以及改进清单和图标的信息。

我们的 Web 应用没有任何协议处理程序；本教程不涉及此主题。如果包含了一些，它们将在“协议处理程序”下找到。由于该部分为空，开发工具会链接到有关该主题的更多信息。

The four icons included in the Manifest file, with the background removed as "show only the minimum safe area for maskable icons is checked.

清单面板还包括对可遮罩图标安全区域的深入了解，以及指向 PWA 图像生成器的链接。此工具为 Android、Apple OS 和 Windows 创建了 100 多个方形 PNG 图像，以及一个列出所有图像及其大小的 JSON 对象。生成的图像可能无法满足您的需求，但为每个操作系统生成的图像大小列表展示了 PWA 可以在何处以及如何提供服务的多样性。

开发工具在识别支持哪些清单成员方面很有用。请注意，Firefox 开发工具包含 dir、lang、orientation、scope 和 id 的条目，尽管我们的清单文件没有包含这些成员。Firefox 还包含每个图标的 purpose 成员的值，如果未明确设置用途，则显示 any。

The Manifest panel in Firefox developer tools, showing values for the not included dir, scope, and id members, and the lang and orientation members without associated values.

接下来

为了使我们的 PWA 离线工作，我们需要添加一个 Service Worker，我们将在不使用框架的情况下完成此操作。

帮助改进 MDN

了解如何贡献

此页面最后由 MDN 贡献者于 2025 年 8 月 13 日修改。

在 GitHub 上查看此页面 • 报告此内容的问题