MiniApp 清单

MiniApp 清单是一个 [JSON] 文档，它扩展并剖析 Web App Manifest [APPMANIFEST] 和 Web App Manifest - Application Information [MANIFEST-APP-INFO]，用于描述与 MiniApp 关联的元数据。

注

本规范定义了一组用于描述 MiniApp 的元数据，通过提供用于描述和设置 MiniApp 的附加约束和特定机制，扩展 Web 应用清单和 Web App Manifest - 应用信息。MiniApp 清单直接复用这些规范中的基本元素（即 name、short_name、description 和 icons），并添加专门影响 MiniApp 的补充成员（例如 app_id、 version、platform_version、device_type、pages、 req_permissions 和 widgets）以及其外观和感受（例如 color_scheme 和 window）。

MiniApp 清单MUST 在其根部包含以下成员：

app_id
icons
name
pages
platform_version
version

MiniApp 清单的 icons 成员中的每个图像资源对象MUST 包含：

src

MiniApp 清单MAY 在其根部包含 widgets 成员。该成员MUST 包含一个由列表组成的数组，其中包含 MiniApp 部件资源。每个 MiniApp 部件资源对象MUST 包含以下成员：

name
path

MiniApp 清单MAY 在其根部包含 req_permissions 成员。该成员MUST 包含一个由列表组成的数组，其中包含 MiniApp 权限资源。每个 MiniApp 权限资源对象 MUST 包含以下成员：

name

MiniApp 用户代理MAY 实现清单的供应商特定扩展，支持可选成员。

下表显示了 MiniApp 清单的成员概要：

根部成员
成员	类型	必需	描述
`app_id`	字符串	是	MiniApp 标识符
`color_scheme`	字符串	否	MiniApp 配色方案
`description`	字符串	否	MiniApp 描述
`device_type`	列表	否	支持的设备
`dir`	字符串	否	文本方向
`icons`	图像资源列表	是	MiniApp 图标
`lang`	字符串	否	MiniApp 主要语言
`name`	字符串	是	MiniApp 名称
`pages`	列表	是	页面路由信息
`platform_version`	平台版本资源	是	支持的平台版本
`req_permissions`	权限资源列表	否	所需权限
`short_name`	字符串	否	MiniApp 短名称
`version`	版本资源	是	MiniApp 版本
`widgets`	部件资源列表	否	MiniApp 部件
`window`	窗口资源	否	窗口样式

图像资源对象的成员
（`icons` 列表）
成员	类型	必需	描述
`label`	字符串	否	无障碍文本
`sizes`	字符串	否	图标的分辨率尺寸
`src`	字符串	是	图标的来源

平台版本资源对象的成员
（`platform_version` 有序映射）
成员	类型	必需	描述
`min_code`	number	是	支持的最低平台版本
`release_type`	字符串	否	目标平台版本类型
`target_code`	字符串	否	目标平台版本代码

权限资源对象的成员
（`req_permissions` 列表）
成员	类型	必需	描述
`name`	字符串	是	权限名称
`reason`	字符串	否	请求权限的原因

版本资源对象的成员
（`version` 有序映射）
成员	类型	必需	描述
`code`	number	是	版本代码
`name`	字符串	是	版本名称

部件资源对象的成员
（`widgets` 列表）
成员	类型	必需	描述
`min_code`	number	否	支持的最低平台版本
`name`	字符串	是	部件名称
`path`	字符串	是	部件路径

窗口资源对象的成员
（`window` 有序映射）
成员	类型	必需	描述
`auto_design_width`	布尔值	否	启用/禁用页面 `design_width` 的自动计算
`background_color`	字符串	否	窗口背景颜色
`background_text_style`	字符串	否	背景文本样式
`design_width`	number	否	基准页面设计宽度
`enable_pull_down_refresh`	布尔值	否	启用下拉刷新事件
`fullscreen`	布尔值	否	全屏显示
`navigation_bar_background_color`	字符串	否	导航栏背景颜色
`navigation_bar_text_style`	字符串	否	导航栏的文本样式
`navigation_bar_title_text`	字符串	否	导航栏标题
`navigation_style`	字符串	否	导航栏样式
`on_reach_bottom_distance`	number	否	触发上拉触底事件的距离
`orientation`	字符串	否	屏幕方向设置

注

其他应用清单成员，例如 scope、 theme_color 和 shortcuts，当前不受 MiniApp 用户代理支持。

本节是非规范性的。

以下代码表示一个 MiniApp 清单示例：

示例 1：清单文档

{
  "dir": "ltr",
  "lang": "en-US",
  "app_id": "org.example.miniapp",
  "name": "MiniApp Demo",
  "short_name": "MiniApp",
  "version": {
    "name": "1.0.1",
    "code": 11
  },
  "description": "A Simple MiniApp Demo",
  "icons": [
    {
      "label": "Red lightning",
      "src": "common/icons/icon.png",
      "sizes": "48x48"
    }
  ],
  "platform_version":{
    "min_code": 1,
    "release_type": "Beta1",
    "target_code": 2
  },
  "pages": [
    "pages/index/index",
    "pages/detail/detail"
  ],
  "window": {
    "background_color": "#ffffff",
    "fullscreen": false,            
    "navigation_bar_text_style": "black",
    "navigation_bar_title_text": "My MiniApp",
    "navigation_bar_background_color": "#f8f8f8"
  },
  "widgets": [
    {
      "name": "widget",
      "min_code": "2",
      "path": "widgets/index/index"
    }
  ],
  "req_permissions": [
    {
      "name": "system.permission.LOCATION",
      "reason": "To show user's position on the map"
    },
    {
      "name": "system.permission.CAMERA",
      "reason": "To scan a QR code"
    }
  ],
  "color_scheme": "light",
  "device_type": [
     "phone",
     "tv",
     "car"
  ]		  
}

