Web 应用清单

W3C 工作草案

关于本文件的更多信息
本版本：
https://www.w3.org/TR/2025/WD-appmanifest-20250903/
最新发布版本：
https://www.w3.org/TR/appmanifest/
最新编辑草稿：
https://w3c.github.io/manifest/
历史：
https://www.w3.org/standards/history/appmanifest/
提交历史
编辑：
Marcos Cáceres (Apple)
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。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：

  • 第一个快捷方式将显示文本 "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 成员用于告知浏览器哪些文档属于网页应用，哪些不属于——即清单会“应用”到哪些页面上。

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

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

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

1.2 dir 成员

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

文本方向包括以下几种，表示 可本地化成员 默认的值：

"ltr"
从左到右文本。
"rtl"
从右到左文本。
"auto"（默认值）
文本方向未知。用户代理应使用启发式方法推断文本显示方向，例如参考 [UAX9] 中描述的 first-strong 算法。

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

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

  1. 将 manifest["dir"] 设为 "auto"。
  2. 如果 json["dir"] 不存在，或 json["dir"] 不是 字符串，则返回。
  3. 对 json["dir"] 去除首尾 ASCII 空白。
  4. 对 json["dir"] 转为小写。
  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 成员用于作为网页应用在各种场景的图标表示。例如，可以用于在其他应用列表中表示网页应用，或与操作系统的任务切换器或系统偏好集成。

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 成员是一个字符串， 作为网页应用所有顶级浏览上下文的 默认屏幕方向。可选值为 OrientationLockType 枚举，即 本规范中的 方向值 （如 "any"、"natural"、"landscape"、"portrait"、"portrait-primary"、 "portrait-secondary"、"landscape-primary"、"landscape-secondary"）。

如果用户代理支持 orientation 成员的值作为默认屏幕方向，则该值在网页应用生命周期内作为默认方向（除非被运行时其他方式覆盖）。这意味着用户代理 必须 在屏幕方向被解锁 [SCREEN-ORIENTATION] 或顶级浏览上下文被导航时返回到默认屏幕方向。

注

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

某些 UI/UX 考量和/或平台规范意味着部分屏幕方向和 不能共用。 哪些方向与显示模式不能共用由实现者自行决定。例如，对于某些用户代理，在 browser 显示模式下可能不适合改变应用的默认屏幕方向。

注

