网页应用程序清单

W3C工作草案

更多关于此文档的详情
此版本：
https://www.w3.org/TR/2025/WD-appmanifest-20250505/
最新发布版本：
https://www.w3.org/TR/appmanifest/
最新编辑草案：
https://w3c.github.io/manifest/
历史：
https://www.w3.org/standards/history/appmanifest/
提交历史
编辑：
Marcos Cáceres (苹果公司)
Kenneth Rohde Christiansen (英特尔公司)
Diego González (微软公司)
Daniel Murphy (谷歌公司)
Christian Liebel (Thinktecture AG)
前编辑：
Matt Giuca (谷歌公司) - 截止到
Anssi Kostiainen (英特尔公司) - 截止到
Aaron Gustafson (微软公司) - 截止到
Mounir Lamouri (谷歌公司)
Rob Dolin (微软公司)
反馈：
GitHub w3c/manifest (拉取请求, 新问题, 打开的问题)
浏览器支持：
caniuse.com

Copyright © 2025 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

摘要

本规范定义了一种基于JSON的文件格式，提供开发人员一个集中位置来放置与网页应用程序相关的元数据。这些元数据包括但不限于网页应用程序的名称、图标链接，以及用户启动网页应用程序时的首选打开URL。清单还允许开发人员声明网页应用程序的默认屏幕方向，并提供设置应用程序显示模式（例如全屏）的能力。此外，清单允许开发人员将网页应用程序“限定”到一个URL。这限制了清单应用的URL范围，并提供了从其他应用程序“深度链接”到网页应用程序的方法。

使用这些元数据，用户代理可以为开发人员提供手段，创建更接近原生应用程序的用户体验。

本文件状态

本节描述了本文件在发布时的状态。当前 W3C 出版物列表及本技术报告的最新修订版可在 W3C 标准与草案索引（https://www.w3.org/TR/）中找到。

警告

本文档由Web应用程序工作组作为 工作草案使用推荐路径发布。

作为工作草案发布并不意味着得到了W3C及其成员的认可。

这是一个草案文档，可能会随时更新、替换或被其他文档废止。除非作为工作进展引用，否则引用此文档不适合。

本文档由根据W3C 专利政策运作的工作组制作。 W3C维护着与工作组成果相关的专利披露的公共列表；该页面还包括披露专利的说明。任何人若实际了解某项专利且认为其包含必要声明，则必须根据W3C专利政策第6节披露信息。

本文档受2023年11月3日W3C流程文件的管理。

1. 网页应用程序清单

应用程序清单是一个 [JSON] 文档，包含网页应用程序启动时的启动参数和应用程序默认设置。

清单有一个相关的清单URL， 即[URL]，从该清单获取。

清单可以在其根目录包含以下任何成员，所有这些成员都是可选的。成员可以按任意顺序出现。

注意

1.1 示例

本节为非规范性内容。

本节展示了开发人员如何利用本规范的各种功能。

1.1.1 典型结构

本节为非规范性内容。

以下展示了一个典型的清单。

示例 1：典型清单 
{
      "lang": "en",
      "dir": "ltr",
      "name": "Super Racer 3000",
      "short_name": "Racer3K",
      "icons": [{
        "src": "icon/lowres.webp",
        "sizes": "64x64",
        "type": "image/webp"
      }, {
        "src": "icon/lowres.png",
        "sizes": "64x64"
      }, {
        "src": "icon/hd_hi",
        "sizes": "128x128"
      }],
      "scope": "/",
      "id": "superracer",
      "start_url": "/start.html",
      "display": "fullscreen",
      "orientation": "landscape",
      "theme_color": "aliceblue",
      "background_color": "red"
    }

1.1.3 声明多个图标

本节为非规范性内容。

本节说明如何使用 icons 成员为 Web 应用声明一组图标。在以下示例中，开发者对与 Web 应用关联的图标做出了如下选择：

  • 开发者包含了两个相同尺寸但不同格式的图标。其中一个通过 type 成员明确标记为 WebP 格式。如果用户代理不支持 WebP，则可以回退到同尺寸的第二个图标。该图标的 MIME 类型 可以通过 HTTP 头确定，也可以在接收到图标的前几个字节后由用户代理嗅探出来。
  • 开发者为像素型图标格式（如 PNG 文件）指定了多种尺寸。这些尺寸为用户代理在特定场景（如设备主屏幕）选择合适图标提供了提示。开发者还包含了一个 ICO 文件（如 hd_hi.ico），其中包含针对特定显示尺寸单独设计的一系列光栅图标。例如，直接将 256x256 的图片缩小到 16x16 的场景通常并不合适，因为图像会丢失大量细节。通常会为 16x16 像素场景单独设计一张不同的图片。此外，还添加了一个 SVG 图标，可以动态缩放以适应任何所需的图标尺寸，但其缺点是在某些场景下（如尺寸过小导致模糊）可能不适用。

图标列表会提供给用户代理，用户代理会为不同场景和位置选择最合适的图标。

示例 3：多个图标 
{
    "icons": [
    {
        "src": "icon/lowres.webp",
        "sizes": "48x48",
        "type": "image/webp"
    },{
        "src": "icon/lowres",
        "sizes": "48x48"
    },{
        "src": "icon/hd_hi.ico",
        "sizes": "72x72 96x96 128x128 256x256"
    },{
        "src": "icon/hd_hi.svg"
    }]
}

1.1.4 创建快捷方式

本节为非规范性内容。

在以下示例中，开发人员包含了两个快捷方式。假设清单的URL是 https://example.com/manifest.webmanifest：

  • 第一个快捷方式会以“Play Later”文本显示。如果操作系统支持上下文菜单项的图标，并且也支持 SVG 图像，用户代理会在文本旁边显示 https://example.com/icons/play-later.svg。启动时，用户代理会实例化一个新的顶级浏览上下文并导航到 https://example.com/play-later。
  • 第二个快捷方式会以“Subscriptions”文本显示。启动时，用户代理会实例化一个新的顶级浏览上下文并导航到 https://example.com/subscriptions?sort=desc。
示例 4：添加快捷方式 
{
  "shortcuts": [
    {
      "name": "Play Later",
      "description": "View the list of podcasts you saved for later",
      "url": "/play-later",
      "icons": [
        {
          "src": "/icons/play-later.svg",
          "type": "image/svg+xml"
        }
      ]
    },
    {
      "name": "Subscriptions",
      "description": "View the list of podcasts you listen to",
      "url": "/subscriptions?sort=desc"
    }
  ]
}

1.1.5 理解“scope”

本节为非规范性内容。

scope 成员告诉浏览器哪些文档属于 Web 应用，哪些不属于——因此，当用户在网站中导航时，清单会“应用”到哪一组网页。

例如，{"scope": "/"} 表示清单适用于该源下的所有文档。另一方面，{"scope": "/racer/"} 表示只有路径为 "/racer/" 下的文档才在作用域内：因此 "/racer/race1.html"、"/racer/race2.html" 等都在作用域内，但 "/elsewhere/" 以及根目录 "/" 下的内容都属于“超出作用域”，清单不会应用于这些路径下的文档。只支持一个作用域路径。技术细节见 5. 导航作用域。

应用清单意味着清单中所有影响展示的成员都会生效，比如显示为“fullscreen”或应用特定的屏幕方向。只要应用导航到在作用域内的 URL，浏览器就会继续应用清单。然而，如果导航到 Web 应用“超出作用域”的页面，清单将不再被应用，浏览器会使用自己的默认设置。例如，应用将不再以全屏显示，而是作为浏览器标签页中的普通网页显示。如何处理页面在作用域内外的切换由实现者自行决定。技术细节见 1.16.5 应用清单。

最后，由于用户可以从某个源下的任意文档安装 Web 应用，因此建议总是在清单中声明 scope 成员。如果清单中缺少 scope 成员，则会使用 start_url 成员的路径作为后备。如果 start_url 也缺失，则会使用安装 Web 应用的文档 URL 作为作用域。为避免意外的导航行为，作者应始终包含 scope 成员，且建议设置为 "/"。