MiniApp 清单使用以下基本应用清单成员。

MiniApp 清单的 dir 成员在指定可本地化成员的基本方向的同时，也指定整个 MiniApp 的默认基本文本方向。

dir 成员的值可以设置为 [APPMANIFEST] 中指定的 text-directions 之一。文本方向值如下：

"ltr": 从左到右文本。
"rtl": 从右到左文本。
"auto" （默认）: 无显式方向性。

注：处理 `dir` 成员

当处理 MiniApp 清单时，根据 [APPMANIFEST] 规范，使用处理 dir 成员算法来处理 dir 成员。

MiniApp 清单的 icons 成员描述用作 MiniApp 图标式表示的图像。该成员是由图像资源有序映射组成的列表。

如 [IMAGE-RESOURCE] 所规定，图像资源由以下内容组成：


label: 一个可选字符串，表示图像的无障碍名称。
sizes: 一个可选字符串，表示图像的尺寸，使用与 link 的 sizes 属性相同的语法表示。
src: 一个URL，用于获取图像数据。

注：处理 `icons` 成员

当处理 MiniApp 清单时，根据 [APPMANIFEST] 规范，使用处理图像资源算法来处理 icons 成员。

注：无障碍考虑

强烈鼓励开发者添加 label，除非图像资源的无障碍名称可以从其上下文中的外部标签推断出来。

MiniApp 清单的 lang 成员在指定可本地化成员的主要语言的同时，也指定整个 MiniApp 的主要语言。该成员是一个字符串，形式为语言标签，即匹配 [BCP47] 中定义的 Language-Tag 产生式的字符串，如 [APPMANIFEST] 中所定义。

注：处理 `lang` 成员

当处理 MiniApp 清单时，根据 [APPMANIFEST] 规范，使用处理 lang 成员算法来处理 lang 成员。

MiniApp 清单的 name 成员是应用的描述性名称。这是直接显示给用户的名称。它与桌面图标一起以及在 MiniApp 管理上下文中用作 MiniApp 的显示名称。

注：处理 `name` 成员

当处理 MiniApp 清单时，根据 [APPMANIFEST] 规范，使用处理文本成员算法来处理 name 成员。

MiniApp 清单的 short_name 成员为 MiniApp 提供一个简洁且易读的名称。当没有足够空间显示 name 中提供的完整 MiniApp 名称时，可以使用它。

注：处理 `short_name` 成员

当处理 MiniApp 清单时，根据 [APPMANIFEST] 规范，使用处理文本成员算法来处理 short_name 成员。

以下成员在 Web App Manifest - Application Information 规范 [MANIFEST-APP-INFO] 中定义。

MiniApp 清单的 description 成员为 MiniApp 提供文本描述，以自然语言表示 Web 应用的目的，如 [MANIFEST-APP-INFO] 中定义

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

如果 json["description"] 不是字符串，则返回。
将 manifest["description"] 设置为 json["description"]。

以下成员定义在 MiniApp 清单的范围内，用于处理 MiniApp 的特定方面。

MiniApp 清单的 app_id 成员是一个字符串，用于唯一标识 MiniApp。该成员主要用于包管理，支持 MiniApp 版本化的更新和发布过程。

app_id 的值既区分大小写，也对 Unicode 中字符的不同编码方式敏感。因此，只有当两个 app_id 值被编码为相同的码点序列时，它们才相等。

注：用法

MiniApp 的一个常见实践是使用类似反向域名的约定，该约定由 Java 包命名约定使用（例如 org.example.miniapp），并遵循以下规则：

appIdRule = name *("." name)
name = ALPHA [*( ALPHA / DIGIT / "-" ) ( ALPHA / DIGIT)]

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

如果 json["app_id"] 不存在，或者如果 json["app_id"] 不是字符串，则返回。
将 manifest["app_id"] 设置为 json["app_id"]。

可选的MiniApp 清单的 color_scheme 成员是一个字符串，用于指示 MiniApp 的首选配色方案（即 "auto"、"light，或 "dark"），覆盖窗口资源对象中的其他配置成员，包括 background_color、 background_text_style、 navigation_bar_text_style、和 navigation_bar_title_text。

该成员MUST 包含以下配色方案值之一：

"auto": 主题颜色适应系统主题颜色。
"light": 用于浅色配色方案。
"dark": 用于深色配色方案。

注：用法

MiniApp 用户代理MAY 实现预定义的样式资源，例如每个配色方案的背景颜色、封面图像和图标。此外，开发者MAY 使用 prefers-color-scheme CSS 媒体特性 [MEDIAQUERIES-5] 为每种模式定义自定义样式表。

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

