CycleTracker：清单和图标

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

虽然根据规范，所有清单键或成员都是可选的，但一些浏览器、操作系统和应用程序分发商需要特定成员才能使 Web 应用程序成为 PWA。通过包含名称或简称、起始 URL、满足某些最低要求的图标以及 PWA 应在其中查看的应用程序视窗类型，您的应用程序将满足 PWA 的清单要求。

我们月经周期追踪应用程序的最小清单文件可能如下所示

{
  "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: 解释应用程序的功能。它提供对应用程序目的和功能的无障碍描述。

任务

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

示例解决方案

{
  "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: #efe; 设置在 body 元素选择器上。我们使用 #eeffee 来确保从占位符外观到应用程序加载的平滑过渡。

{
  "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 类型。

{
  "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 中），如果您在 HTML 文档的 <head> 中包含非标准 apple-touch-icon，通过 <link>，它们将优先于清单中声明的图标。

任务

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

玩弄 CycleTracker 的“cycle”和“period”这两个词，以及我们选择的绿色主题颜色，我们的图标图像可以都是浅绿色的正方形，带有绿色的圆圈。我们最小的尺寸 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%;
}

示例解决方案

{
  "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 资源，我们使用 <link> 元素，带有 rel="manifest" 属性，并将 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>

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

使用清单文件，并且从https:// URL（或localhost）加载时，大多数浏览器将识别您的网站为 PWA，有些浏览器会提示安装它。要使我们的 PWA 脱机工作，我们还需要添加一个服务工作者。

调试清单文件

一些浏览器开发者工具提供了对应用程序清单的洞察。在 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 还提供错误和警告、协议处理程序，以及有关如何改进清单和图标的信息。

我们的网络应用程序没有任何协议处理程序；本教程中没有涵盖该主题。如果我们包含了一些协议处理程序，它们将位于“协议处理程序”下。由于该部分为空，因此开发者工具会链接到有关该主题的更多信息。

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 图像生成器的链接。此工具创建了 100 多个用于 Android、Apple OS 和 Windows 的正方形 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 脱机工作，我们需要添加一个服务工作者，我们将在不使用框架的情况下进行操作。