1.2 dir 成员

清单的 dir 成员指定可本地化成员的 默认方向。 dir成员的值可以设置为 文本方向之一。

文本方向如下，表示可本地化成员的值默认是：

"ltr"
从左到右的文本。
"rtl"
从右到左的文本。
"auto" (默认)
文本方向未知。用户代理应使用启发式算法来估计文本的显示，例如 [UAX9] 中描述的首强算法。

文本方向列表是 列表 « "ltr"、"rtl"、 "auto" »。

要处理 dir 成员，给定 有序映射 json 和 有序映射 manifest：

  1. 将 manifest["dir"] 设为 "auto"。
  2. 如果 json["dir"] 不存在，或 json["dir"] 不是字符串，则返回。
  3. 对 json["dir"] 去除首尾 ASCII 空白。
  4. 对 json["dir"] ASCII 小写化。
  5. 如果文本方向列表不包含 json["dir"]，则返回。
  6. 将 manifest["dir"] 设为 json["dir"]。

1.3 lang 成员

manifest 的 lang 成员是一个字符串，其形式为 语言标签，用于指定 manifest 的可本地化成员的语言。如果未指定 lang 成员，则语言视为未知。

注意

指定语言可以提升用户体验，帮助用户代理选择最合适的处理方式或资源，例如字体、样式、断字或无障碍的文本转语音语音。

语言标签 是一个字符串，其格式需符合 [BCP47] 中定义的 Language-Tag 的规范。

注意

语言标签不区分大小写。语言标签示例包括 'fr'（法语）、'en-AU'（澳大利亚英语）、或 'zh-Hans-CN'（中国大陆简体中文）。

要处理 lang 成员，给定 有序映射 json 和 有序映射 manifest：

  1. 如果 json["lang"] 不存在，或 json["lang"] 不是字符串，则返回。
  2. 对 json["lang"] 去除首尾 ASCII 空白。
  3. 如果调用 IsStructurallyValidLanguageTag 并传入 json["lang"] 返回 false，则返回。
  4. 设置 manifest["lang"] 为调用 CanonicalizeUnicodeLocaleId 抽象操作并传入 json["lang"] 的结果。

1.4 name 成员

manifest 的 name 成员是一个字符串，表示 Web 应用的名称，通常会展示给用户（例如在其他应用列表中，或作为图标的标签）。

name 成员是一个可本地化成员。

name 成员作为 可访问名称服务于已安装的网页应用程序。

注意：处理`name`成员

在处理清单时，使用处理文本成员算法来处理name成员。

1.5 short_name 成员

manifest 的 short_name 成员是一个字符串，表示 Web 应用名称的简短版本。它用于没有足够空间显示完整应用名称的场景。

short_name 成员是一个可本地化成员。

注意：处理`short_name`成员

在处理清单时，使用处理文本成员算法来处理short_name成员。

1.6 scope 成员

manifest 的 scope 成员是一个字符串，表示该 Web 应用导航作用域的应用上下文。

注意：默认范围

要处理 scope 成员，给定 有序映射 json 和 有序映射 manifest：

  1. 将 manifest["scope"] 设置为以 manifest["start_url"] 作为基础 URL 解析 "." 的结果。
  2. 如果 json["scope"] 是空字符串，则返回。
  3. 令 scope 为以 manifest URL 作为基础 URL 解析 json["scope"] 的结果。
  4. 如果 scope 解析失败，则返回。
  5. 将 scope 的 query 和 fragment 设为 null。
  6. 如果 manifest["start_url"] 不在 scope 作用域内，则返回。
  7. 否则，将 manifest["scope"] 设置为 scope。

1.7 icons 成员

清单的 icons 成员是图像，用于在各种上下文中作为网页应用程序的图标。例如，它们可以用来代表网页应用程序在其他应用程序列表中的位置，或与操作系统的任务切换器和/或系统首选项集成。

icons 成员是一个可本地化成员。

注意

1.8 display 成员

清单的 display 成员表示开发人员首选的网页应用程序显示模式。它的值是一个 显示模式。

要处理 display 成员，给定 有序映射 json 和 有序映射 manifest：

  1. 将 manifest["display"] 设为 "browser"。
  2. 如果 json["display"] 不存在，或 json["display"] 不是字符串，则返回。
  3. 去除首尾 ASCII 空白 于 json["display"]。
  4. ASCII 小写化 json["display"]。
  5. 如果display modes list不包含 json["display"]，则返回。
  6. 将 manifest["display"] 设为 json["display"]。

1.9 orientation 成员

manifest 的 orientation 成员是一个字符串，用来作为此 Web 应用所有顶级浏览上下文的默认屏幕方向。可用值是 OrientationLockType 枚举中的值，本规范将其称为方向值 （即 "any"、"natural"、"landscape"、"portrait"、"portrait-primary"、"portrait-secondary"、"landscape-primary" 或 "landscape-secondary"）。

如果用户代理支持orientation 成员的值作为默认屏幕方向，那么在 Web 应用的生命周期内（除非在运行时通过其他方式覆盖），该值会一直作为 默认屏幕方向。这意味着当屏幕方向被解锁时（参考 [SCREEN-ORIENTATION]），或顶级浏览上下文被导航时，用户代理 必须将方向恢复到默认屏幕方向。

Note

尽管本规范依赖了 [SCREEN-ORIENTATION] 中的 OrientationLockType，但用户代理 可选 实现 [SCREEN-ORIENTATION] API。当然，鼓励支持 [SCREEN-ORIENTATION] API。

一些 UI/UX 考量以及/或平台约定会导致某些屏幕方向和无法同时使用。 具体哪些方向和显示模式无法同时使用由实现者自行决定。例如，对于某些用户代理，在 browser 显示模式下更改应用的 默认屏幕方向可能不合理。

Note

一旦 Web 应用正在运行，其他方式也可以改变顶级浏览上下文的屏幕方向（例如通过 [SCREEN-ORIENTATION] API）。

要处理 orientation 成员，给定 有序映射 json 和 有序映射 manifest：

  1. 如果 json["orientation"] 不存在，或 json["orientation"] 不是字符串， 则返回。
  2. 去除首尾 ASCII 空白 于 json["orientation"]。
  3. ASCII 小写化 json["orientation"]。
  4. 如果 json["orientation"] 不包含任何方向值，则返回。
  5. 将 manifest["orientation"] 设为 json["orientation"]。

1.10 start_url 成员

该 manifest 的 start_url 成员是一个 字符串，用于表示 起始 URL，这是开发者希望用户代理在用户启动该 Web 应用时加载的 URL（例如，当用户从设备的应用菜单或主屏点击该 Web 应用图标时）。

该 start_url 成员仅作参考，用户代理可以 忽略它，或允许终端用户选择不使用它。用户代理可以 也允许终端用户在创建该 Web 应用的书签或之后的任何时间修改该 URL。

要 处理 start_url 成员，给定 有序映射 json、有序映射 manifest、URL manifest URL，以及 URL document URL：

  1. 将 manifest["start_url"] 设置为 document URL。
  2. 如果 json["start_url"] 不存在，或者 json["start_url"] 不是 字符串，则返回。
  3. 如果 json["start_url"] 的类型不是 字符串，或者 json["start_url"] 是空字符串，则返回。
  4. 令 start URL 为使用 manifest URL 作为基准 URL， 解析 json["start_url"] 的结果。
  5. 如果 start URL 失败，则返回。
  6. 如果 start URL 与 document URL 不 同源，则返回。
  7. 否则，将 manifest["start_url"] 设置为 start URL。

1.10.1 隐私考虑：start_url跟踪

start_url可能会被设计成表明应用程序是从浏览器外部启动的（例如，"start_url": "index.html?launcher=homescreen"）。这在分析和定制中可能有用，但也可能会开发者在start_url中编码唯一标识用户的字符串，这涉及指纹识别/隐私敏感信息。