如果 json["color_scheme"] 不存在，
或如果 json["color_scheme"] 不是字符串，
或如果 json["color_scheme"] 不匹配配色方案值之一，则返回。
将 manifest["color_scheme"] 设置为 json["color_scheme"]。

可选的MiniApp 清单的 device_type 成员是一个由字符串组成的列表，用于指示 MiniApp 预期运行的设备类型。该成员的值告知用户代理，该 MiniApp 是否被设计为能够在特定平台上正常运行，例如智能手机、智能电视、车载主机、可穿戴设备和其他设备。

该成员在初始化过程中用于设备兼容性验证。通过检查其值，用户代理会根据 UI 组件、CSS 支持和 API 的兼容性，决定 MiniApp 是否适合在该平台上运行。如果验证过程失败，MiniApp 用户代理决定如何实现平台行为（例如停止初始化阶段并拒绝安装，或安装 MiniApp 但拒绝执行）。

注：用法

本文档未规定该成员的可能值列表，以在实现中保持灵活性，并考虑任何设备和用例。一些常见值包括：smartphone、tablet、tv、car、 wearable 和 iot。

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

如果 json["device_type"] 不存在，或者如果 json["device_type"] 不是列表，则返回。
令 device_type 为一个新的空列表。
对 json["device_type"] 的每个 item 执行：
1. 如果 item 不是字符串，则返回。
2. 将 item 追加到 device_type。
将 manifest["device_type"] 设置为 device_type。

MiniApp 清单的 pages 成员是一个由相对 URL 字符串组成的列表，用于指定 MiniApp 中包含的页面集合。列表中的每一项表示一个由其页面路由标识的页面。

MiniApp 页面路由是 MiniApp 页面的相对路径和文件名。在配置页面路由时，开发者MAY 省略定义页面主组件的文件扩展名（例如 pages/mypage 或 pages/mypage.html）。

pages 列表中的第一项定义 MiniApp 的主页或入口点。

注：用法

为了与 Web 平台兼容，RECOMMENDED 将 pages 与 Web 应用清单的 start_url 和 scope 成员一起使用。这些成员将设置为以下值：

start_url SHOULD 设置为 pages 成员中第一项的相同值；并且
scope SHOULD 设置为值 "."。

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

如果 json["pages"] 不存在，或者如果 json["pages"] 不是列表，则返回。
令 pages 为一个新的列表。
对 json["pages"] 的每个 item 执行：
1. 如果 item 不是字符串，则返回。
2. 令 url 为解析 item 的结果。
3. 如果 url 为失败，则继续。
4. 将 pages 追加到 url。
将 manifest["pages"] 设置为 pages。

MiniApp 清单的 platform_version 成员包含一个MiniApp 平台版本资源有序映射，用于描述运行 MiniApp 的最低要求和预期平台版本，包括 min_code、 target_code、和 release_type。

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

如果 json["platform_version"] 不存在，或者如果 json["platform_version"] 不是有序映射，则返回。
令 platform_version 为一个新的有序映射。
处理平台版本的 min_code 成员，传入 json["platform_version"] 和 platform_version。
处理平台版本的 target_code 成员，传入 json["platform_version"] 和 platform_version。
处理平台版本的 release_type 成员，传入 json["platform_version"] 和 platform_version。
如果 platform_version["min_code"] 不存在，则返回 failure。
将 manifest["platform_version"] 设置为 platform_version。

可选的MiniApp 清单的 req_permissions 成员是一个由 MiniApp 权限资源有序映射组成的列表。

每个 MiniApp 权限资源声明了使用某项具体系统功能（例如访问设备的位置、用户联系人、传感器和摄像头）的请求，这些功能是 MiniApp 正常执行所需的。

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

如果 json["req_permissions"] 不存在，或者如果 json["req_permissions"] 不是列表，则返回。
令 permissions 为一个新的列表。
对 json["req_permissions"] 的每个 item 执行：
1. 如果 item 不是有序映射，则继续。
2. 令 permission 为一个有序映射。
3. 处理权限资源的 name 成员，传入 item 和 permission。
4. 如果 permission["name"] 不存在，则继续。
5. 处理权限资源的 reason 成员，传入 item 和 permission。
6. 将 permission 追加到 permissions。
将 manifest["req_permissions"] 设置为 permissions。

注：保护用户隐私

用户代理会请求用户同意，以在访问这些特定功能期间保护其隐私。 req_permissions 成员中的这些信息可由应用商店或托管平台使用，以根据用户偏好、隐私政策或设备能力筛选 MiniApp。

MiniApp 清单的 version 成员包含一个MiniApp 版本资源有序映射，用于表示 code 和 name。

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

如果 json["version"] 不存在，或者如果 json["version"] 不是有序映射，则返回。
令 version 为一个新的有序映射。
处理版本的 code 成员，传入 json["version"] 和 version。
处理版本的 name 成员，传入 json["version"] 和 version。
将 manifest["version"] 设置为 version。

可选的MiniApp 清单的 widgets 成员是一个由 MiniApp 部件资源组成的列表，这些部件资源是 MiniApp 的一部分。

MiniApp 包MAY 同时包含MiniApp 页面和 Widgets。

作为 MiniApp 一部分的 widget 会应用MiniApp 清单的一些成员，包括：