网页应用运行后，也可通过其他方式改变顶级浏览上下文的屏幕方向（如 [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 同源。

身份被用户代理用来在全局唯一识别应用。当用户代理遇到 身份与已安装应用不符的清单时，应当把该清单当作不同应用，即使来自相同 URL。当用户代理遇到 manifest["id"] 等于（可选排除片段）某已安装应用的 身份时，应当视该清单为现有应用清单的替代，而不是新应用，即使该清单来自不同 URL。

注：最好排除片段
注

身份可用于收集网页应用列表的服务唯一识别应用。

注

身份虽然按 URL 处理，但并不指向可导航的资源，因此不要求在 scope 内。

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

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

1.12 theme_color 成员

清单 的 theme_color 成员作为应用上下文的默认主题色。主题色的定义见 [HTML]。

如果用户代理将 theme_color 成员的值作为默认主题色，则该颜色会作为所有浏览上下文的主题色，前提是这些上下文已应用了该清单。但用户代理可以覆盖默认主题色，如果某个文档的 URL 在 scope 内，且其 应用上下文的清单 包含一个 meta 元素，其 name 属性为 "theme-color"。 但用户代理不应通过 meta 元素覆盖默认主题色，如果文档 URL 不在 scope 内，因为应用无法控制这些文档。

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

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

注

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

1.13 background_color 成员

清单 的 background_color 成员描述网页应用的预期背景色。该值与应用样式表中已有内容重复，但可被用户代理用于在实际文件加载前（无论是来自网络还是磁盘）绘制网页应用的背景色，只要已知清单即可。

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. 遍历 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" 存在且为字符串，则去除空白并设置 normalizedValue["value"]。
    2. 如果 "lang" 存在且为字符串，则去除空白并设置 normalizedValue["lang"]。
    3. 如果 "dir" 存在且为字符串：
      1. 去除空白。
      2. 如果文本方向列表包含该值，则设置 normalizedValue["dir"]。
  4. 如果 "value" 不存在，则返回。
  5. 如果 "lang" 不存在，则设置 normalizedValue["lang"] 为 defaultLanguageTag。
  6. 如果 "dir" 不存在，则设置 normalizedValue["dir"] 为 defaultDirection。
  7. 如果用 normalizedValue["lang"] 或 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. 遍历 languageTag：
    1. 如果调用 IsStructurallyValidLanguageTag 参数为 languageTag 返回 false，则继续下一个。
    2. 运行 处理图片资源，参数为 languageMap[languageTag] 作为图片资源列表， map[member]、manifest URL 和 languageTag。

1.16 清单生命周期

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

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

1.16.1 清单处理

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

下述算法定义了一个处理扩展点：其他规范如果要给清单添加新成员，建议在该算法点挂钩。本规范不应修改 manifest 对象中已有值。

处理清单的步骤如下算法。算法参数为URL document URL、URL manifest URL，以及字节序列 bodyBytes。

  1. 令 json 为 解析 JSON 字节为 infra 值，参数为 bodyBytes。
  2. 如果 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，且其 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。

1.16.2 颜色成员处理

注：支持的颜色

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

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

  1. 如果 json[member] 不存在或不是字符串，则返回。
  2. 去除 json[member] 首尾 ASCII 空白。
  3. 令 color 为按 CSS 语法解析该值为 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. 去除 json[member] 首尾 ASCII 空白。
  3. 设置 map[member] 为 json[member] 的值。

1.16.4 无文档时处理清单

处理清单步骤由 [HTML] 的 link 元素处理步骤调用，用户代理也可以在无关联 文档时处理清单。

在此情况下，为保证与 [HTML] 对应步骤一致，用户代理应当至少确保过去某一时刻：

注：这些检查的理由

1.16.5 应用清单

已处理清单被应用于顶级浏览上下文，即清单成员影响该浏览上下文的展示和/或行为。每当 顶级浏览上下文创建时，用户代理可以 在导航开始前为其应用清单。

注

应用清单的顶级浏览上下文称为应用上下文。

如果应用上下文因用户代理被要求导航到深度链接而创建，则用户代理必须立即导航到该深度链接，参数 historyHandling 设为 "replace"。否则，创建应用上下文时，用户代理必须立即导航到start URL，参数 historyHandling 设为 "replace"。

注

1.16.6 清单更新

按照 manifest link 关系的规范，清单会在每次页面加载时获取并处理。当处理清单成功后，用户代理可以为与应用关联的当前和未来应用上下文应用更新后的清单。

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

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

安全敏感成员应当采用 [UTS55] 描述的双向隔离方式展示，无论其方向如何。

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

相反，用户代理应当以合适的管理选项展示安全敏感成员的更改，让用户能做出知情决定是否更新网页应用。

如果更新不涉及安全敏感成员的更改，用户代理可以自动应用更改。

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

注：用户代理不会应用部分更新

2. 清单图片资源

每个 清单图片资源 都是一个 图片资源，在概念上属于网页应用的一部分，可用于不同场景，具体取决于使用该对象的成员语义（例如作为应用菜单的图标等）。

清单图片资源与 图片资源的区别在于它可以有一个额外的 purpose 成员。

用户代理可以在向用户展示之前，根据平台视觉风格对与 清单图片资源关联的图片进行修改，例如将角变圆或使用特定颜色绘制。建议开发者针对这些场景准备图片资源，以避免因颜色变化或角被裁剪而丢失重要信息。

2.1 purpose 成员

purpose 成员是一个 唯一空格分隔字符串集合。允许的值为 图标用途。

当 清单图片资源用作 图标 时， 开发者可以提示该图片在主机 操作系统中的特殊用途（即更好集成）。 用户代理不应将图标用于与声明用途不符的场景。

注

例如，具有用途 "monochrome" 的图标可用作徽章或纯色填充的置顶图标，与应用的全彩启动图标视觉区分。用户代理会将 purpose 成员的值作为提示，决定图标在何处及如何展示。除非开发者另有声明，用户代理可将图标用于 任意用途。

图标用途包括：

monochrome
用户代理可在需要纯色填充的单色图标的场景下展示该图标。图标中的色彩信息会被丢弃，仅保留 alpha 数据。用户代理可将图标用作任意纯色填充的蒙版。
maskable
图片专为图标遮罩与安全区设计，图片中超出 安全区的部分可安全地被用户代理遮罩掉。
any（默认）
用户代理可自由展示图标于无需特殊 purpose 的场景。例如，具有 "any" 用途的 清单图片资源不会在需要 "monochrome" 的场景被使用。

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

注

如果图标声明多个用途，则可用于任一用途。若声明的用途均未被识别，则图标会被完全忽略。例如，若图标用途为 "monochrome fizzbuzz"，则可作为单色图标使用，因为 "monochrome" 是有效用途。但若用途仅为 "fizzbuzz"，则图标会被忽略。

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

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

2.2 内容安全策略

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

2.3 图标遮罩与安全区

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

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

注

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

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

该区域内的所有像素在所有遮罩下都保证可见。安全区外的像素不保证可见（但根据具体遮罩可能可见）。

用户代理可以应用任意尺寸的遮罩，将距离中心超过图像尺寸2/5（宽高最小值，若非正方形）的像素（即安全区以外）变为透明。

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

用户代理可以通过增加额外内边距使图标变大。

如果图标包含透明像素，用户代理必须将图标与一个实色（如白色）背景合成，实色由用户代理决定。

注

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

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 单色图标与纯色填充

某些平台要求图标以纯色填充显示，例如单一颜色，只有图标的透明度可在 manifest 中声明。由于网页应用需兼容多平台，可以通过添加 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. 快捷方式项

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

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

3.1 name 成员

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

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

3.2 short_name 成员

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

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

3.3 description 成员

快捷方式项 的 description 成员是一个字符串， 开发者可用来描述该快捷方式用途。用户代理可以向辅助技术展示该信息。

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

3.4 url 成员

快捷方式项 的 url 成员是某个 已处理清单的 scope 内的 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。
  3. 如果 url 失败，则返回失败。
  4. 如果 url 不在 scope 的 scope 内，则返回失败。
  5. 令 shortcut 为 有序映射 «[ "url" → url, "name" → item["name"] ]»。
  6. 处理 *_localized 文本成员，参数为 item、shortcut、"name_localized" 和 defaultDirection。
  7. 如果 "short_name" 存在且为字符串，则设置 shortcut["short_name"] 为 item["short_name"]。
  8. 处理 *_localized 文本成员，参数为 item、shortcut、"short_name_localized" 和 defaultDirection。
  9. 如果 "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. 可安装的网页应用

任何网站都是可安装网页应用。

用户代理可以为终端用户提供一个机制，将网页应用安装到终端设备，让用户可以实例化一个新的顶级浏览上下文并应用清单的成员 apply。

一旦网页应用被安装，就称为已安装网页应用：即清单成员或其默认值已被应用于该网页应用的顶级浏览上下文。这将已安装网页应用与传统书签区分开来，传统书签打开网页时不会应用清单属性。

注

例如，在支持安装的用户代理中，网页应用可以以类似原生应用的方式呈现并启动：如在主屏幕、启动器或开始菜单中显示带标签的图标。当启动网页应用时，用户代理会在加载start URL前将清单应用于顶级浏览上下文。这使用户代理可以应用相关清单值，比如改变网页应用的显示模式和屏幕方向。或者，用户代理也可以仅将网页应用安装到其书签列表中。

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 启动网页应用

由操作系统或用户代理决定时，运行 启动网页应用的步骤，参数为 已处理清单。

注

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

启动网页应用的步骤如下算法。该算法接收一个已处理清单 manifest，可选参数 URL target URL， 可选参数 POST resource POST resource，返回一个 应用上下文。

如果给定 target URL，则必须保证其在 manifest 的 scope 内。

其他规范可以替换此算法步骤，替换后所有 启动网页应用调用都生效。

注

此算法可被替换以支持实验性 launch_handler 清单字段，配置所有网页应用启动行为。替换后的算法默认会调用 创建新应用上下文，但特定条件下行为可变。

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

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

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

4.3 隐私与安全注意事项

建议为用户提供安装网页应用的界面时，也应允许用户检查与网页应用相关的图标、名称、start URL、来源等信息。这可以让用户在安装前有机会有意识地批准并可能修改相关信息，也能帮助用户判断该网页应用是否冒充其他应用（例如使用意外的图标或名称）。

建议用户代理防止其他应用判断系统上已安装哪些应用（例如通过用户代理缓存的计时攻击）。可以在网页应用安装后使清单引用的资源（如图标）失效，或使用与常规浏览不同的缓存。

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。

用户代理一旦应用某种 显示模式于 应用上下文后，该模式成为该顶级浏览上下文的默认显示模式（即窗口被 导航时采用该模式）。用户代理可以因安全原因覆盖默认显示模式（如浏览到其他来源），或可以允许用户切换其他显示模式。

当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。
注

上述循环总能返回结果，因为 browser 在所有模式的 回退链里，并且所有用户代理都必须支持 browser 显示模式。

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

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

注

用户代理实际暴露的是已应用的显示模式——不一定是清单声明的模式——通过 display-mode 媒体特性，可通过 CSS 或 JavaScript 获取。注意该媒体特性也会反映未应用清单时网页的其他显示模式。例如用户将页面切换为全屏，则用户代理会通过 display-mode 媒体特性将此变更反映给 CSS 和脚本。

7. 隐私与安全注意事项

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

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

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

网页应用可以包含内容，同时与本地设备和远程主机交互，实现者需要关注向远程主机暴露隐私信息带来的隐私影响。缓解和防御措施由实现负责，本规范不作具体规定。但建议实现者在设计这些措施时，应提升用户对信息分享的知晓度，并提供便捷界面以撤销权限。

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

开发者需关注 [CSP3] 规范中的安全事项，尤其是将 data: 作为有效来源以“内联”清单。这样做可能允许清单直接包含于文档中，导致 XSS 攻击，建议彻底避免这种做法。

建议在为终端用户提供网页应用安装界面时，同时允许检查与网页应用相关的图标、名称、start URL、来源等信息。这样，用户有机会在安装前主动批准并可能修改相关信息，也能判断该网页应用是否冒充其他应用（如使用意外图标或名称）。

建议用户代理防止其他应用判断系统已安装哪些应用（如通过用户代理缓存的计时攻击）。可通过在网页应用安装后使清单链接的资源（如图标）缓存失效，或采用与普通浏览不同的缓存实现。

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

网页应用运行时，建议用户代理为用户提供访问应用常用信息的方式，如来源、启动/当前 URL、已授权权限、关联图标。具体如何展示由实现者自行决定。

另外，应用清单设置 display mode 为除 "browser" 以外的值时， 建议用户代理应明确告知用户已离开普通网页浏览环境。理想情况下，启动或切换到网页应用时，表现与主机平台启动或切换其他应用一致，例如采用明显且较长的动画过渡，或语音播报“正在启动应用X”。

display 成员允许来源一定程度上控制用户代理的原生 UI。全屏后可尝试模仿其他应用的界面。通过 'display-mode' 媒体特性 [MEDIAQUERIES-5]，脚本可获知网页应用的显示模式。

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

本节为非规范性内容。

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

注：Web Manifest JSON Schema

F. 国际化

本节为非规范性内容。

预计作者将通过以下方式之一对清单内容进行本地化：

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

基于上述选项，开发者需关注终端用户首选语言的隐私问题：当终端用户已明确向网页应用指定语言偏好（即不只是用用户代理默认语言设置），将用户的首选语言明文发送到网络通常不合适。这样会暴露关于用户的个人信息。因此，鼓励开发者采用 [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。2025年6月17日。W3C工作草案。URL：https://www.w3.org/TR/accname-1.2/
[BCP47]
用于标识语言的标签。A. Phillips, Ed.; M. Davis, Ed. IETF。2009年9月。最佳当前实践。URL：https://www.rfc-editor.org/rfc/rfc5646
[CSP3]
内容安全策略第3级。Mike West; Antonio Sartori。W3C。2025年7月11日。W3C工作草案。URL：https://www.w3.org/TR/CSP3/
[css-color-4]
CSS颜色模块第4级。Chris Lilley; Tab Atkins Jr.; Lea Verou。W3C。2025年4月24日。CRD。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/rfc/rfc2318
[css-syntax-3]
CSS语法模块第3级。Tab Atkins Jr.; Simon Sapin。W3C。2021年12月24日。CRD。URL：https://www.w3.org/TR/css-syntax-3/
[dom]
DOM 标准。Anne van Kesteren。WHATWG。Living Standard。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/rfc/rfc4329
[fetch]
Fetch 标准。Anne van Kesteren。WHATWG。Living Standard。URL：https://fetch.spec.whatwg.org/
[HTML]
HTML 标准。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]
图片资源。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。Living Standard。URL：https://infra.spec.whatwg.org/
[JSON]
JavaScript对象表示法（JSON）数据交换格式。T. Bray, Ed. IETF。2017年12月。互联网标准。URL：https://www.rfc-editor.org/rfc/rfc8259
[MEDIAQUERIES-5]
媒体查询第5级。Dean Jackson; Florian Rivoal; Tab Atkins Jr.; Daniel Libby。W3C。2021年12月18日。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/rfc/rfc2046
[permissions]
权限。Marcos Caceres; Mike Taylor。W3C。2025年6月24日。W3C工作草案。URL：https://www.w3.org/TR/permissions/
[RFC2119]
RFC中用于指示需求级别的关键字。S. Bradner。IETF。1997年3月。最佳当前实践。URL：https://www.rfc-editor.org/rfc/rfc2119
[RFC7159]
JavaScript对象表示法（JSON）数据交换格式。T. Bray, Ed. IETF。2014年3月。建议标准。URL：https://www.rfc-editor.org/rfc/rfc7159
[RFC8174]
RFC2119关键字的大写与小写歧义。B. Leiba。IETF。2017年5月。最佳当前实践。URL：https://www.rfc-editor.org/rfc/rfc8174
[SCREEN-ORIENTATION]
屏幕方向。Marcos Caceres。W3C。2023年8月9日。W3C工作草案。URL：https://www.w3.org/TR/screen-orientation/
[UAX9]
Unicode双向算法。Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy。Unicode Consortium。2024年9月2日。Unicode标准附录#9。URL：https://www.unicode.org/reports/tr9/tr9-50.html
[UNICODE]
Unicode标准。Unicode Consortium。URL：https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
Unicode安全注意事项。Mark Davis; Michel Suignard。Unicode Consortium。2014年9月19日。Unicode技术报告#36。URL：https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL 标准。Anne van Kesteren。WHATWG。Living Standard。URL：https://url.spec.whatwg.org/
[UTS55]
Unicode源代码处理。Robin Leroy; Mark Davis。Unicode Consortium。2024年1月29日。Unicode技术标准#55。URL：https://www.unicode.org/reports/tr55/tr55-5.html

L.2 参考性引用

[FULLSCREEN]
全屏API标准。Philip Jägenstedt。WHATWG。Living Standard。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。Living Standard。URL：https://mimesniff.spec.whatwg.org/
[RFC7258]
广泛监控即攻击。S. Farrell; H. Tschofenig。IETF。2014年5月。最佳当前实践。URL：https://www.rfc-editor.org/rfc/rfc7258
[RFC9110]
HTTP语义。R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed. IETF。2022年6月。互联网标准。URL：https://httpwg.org/specs/rfc9110.html
[SERVICE-WORKERS-1]
Service Worker。Yoshisato Yanagisawa; Monica CHINTALA。W3C。2025年3月6日。CRD。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/rfc/rfc5246
[webidl]
Web IDL 标准。Edgar Chen; Timothy Gu。WHATWG。Living Standard。URL：https://webidl.spec.whatwg.org/