注意: 不要向start URL添加标识符

开发者在start URL中包含唯一标识用户的信息是不好的做法，因为这会产生无法通过清除站点数据来删除的指纹。然而，本规范无法实际阻止开发者这样做。

鉴于上述情况，建议用户代理在安装时或之后的任何时间允许用户检查并在必要时修改应用程序的start URL。

用户代理可以提供其他保护措施，例如，当用户清除来自某源的数据时，用户代理可以建议卸载属于该源范围的应用程序，从而移除应用程序的start URL中的潜在指纹。

1.11 id 成员

该 manifest 的 id 成员是一个 字符串，用于表示 该应用的身份 (identity)。 该 identity 采用与 start URL 同源的 URL 形式。

该 identity 被用户代理用于在全局范围内唯一识别应用。当用户代理发现一个 manifest 的 identity 与已安装的应用不对应时，即使它与另一个应用来自相同的 URL，用户代理 SHOULD 将此 manifest 视为独立应用。当用户代理发现一个 manifest，其 manifest["id"] 与已安装应用的 identity 相等（可选择排除片段）时，即使它与之前所见的 URL 不同，也 SHOULD 将之视为对已安装应用 manifest 的替代，而不是独立应用。

Note: Excluding fragments is best practice
Note

identity 可被收集 Web 应用列表的服务用于唯一标识这些应用。

Note

identity 的处理方式类似于 URL，但它并不指向可跳转的资源，所以不要求 处于范围内。

要 处理 id 成员，给定 有序映射 json 和 有序映射 manifest：

  1. 将 manifest["id"] 设置为 manifest["start_url"]。
  2. 如果 json["id"] 的类型不是 字符串， 则返回。
  3. 如果 json["id"] 是空字符串，则返回。
  4. 令 base origin 为 manifest["start_url"] 的 origin。
  5. 令 id 为在使用 base origin 作为基准 URL 解析 json["id"] 的结果。
  6. 如果 id 解析失败，则返回。
  7. 如果 id 与 manifest["start_url"] 不 同源，则返回。
  8. 将 id 的 fragment 设为 null。
  9. 将 manifest["id"] 设为 id。

1.12 theme_color 成员

manifest的 theme_color 成员作为应用程序上下文的默认主题颜色。什么构成主题颜色在[HTML]中定义。

如果用户代理将 theme_color 成员的值作为 默认主题颜色，则该颜色将成为向该 manifest 应用的所有 浏览上下文的 主题颜色。但是，如果某个 document 的 URL 处于范围内，且包含一个 meta 元素，其 name 属性值为 "theme-color"， 则用户代理可以覆盖 默认主题颜色。但是，如果 document 的 URL 不 处于范围内，则用户代理不应通过 meta 元素（其 name 值为 "theme-color"）覆盖 默认主题颜色，因为应用无法控制这些文档。

用户代理在某些环境下可以忽略 主题颜色的alpha 分量。例如，在大多数环境下， 主题颜色不允许透明。

实现者可以覆盖 theme_color 成员所定义的值，以支持 prefers-color-scheme。

注意

当处理manifest时，处理颜色成员算法用于处理theme_color成员。

1.13 background_color 成员

manifest 的 background_color 成员描述了 Web 应用预期的背景颜色。它重复了应用样式表中已有的信息，但可以被 用户代理 用于在实际获取文件（无论是从网络还是磁盘）之前，已知 manifest 的 Web 应用绘制背景色。

background_color 成员仅用于提升 Web 应用加载时的用户体验， 不得被 用户代理 在 Web 应用样式表可用时作为背景色使用。

实现者可以覆盖 background_color 成员定义的值，以支持 prefers-color-scheme。

注释

当处理manifest时，处理颜色成员的算法用于处理background_color成员。

1.14 shortcuts 成员

manifest 的 shortcuts 成员是一个 列表， 其中包含多个 快捷方式项，用于访问 Web 应用中的关键任务。

注释

快捷方式的展示方式及展示的数量由用户代理和/或操作系统自行决定。

要 处理 shortcuts 成员，给定 有序映射 json、有序映射 manifest，以及 URL manifest URL：

  1. 令 processedShortcuts 为一个新的 列表。
  2. 设置 manifest["shortcuts"] 为 processedShortcuts。
  3. 如果 json["shortcuts"] 不存在，或 json["shortcuts"] 不是 列表，则返回。
  4. 对于 json["shortcuts"] 中的每个 entry：
    1. 令 shortcut 为用 entry、manifest URL、manifest["scope"] 和 manifest["dir"] 调用 处理一个快捷方式 的结果。
    2. 如果 shortcut 失败，则继续。
    3. 将 shortcut 添加到 processedShortcuts。

用户代理应该通过与主操作系统中应用程序图标的上下文菜单一致的交互来公开快捷方式（例如，右键单击或长按）。用户代理应该按清单中提供的顺序呈现快捷方式。用户代理应该以与主操作系统中应用程序图标的上下文菜单一致的方式表示快捷方式。为了与主操作系统的约定或限制保持一致，用户代理可以截断展示的快捷方式列表。

1.15 *_localized 成员

可本地化成员是指可以本地化的 manifest 成员。 manifest 的每个 可本地化成员 都有一个对应的 *_localized 成员，其中 * 代表成员名称。

语言映射（language map） 是一个 有序映射，其键为 语言标签，值为 本地化值。 本地化值 是以该键指定的语言进行本地化的内容。

分配给可本地化成员的值是默认表示。 *_localized成员包含语言映射，用于为应用程序中的给定本地化值定义本地化的值。用户代理应该使用用户的本地化设置选择与用户偏好最匹配的本地化值。当没有可用的本地化值时，将使用默认表示。

1.15.1 本地化文本值

本地化文本对象是一个带有以下属性的 有序映射：

value
本地化的 字符串。
dir （可选）
文本方向。
lang （可选）
语言标签。

对于接受 字符串 的 可本地化成员， *_localized 成员的 语言映射可接受 字符串或 本地化文本对象作为 本地化值。

当使用 字符串，或 本地化文本对象缺少 dir 成员时，将应用 默认方向 （manifest 的 dir 成员）。

Note

当使用 字符串，或 本地化文本对象缺少 lang 成员时，将应用 语言映射键的语言标签。

Note

要 处理 *_localized 文本成员，给定 有序映射 json、 有序映射 map、 字符串 member，以及 文本方向 defaultDirection：

  1. 如果 member 不在 json 中，返回。
  2. 令 languageMap 为 json[member]。
  3. 如果 languageMap 不是 有序映射，返回。
  4. 令 languageTags 为 languageMap 的 所有键。
  5. 将 map[member] 设为一个新的 有序映射。
  6. 对于 languageTags 中的每个 languageTag，执行 处理本地化文本对象，传入 languageMap[languageTag]、languageTag、map、member 和 defaultDirection。

要 处理本地化文本对象，给定 字符串 或 有序映射 localizedValue、字符串 defaultLanguageTag、有序映射 map、 字符串 member，以及 文本方向 defaultDirection：

  1. 令 normalizedValue 为一个 有序映射。
  2. 如果 localizedValue 是 字符串， 去除首尾 ASCII 空白后， 设置 normalizedValue["value"] 为 localizedValue。
  3. 如果 localizedValue 是 有序映射：
    1. 如果 localizedValue 中存在 "value" 且其为 字符串，去除首尾 ASCII 空白后， 设置 normalizedValue["value"] 为 localizedValue["value"]。
    2. 如果 localizedValue 中存在 "lang" 且其为 字符串，去除首尾 ASCII 空白后， 设置 normalizedValue["lang"] 为 localizedValue["lang"]。
    3. 如果 localizedValue 中存在 "dir" 且其为 字符串：
      1. 去除首尾 ASCII 空白。
      2. 如果 文本方向列表 包含 localizedValue["dir"]， 设置 normalizedValue["dir"] 为 localizedValue["dir"]。
  4. 如果 normalizedValue 中不存在 "value"，返回。
  5. 如果 normalizedValue 中不存在 "lang"， 设置 normalizedValue["lang"] 为 defaultLanguageTag。
  6. 如果 normalizedValue 中不存在 "dir"， 设置 normalizedValue["dir"] 为 defaultDirection。
  7. 如果调用 IsStructurallyValidLanguageTag 检查 normalizedValue["lang"] 或 defaultLanguageTag 返回 false，则返回。
  8. 设置 map[member][defaultLanguageTag] 为 normalizedValue。