dir；
lang；
app_id；
name；
short_name；
icons；
version

但是，widget 也具有其专属字段，这些字段在MiniApp 部件资源中定义。

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

如果 json["widgets"] 不存在，或者如果 json["widgets"] 不是列表，则返回。
令 widgets 为一个新的空列表。
对 json["widgets"] 的每个 item 执行：
1. 如果 item 不是有序映射，则继续。
2. 令 widget 为一个有序映射。
3. 处理 widget 的 name 成员，传入 item 和 widget。
4. 处理 widget 的 path 成员，传入 item 和 widget。
5. 处理 widget 的 min_code 成员，传入 item、manifest 和 widget。
6. 如果 widget["name"] 不存在，或者如果 item["path"] 不存在，则继续。
7. 将 widget 追加到 widgets。
将 manifest["widgets"] 设置为 widgets。

可选的MiniApp 清单的 window 成员包含一个MiniApp 窗口资源有序映射，用于描述 MiniApp 框架的外观和感受，包括状态栏、导航栏、标题、背景颜色以及其他视觉配置元素的样式。

window 对象成员继承自 MiniApp 清单根部的 dir 和 lang 成员的文本方向和语言配置。

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

如果 json["window"] 不存在，或者如果 json["window"] 不是有序映射，则返回。
令 window 为一个新的有序映射 «[ "auto_design_width" → false, "background_color" → "#ffffff", "background_text_style" → "dark", "design_width" → 750, "enable_pull_down_refresh" → false, "fullscreen" → "false", "navigation_bar_background_color" → "#000000", "navigation_bar_text_style" → "white", "navigation_bar_title_text" → "default", "on_reach_bottom_distance" → 50, "orientation" → "portrait" ]»。
处理 window 的 auto_design_width 成员，传入 json["window"] 和 window。
处理颜色成员，传入 json["window"]、window 和 "background_color"。
处理 window 的 background_text_style 成员，传入 json["window"] 和 window。
处理 window 的 design_width 成员，传入 json["window"] 和 window
处理 window 的 enable_pull_down_refresh 成员，传入 json["window"] 和 window。
处理 window 的 fullscreen 成员，传入 json["window"] 和 window。
处理颜色成员，传入 json["window"]、window 和 "navigation_bar_background_color"。
处理 window 的 navigation_bar_text_style 成员，传入 json["window"] 和 window。
处理 window 的 navigation_bar_title_text 成员，传入 json["window"] 和 window。
处理 window 的 navigation_style 成员，传入 json["window"] 和 window。
处理 window 的 on_reach_bottom_distance 成员，传入 json["window"] 和 window。
处理 window 的 orientation 成员，传入 json["window"] 和 window。
处理 window 的 auto_design_width 成员，传入 json["window"] 和 window。
将 manifest["window"] 设置为 window。

MiniApp 清单作为应用清单的扩展，提供了一个补充算法，用于在 [APPMANIFEST] 中定义的处理清单算法的扩展点处处理。因此，用户代理首先处理应用清单的成员，然后在扩展点处继续使用以下算法处理 MiniApp 清单成员。

要在扩展点处处理 MiniApp 清单，给定有序映射 json 和有序映射 manifest：

如果 manifest["name"] 不存在，则抛出一个 TypeError。
如果 manifest["icons"] 不存在，则抛出一个 TypeError。
令 icons 为 manifest["icons"]。
如果 icons["src"] 不存在，则抛出一个 TypeError。
如果 manifest["icons"] 不存在，则抛出一个 TypeError。
处理 app_id 成员，传入 json 和 manifest。
如果 manifest["app_id"] 不存在，则抛出一个 TypeError。
处理 color_scheme 成员，传入 json 和 manifest。
处理 description 成员，传入 json 和 manifest。
处理 device_type 成员，传入 json 和 manifest。
处理 pages 成员，传入 json 和 manifest。
如果 manifest["pages"] 不存在，则抛出一个 TypeError。
处理 platform_version 成员，传入 json 和 manifest。
如果 manifest["platform_version"] 不存在，则抛出一个 TypeError。
处理 req_permissions 成员，传入 json 和 manifest。
处理 version 成员，传入 json 和 manifest。
如果 manifest["version"] 不存在，则抛出一个 TypeError。
处理 widgets 成员，传入 json 和 manifest。
处理 window 成员，传入 json 和 manifest。

MiniApp 平台版本资源是一个有序映射，指示 MiniApp 要使用的最低和目标平台版本。

以下成员定义在 MiniApp 清单的范围内，用于处理平台版本资源的特定方面。

MiniApp 平台版本资源的 min_code 成员是一个非负整数，表示 MiniApp 用户代理平台的最低支持版本，以确保 MiniApp 的正常运行。

要处理平台版本的 min_code 成员，给定有序映射 json 和有序映射 platform_version：

如果 json["min_code"] 不存在，或者如果 json["min_code"] 不是 number，则返回 failure。
将 platform_version["min_code"] 设置为 json["min_code"]。

MiniApp 平台版本资源的 release_type 成员是一个字符串，用于指示运行应用所需的 MiniApp 用户代理目标平台版本的发布类型。

注：用法

MiniApp 供应商可以为该成员推荐特定的版本化方案和值（例如 CanaryN、BetaN 或 Release，其中 N 表示正整数，例如 Beta1）。

