Web 应用清单

W3C 工作草案

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

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

摘要

本规范定义了一种基于 JSON 的文件格式，为开发者提供了一个集中存放与网页应用相关元数据的位置。这些元数据包括但不限于网页应用的名称、图标链接，以及用户启动网页应用时优先打开的 URL。Manifest 还允许开发者声明网页应用的默认屏幕方向，并可设置应用的显示模式（例如全屏）。此外，Manifest 允许开发者为网页应用设定“作用域”URL，从而限制 Manifest 的适用范围，并为其他应用实现网页应用的深度链接提供方法。

通过这些元数据，用户代理可以为开发者提供更接近原生应用体验的方式。

本文档状态

本节描述了本文档在发布时的状态。当前 W3C 发布列表和本技术报告的最新修订版可在 W3C 标准与草案索引中找到。

警告

本文档由 Web Applications 工作组以 推荐标准流程发布为工作草案。

作为工作草案发布不代表 W3C 及其成员的认可。

本文件为草案，可能随时被更新、替换或废弃。除作为进行中的工作外，不应引用此文档。

本文件由遵循 W3C 专利政策的工作组编制。 W3C维护着 与本组交付成果相关的公开专利披露列表； 该页面还包括披露专利的说明。有个人实际知晓某专利并认为包含 必要权利要求时，须按照 W3C 专利政策第6节披露相关信息。

本文档受 2025年8月18日 W3C 流程文件管辖。

1. Web 应用清单