Note

处理本地化文本对象算法既可接受 字符串，也可接受 本地化文本对象作为 本地化值参数，但处理结果会被规范化为包含 value、 lang 和 dir 成员的本地化文本对象。

1.15.2 本地化图片资源

对于接受 可本地化成员的 图片资源列表， *_localized 成员的 语言映射 可接受一个 图片资源列表 作为 本地化值。

要 处理 *_localized 图片资源成员，给定 有序映射 json、 有序映射 map、 字符串 member，以及 URL manifest URL：

  1. 如果 member 不在 json 中，返回。
  2. 令 languageMap 为 json[member]。
  3. 如果 languageMap 不是 有序映射，返回。
  4. 令 languageTags 为 languageMap 的 所有键。
  5. 设置 map[member] 为一个新的 有序映射。
  6. 对于 languageTags 中的每个 languageTag：
    1. 如果调用 IsStructurallyValidLanguageTag 检查 languageTag 返回 false，则 继续。
    2. 调用 处理图片资源，传入 languageMap[languageTag] 作为 图片资源列表， map[member]， manifest URL，以及 languageTag 作为成员。

1.16 Manifest 生命周期

本节定义了处理 manifest和 应用 manifest的算法。

用户代理必须支持"manifest"链接类型以及如何获取和处理关联资源的相关步骤。

1.16.1 处理 manifest

当被指示忽略时，用户代理必须视导致该条件的 manifest、成员或值为不存在。

下述算法提供了一个处理扩展点：其他为 manifest 添加新成员的规范建议在此算法点进行挂钩。它们不应 修改 manifest 对象中已存在的值。

Note

处理扩展点 旨在帮助避免猴子补丁相关问题。

处理 manifest的步骤如下算法所示。该算法接收一个 URL document URL， 一个 URL manifest URL， 以及一个 字节序列 bodyBytes。

  1. 令 json 为 解析 JSON 字节为 Infra 值 的结果，参数为 bodyBytes。
  2. 如果 json 是解析异常，或 json 不是 有序映射：
    1. 将 json 设为空的 有序映射。
  3. 令 manifest 为一个空的 有序映射。
  4. 处理 dir 成员，传入 json 和 manifest。
  5. 处理 lang 成员，传入 json 和 manifest。
  6. 处理文本成员，传入 json、manifest 和 "name"。
  7. 处理 *_localized 文本成员，传入 json、 manifest、"name_localized" 和 manifest["dir"]。
  8. 处理文本成员，传入 json、manifest 和 "short_name"。
  9. 处理 *_localized 文本成员，传入 json、 manifest、"short_name_localized" 和 manifest["dir"]。
  10. 处理 start_url 成员，传入 json、manifest、 manifest URL 和 document URL。
  11. 处理 id 成员，传入 json 和 manifest。
  12. 如果 document 的 已处理 manifest 不为 null，且其 id 不 等于 manifest["id"]，则返回。
  13. 处理 scope 成员，传入 json、manifest 和 manifest URL。
  14. 处理颜色成员，传入 json、manifest 和 "theme_color"。
  15. 处理颜色成员，传入 json、manifest 和 "background_color"。
  16. 处理 display 成员，传入 json 和 manifest。
  17. 处理图片资源，传入 json["icons"]、 manifest、manifest URL 和 "icons"。
  18. 处理 *_localized 图片资源成员，传入 json、manifest、 "icons_localized" 和 manifest URL。
  19. 处理 orientation 成员，传入 json、 manifest。
  20. 处理 shortcuts 成员，传入 json、manifest 和 manifest URL。
  21. 处理扩展点：在此处处理任何专有或其他受支持的成员。
  22. 将 document 的 已处理 manifest 设为 manifest。

1.16.2 处理颜色成员

Note: 支持的颜色

仅支持 sRGB 颜色，以及用户代理无需外部知识即可转换为 sRGB 的颜色（如 "AliceBlue"）。 例如，lab(…) 或 color(display-p3, …) 可被转换为 sRGB，但 color(--custom-profile, …) 需要查找匹配的 "@color-profile" 规则，而 manifest 中无法指定。

要 处理颜色成员，使用 有序映射 json、有序映射 map，以及 字符串 member：

  1. 如果 json[member] 不存在，或不是 字符串，则返回。
  2. 去除首尾 ASCII 空白 json[member]。
  3. 令 color 为将 json[member] 作为 CSS 颜色解析的结果。
  4. 如果 color 解析失败，则返回。
  5. 如果 color 可以仅凭用户代理已知信息转换为 sRGB，则将 color 转换为 sRGB。
  6. 如果 color 不是 sRGB 颜色，则返回。
  7. 将 map[member] 设为 color。

1.16.3 处理文本成员

要 处理文本成员，给定 有序映射 json、有序映射 map，以及 字符串 member：

  1. 如果 json[member] 不存在，或不是 字符串，则返回。
  2. 去除首尾 ASCII 空白 json[member]。
  3. 将 map[member] 设为 json[member] 的值。

1.16.4 无文档处理 manifest

处理 manifest步骤由 [HTML] 的 link 元素处理流程调用，但用户代理也可以在没有关联 文档的情况下处理 manifest。

在这种情况下，为了符合 [HTML] 中相应步骤的保证，用户代理应当确保至少在过去的某个时刻：

Note: 这些检查的理由

1.16.5 应用 manifest

已处理 manifest会应用到 顶级浏览上下文， 意味着 manifest 的成员会影响该浏览上下文的展示和/或行为。 每当创建一个 顶级浏览上下文时，用户代理可以 在导航开始前 应用一个 manifest。

Note

被应用了 manifest 的 顶级浏览上下文称为 应用上下文。

如果由于用户代理被要求导航到一个 深链而创建了 应用上下文，用户代理必须立即以 historyHandling 为 "replace" 导航到该 深链。 否则，在创建 应用上下文时，用户代理必须立即以 historyHandling 为 "replace" 导航到 起始 URL。

Note

1.16.6 更新 manifest

如 manifest link 关系所述，manifest 会在每次页面加载时获取并处理。当处理 manifest成功时，用户代理可以将更新后的 manifest 应用于与该应用关联的所有当前和未来的 应用上下文。

为了更新目的，下列成员为 安全敏感成员，因为它们会在安装和启动界面中展示：

  1. short_name 及其在 short_name_localized 中的本地化表示，
  2. icons 及其在 icons_localized 中的本地化表示，
  3. name 及其在 name_localized 中的本地化表示。

安全敏感成员应当按照 [UTS55] 中描述的方式进行双向隔离显示，无论其文本方向如何。

用户代理不应在未获得用户明确许可的情况下，自动应用 安全敏感成员的更改。

相反，用户代理应当为安全敏感成员的更改提供适当的管理选项，以便用户可以自主决定是否更新 Web 应用。

如果更新未包含安全敏感成员的更改，用户代理可以自动应用这些更改。

如果用户更改了本地化设置，用户代理可以自动将启动界面上可见的 安全敏感成员 调整为 *_localized 成员中指定的本地化表示。此类更改应当在用户下次打开 Web 应用时展示给用户。

Note: 用户代理不会应用部分更新

2. Manifest 图像资源

每个 manifest 图片资源 是一个 图片资源，在概念上属于 Web 应用，可根据使用该对象的成员语义在不同场景下使用（例如，作为应用菜单中的图标等）。