要处理平台版本的 release_type 成员，给定有序映射 json 和有序映射 platform_version：

如果 json["release_type"] 不存在，或者如果 json["release_type"] 不是字符串，则返回。
将 platform_version["release_type"] 设置为 json["release_type"]。

MiniApp 平台版本资源的 target_code 成员是一个非负整数，表示 MiniApp 用户代理平台的目标支持版本，以确保 MiniApp 的正常运行。

要处理平台版本的 target_code 成员，给定有序映射 json 和有序映射 platform_version：

如果 json["target_code"] 不存在，或者如果 json["target_code"] 不是 number，则返回。
将 platform_version["target_code"] 设置为 json["target_code"]。

MiniApp 权限资源是一个有序映射，用于描述使用某项具体系统功能（例如访问设备的位置、用户联系人、传感器和摄像头）的请求，这些功能是 MiniApp 正常执行所需的。

以下成员定义在 MiniApp 清单的范围内，用于处理权限资源的特定方面。

MiniApp 权限资源的 name 成员是一个字符串，用于指示所请求功能的名称。

要处理权限资源的 name 成员，给定有序映射 json 和有序映射 permission：

如果 json["name"] 不存在，或
如果 json["name"] 不是字符串，或者如果 json["name"] 是空字符串，则返回。
将 permission["name"] 设置为 json["name"]。

可选的MiniApp 权限资源的 reason 成员是一个字符串，用于指示请求 [MiniApp permission resource/name=] 属性中指定功能的原因。

要处理权限资源的 reason 成员，给定有序映射 json 和有序映射 permission：

如果 json["reason"] 不存在，或
如果 json["reason"] 不是字符串，或者如果 json["reason"] 是空字符串，则返回。
将 permission["reason"] 设置为 json["reason"]。

MiniApp 版本资源是一个有序映射，用于描述 MiniApp 的版本代码和版本名称。

以下成员定义在 MiniApp 清单的范围内，用于处理版本资源的特定方面。

MiniApp 版本资源的 code 成员是一个非负整数，表示 MiniApp 的版本。它主要用于增强 MiniApp 的可维护性和安全性（例如增量版本之间的兼容性）。 code 成员旨在支持开发和部署过程，通常不会显示给最终用户。

要处理版本的 code 成员，给定有序映射 json 和有序映射 version：

如果 json["code"] 不存在，或者如果 json["code"] 不是 number，则返回 failure。
令 version 为一个 number，初始值为 1。
如果 json["code"] 大于 0，则：
将 version 设置为 json["code"]。
将 version["code"] 设置为 version。

MiniApp 版本资源的 name 成员是一个字符串，主要用于描述 MiniApp 的版本信息，在版本控制、MiniApp 应用和平台兼容性中发挥重要作用。它通常被视为公开显示并展示给用户的版本。

注：用法

该成员的RECOMMENDED 格式为 X.Y.Z，其中 X、Y 和 Z 是非负整数值（例如 1.10.0），如 Semantic Versioning [SEMANTIC-VERSIONING] 中所规定。

要处理版本的 name 成员，给定有序映射 json 和有序映射 version：

如果 json["name"] 不存在，或者如果 json["name"] 不是字符串，则返回 failure。
将 version["name"] 设置为 json["name"]。

MiniApp 窗口资源是一个有序映射，用于定义和配置包含 MiniApp 的窗口。

以下成员定义在 MiniApp 清单的范围内，用于描述 MiniApp 窗口资源。

auto_design_width 成员是一个布尔值，用于指示页面的 design_width 是否由用户代理自动计算。当 auto_design_width 为 true 时， design_width 的值会被忽略。在这种情况下，系统的基准宽度会根据屏幕的像素密度自动确定。

默认值：false。

要处理 window 的 auto_design_width 成员，给定有序映射 json 和有序映射 window：

如果 json["auto_design_width"] 不存在，或者如果 json["auto_design_width"] 不是布尔值，则返回。
将 window["auto_design_width"] 设置为 json["auto_design_width"]。

background_color 成员是一个字符串，用于指定包含 MiniApp 的窗口的背景颜色。

该成员支持 sRGB 颜色，并且等同于应用清单的 background_color。

默认值："#ffffff"。

注：处理 `background_color` 成员

当处理 MiniApp 清单时，根据 [APPMANIFEST] 规范，使用处理颜色成员算法来处理 window 的 background_color 成员。

background_text_style 成员是一个字符串，用于指定背景文本样式，表示浅色或深色主题（即 "light" 或 "dark"）。

该成员支持 prefers-color-scheme 的值，并且MUST 包含以下背景文本样式值之一：

"light": 用于浅色样式。
"dark" （默认）: 用于深色样式。

要处理 window 的 background_text_style 成员，给定有序映射 json 和有序映射 window：

如果 json["background_text_style"] 不存在，或
如果 json["background_text_style"] 不是字符串，或
如果 json["background_text_style"] 不包含背景文本样式值之一，则返回。
将 window["background_text_style"] 设置为 json["background_text_style"]。

design_width 成员是一个 number，用于指示页面设计在像素单位中的基准宽度。它用于视觉上调整页面组件。

该值是非负整数，默认值为 750。