一个 应用清单 是一个 [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 成员为网页应用声明一组图标。下例中，开发者对网页应用关联的图标进行了如下选择：

  • 开发者包含了两个尺寸相同但格式不同的图标。一个通过 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：

  • 第一个快捷方式将显示为文本“稍后播放”。如果操作系统支持为上下文菜单 项显示图标，并且还支持为此目的使用 SVG 图像，则用户 代理会在该文本旁显示 https://example.com/icons/play-later.svg。启动时，用户代理将实例化一个新的 顶层可遍历对象并导航到 https://example.com/play-later。
  • 第二个快捷方式将显示为文本 “订阅”。启动时，用户代理将实例化一个 新的顶层可遍历对象并导航到 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 成员用于告知浏览器哪些文档属于网页应用，哪些不属于——即清单会“应用”到哪些页面上。

例如，{"scope": "/"} 表示清单适用于整个源站的所有文档。而 {"scope": "/racer/"} 则表示只有 "/racer/" 路径下的文档才 在 scope 内：如 "/racer/race1.html"、"/racer/race2.html" 等都 在 scope 内，而 "/elsewhere/" 及根目录 "/" 都在“scope 外”，清单不会应用到这些路径的文档。仅支持一个 scope 路径。技术细节见 5. 导航作用域。

应用清单意味着清单中影响展示的成员会生效，比如显示模式 fullscreen 或设定屏幕方向。只要应用导航到 scope 内的 URL，浏览器就会持续应用清单。若导航到“scope 外”，清单就不再应用，浏览器会采用自己的默认设置。比如应用不再全屏，而是在普通标签页显示。实现细节由浏览器自行决定。技术细节见 1.17.5 应用清单。

最后，由于用户可能从任一源站文档安装网页应用，建议清单中始终声明 scope 成员。如果清单缺少 scope，则将 start_url 的路径作为后备。如果 start_url 也缺失，则使用安装网页应用的文档 URL 作为 scope。为避免导航行为异常，建议作者始终包含 scope，最好值为 "/"。

1.2 dir 成员

清单的 dir 成员指定了可本地化成员的默认 方向，这些成员属于清单。 dir 成员的值可以设置为某个 文本方向。

文本方向如下，它们表示 可本地化成员的值默认采用：

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

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

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

  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 成员

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

注

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

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

注

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

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

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

1.4 name 成员

清单 的 name 成员是一个字符串， 代表网页应用通常展现给用户的名称（例如在应用列表中，或作为图标标签）。

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

name 成员作为 可访问名称，用于 已安装网页应用。

注: 处理 `name` 成员

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

1.5 short_name 成员

清单 的 short_name 成员是一个字符串， 代表网页应用名称的简短版本。当没有足够空间显示完整名称时使用。

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

注: 处理 `short_name` 成员

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

1.6 scope 成员

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

注：默认作用域

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

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

1.7 icons 成员

清单的 icons 成员指定了在各种上下文中用作 Web 应用程序图标表示的图像。 例如，它们可用于在其他应用程序列表中表示 Web 应用程序， 或将 Web 应用程序与操作系统的任务 切换器和/或系统偏好设置集成。

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

注

1.8 display 成员

清单 的 display 成员表示开发者对网页应用首选的显示模式。其值为 显示模式。

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

  1. 将 manifest["display"] 设为 "browser"。
  2. 如果 json["display"] 不存在 或 json["display"] 不是字符串，则返回。
  3. 对 json["display"] 去除首尾 ASCII 空白。
  4. 对 json["display"] 转为小写。
  5. 如果 显示模式列表不包含 json["display"]，则返回。
  6. 将 manifest["display"] 设为 json["display"]。

1.9 orientation 成员

清单的 orientation 成员是一个字符串，它 用作 Web 应用程序所有默认屏幕方向的顶层 可遍历对象。可能的值为 OrientationLockType 枚举的值，在 本 规范中称为方向值 （即“any”、“natural”、“landscape”、“portrait”、“portrait-primary”、 “portrait-secondary”、“landscape-primary”或“landscape-secondary”）。

如果用户代理支持将orientation 成员的值用作默认屏幕方向，那么该值将 在 Web 应用程序的整个生命周期内用作默认屏幕方向（除非在运行时通过其他方式覆盖）。这 意味着，每当方向 被解锁 [SCREEN-ORIENTATION]，或者顶层可遍历对象 被导航时，用户代理都必须将方向恢复为 默认屏幕方向。

注

虽然规范依赖 [SCREEN-ORIENTATION] 的 OrientationLockType， 但用户代理实现 [SCREEN-ORIENTATION] API 属于可选。当然鼓励支持 [SCREEN-ORIENTATION] API。

某些 UI/UX 方面的考虑和/或平台约定意味着， 某些屏幕方向不能一起使用。哪些方向 和显示模式不能一起使用，由实现者自行决定。 例如，对于某些用户代理，在处于 browser 显示模式时，更改应用程序的默认屏幕方向可能没有 意义。

注

Web 应用程序运行后，可以通过其他方式更改 顶层可遍历对象的方向（例如通过 [SCREEN-ORIENTATION] API）。

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

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

1.10 start_url 成员

清单 的 start_url 成员是一个字符串， 表示 启动 URL，即开发者希望用户代理在用户启动网页应用时加载的 URL（比如用户在设备的应用菜单或主屏幕点击网页应用图标时）。

start_url 成员仅为建议，用户代理 可以 忽略它，或让终端用户选择是否使用它。用户代理 可以 允许终端用户修改该 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"] 类型不是字符串，或为空字符串，则返回。
  4. 令 start URL 为 解析 json["start_url"]，基准 URL 为 manifest 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，比如服务分配的标识符，如 "?user=123"、"/user/123/" 或 "https://user123.foo.bar"。这些属于指纹/隐私敏感信息，用户可能并不知情。

注：不要在 start_url 中添加用户标识

开发者使用 start URL 包含唯一标识用户的信息是很糟糕的做法，因为这会形成用户指纹，且用户清除站点数据时不会被清除。不过本规范无法实际阻止开发者这样做。

基于上面原因，建议用户代理在安装应用或之后任何时候允许用户检查并如有必要修改应用的 start URL。

用户代理 可以 提供其它防护措施。例如，若用户清除某源的站点数据，用户代理 可以 提供卸载该源下 scope 内的应用的选项，从而移除应用 start_url 中可能的指纹。

1.11 id 成员

清单 的 id 成员是一个字符串， 表示应用的身份。身份以 URL 形式展现，并且与 start_url 同源。

标识被用户代理用来 在全局范围内唯一标识应用程序。当用户代理 看到某个 manifest 的标识与某个已安装应用程序 不对应时，它应当 将该 manifest 视为一个不同应用程序的描述，即使 它与另一个应用程序来自同一个 URL。 当用户代理看到某个 manifest，其中manifest["id"]与某个 已安装应用程序的标识相等（并且排除片段可选地设为 true）时， 它应当将此用作一个信号，表明 该 manifest 是对已安装应用程序 manifest 的替代， 而不是一个不同的应用程序，即使它 来自于与先前所见不同的 URL。

注意：排除片段是最佳实践
注意

标识可被收集 Web 应用列表的服务用来 唯一标识应用。

注意

标识按 URL 方式处理， 但它并不指向可导航到的资源，因此 不要求其在作用域内。

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

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

1.12 theme_color 成员

manifest 的 theme_color 成员是一个可主题化成员，用作应用上下文的默认主题色。 什么是主题色在[HTML]中有定义。

如果用户代理采用theme_color 成员的值作为默认主题颜色，那么该颜色将用作 应用了该清单的所有顶层可遍历对象的主题颜色，其中该清单被应用。但是，如果某个文档 的URL 位于应用程序上下文的清单 的作用域内，并且该文档包含一个 meta 元素，且该元素的 name 属性为 “theme-color”，则用户代理可以覆盖 默认主题颜色。 但是，对于文档的 URL不位于作用域内的情况，用户代理不应 通过一个 meta 元素覆盖默认主题颜色，其中该元素的 name 属性为“theme-color”，因为应用程序 无法控制这些文档。

用户代理可以根据上下文忽略 主题色的alpha 通道，例如在大多数环境下，主题色不能是透明的。

实现者可以为支持 prefers-color-scheme 而覆盖 theme_color 成员值。

注

当处理清单时，使用 处理颜色成员 算法处理 theme_color 成员。

1.13 background_color 成员

manifest 的 background_color 成员是一个 可主题化成员，描述网络应用的期望背景色。 它重复了应用样式表中已有的内容， 但可被用户代理用于在实际可用文件之前（无论来自网络获取还是磁盘读取）， 绘制已知 manifest 的网络应用背景色。

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

实现者可以为支持 prefers-color-scheme 而覆盖 background_color 成员值。

注

当处理清单时，使用 处理颜色成员 算法处理 background_color 成员。

1.14 shortcuts 成员

清单 的 shortcuts 成员是一个列表， 包含一组shortcut item，用于访问网页应用的关键任务。

注

快捷方式如何展示，以及展示多少，由用户代理和/或操作系统自行决定。

要处理 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 成员

一个 可本地化成员 是 清单 或 快捷方式项 中可以本地化的成员。每个 可本地化成员 都有一个对应的 *_localized 成员，其中 * 表示成员名称。

以下 成员可以本地化：

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

分配给 可本地化成员 的值是 默认表示。 *_localized 成员包含一个 语言映射，其中 定义的 本地化值 供应用程序中的给定 可本地化成员 使用。用户代理 应当 使用用户的本地化 设置来选择 本地化值，其 语言标签 键 与用户的偏好最匹配。如果没有这样的 本地化 值 可用，则使用 默认表示。

1.15.1 文本值本地化

本地化文本对象是一个有序映射，包含以下属性：

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

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

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

注

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

注

要处理 *_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是一个字符串， 则从localizedValue中去除首尾 ASCII 空白，并 设置 normalizedValue["value"]为localizedValue。
  3. 如果localizedValue是一个有序映射：
    1. 如果"value"在localizedValue中存在，且 localizedValue["value"]是一个字符串，则从localizedValue["value"]中去除首尾 ASCII 空白，并 设置 normalizedValue["value"]为 localizedValue["value"]。
    2. 如果"lang"在localizedValue中存在，且 localizedValue["lang"]是一个字符串，则从localizedValue["lang"]中去除首尾 ASCII 空白，并 设置 normalizedValue["lang"]为 localizedValue["lang"]。
    3. 如果"dir"在localizedValue中存在，且 localizedValue["dir"]是一个字符串：
      1. 从 localizedValue["dir"]中去除首尾 ASCII 空白。
      2. 如果文本方向列表 包含 localizedValue["dir"]，则设置 normalizedValue["dir"]为localizedValue["dir"]。
  4. 如果"value"不在normalizedValue中存在，则返回。
  5. 如果"lang"不在normalizedValue中存在， 则设置 normalizedValue["lang"]为defaultLanguageTag。
  6. 如果"dir"不在normalizedValue中存在， 则设置 normalizedValue["dir"]为defaultDirection。
  7. 如果以normalizedValue["lang"]调用 IsStructurallyValidLanguageTag 或以defaultLanguageTag调用 IsStructurallyValidLanguageTag 返回 false，则返回。
  8. 设置 map[member][defaultLanguageTag]为 normalizedValue。
注

处理本地化文本对象 算法对本地化值参数既接受 字符串，也接受本地化文本对象，但处理结果将被规范化为 一个设置了 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. 如果以languageTag调用 IsStructurallyValidLanguageTag 返回 false，则继续。
    2. 运行处理图像资源，传入 languageMap[languageTag]作为列表 形式的图像资源，以及map[member]、manifest URL和languageTag 作为成员。

1.16 color_scheme_dark 成员

manifest 的 color_scheme_dark 成员是一个有序映射，其键为可主题化成员，值为当操作系统使用深色主题时这些成员覆盖的颜色值。

可主题化成员是下列 manifest 成员之一：

当应用 manifest 且操作系统使用深色 颜色主题时，对于可主题化成员member中每个在 color_scheme_dark中存在的项，用户代理 应当使用color_scheme_dark[member]的值 替代member的值，除非用户偏好（例如无障碍设置） 具有更高优先级。

1.16.1 可主题化成员的主题化

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

  1. 如果 json["color_scheme_dark"] 不存在，则返回。
  2. 令 colorScheme 为 json["color_scheme_dark"]。
  3. 如果 colorScheme 不是有序映射，则返回。
  4. 令 processedColorScheme 为新的有序映射。
  5. 设置 manifest["color_scheme_dark"] 为 processedColorScheme。
  6. 对于 « "theme_color", "background_color" » 中的每个 member：
    1. 处理颜色成员，传入 colorScheme、 processedColorScheme、member。

1.17 清单生命周期

本节定义了处理清单与 应用清单的算法。

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

1.17.1 处理清单

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

下述算法提供一个处理扩展点：鼓励向清单添加新成员的其它规范在算法此处接入自身。 它们不应更改manifest对象中已有的值。

Note

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

处理清单的步骤如下 算法所示。该算法接受一个 URL 文档 URL、一个 URL 清单 URL、一个 字节序列 bodyBytes，以及 client（一个 环境设置对象 或 null）。

  1. 令 json 为 使用 bodyBytes 调用 解析JSON字节为Infra值 的结果。
  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 的 已处理清单不为 null，且document的已处理清单的 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. 处理 color_scheme_dark 成员，传递 json、 manifest 和 manifest URL。
  20. 处理 orientation 成员，传递 json、 manifest。
  21. 处理 shortcuts 成员，传递 json、 manifest 和 manifest URL。
  22. 处理扩展点：此时处理算法中的专有成员或其它已支持成员。
  23. 将 manifest 的 客户端 设置为 client。
  24. 设置 document 的 已处理清单 为 manifest。

1.17.2 处理颜色成员

Note: 支持的颜色

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

要处理颜色成员，给定有序映射 json、有序映射 map，和 字符串 member：

  1. 若 json[member] 不 存在 或 json[member] 不是 字符串，则返回。
  2. 去除 json[member] 首尾的ASCII空白。
  3. 令 color 为 按CSS色彩语法解析 json[member] 的结果。
  4. 若 color 失败，则返回。
  5. 如果 color 可以仅依靠用户代理固有信息转换为sRGB， 则转换 color 为sRGB。
  6. 若 color 不是sRGB 色彩，则返回。
  7. 设置 map[member] 为 color。

1.17.3 处理文本成员

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

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

1.17.4 无文档情况下处理清单

处理清单的步骤由 [HTML] 在处理 link 元素的步骤中调用，此时 client 是 文档的 相关设置对象。这些步骤 也可以 被用户代理调用，以在没有关联 文档 的情况下处理清单，此时 client 为 null。

在这种情况下，为了匹配[cite:HTML]中对等步骤做出的保证，用户代理应该确保过去至少某一时刻：

Note: 这些检查的理由

1.17.5 应用清单

一个 已处理的清单 被 应用 于一个 顶层可遍历对象， 意味着这些成员（属于 清单）正在影响 呈现和/或行为（属于 顶层可遍历对象）。 每当一个 顶层可遍历对象 被创建时，用户 代理 可以 应用 一个清单于该对象，时间早于 导航 开始。

用户代理也可以向现有的 顶层可遍历对象应用一个清单。如果活动文档的 URL位于 清单的作用域内，则 现有的顶层可遍历对象将成为一个应用程序上下文。如果该URL不位于 作用域内，则产生的行为由实现定义。

注
注

已应用清单的顶层可遍历对象 称为应用程序 上下文。

也可以从一个顶层可遍历对象中取消应用已处理的清单。发生这种情况时， 该顶层可遍历对象 将不再是应用程序上下文。

注

如果创建应用程序上下文是因为 用户代理被要求导航到一个深层链接，则用户 代理必须立即导航到该深层链接，并将 historyHandling设置为“replace”。否则，在创建 应用程序上下文时，用户代理必须立即 导航到起始 URL，并将 historyHandling 设置为“replace”。

注

1.17.6 更新清单

如 manifest 链接关系所规定，清单会在每次页面加载时 获取并处理。当处理清单成功时，用户代理 可以将更新后的 清单应用于与该应用程序关联的任何当前和未来应用程序上下文。

如果src成员已更改，用户代理应当认为清单图像资源 已更新。如果 src未更改，则在某些情况下，用户 代理可以下载 图像并检查视觉差异。

注：图标 元数据更改

为了进行更新，以下成员属于 安全敏感成员，因为它们会在 安装期间以及启动界面上呈现：

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

清单的所有其他成员均被视为非安全敏感成员。

安全敏感更新是对 安全敏感成员的更新。相应地， 非安全敏感更新是 对 非安全敏感成员的更新。

在考虑类型为 清单图像资源（例如icons）的已更新安全敏感成员时，如果 用户代理发现图像在视觉上没有显著差异，则用户代理可以将其视为非安全敏感更新。

用户代理应当立即应用所有非安全敏感更新。

用户代理应当向用户呈现所有安全敏感更新，并在应用 更改之前要求用户给予明示许可。

注：呈现更新时 显示的用户选项示例

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

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

2. 清单图片资源

每个 清单图像资源 都是一个 图像资源。清单图像资源的呈现上下文由关联的清单成员的语义决定（例如，icons 成员通常用于表示应用图标）。

清单图像资源 与普通 图像资源 的不同之处在于，它可以拥有一个额外的 purpose 成员。

用户代理 可以 修改与 清单图像资源 关联的图像，以便在显示给用户之前更好地匹配平台的视觉风格，例如通过圆角处理或用特定颜色绘制。建议开发者为这种情况准备图像资源，以避免通过颜色变化或裁剪角落而丢失重要信息。

要根据给定的 清单图像资源 image 和一个 应用程序清单 manifest 获取清单图像资源，返回 获取图像资源的结果或 null：

  1. 如果 manifest 的客户端为 null，则返回 null。
    注
  2. 令 request 为一个新的请求。
  3. 将 request 的URL 设置为 image 的src。
  4. 将 request 的目标设置为“image”。
  5. 将 request 的客户端设置为 manifest 的客户端。
  6. 返回使用 image 和 request获取图像资源的结果。
注

2.1 purpose 成员

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

当 清单图像资源 用作图标时， 开发者 可以提示该图像旨在宿主 OS 的上下文中用于某种特殊用途（即实现更好的集成）。用户 代理 不应 将图标用于其声明的 图标 用途以外的用途。

注

例如，用途为“monochrome”的图标可以 用作具有 纯色填充的徽章或固定图标，在视觉上 与应用程序的全彩启动图标有所区别。用户代理 将 purpose 成员的值用作 提示，以确定在何处以及如何显示 purpose。除非 开发者 另有声明，否则用户代理可以将图标用于 任何用途。

图标用途如下：

monochrome
用户代理可以在需要具有 纯色填充的单色图标的位置显示此图标。图标中的颜色信息 会被丢弃，仅使用 alpha 数据。随后，用户代理可以 像使用遮罩一样，将该图标应用于任何 纯色填充。
maskable
该图像的设计考虑了 图标遮罩和 安全区域，因此图像中位于 安全区域之外的任何部分都可以安全地被用户代理 忽略并通过遮罩隐藏。
any（默认）
用户代理可以自由地在不要求特定 purpose 的 位置显示该图标。例如，一个 清单图像资源 如果具有 "any" 用途，就不会在 要求 "monochrome" 的上下文中使用。

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

注

如果一个图标包含多个用途，则可以将其用于 其中任何一种用途。如果声明的用途均无法识别，则 完全忽略该图标。例如，如果图标的用途为 "monochrome fizzbuzz"，则可以将其用作单色图标， 因为 "monochrome" 是有效的用途。但是，如果图标仅具有 "fizzbuzz" 用途，则会被忽略。

要确定图像的用途，给定一个 有序 映射 json：

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

2.2 内容安全策略

决定 用户代理 能否 获取图标图像（获取清单图像 资源）的安全策略 由 img-src 指令 [CSP3] 规定，该指令与清单的 所有者 Document 关联。

2.3 图标遮罩与安全区

某些平台有自己的图标形状偏好，但由于网页应用需要跨平台兼容，可以通过添加 maskable 用途，指示图标可以由用户代理自定义遮罩。这样平台可以保证图标与整体视觉风格融合，还能在不同位置应用不同遮罩和背景色。

安全区是 maskable 图标内始终可见的区域，与用户代理偏好无关。安全区定义为以图标中心为圆心，半径为图标尺寸的2/5（40%）的圆。如果图标不是正方形，则取宽高较小值。

注

设计 maskable 图标时，应确保所有重要元素都在 安全区内。

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

此区域中的所有像素都保证会在所有蒙版中显示。 安全区域之外的像素不保证会显示（但可以） 是否可见取决于所应用的蒙版。

用户代理可以应用任意大小的蒙版，从而使任何距离 中心点超过图像尺寸的 2/5（若非正方形，则取宽度和高度中的较小值） 的像素（即安全区域） 变为透明。

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

用户代理可以通过添加额外的内边距来放大图标。

如果图标包含透明像素，用户代理 必须 将图标合成到一种 纯色填充（例如白色）上，该填充由用户 代理自行选择。

注

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

2.3.1 遮罩示例

注

保持内容在 安全区内，大多数图标上下左右约有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 应用程序需要 跨多个平台运行，因此可以通过添加 monochrome 用途，表明图标可以应用 用户代理指定的颜色。这使平台能够 确保图标与平台的外观协调一致，并且 甚至可以在整个平台的不同位置应用不同的颜色 和内边距。

当展示 monochrome 图标时，用户代理不得分别显示像素的红、绿、蓝分量。用户代理应当用像素原始 alpha 值显示，但红绿蓝值可自选。推荐用户代理为所有像素使用同一颜色值。

注

设计 monochrome 图标时可将所有像素设为黑色，仅用透明度形成图标剪影。

用户代理可以通过添加额外内边距放大图标。

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

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. 遍历 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 成员是一个位于作用域内的 URL，该作用域属于已处理的 清单，当 关联的快捷方式被激活时，将打开该 URL。

3.5 icons 成员

该快捷方式项的 icons 成员列出了在各种上下文中用作 快捷方式图标表示的图像。

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

3.6 启动 快捷方式

当具有 manifest 的快捷方式项 shortcut 被调用时， 执行使用 manifest 和 shortcut.url 启动 Web 应用程序的步骤。

3.7 处理快捷方式项

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

  1. 如果存在以下任一情况，则返回失败：
  2. 令 url 为以 manifest URL 作为基准 URL 解析 item["url"] 的结果。
  3. 如果 url 为失败，则返回失败。
  4. 如果 url 不在 scope 的作用域 内，则返回 失败。
  5. 令 shortcut 为有序映射 «[ "url" → url, "name" → item["name"] ]»。
  6. 处理一个 *_localized 文本 成员，传入 item、 shortcut、"name_localized" 和 defaultDirection。
  7. 如果 "short_name" 存在于 item 中，且 item["short_name"] 是一个字符串，则将 shortcut["short_name"] 设置为 item["short_name"]。
  8. 处理一个 *_localized 文本 成员，传入 item、 shortcut、"short_name_localized" 和 defaultDirection。
  9. 如果 "description" 存在于 item 中，且 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 应用程序一旦被安装，就称为已安装的 Web 应用程序：也就是说，清单的 成员或其默认值被应用于 Web 应用程序的顶层 可遍历对象。这将已安装的 Web 应用程序与传统书签区分开来，因为从 传统书签打开网页时，不会向其 应用清单的属性。

注

例如，在支持安装的用户代理上，可以通过一种对 最终用户而言与原生应用程序无法区分的方式呈现和启动 Web 应用程序：例如，在主屏幕、启动器或开始 菜单中显示为带有标签的图标。当启动 Web 应用程序时， 用户代理会在加载 起始 URL之前，向顶层可遍历对象 应用清单。这使用户代理 有机会应用清单中的相关值，并可能 更改 Web 应用程序的显示模式和屏幕方向。或者，同样作为示例，用户代理 可以将 Web 应用程序安装到用户代理自身的 书签列表中。

4.1 应用名称

该 应用程序名称 取自以下两者之一： name 成员或 short_name 成员。用户 代理 应当 首先从其 对应的 *_localized 成员解析本地化值。

当 name 成员或 short_name 成员缺失、为空或类型 不正确时， 用户代理 可以 使用 name 成员作为 short_name 成员的回退选项，或将 short_name 成员 作为 name 成员的回退选项。

如果 name 和 short_name 成员均 缺失、为空或类型不正确，用户代理 可以 回退到 Document，以寻找合适的替代内容 来替代缺失的清单 成员（例如，使用 application-name 替代 name 或 short_name）。或者，用户代理 应当 指定符合平台惯例的默认名称（例如“未命名”）。 或者，用户代理 可以 允许最终用户 输入一些文本，作为 应用程序名称。

当 name 和 short_name 成员 都存在时，由实现决定哪个成员 最适合可用空间（例如， short_name 成员可能更适合 图标下方的 可用空间）。

4.2 启动网页应用

由操作系统或用户代理自行决定，运行 启动Web应用的步骤，传入 已处理清单。

注

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

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

如果提供了 target URL，必须 位于scope内 （指manifest）。

其他规范可以用自己的步骤替换此算法。这种替换将作用于所有 启动Web应用的调用。

注

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

  1. 返回运行 创建新的应用上下文 步骤（传入 manifest、target URL 和 POST resource）的结果。

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

  1. 如果未给定 target URL，则将 target URL 设置为 起始 URL。
  2. 令 traversable 为使用 target URL 和 POST resource 运行创建新的顶层 可遍历对象的步骤所得的结果。
  3. 将 manifest应用于 traversable。
  4. 返回 traversable。

4.3 隐私与安全注意事项

建议为最终用户提供 安装 Web 应用程序能力的用户界面，也允许检查与该 Web 应用程序相关的图标、 名称、起始 URL、源等信息。 这是为了给最终用户一个机会，在安装之前有意识地决定是否批准， 并且可能修改与该 Web 应用程序相关的信息。这也给了 最终用户一个机会来辨别该 Web 应用程序是否在冒充 另一个 Web 应用程序，例如通过使用意外的图标或 名称。

建议用户代理阻止其他应用程序 确定系统上安装了哪些应用程序（例如，通过对用户代理缓存进行 时序攻击）。例如，这可以通过在 Web 应用程序已安装之后，使清单中链接的资源 （例如图标）从用户代理缓存中失效来实现——或者使用与常规 Web 浏览 不同的完全独立的缓存。

4.4 卸载

用户代理应当提供机制让用户移除已安装网页应用。

建议在卸载时，用户代理同时为用户提供撤销与应用相关的其他持久化数据和设置的机会，如权限和持久存储。

6. 显示模式

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

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

fullscreen
打开网页应用时隐藏浏览器 UI 元素，占据所有可用显示区域。
standalone
打开网页应用时外观类似独立原生应用，如拥有独立窗口、应用启动器图标等。此模式下用户代理会隐藏标准浏览器 UI（如 URL 栏），但可包含系统状态栏、返回按钮等系统 UI 元素。
minimal-ui
类似 standalone，但为用户提供最小化的导航控制（如后退、前进、刷新、地址查看等 UI）。用户代理可添加其他平台定制 UI，如“分享”、“打印”等按钮。
browser （默认）
按平台惯例用用户代理打开网页应用超链接（如浏览器标签或新窗口）。
注

fullscreen 显示模式与 Fullscreen API Standard 独立无关。fullscreen 显示模式影响浏览器窗口全屏状态，而 [FULLSCREEN] API 仅作用于视口内元素。因此网页应用可设置 显示模式为 fullscreen，但 document.fullScreenElement 返回 null，fullscreenEnabled 返回 false。

一旦清单被应用于顶层可遍历对象，则 当前生效的显示模式就是该对象的已应用的显示模式，适用于 该顶层可遍历对象。其初始值是 执行 以下确定 Web 应用程序所选显示模式的步骤 并传入该清单的结果。用户代理可以出于安全原因更改已应用的显示模式（例如，当顶层可遍历对象被 导航至作用域之外时），并且／或者用户代理可以向 用户提供切换到另一种显示模式的方式。

当display成员缺失，或者不存在 有效的display成员时，用户代理使用browser 显示模式作为已应用的显示模式。因此， 用户代理必须支持browser 显示模式。

每种显示模式都有一条回退链，它是一个由 显示模式组成的列表。以下显示模式的回退链分别为：

  1. browser 为 «»。
  2. minimal-ui 为 « "browser" »。
  3. standalone 为 « "minimal-ui", "browser" »。
  4. fullscreen 为 « "standalone", "minimal-ui", "browser" »。

确定 Web 应用程序所选显示模式的步骤 由以下算法给出。该算法接受一个 已处理的清单 manifest，并 返回一种显示模式。

  1. 处理扩展点：此处可处理专有/支持的其它显示模式。
  2. 如果用户代理支持 manifest["display"]，则返回 manifest["display"]。
  3. 对于 fallback_mode 属于 回退链 manifest["display"] 的每一项：
    1. 如果用户代理支持此 fallback_mode，则返回 fallback_mode。
  4. 断言：永远不会执行到此步骤。
注

由于browser位于每种模式的 回退链中，并且要求所有用户代理都支持 browser 显示模式， 因此可以保证上述循环会在断言之前返回一个值。

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

用户代理必须在 display-mode 媒体特性中，反映 Web 应用的已应用 显示模式 [MEDIAQUERIES-5]。

注

用户代理会通过可由 CSS 或 JavaScript 访问的 display-mode 媒体 特性，暴露已应用显示模式——不 一定是 清单中声明的那个。注意，当清单未被应用时，此媒体 特性也会反映 Web 页面的其他显示模式。例如，如果最终用户将 页面置于全屏，则用户代理会通过 display-mode 媒体特性，将此更改反映到 CSS 和脚本。

7. 隐私和安全注意事项

7.1 隐私注意事项

本规范不直接处理高价值数据。 但是，已安装的 Web 应用程序及其数据可能被 视为“高价值”数据（尤其是从隐私角度来看）。

由于 Web 应用程序可以包含能够同时 与本地设备和远程主机交互的内容， 实现者需要考虑向远程主机 暴露私有信息所产生的隐私影响。缓解措施和 深度防御措施由实现负责， 本规范不作规定。但是，在设计这些 措施时，建议实现者让用户了解 信息共享情况，并提供可轻松访问的界面， 以便撤销许可。

建议用户代理防止其他应用程序 确定系统上安装了哪些应用程序（例如，通过 对用户代理缓存发起计时攻击）。例如，可以在 Web 应用程序被安装后，使清单所链接的资源 （例如图标）在用户代理缓存中失效，或者使用与 常规 Web 浏览所用缓存完全不同的缓存。

可以设想，快捷方式的url可能被 特意构造，以表明应用程序是从浏览器外部启动的 （例如，"url": "/task/?from=homescreen"）。还可以 设想，开发者可能会将能够唯一标识用户的字符串编码到url中（例如，由服务器分配的 UUID）。这是用户可能未意识到的 指纹识别/隐私敏感信息，并且与编码到起始 URL中的标识符一样，在 用户清除站点数据时不会被清除。

与起始 URL一样，建议用户 代理允许用户在安装时或 此后的任何时间检查并在必要时修改快捷方式的url。

7.2 安全注意事项

由于清单格式为 JSON，并将使用 [UNICODE] 进行编码， 因此适用 [JSON] 和 [UNICODE-SECURITY] 中描述的安全注意事项。此外，由于 无法阻止开发者在 清单中包含自定义/不受约束的数据，因此实现者需要对其他方面 不受约束的成员类型值施加其自身 特定于实现的限制，例如防止拒绝服务 攻击、防止内存耗尽，或规避 特定于平台的限制。

Web 应用程序通常包含 ECMAScript、HTML、CSS 文件 和其他媒体，它们在沙盒环境中执行。因此， 实现者需要了解其所支持类型的安全影响。 具体而言，实现者至少需要考虑以下 规范中概述的安全影响：[CSS-MIME]、[ECMAScript-MIME]、[HTML]。

由于本规范允许在清单的 某些成员中声明 URL，因此实现者需要考虑 [URL] 规范中讨论的安全注意事项。 计划显示清单中找到的IRI 和IDNA地址的实现，强烈建议遵循 [UNICODE-SECURITY] 中给出的安全建议。

开发者需要了解整个 [CSP3] 规范中讨论的安全注意事项，尤其是与 为了内联清单而将 data: 设为有效源有关的注意事项。 这样做允许将清单直接包含在文档本身中， 从而可能引发 XSS 攻击；最好完全避免 这种做法。

建议让最终用户能够 安装 Web 应用程序的 UI，也允许检查与该 Web 应用程序 有关的图标、名称、起始 URL、源等信息。 这是为了让最终用户有机会在安装 Web 应用程序之前， 有意识地决定是否批准，并可能修改 与该 Web 应用程序有关的信息。这也使 最终用户有机会辨别 Web 应用程序是否在仿冒 另一个 Web 应用程序，例如使用意料之外的图标或 名称。

Web 应用程序运行时，建议用户 代理向最终用户提供一种方式，以访问有关 Web 应用程序的 常见信息，例如源、起始和/或当前 URL、已授予的许可和关联的图标。如何向最终用户 公开这些信息由实现者决定。

此外，当应用一个将显示 模式设置为“browser”以外任何值的清单时， 建议用户代理向最终用户明确表明， 他们正在离开 Web 浏览器的常规浏览上下文。 理想情况下，启动 Web 应用程序或切换到 Web 应用程序的方式， 应与在宿主平台中启动或切换到其他 应用程序的方式一致。例如，使用长时间且明显的 动画过渡，或者朗读文本“正在启动应用程序 X”。

display成员允许源在一定程度上控制 用户代理的原生 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类型的应用程序：
网页浏览器
附加信息：
Magic number(s):
N/A
文件扩展名：
.webmanifest
Macintosh 文件类型码：
TEXT
联系人及邮箱：
Web Applications Working Group 可通过 public-webapps@w3.org 联系。
预期用途：
COMMON
使用限制：
无
作者：
W3C Web Applications Working Group。
变更控制者：
W3C。

B. 一致性

本规范中被标注为非规范性的章节，以及所有编写指南、图表、示例和注释，均为非规范性内容。除此之外的内容均为规范性内容。

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

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

注

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

B.1 扩展性

本节为非规范性内容。

本规范设计为可扩展。鼓励其他规范为清单定义新成员，但在这样做时请遵循本规范的约定。特别是，应使用 处理扩展点 挂钩到处理清单的步骤。并且，务必按照本规范规定的方式，明确写出你的成员处理步骤，以保持平台的一致性。

为方便社区查找扩展，请将你的扩展加入扩展注册表。

指定新成员时，不要覆盖或猴子补丁 本规范中的任何定义内容。也不要假设你的成员会在其他成员之前或之后被处理。请保持新成员及其处理原子且自包含。注意，实现可自由忽略其不支持或未识别的成员。

如编辑者在编写规范时，临时需要修补本规范以协助实现，请提交问题，让社区知晓编辑者的意图。

B.1.1 专有清单成员

本节为非规范性内容。

虽然专有扩展并不理想，但实际上无法完全避免。如果用户代理选择解释清单JSON中未在本文件规定的成员，可以做，但需谨慎。

鼓励实现者在添加专有扩展时，考虑其是否有可能成为标准（即，是否有必要让其他平台上的第二个用户代理也能使用该成员，即使目前只有一个用户代理感兴趣）。如果确实如此，请以厂商中立方式设计API，并将其提案为标准。如果新成员是真正专有的（即只在专有生态系统中有意义），请采用本流程并以该专有生态系统的简称为前缀，以避免命名冲突。

不要使用计划后续移除的厂商前缀（这些前缀往往会永远保留）。只用当下及未来均有意义的前缀。

鼓励实现者将专有扩展加入我们的扩展注册表。这样社区可追踪厂商和/或Web社区定义和文档化的扩展。我们会定期考虑这些扩展是否标准化。

下方为三个假设专有扩展的示例。

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

在此示例中，我们故意选择了可能为外部站点或服务的（虚构）名称，而不是浏览器或浏览器厂商的名称。这些不是浏览器厂商的前缀，而是专有服务的前缀。

C. 应用信息

本节为非规范性内容。

Web Application Manifest 的若干成员可提供关于网页应用如何在数字商店、安装对话框或其它分发和营销场景中展示的元数据。为更好地支持上述用例，以下成员已被移至 Web App Manifest - Application Information：

E. JSON Schema

本节为非规范性内容。

有兴趣验证清单文档的开发者可以在 schemastore.org 找到非官方的清单格式 JSON 架构。其采用 Apache 2.0 许可。该架构由 Mads Kristensen 友好维护。如果开发者 发现 JSON 架构存在任何问题，请在 GitHub 上的 SchemaStore 仓库中提交错误报告。

F. 国际化注意事项

本节为非规范性内容。

预期作者将使用以下选项之一 对清单内容进行本地化：

清单中的本地化值：

作者可以使用相应的 *_localized 成员（例如 name_localized），为清单的可本地化成员提供本地化值。 各个本地化条目可以是字符串或本地化文本对象。本地化文本对象可以使用其 lang和 dir属性指定自身的自然语言和文本方向 元数据，从而覆盖清单范围的lang和 dir成员提供的任何默认值。

用户代理可以采用以下方式之一处理本地化值：

直通式本地化：
用户代理在安装期间将所有本地化值（整个语言 映射）传递给宿主操作系统。当 用户在操作系统级别更改其首选语言时，宿主 操作系统可以立即呈现更新后的本地化值 （例如应用程序名称），而无须运行用户代理。
按需/更新时求值：
用户代理在解析时根据用户当前的区域设置 对本地化值求值。当用户更改系统 语言时，应用程序属性不会立即更新。相反， 它们会在用户下次访问应用程序时或 在后台更新检查期间更新，从而允许用户代理在 更新宿主操作系统之前，检查安全敏感更改 （例如名称更改）并可能要求用户确认。
动态设置语言：
例如，这可以包括询问最终用户其 首选语言是什么，并根据该语言 偏好动态添加或替换文档中的 清单链接关系（例如，使用类似 "manifest.php?lang=fr" 的 URL）。
使用服务器端语言协商或地理定位：
托管 Web 应用程序的服务器可以尝试通过 地理定位或执行语言协商，预先确定最终用户的语言（例如，通过 HTTP “Accept-Language”标头 [RFC9110] 或自定义 HTTP 标头）。有关 更多详细信息和最佳实践，请参阅W3C 国际化文章使用 Accept-Language 设置区域设置和HTTP 标头、meta 元素和语言信息。

鉴于上述选项，开发者需要注意 与最终用户首选语言有关的隐私：当 最终用户已向 Web 应用程序明确表明其语言偏好时（即并非仅使用用户代理的默认语言 设置），通常不应通过网络以明文形式发送 最终用户的首选语言。这样做会泄露最终用户的 个人信息。因此，鼓励开发者 使用 [TLS]，以降低其 Web 应用程序遭受普遍监控的可能性 [RFC7258]。

G. 用例与需求

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

H. 问题摘要

本规范未列出任何问题。

I. 变更记录

本节为非规范性内容。

以下是自首次公开工作草案以来的一些重大变更：

J. 致谢

本节为非规范性内容。

本文档引用了 [HTML] 规范的部分内容，遵循该规范的许可协议。

Dave Raggett 和 Dominique Hazael-Massieux 通过 HTML5Apps 项目为本规范做出了贡献。

Claudio Gomboli 提供了图标示例图片。

印第安纳大学布卢明顿分校的安全研究者通过报告与越界导航相关的潜在风险，为本规范做出了贡献。

K. 索引

K.1 本规范定义的术语

K.2 引用定义的术语

L. 参考文献

L.1 规范性引用

[accname-1.2]
无障碍名称与描述计算 1.2. Bryan Garaventa; Melanie Sumner. W3C. 2026 年 10 月 12 日. W3C 工作草案. URL: https://www.w3.org/TR/accname-1.2/
[BCP47]
用于标识语言的标签. Addison Phillips; Mark Davis. IETF. 2009 年 9 月. 最佳当前实践. URL: https://www.rfc-editor.org/info/bcp47
[CSP3]
内容安全策略第 3 级. Mike West; Antonio Sartori. W3C. 2026 年 9 月 16 日. W3C 工作草案. URL: https://www.w3.org/TR/CSP3/
[css-color-4]
CSS 颜色模块第 4 级. Tab Atkins Jr.; Chris Lilley; Lea Verou. W3C. 2026 年 10 月 9 日. 候选推荐标准草案. URL: https://www.w3.org/TR/css-color-4/
[CSS-MIME]
text/css 媒体类型. H. Lie; B. Bos; C. Lilley. IETF. 1998 年 3 月. 信息性文档. URL: https://www.rfc-editor.org/info/rfc2318/
[css-syntax-3]
CSS 语法模块第 3 级. Tab Atkins Jr.; Simon Sapin. W3C. 2026 年 10 月 1 日. 候选推荐标准草案. URL: https://www.w3.org/TR/css-syntax-3/
[dom]
DOM 标准. Anne van Kesteren. WHATWG. 现行标准. URL: https://dom.spec.whatwg.org/
[ECMA-402]
ECMAScript 国际化 API 规范. Ecma International. URL: https://tc39.es/ecma402/
[ECMAScript-MIME]
脚本媒体类型. B. Hoehrmann. IETF. 2006 年 4 月. 信息性文档. URL: https://www.rfc-editor.org/info/rfc4329/
[fetch]
Fetch 标准. Anne van Kesteren. WHATWG. 现行标准. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML 标准. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. 现行 标准. URL: https://html.spec.whatwg.org/multipage/
[image-resource]
图像资源. Aaron Gustafson; Rayan Kanso; Marcos Caceres. W3C. 2021 年 6 月 4 日. W3C 工作草案. URL: https://www.w3.org/TR/image-resource/
[INFRA]
Infra 标准. Anne van Kesteren; Domenic Denicola. WHATWG. 现行标准. URL: https://infra.spec.whatwg.org/
[JSON]
JavaScript 对象表示法 (JSON) 数据 交换格式. T. Bray, 编辑. IETF. 2017 年 12 月. 互联网标准. URL: https://www.rfc-editor.org/info/rfc8259/
[MEDIAQUERIES-5]
媒体查询第 5 级. Tab Atkins Jr.; Florian Rivoal; Daniel Libby; Luke Warlow. W3C. 2026 年 2 月 19 日. W3C 工作草案. URL: https://www.w3.org/TR/mediaqueries-5/
[MIME-TYPES]
多用途互联网邮件扩展 (MIME) 第二部分：媒体类型. N. Freed; N. Borenstein. IETF. 1996 年 11 月. 草案 标准. URL: https://www.rfc-editor.org/info/rfc2046/
[permissions]
权限. Marcos Caceres; Mike Taylor. W3C. 2025 年 10 月 6 日. W3C 工作草案. URL: https://www.w3.org/TR/permissions/
[RFC2119]
在 RFC 中使用的关键词，用于指示 要求级别. S. Bradner. IETF. 1997 年 3 月. 最佳当前实践. URL: https://www.rfc-editor.org/info/rfc2119/
[RFC7159]
JavaScript 对象表示法 (JSON) 数据 交换格式. T. Bray, 编辑. IETF. 2014 年 3 月. 提议标准. URL: https://www.rfc-editor.org/info/rfc7159/
[RFC8174]
大写与小写的歧义，涉及 RFC 2119 关键词. B. Leiba. IETF. 2017 年 5 月. 最佳当前实践. URL: https://www.rfc-editor.org/info/rfc8174/
[SCREEN-ORIENTATION]
屏幕方向. Marcos Caceres; Léonie Watson. W3C. 2026 年 8 月 6 日. W3C 工作草案. URL: https://www.w3.org/TR/screen-orientation/
[UAX9]
Unicode 双向 算法. Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy. Unicode 联盟. 1 日，2026 年 9 月. Unicode 标准附录 #9. URL: https://www.unicode.org/reports/tr9/tr9-52.html
[UNICODE]
Unicode 标准. Unicode 联盟. URL: https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
Unicode 安全性 注意事项. Mark Davis; Michel Suignard. Unicode 联盟. 9 月 19 日， 2014 年. Unicode 技术报告 #36. URL: https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL 标准. Anne van Kesteren. WHATWG. 现行标准. URL: https://url.spec.whatwg.org/
[UTS55]
Unicode 源代码 处理. Robin Leroy; Mark Davis. Unicode 联盟. 2024 年 1 月 29 日. Unicode 技术标准 #55. URL: https://www.unicode.org/reports/tr55/tr55-5.html

L.2 参考性引用

[FULLSCREEN]
全屏 API 标准。Philip Jägenstedt。WHATWG。现行标准。URL：https://fullscreen.spec.whatwg.org/
[i18n-glossary]
国际化术语表。 Richard Ishida；Addison Phillips。W3C。2024 年 10 月 17 日。W3C 工作组说明。URL：https://www.w3.org/TR/i18n-glossary/
[manifest-app-info]
Web 应用清单——应用程序 信息。Aaron Gustafson。W3C。2023 年 8 月 21 日。W3C 工作组说明。URL： https://www.w3.org/TR/manifest-app-info/
[mimesniff]
MIME 嗅探标准。Gordon P. Hemsley。WHATWG。现行标准。URL：https://mimesniff.spec.whatwg.org/
[RFC7258]
普遍监控是一种 攻击。S. Farrell；H. Tschofenig。IETF。2014 年 5 月。最佳当前实践。URL：https://www.rfc-editor.org/info/rfc7258/
[RFC8246]
HTTP 不可变响应。P. McManus。IETF。2017 年 9 月。提议标准。URL：https://httpwg.org/specs/rfc8246.html
[RFC9110]
HTTP 语义。R. Fielding，编辑； M. Nottingham，编辑；J. Reschke，编辑。IETF。2022 年 6 月。互联网标准。URL：https://httpwg.org/specs/rfc9110.html
[SERVICE-WORKERS]
Service Workers 每夜构建版。Monica CHINTALA；Yoshisato Yanagisawa。W3C。2026 年 9 月 17 日。候选推荐草案。URL：https://www.w3.org/TR/service-workers/
[TLS]
传输层安全（TLS）协议 第 1.2 版。T. Dierks；E. Rescorla。IETF。2008 年 8 月。提议标准。URL： https://www.rfc-editor.org/info/rfc5246/