manifest 图片资源与 图片资源的不同之处在于它可以拥有额外的 purpose 成员。

用户代理可以 修改与 manifest 图像资源相关联的图像，以更好地匹配平台的视觉风格， 在显示给用户之前。例如，通过将图像的角变圆或以特定颜色绘制。建议开发人员准备好他们的图像资源以适应这些情况， 以避免通过例如颜色变化或角被裁剪等方式丢失重要信息。

2.1 purpose 成员

purpose 成员是一个 无序且唯一的以空格分隔的标记集合。允许的取值为 图标用途。

当 manifest 图像资源 作为一个 图标 使用时， 开发者可以提示该图像在主机 OS 的上下文中具有某种特殊用途 （即为了更好的集成）。用户代理 不应 使用与声明的 图标用途 不符的图标。

Note

例如，带有 "monochrome" 用途的图标可以作为徽章或固定图标使用，采用纯色填充，与应用的全彩启动图标在视觉上区分开。用户代理会将 purpose 成员的值作为提示，用于决定图标的展示位置和方式。除非开发者另有声明，用户代理可以将图标用于 任意用途。

图标用途 如下：

monochrome
用户代理可以在需要 带有实色填充的单色图标 的地方显示此图标。图标中的颜色信息会被丢弃，仅使用 alpha 数据。 用户代理可以将该图标作为任何实色的遮罩来使用。
maskable
该图像是以 图标遮罩和安全区 为设计目标的，因此图像中超出 安全区 的任何部分都可以被用户代理安全地忽略和遮罩掉。
any（默认）
用户代理可以自由地在不需要 purpose 的地方显示此图标。例如，具有 "any" 用途的 manifest 图像资源 不会用于需要 "monochrome" 的上下文中。

图标用途列表 是 列表 « "monochrome"、"maskable"、"any" »。

Note

如果一个图标包含多个用途，则可用于这些用途中的任意一种。如果声明的用途都不被识别，则该图标会被完全忽略。例如，如果一个图标的用途为 "monochrome fizzbuzz"，则它可以作为 monochrome 图标使用，因为 "monochrome" 是有效用途。 但如果图标只有 "fizzbuzz" 用途，则会被忽略。

要确定图片用途，给定 有序映射 json：

  1. 如果 json["purpose"] 不存在，或不是 字符串：
    1. 返回 集合 « "any" »。
  2. 令 keywords 为 按 ASCII 空白分割 json["purpose"] 的结果。
  3. 令 purposes 为新的 集合。
  4. 对于 keywords 中的每个 keyword：
    1. 如果 图标用途列表不包含 keyword， 则继续。
    2. 否则，追加 keyword 到 purposes。
  5. 如果 purposes 为空，则返回失败。
  6. 返回 purposes。

2.2 内容安全政策

管理用户代理是否可以获取图标图片的安全策略由与 manifest 所属 Document 关联的 img-src 指令 [CSP3] 控制。

2.3 图标遮罩和安全区域

一些平台有其首选的图标形状，但由于网络应用程序应在多个平台上工作，因此可以通过添加 maskable 目的，指示图标可以应用用户代理指定的遮罩。这样，平台可以确保图标与平台良好集成，甚至可以在平台的不同位置应用不同的遮罩和背景颜色。

安全区域 是 maskable 图标中始终可见的区域，无论用户代理的偏好如何。它被定义为一个圆，中心点位于图标的中心，半径为图标大小的 2/5（40%），即使图标不是正方形，也意味着图标宽度和高度中的较小值。

Note

设计 maskable 图标的设计者应确保所有重要内容都位于 安全区 内。

安全区域图示
图 1 安全区域是一个居中的圆，半径为图标宽度和高度的最小值的 2/5（40%）。

此区域内的所有像素在所有遮罩中都保证可见。安全区域外的像素无法保证始终可见，取决于所应用的遮罩。

用户代理 可以 应用任意大小的遮罩，使得距离图像中心（安全区域）超过图像大小 2/5 的像素透明。

用户代理 不得 将安全区域内的任何像素变为透明。

用户代理 可以 通过添加额外的填充来放大图标。

如果图标包含透明像素，用户代理 必须 将图标合成到用户代理选择的实色填充（例如白色）上。

Note

建议设计者在 maskable 图标中避免使用透明像素。

2.3.1 遮罩示例

Note

保持在安全区内，大多数图标在上下左右会有约 10% 的留白区域，这部分应无内容或仅有非核心内容（如图标背景）。建议开发者在仅显示安全区时检查自己的图标效果。

2.3.1.1 带有 “maskable” 目的的图标
一个图标覆盖在棋盘背景上
图 2 图像 带有透明背景的基础图像
一个紫色圆圈中的图标（尺寸的 40%）覆盖在黄色背景上
图 3 安全区域 半径为图标大小的 2/5（40%）的圆圈
2.3.1.2 遮罩示例
一个位于圆角黄色方形中的图标，背景为紫色
图 4 圆角方形 Android
一个位于极圆角黄色方形中的图标，背景为紫色
图 5 极圆角方形 Android
一个位于圆形黄色背景中的图标，背景为紫色
图 6 圆形 Android
一个位于稍圆角黄色方形中的图标，背景为紫色
图 7 圆角方形 iOS
一个黄色背景中的图标
图 8 全屏 Windows

2.4 单色图标和实心填充

一些平台强制要求图标以实心填充的形式显示，例如单一颜色，其中只有图标的透明度可以在 清单中声明。由于Web应用程序需要跨多个平台工作，可以通过添加 单色目的来指示图标可以应用由用户代理指定的颜色。这允许平台确保图标与平台良好集成，甚至在平台的不同地方应用不同的颜色和填充。

当呈现单色图标时，用户代理不得独立显示像素的红色组件、绿色组件或蓝色组件。用户代理应显示每个像素的原始alpha值，但红、绿和蓝的值由用户代理选择。建议用户代理为所有像素使用相同的颜色值。

注

单色图标的设计者可以将所有像素设置为黑色，仅使用透明度来创建其图标的轮廓。

用户代理可以通过添加额外的填充来放大图标。

用户代理可以在透明像素后面添加任意颜色的背景，并且应确保背景与图标有足够的对比度。

2.4.1 单色图标的使用示例

2.4.1.1 使用示例
一个黑色图标在棋盘格背景上
图 9 图像 无颜色的基础图像。
一个黑暗渐变图标在棋盘格背景上
图 10 渐变填充 用渐变填充的图像。
一个深黄色图标在浅灰色背景上
图 11 带填充的纯色填充 用清单中的主题颜色填充。

2.5 处理图像资源

要 处理图片资源，给定 列表 images、 有序映射 map、manifest URL 和 字符串 member：

  1. 令 imageResources 为一个新的 列表。
  2. 将 map[member] 设为 imageResources。
  3. 如果 images 不是 列表，则返回。
  4. 对于 images 中的每个 potential image：
    1. 令 image 为运行 从 JSON 处理图片资源，参数为 potential image 和 manifest URL 的结果。
    2. 如果 image 失败，则继续。
    3. 令 purposes 为 确定图片用途， 参数为 potential image。
    4. 如果 purposes 失败，则继续。
    5. 将 image["purpose"] 设为 purposes。
    6. 追加 image 到 imageResources。

3. 快捷方式项目

每个 快捷项 是一个 有序映射，表示指向 Web 应用内关键任务或页面的链接。它具有以下成员：

用户代理可以利用这些成员组装一个上下文菜单，当用户与 Web 应用图标交互时由操作系统显示。当用户从操作系统菜单调用快捷方式时，用户代理应当运行 启动快捷方式。

3.1 name 成员

快捷项的 name 成员是一个字符串，表示快捷方式的名称，通常会在上下文菜单中展示给用户。

name 成员是一个 可本地化成员。

3.2 short_name 成员

快捷项的 short_name 成员是一个字符串，表示快捷方式名称的简短版本。它用于空间不足以显示完整名称的场景。