要处理 window 的 design_width 成员，给定有序映射 json 和有序映射 window：

如果 json["design_width"] 不存在，或
如果 json["design_width"] 不是 number，或者如果 json["design_width"] 小于 0，则返回。
将 window["design_width"] 设置为 json["design_width"]。

enable_pull_down_refresh 成员是一个布尔值，用于指定在与 MiniApp 交互期间是否启用 pull-to-refresh 事件。

默认值：false。

要处理 window 的 enable_pull_down_refresh 成员，给定有序映射 json 和有序映射 window：

如果 json["enable_pull_down_refresh"] 不存在，
或者如果 json["enable_pull_down_refresh"] 不是布尔值，则返回。
将 window["enable_pull_down_refresh"] 设置为 json["enable_pull_down_refresh"]。

fullscreen 成员是一个布尔值，用于指示 MiniApp 是否以全屏显示模式显示。

注：用法

当该成员取 true 值时，它等同于应用清单的 display 成员上的 fullscreen 值。当其取 false 值时，它等同于 minimal-ui。

默认值：false。

要处理 window 的 fullscreen 成员，给定有序映射 json 和有序映射 window：

如果 json["fullscreen"] 不存在，
或者如果 json["fullscreen"] 不是布尔值，则返回。
将 window["fullscreen"] 设置为 json["fullscreen"]。

navigation_bar_background_color 成员是一个字符串，用于指定 MiniApp 导航栏背景的颜色。

该成员支持 sRGB 颜色。

默认值："#000000"。

该成员按照 [APPMANIFEST] 中的规定处理。

注：处理 `navigation_bar_background_color` 成员

当处理 MiniApp 清单时，根据 [APPMANIFEST] 规范，使用处理颜色成员算法来处理 window 的 navigation_bar_background_color 成员。

navigation_bar_text_style 成员是一个字符串，用于指示导航栏标题的文本颜色（即 "white" 或 "black"）。

该成员MUST 包含以下文本样式值之一：

"white" （默认）: 用于白色文本颜色。
"black": 用于黑色文本颜色。

要处理 window 的 navigation_bar_text_style 成员，给定有序映射 json 和有序映射 window：

如果 json["navigation_bar_text_style"] 不存在，或
如果 json["navigation_bar_text_style"] 不是字符串，或
如果 json["navigation_bar_text_style"] 不包含文本样式值之一，则返回。
将 window["navigation_bar_text_style"] 设置为 json["navigation_bar_text_style"]。

navigation_bar_title_text 成员是一个字符串，用于指定 MiniApp 导航栏的标题。

要处理 window 的 navigation_bar_title_text 成员，给定有序映射 json 和有序映射 window：

如果 json["navigation_bar_title_text"] 不存在，或
如果 json["navigation_bar_title_text"] 不是字符串，则返回。
将 window["navigation_bar_title_text"] 设置为 json["navigation_bar_title_text"]。

navigation_style 成员是一个字符串，用于指定导航栏的样式（即 "default" 或 "custom"）。

该成员MUST 包含以下导航样式值之一：

"default" （默认）: 用于应用默认样式。
"custom": 用于应用自定义导航栏。

要处理 window 的 navigation_style 成员，给定有序映射 json 和有序映射 window：

如果 json["navigation_style"] 不存在，或
如果 json["navigation_style"] 不是字符串，或
如果 json["navigation_style"] 不包含导航样式值之一，则返回。
将 window["navigation_style"] 设置为 json["navigation_style"]。

注：用法

右上角的胶囊按钮不可自定义。

on_reach_bottom_distance 成员是一个 number，用于定义触发页面上拉事件所需的距窗口底部的垂直偏移量。该成员的值是以像素单位表示的非负整数。

默认值：50。

要处理 window 的 on_reach_bottom_distance 成员，给定有序映射 json 和有序映射 window：

如果 json["on_reach_bottom_distance"] 不存在，或
如果 json["on_reach_bottom_distance"] 不是 number，或
如果 json["on_reach_bottom_distance"] 小于 0，则返回。
将 window["on_reach_bottom_distance"] 设置为 json["on_reach_bottom_distance"]。

orientation 成员是一个字符串，用于指定 MiniApp 的屏幕方向配置。

该成员支持方向值："portrait" 和 "landscape"，它们定义在 OrientationLockType [SCREEN-ORIENTATION] 中。

注：用法

该成员等同于应用清单的 orientation。

默认值："portrait"。

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

如果 json["orientation"] 不存在，或
如果 json["orientation"] 不是字符串，或
如果 json["orientation"] 不包含方向值之一，则返回。
将 window["orientation"] 设置为 json["orientation"]。

可本地化成员是一个清单成员，其内容可以适应特定的语言、地理和文化方面。这些可本地化成员共享在清单根部定义的语言标签（lang）和显示方向（dir）。

以下成员是可本地化成员：

name
short_name
description
MiniApp 窗口资源的 navigation_bar_title_text
MiniApp 部件资源的 name

作为 MiniApp 包的重要组成部分， manifest.json 文件通过引用不同文件类型中的MiniApp 包资源来描述 MiniApp 的若干重要方面，例如 pages 目录中的页面脚本和视觉配置文件，以及 common 目录中的图像。详见 [MINIAPP-PACKAGING]。