short_name 成员是一个 可本地化成员。

3.3 description 成员

快捷项的 description 成员是一个字符串，允许开发者描述该快捷方式的用途。用户代理可以将此信息暴露给辅助技术。

description 成员是一个 可本地化成员。

3.4 url 成员

快捷项的 url 成员是一个 已处理 manifest 作用域内的 URL，在激活关联快捷方式时会打开该地址。

3.5 icons 成员

快捷方式项目的 icons 成员列出作为快捷方式在各种上下文中的标志性表示的图像。

icons 成员是一个 可本地化成员。

3.6 启动快捷方式

当 快捷方式项目 shortcut 含有 manifest 被调用时，运行步骤 启动网络应用程序，并传递 manifest 和 shortcut.url。

3.7 处理快捷方式项目

要 处理快捷项，给定 有序映射 item、URL manifest URL、URL scope，以及 文本方向 defaultDirection：

  1. 如满足以下任一条件，则返回失败：
    • item 不是 有序映射。
    • item["name"] 不存在。
    • item["name"] 为空字符串。
    • item["url"] 不存在。
    • item["url"] 不是 字符串。
  2. 令 url 为 解析 item["url"]，以 manifest URL 作为基础 URL 的结果。
  3. 如果 url 解析失败，则返回失败。
  4. 如果 url 不在 scope 内，则返回失败。
  5. 令 shortcut 为 有序映射 «[ "url" → url， "name" → item["name"] ]»。
  6. 处理 *_localized 文本成员，传入 item、 shortcut、"name_localized" 和 defaultDirection。
  7. 如果 item 中存在 "short_name"，且其为 字符串，则设置 shortcut["short_name"] 为 item["short_name"]。
  8. 处理 *_localized 文本成员，传入 item、 shortcut、"short_name_localized" 和 defaultDirection。
  9. 如果 item 中存在 "description"，且其为 字符串，则设置 shortcut["description"] 为 item["description"]。
  10. 处理 *_localized 文本成员，传入 item、 shortcut、"description_localized" 和 defaultDirection。
  11. 处理图片资源，传入 item["icons"]、shortcut、 manifest URL 和 "icons"。
  12. 处理 *_localized 图片资源成员，传入 item、 shortcut、"icons_localized" 和 manifest URL。
  13. 返回 shortcut。

4. 可安装 Web 应用

任何网站都是一个可安装 Web 应用。

用户代理可以为终端用户提供一种方式，将 Web 应用安装到用户设备上，使用户能够实例化一个新的 顶级浏览上下文，并应用 manifest 的各成员 配置。

一旦 Web 应用被安装，它就被称为已安装 Web 应用：即 manifest 的成员或其默认值被 应用到该 Web 应用的 顶级浏览上下文。这使已安装 Web 应用区别于传统书签，因为通过传统书签打开网页时不会应用 manifest 的属性。

Note

例如，在支持安装的用户代理中，Web 应用可以以与原生应用无异的方式呈现和启动：比如作为带标签的图标出现在主屏、启动器或开始菜单。当 启动 Web 应用时，用户代理会在加载 起始 URL前将 manifest 应用到 顶级浏览上下文。这样用户代理有机会应用 manifest 的相关值，比如更改 Web 应用的 显示模式和屏幕方向。或者，用户代理也可以将 Web 应用 安装到自身的书签列表中。

4.1 应用名称

应用名称来自 name 成员或 short_name 成员。用户代理应当优先从对应的 *_localized 成员解析本地化值。

当 name 或 short_name 成员缺失、为空或类型错误时，用户代理可以用 name 成员作为 short_name 的后备，或反之亦然。

如果 name 和 short_name 都缺失、为空或类型错误，用户代理可以回退到 Document，查找合适的替代（如用 application-name 替代 name 或 short_name）。或者，用户代理应当分配一个遵循平台规范的默认名称（如“未命名”）。也可以允许终端用户输入文本作为 应用名称。

当 name 和 short_name 都存在时，具体使用哪个成员由实现自行决定（例如 short_name 可能更适合用于图标下方空间有限的场景）。

4.2 启动 Web 应用

由操作系统或用户代理自行决定，运行启动 Web 应用的步骤，参数为 已处理 manifest。

Note

这通常发生在用户从应用启动界面（如主屏、启动器或开始菜单）选择已安装的 Web 应用时。

启动 Web 应用的步骤如下算法所示。该算法接收 已处理 manifest manifest，可选 URL target URL， 可选 POST 资源 POST resource，返回一个 应用上下文。

如果给定 target URL，则其必须在 manifest 的作用域内。

其他规范可以用自己的步骤替换本算法的步骤。此替换对所有 启动 Web 应用的调用生效。

Note

该算法可被替换，以便实验性的 launch_handler manifest 字段配置所有 Web 应用启动行为。替换算法默认会调用 创建新应用上下文，但在特定条件下行为不同。

  1. 返回运行创建新应用上下文的结果，参数为 manifest、target URL 和 POST resource。

创建新应用上下文的步骤如下算法所示。该算法接收 已处理 manifest manifest，可选 URL target URL，可选 POST 资源 POST resource，返回一个 应用上下文。

  1. 如果未给定 target URL，则将其设为 起始 URL。
  2. 令 traversable 为运行 创建新的顶级 traversable，参数为 target URL 和 POST resource 的结果。
  3. 令 browsing context 为 traversable 的 活动浏览上下文。
  4. 应用 manifest 到 browsing context。
  5. 返回 browsing context。

4.3 隐私与安全注意事项

建议为终端用户提供安装 Web 应用的 UI 时，也允许用户检查图标、名称、起始 URL、来源等信息。这样可以让用户有机会在安装前有意识地批准并（如有需要）修改相关信息，也有助于用户辨别 Web 应用是否在冒充其他应用（例如使用意外的图标或名称）。

建议用户代理阻止其他应用判断系统上已安装了哪些应用（例如通过对用户代理缓存的计时攻击）。这可以通过在 Web 应用安装后使 manifest 关联资源（如图标）从缓存失效，或使用与常规 Web 浏览不同的缓存实现。

4.4 卸载

用户代理应当为用户提供移除已安装 Web 应用的机制。

建议在移除时，用户代理还应为用户提供撤销与该应用关联的其他持久数据和设置（如权限和持久存储）的机会。

6. 显示模式

显示模式表示 Web 应用在操作系统（OS）环境下的呈现方式（如全屏等）。显示模式对应于特定平台上的用户界面（UI）范式和功能。显示模式的 UI 规范仅供参考，具体解释由实现者自行决定。

本规范定义了以下显示模式：

fullscreen
以隐藏浏览器 UI 元素的方式打开 Web 应用，占据全部可用显示区域。
standalone
以类似原生应用的外观和体验打开 Web 应用。包括独立窗口、应用启动器中的专属图标等。在此模式下，用户代理会排除标准浏览器 UI 元素（如地址栏），但可包含系统 UI 元素（如状态栏、系统返回按钮）。
minimal-ui
类似于 standalone，但为用户提供一组用于导航的最小 UI 元素（如后退、前进、刷新、查看地址等）。用户代理还可包含平台特定的 UI 元素，如“分享”、“打印”按钮等。
browser （默认）
按平台惯例在用户代理中打开 Web 应用（如在浏览器标签页或新窗口中）。
Note

fullscreen 显示模式与 Fullscreen API 标准是正交且独立的。fullscreen 显示模式影响浏览器窗口的全屏状态，而 [FULLSCREEN] API 作用于视口内的元素。因此，Web 应用可以设置为 fullscreen 显示模式，但 document.fullScreenElement 仍为 null，fullscreenEnabled 也为 false。

一旦用户代理应用某个显示模式到 应用上下文，该模式即成为该 顶级浏览上下文的默认显示模式（即窗口导航时采用的显示模式）。用户代理可以因安全原因（例如顶级浏览上下文导航到其他 origin）覆盖默认显示模式，也可以为用户提供切换到其他显示模式的方式。

当 display 成员缺失或无效时，用户代理会使用 browser 显示模式作为 默认显示模式。 因此，用户代理必须支持 browser 显示模式。

每个 显示模式都有一个 回退链，即一组 显示模式。以下是各模式的 回退链：

  1. browser：«»。
  2. minimal-ui：« "browser" »。
  3. standalone：« "minimal-ui"， "browser" »。
  4. fullscreen：« "standalone"， "minimal-ui"，"browser" »。

确定 Web 应用选用显示模式的步骤 如下。该算法接收 已处理 manifest manifest，返回一个显示模式。

  1. 处理扩展点：此处可处理专有或其他受支持的显示模式。
  2. 如果用户代理支持 manifest["display"]，则返回该值。
  3. 对于 fallback_mode 属于 回退链（即 manifest["display"] 的回退链）：
    1. 如果用户代理支持 fallback_mode，则返回 fallback_mode。
Note

上述循环必定会返回一个值，因为 browser 总在所有模式的 回退链中，且所有用户代理都必须支持 browser 显示模式。

显示模式列表为 列表 « "fullscreen"、"standalone"、"minimal-ui"、"browser" »。

用户代理必须通过 display-mode 媒体特性 [MEDIAQUERIES-5] 反映 Web 应用的实际显示模式。

Note

用户代理暴露的是实际应用的显示模式，而不一定是 manifest 中声明的模式。通过 CSS 或 JavaScript 可访问 display-mode 媒体特性。注意该特性在未应用 manifest 时也会反映页面的其他显示模式。例如，用户将页面切换到全屏时，用户代理会通过该媒体特性将变化反映到 CSS 和脚本。

7. 隐私与安全注意事项

本规范不直接涉及高价值数据。但已安装 Web 应用及其数据可被视为“高价值”（尤其从隐私角度）。

由于 manifest 格式为 JSON，并采用 [UNICODE] 编码，因此 [JSON] 和 [UNICODE-SECURITY] 中描述的安全注意事项同样适用。此外，由于无法阻止开发者在 manifest 中包含自定义/无限制数据，实现者需对未受约束成员类型的值施加实现相关的限制，例如防止拒绝服务攻击、防止内存耗尽或规避平台限制。

Web 应用通常包含 ECMAScript、HTML、CSS 文件及其他媒体，这些内容在沙箱环境中执行。因此，实现者需关注所支持类型的安全影响。特别是要参考以下规范中的安全注意事项：[CSS-MIME]、[ECMAScript-MIME]、[HTML]。

由于 Web 应用可包含能同时与本地设备和远程主机交互的内容，实现者需考虑因向远程主机暴露隐私信息而带来的隐私影响。缓解和防御措施由实现自行决定，本规范不做规定。但在设计这些措施时，建议实现者提升用户对信息共享的感知，并提供便捷的权限撤销接口。

本规范允许在 manifest 某些成员中声明 URL，实现者需参考 [URL] 规范中的安全注意事项。实现如需展示 manifest 中的 IRIs 和 IDNA 地址，强烈建议遵循 [UNICODE-SECURITY] 的安全建议。

开发者需关注 [CSP3] 规范中的安全注意事项，尤其是关于将 data: 作为 manifest 内联来源的部分。这样做可能导致 XSS 攻击，因为 manifest 可被直接包含在文档中，建议完全避免此做法。

建议为终端用户提供安装 Web 应用的 UI 时，也允许用户检查图标、名称、起始 URL、来源等信息。这样可以让用户有机会在安装前有意识地批准并（如有需要）修改相关信息，也有助于用户辨别 Web 应用是否在冒充其他应用（例如使用意外的图标或名称）。

建议用户代理阻止其他应用判断系统上已安装了哪些应用（例如通过对用户代理缓存的计时攻击）。这可以通过在 Web 应用安装后使 manifest 关联资源（如图标）从缓存失效，或使用与常规 Web 浏览不同的缓存实现。

理论上，快捷方式的 url 可被设计为指示应用是从浏览器外部启动的（如 "url": "/task/?from=homescreen"）。开发者也可能在 url 中编码唯一标识用户的字符串（如服务器分配的 UUID）。这些都是指纹/隐私敏感信息，用户可能并不知情。

Web 应用运行时，建议用户代理为终端用户提供访问 Web 应用常用信息的方式，如来源、起始/当前 URL、已授予权限、关联图标等。具体如何呈现由实现者决定。

此外，当应用 manifest 并将 显示模式设置为非 "browser" 时，建议用户代理明确告知用户其已离开常规浏览器上下文。理想情况下，启动或切换到 Web 应用的方式应与主机平台上的其他应用一致。例如，使用明显的动画过渡，或语音提示“正在启动应用 X”。

display 成员允许 origin 对用户代理的原生 UI 进行一定程度的控制。应用获得全屏后，可能试图模仿其他应用的界面。通过 'display-mode' 媒体特性 [MEDIAQUERIES-5]，脚本可获知 Web 应用的显示模式。

A. IANA 考虑

Mime 类型 application/manifest+json 是 应用清单媒体类型。Mime 类型和 .webmanifest 文件扩展名均已在互联网号码分配局 (IANA) 注册。

A.1 媒体类型注册

如果传输清单的协议支持 [MIME-TYPES] 规范（例如 HTTP）， 推荐 清单使用 应用清单媒体类型。

类型名称:
application
子类型名称:
manifest+json
必需参数:
N/A
可选参数:
N/A
编码考虑:
同 application/json ([RFC7159] 第 8.1 节)
隐私和安全考虑:
见 7. 隐私和安全考虑。
使用该 MIME 类型的应用程序:
Web 浏览器
其他信息:
魔法数字:
N/A
文件扩展名:
.webmanifest
Macintosh 文件类型代码:
TEXT
联系人及邮件地址:
可通过 Web 应用工作组联系 public-webapps@w3.org。
预期用途:
COMMON
使用限制:
无
作者:
W3C 的 Web 应用工作组。
变更控制者:
W3C。

B. 一致性

与标记为非规范的部分一样，本规范中的所有作者指南、图表、示例和注释均为非规范内容。规范中的其他所有内容均为规范内容。

本文档中的关键词 MAY、MUST、MUST NOT、OPTIONAL、RECOMMENDED、SHOULD 和 SHOULD NOT 应按照 BCP 14 [RFC2119] [RFC8174] 的说明进行解释，仅当这些词以全大写形式出现时才具有上述含义。

只有一种产品类别可以声称符合本规范：用户代理。

Note

虽然本规范主要面向 Web 浏览器，但其他软件也可以以符合规范的方式实现。例如，搜索引擎或爬虫可以查找并处理 manifest，以构建可安装 Web 应用站点的目录。

B.1 扩展性

本节为非规范性内容。

本规范设计为可扩展的。鼓励其他规范为清单定义新成员。然而，在这样做时，请遵循本规范中使用的约定。 特别是，使用 处理扩展点 挂钩到 处理清单 的步骤中。此外，确保按照本规范规定的方式指定处理你的特定成员的步骤。这样有助于保持平台的这一部分一致。

为方便社区轻松找到扩展，请将你的扩展添加到 扩展注册表。

在指定新成员时，请勿覆盖或 monkey patch 本规范中定义的任何内容。也不要假设你的成员将在其他任何成员之前或之后进行处理。请保持新成员及其处理原子化和独立。 还要注意，实施者可以自由忽略他们不认识或不支持的任何成员。

如果编辑在编写规范时，临时希望对本规范进行补丁以协助实现，请提交 issue，以便社区了解编辑的意图和尝试。

B.1.1 专有清单成员

本节为非规范性内容。

虽然专有扩展是不受欢迎的，但它们实际上是无法避免的。如果用户代理选择解释清单 JSON 中未在本文档中指定的成员，则它可以这样做，但需要谨慎。