MiniApp 的正常运行依赖于清单中的适当配置以及MiniApp 包资源的可用性。这种依赖需要在开发阶段和部署阶段都进行检查。

清单数据帮助平台正确配置和处理应用。文档暴露的信息是公开的，因此第三方代理（例如应用市场和仓库）可以使用清单信息来维护应用版本、分类并列出它们。

由于清单是 JSON 文档，并且通常会使用 [UNICODE] 编码，因此 [JSON] 和 [UNICODE-SECURITY] 中描述的安全考虑适用。为了防止开发者在清单中包含自定义/不受约束的数据，实现者可以使用比 JSON Schema 中定义的更严格的模式，对成员名称、类型和值范围施加其实现特定的限制（例如防止内存溢出，或满足平台特定限制）。

MiniApp 资源（包括清单）的完整性作为整个MiniApp 包的一部分，由加密哈希机制保护，如 [MINIAPP-PACKAGING] 中详述。

MiniApp 在目录中组织不同文件资源，这些目录位于一个容器内。清单成员，例如 icons、pages 和 widgets 包含指向托管平台上本地资源的路径。MiniApp 用户代理MUST 保证沙箱化环境，检查这些路径的有效性，以防止对 MiniApp 包之外的非法访问。

开发者可以访问托管平台上的外部 MiniApp 数据资源（即未包含在主包中的资源）（例如指向其他应用和共享存储的深链接）或远程 HTTP 服务器。在前一种情况下，MiniApp 用户代理应实现所有必要机制，以保证平台上的沙箱化环境。

pages 成员定义 MiniApp 组件的路由，包括一组页面映射，其中相对路径指向存储在 MiniApp 容器内的资源。用户代理MUST 忽略外部 URL 或不对应于 MiniApp 容器中有效资源的路径。

清单规定了 MiniApp 运行期间可能请求的功能，这些功能涉及访问传感器以及通过网络连接或通过与设备的直接连接（例如通过 Bluetooth、NFC 或 USB）与其他设备通信。该声明并不意味着能够访问和使用该功能。但是，用户代理MUST 实现机制，以保证服务和 API 的正确使用，并处理每项具体功能中的潜在漏洞。

本规范并不直接处理敏感数据。不过，MiniApp 清单中定义的信息有助于平台配置其隐私策略，使 MiniApp 能够管理其他设备的硬件、软件和数据资源，而这些资源可能影响隐私。

MiniApp 清单并不促使收集、使用或披露个人数据。不过，MiniApp 用户代理MUST 控制对敏感设备服务和功能的访问，这些服务和功能可能会导致指纹识别。用户在权限管理中的行为模式，以及设备的特定约束（即汽车、IoT 和 SmartTV 的 MiniApp），可能允许对用户进行指纹识别。因此，MiniApp 用户代理MUST 控制对设备资源的访问并保持沙箱化环境，保护对敏感资源的访问，例如设备传感器、外部软件和个人数据，并且不披露用户偏好。

通过清单的 req_permissions 成员，开发者声明 MiniApp 访问强大功能的要求。该成员允许平台理解 MiniApp 可能请求的受限资源（name 成员），告知用户潜在后果，并授予（或保持阻止）对这些资源的访问。开发者SHOULD 使用 reason 成员来说明请求这些高级资源的清晰且易于理解的理由。

用户代理MUST 管理用户偏好，包括用户应明确授予以使用强大功能（例如地理定位和设备传感器）的权限。用户代理MUST 实现机制，以便跨会话记住这些用户偏好，使用户能够在任何时候撤销和授予权限。无需跨会话持久化与清单相关的其他信息。

与 Web 应用一样，MiniApp 可以使用 UI 对话框进行安装。在安装过程中，用户代理SHOULD 显示有关应用的清晰信息（即 app_id、 name、 short_name、 icons、 description）。这种透明信息允许最终用户在安装前作出有意识的决定。基于此元数据，用户代理MAY 使用包内的数字签名方法，如 MiniApp 打包中所定义，以验证应用的完整性并最大化用户信任。

用户代理SHOULD 提供一种机制来移除已安装的 MiniApp。RECOMMENDED 在移除时，用户代理还向用户提供撤销与该应用关联的其他持久数据和设置的机会，例如权限和持久存储。