我们鼓励实现者在添加专有扩展时，考虑这些扩展是否有成为标准的可能（即使目前没有其他用户代理感兴趣，是否有意义让其他平台的用户代理也能使用该成员）。如果有，请作者以厂商中立的方式设计 API，并将其提议为标准。如果新成员确实是专有的（即只在专有生态系统中有意义），请按照本流程操作，并使用该专有生态系统的简称作为前缀，以避免命名冲突。

不要使用打算在成为标准后移除的厂商前缀（这些前缀往往会永久保留）。只应使用现在和将来都合理的前缀。

我们鼓励实现者将专有扩展添加到我们的 扩展注册表。 这允许社区跟踪供应商和/或网络社区定义和记录的扩展。我们将定期考虑这些扩展是否应标准化。

以下是三个假设的专有扩展示例。

示例 13：专有扩展 
{
      ...
      "kpl_fancy_feature": "some/url/img",
      "gmpc_awesome_thing": { ... },
      "blitzly_site_verification": "KEY_9864D0966935"
      ...
    }
Note

在本示例中，我们特意选择了（虚构的）可能代表外部站点或服务的名称，而不是浏览器或浏览器厂商的名称。这些不是由发明它们的浏览器所有的厂商前缀，而是专有服务的前缀。

C. 应用信息

本节为非规范性内容。

Web Application Manifest 的若干成员为 Web 应用在数字商店、安装对话框或其他营销/分发场景下的展示方式提供了额外元数据。为更好地支持这些用例，以下成员已移至 Web App Manifest - Application Information：

E. JSON Schema

本节为非规范性内容。

有兴趣校验 manifest 文档的开发者可在 JSON schema for the manifest format 和 schemastore.org 找到非官方 JSON Schema。该 Schema 采用 Apache 2.0 许可，由 Mads Kristensen 维护。如发现问题，请在 SchemaStore 仓库 提交 issue。

Note：Web Manifest JSON Schema

F. 国际化

本节为非规范性内容。

预期作者会通过以下方式之一对 manifest 内容进行本地化：

在 manifest 中提供本地化值：
作者可以为 manifest 的可本地化成员提供本地化值。用户代理会将所有本地化值传递给主机操作系统。当用户在操作系统层面更改区域设置（locale）时，操作系统可展示已安装 Web 应用的最新本地化值。
动态设置语言：
例如，询问终端用户的首选语言，并根据该语言偏好动态添加或替换文档中的 manifest 链接关系（如使用 "manifest.php?lang=fr" 这样的 URL）。
在服务器端使用内容协商、地理定位等：
托管 Web 应用的服务器可以通过地理定位或内容协商（如 HTTP "Accept-Language" 头 [RFC9110]，或自定义 HTTP 头）来预判终端用户的语言。

鉴于上述选项，开发者需注意用户首选语言的隐私问题：当用户明确向 Web 应用指明其语言偏好（即不仅仅使用用户代理默认语言设置）时，明文传输用户首选语言通常是不合适的，这会泄露用户的个人信息。因此，建议开发者使用 [TLS]，以降低 Web 应用被广泛监控的风险 [RFC7258]。

G. 用例与需求

本文档旨在解决 可安装 Web 应用的用例与需求。

H. 问题摘要

本规范未列出任何问题。

I. 变更日志

本节为非规范性内容。

以下是自首次公开工作草案（First Public Working Draft）以来的一些重要变更：

J. Acknowledgements

This section is non-normative.

This document reuses text from the [HTML] specification, as permitted by the license of that specification.

Dave Raggett and Dominique Hazael-Massieux contributed to this specification via the HTML5Apps project.

Claudio Gomboli for icon example images.

Indiana University Bloomington security researchers have contributed to this specification by reporting potential risks related to out-of-scope navigation.

K. Index

K.1 Terms defined by this specification

K.2 Terms defined by reference

L. References

L.1 Normative references

[accname-1.2]
Accessible Name and Description Computation 1.2. Bryan Garaventa; Melanie Sumner. W3C. 3 April 2025. W3C Working Draft. URL: https://www.w3.org/TR/accname-1.2/
[BCP47]
Tags for Identifying Languages. A. Phillips, Ed.; M. Davis, Ed. IETF. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646
[CSP3]
Content Security Policy Level 3. Mike West; Antonio Sartori. W3C. 30 April 2025. W3C Working Draft. URL: https://www.w3.org/TR/CSP3/
[css-color-4]
CSS Color Module Level 4. Chris Lilley; Tab Atkins Jr.; Lea Verou. W3C. 24 April 2025. CRD. URL: https://www.w3.org/TR/css-color-4/
[CSS-MIME]
The text/css Media Type. H. Lie; B. Bos; C. Lilley. IETF. March 1998. Informational. URL: https://www.rfc-editor.org/rfc/rfc2318
[css-syntax-3]
CSS Syntax Module Level 3. Tab Atkins Jr.; Simon Sapin. W3C. 24 December 2021. CRD. URL: https://www.w3.org/TR/css-syntax-3/
[dom]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMA-402]
ECMAScript Internationalization API Specification. Ecma International. URL: https://tc39.es/ecma402/
[ECMAScript-MIME]
Scripting Media Types. B. Hoehrmann. IETF. April 2006. Informational. URL: https://www.rfc-editor.org/rfc/rfc4329
[fetch]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[image-resource]
Image Resource. Aaron Gustafson; Rayan Kanso; Marcos Caceres. W3C. 4 June 2021. W3C Working Draft. URL: https://www.w3.org/TR/image-resource/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[JSON]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259
[MEDIAQUERIES-5]
Media Queries Level 5. Dean Jackson; Florian Rivoal; Tab Atkins Jr.; Daniel Libby. W3C. 18 December 2021. W3C Working Draft. URL: https://www.w3.org/TR/mediaqueries-5/
[MIME-TYPES]
Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2046
[permissions]
Permissions. Marcos Caceres; Mike Taylor. W3C. 20 December 2024. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC7159]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[SCREEN-ORIENTATION]
Screen Orientation. Marcos Caceres. W3C. 9 August 2023. W3C Working Draft. URL: https://www.w3.org/TR/screen-orientation/
[UAX9]
Unicode Bidirectional Algorithm. Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy. Unicode Consortium. 2 September 2024. Unicode Standard Annex #9. URL: https://www.unicode.org/reports/tr9/tr9-50.html
[UNICODE]
The Unicode Standard. Unicode Consortium. URL: https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
Unicode Security Considerations. Mark Davis; Michel Suignard. Unicode Consortium. 19 September 2014. Unicode Technical Report #36. URL: https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[UTS55]
Unicode Source Code Handling. Robin Leroy; Mark Davis. Unicode Consortium. 29 January 2024. Unicode Technical Standard #55. URL: https://www.unicode.org/reports/tr55/tr55-5.html

L.2 Informative references

[FULLSCREEN]
Fullscreen API Standard. Philip Jägenstedt. WHATWG. Living Standard. URL: https://fullscreen.spec.whatwg.org/
[i18n-glossary]
Internationalization Glossary. Richard Ishida; Addison Phillips. W3C. 17 October 2024. W3C Working Group Note. URL: https://www.w3.org/TR/i18n-glossary/
[manifest-app-info]
Web App Manifest - Application Information. Aaron Gustafson. W3C. 21 August 2023. W3C Working Group Note. URL: https://www.w3.org/TR/manifest-app-info/
[mimesniff]
MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[RFC7258]
Pervasive Monitoring Is an Attack. S. Farrell; H. Tschofenig. IETF. May 2014. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc7258
[RFC9110]
HTTP Semantics. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed. IETF. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9110.html
[SERVICE-WORKERS-1]
Service Workers. Yoshisato Yanagisawa; Monica CHINTALA. W3C. 6 March 2025. CRD. URL: https://www.w3.org/TR/service-workers/
[TLS]
The Transport Layer Security (TLS) Protocol Version 1.2. T. Dierks; E. Rescorla. IETF. August 2008. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5246
[webidl]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/