[APPMANIFEST]: Web 应用清单。Marcos Caceres; Kenneth Christiansen; Diego Gonzalez-Zuniga; Daniel Murphy; Christian Liebel。W3C。2024 年 11 月 7 日。W3C 工作草案。URL：https://www.w3.org/TR/appmanifest/
[BCP47]: 用于识别语言的标签。A. Phillips, Ed.; M. Davis, Ed. IETF。2009 年 9 月。最佳当前实践。URL：https://www.rfc-editor.org/rfc/rfc5646
[css-color-4]: CSS 颜色模块第 4 级。Chris Lilley; Tab Atkins Jr.; Lea Verou。W3C。2024 年 2 月 13 日。CRD。URL：https://www.w3.org/TR/css-color-4/
[css-values]: CSS 值和单位模块第 3 级。 Tab Atkins Jr.; Elika Etemad。W3C。2024 年 3 月 22 日。CRD。URL：https://www.w3.org/TR/css-values-3/
[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, Ed. IETF。2017 年 12 月。互联网标准。URL：https://www.rfc-editor.org/rfc/rfc8259
[MANIFEST-APP-INFO]: Web App Manifest - 应用信息。Aaron Gustafson。W3C。2023 年 8 月 21 日。W3C 工作组说明。URL： https://www.w3.org/TR/manifest-app-info/
[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/
[MINIAPP-PACKAGING]: MiniApp 打包。Martin Alvarez-Espinar; Qing An; Tengyuan Zhang; Yongjing ZHANG; Dan Zhou。W3C。2023 年 10 月 23 日。W3C 工作草案。URL：https://www.w3.org/TR/miniapp-packaging/
[permissions]: 权限。Marcos Caceres; Mike Taylor。W3C。2024 年 12 月 20 日。W3C 工作草案。URL：https://www.w3.org/TR/permissions/
[RFC2119]: 用于 RFC 中表示要求级别的关键字。S. Bradner。IETF。1997 年 3 月。最佳当前实践。URL：https://www.rfc-editor.org/rfc/rfc2119
[RFC5234]: 语法规范的增广 BNF： ABNF。D. Crocker, Ed.; P. Overell。IETF。2008 年 1 月。互联网标准。URL：https://www.rfc-editor.org/rfc/rfc5234
[RFC8174]: RFC 2119 关键字中大写与小写的歧义。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/
[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。现行标准。URL：https://url.spec.whatwg.org/
[webidl]: Web IDL 标准。Edgar Chen; Timothy Gu。 WHATWG。现行标准。URL：https://webidl.spec.whatwg.org/

[SEMANTIC-VERSIONING]: 语义化版本。URL：https://semver.org/
[UAAG20]: 用户代理无障碍指南（UAAG） 2.0。James Allan; Greg Lowney; Kimberly Patch; Jeanne F Spellman。W3C。2015 年 12 月 15 日。W3C 工作组说明。URL：https://www.w3.org/TR/UAAG20/

MiniApp 清单

摘要

本文档状态

1. MiniApp 清单

1.1 一致性

1.2 成员概要

1.3 示例

1.4 Web Application Manifest 成员

1.4.1 dir 成员

1.4.2 icons 成员

1.4.3 lang 成员

1.4.4 name 成员

1.4.5 short_name 成员

1.5 应用信息 成员

1.5.1 description 成员

1.6 补充成员

1.6.1 app_id 成员

1.6.2 color_scheme 成员

1.6.3 device_type 成员

1.6.4 pages 成员

1.6.5 platform_version 成员

1.6.6 req_permissions 成员

1.6.7 version 成员

1.6.8 widgets 成员

1.6.9 window 成员

1.7 处理清单

2. MiniApp 平台版本 资源

2.1 min_code 成员

2.2 release_type 成员

2.3 target_code 成员

3. MiniApp 权限资源

3.1 name 成员

3.2 reason 成员

4. MiniApp 版本资源

4.1 code 成员

4.2 name 成员

5. MiniApp 部件资源成员

5.1 name 成员

5.2 path 成员

5.3 min_code 成员

6. MiniApp 窗口资源成员

6.1 auto_design_width 成员

6.2 background_color 成员

6.3 background_text_style 成员

6.4 design_width 成员

6.5 enable_pull_down_refresh 成员

6.6 fullscreen 成员

6.7 navigation_bar_background_color 成员

6.8 navigation_bar_text_style 成员

6.9 navigation_bar_title_text 成员

6.10 navigation_style 成员

6.11 on_reach_bottom_distance 成员

6.12 orientation 成员

7. 可本地化成员

8. 依赖项

9. 无障碍考虑

10. 安全考虑

11. 隐私考虑

A. 一致性

B. JSON Schema

C. 致谢

D. 可扩展性

E. 参考文献

E.1 规范性参考文献

E.2 资料性参考文献

1.4.1 `dir` 成员

1.4.2 `icons` 成员

1.4.3 `lang` 成员

1.4.4 `name` 成员

1.4.5 `short_name` 成员

1.5 应用信息成员

1.5.1 `description` 成员

1.6.1 `app_id` 成员

1.6.2 `color_scheme` 成员

1.6.3 `device_type` 成员

1.6.4 `pages` 成员

1.6.5 `platform_version` 成员

1.6.6 `req_permissions` 成员

1.6.7 `version` 成员

1.6.8 `widgets` 成员

1.6.9 `window` 成员

2. MiniApp 平台版本资源

2.1 `min_code` 成员

2.2 `release_type` 成员

2.3 `target_code` 成员

3.1 `name` 成员

3.2 `reason` 成员

4.1 `code` 成员

4.2 `name` 成员

5.1 `name` 成员

5.2 `path` 成员

5.3 `min_code` 成员

6.1 `auto_design_width` 成员

6.2 `background_color` 成员

6.3 `background_text_style` 成员

6.4 `design_width` 成员

6.5 `enable_pull_down_refresh` 成员

6.6 `fullscreen` 成员

6.7 `navigation_bar_background_color` 成员

6.8 `navigation_bar_text_style` 成员

6.9 `navigation_bar_title_text` 成员

6.10 `navigation_style` 成员

6.11 `on_reach_bottom_distance` 成员

6.12 `orientation` 成员