MiniApp 打包

MiniApp 根目录是 MiniApp 包文件系统的基础目录。

根目录在 MiniApp 包中保存 若干保留文件，其中包括全局数据以及关于 MiniApp 生命周期管理的信息，包括：

manifest.json

MiniApp 清单是一个 JSON 文档，负责 MiniApp 的全局 配置。清单文件包含一组必需和可选 属性，用于指明 MiniApp 的设置，包括页面的路由和路径以及 MiniApp 的窗口配置（例如，导航栏样式、背景图像、 背景颜色、页面标题等），依照 MiniApp Manifest 规范 [MINIAPP-MANIFEST]。

app.css

此文件是应用的主样式表，开发者在其中定义 MiniApp 内页面的通用样式和 外观方面。它MAY 为空。

app.js

此脚本文档具有 MiniApp 的基本服务逻辑，并包含 MiniApp 生命周期 [MINIAPP-LIFECYCLE] 的基本 配置和控制，包括对启动、显示和隐藏 MiniApp 的 事件管理。

pages 目录包含一组用于显示和用户交互的文件， 属于 MiniApp 页面。

MiniApp 页面由一组资源定义，其文件由唯一文件名 （例如 intro）和特定扩展名标识，该扩展名定义资源类型，例如应用的业务逻辑 （例如 intro.js）、结构和内容（例如 intro.html）以及 作用域样式表（例如 intro.css）。

开发者MAY 根据需要包含其他类型的资源。 此外，与页面相关的文件（以相同文件名标识）MAY 组织在每个页面的特定子目录中，或 直接存储在 pages 目录下。

/
    |___manifest.json
    |___app.js
    |___app.css
    |___pages/
            |___detail.js
            |___detail.html
            |___detail.css
            |___list.js
            |___list.html
            |___list.css

/
    |___manifest.json
    |___app.js
    |___app.css
    |___pages/
            |___detail/
                    |___detail.js
                    |___detail.html
                    |___detail.css
            |___list
                    |___list.js
                    |___list.html
                    |___list.css

• .html 资源定义 MiniApp 页面的结构和内容。基于 HTML，该类型文件的语法、 结构和其他要求在 HTML 资源一节中定义。
• .css 资源定义 MiniApp 页面的样式表。该类型资源的语法、 结构和其他要求在 CSS 资源一节中定义。
• .js 资源包含 MiniApp 页面的业务逻辑，包括应用运行所需的函数、数据和其他配置 方面。此类资源负责 MiniApp 页面的设置和生命周期管理，如 MiniApp Lifecycle 规范 [MINIAPP-LIFECYCLE] 中所定义。这些类型文件的语法和格式在 脚本资源一节中定义。

可选的 common 目录包含资源，例如 可从 MiniApp 中的页面访问的组件、多媒体资源、文档和库。 此目录的内部结构是灵活的，因此这些公共资源MAY 可根据需要 组织在自定义子目录中，并使用不同的命名约定。

可选的 i18n 目录是 根目录中的一个 子目录，其中包含 本地化资源，属于 MiniApp 包。

i18n 目录包含多语言本地化资源，用于支持 MiniApp 内容的 国际化。此目录中每个 .json 文档的文件名遵循 [BCP47] 中定义的 Language-Tag 表示法，并表示该特定语言的具体 配置。

i18n 目录MAY 包含与 MiniApp 支持的语言或区域设置一样多的本地化资源。这些文件的格式在 本地化资源一节中定义。

MiniApp 包中的任何文件名和路径名 MUST 遵守以下限制，以适应操作系统的潜在 限制，并促进与大多数 平台和文件系统的互操作性，如 面向规范开发者的国际化最佳实践所指定。

• 文件名和文件路径区分大小写。
• 文件名和文件路径 MUST 使用 UTF-8 [Unicode] 编码。
• 文件名SHOULD NOT 超过 255 字节长度。
• 路径名SHOULD NOT 超过 65535 字节长度。
• 文件名和路径名 MUST NOT 使用以下 [Unicode] 码点：
  • " [U+0022 QUOTATION MARK]
  • * [U+002A ASTERISK]
  • / [U+002F SOLIDUS]
  • : [U+003A COLON]
  • < [U+003C LESS-THAN SIGN]
  • > [U+003E GREATER-THAN SIGN]
  • \ [U+005C REVERSE SOLIDUS]
  • | [U+007C VERTICAL LINE]
  • U+007F DEL
  • U+E0001 LANGUAGE TAG
  • U+E007F CANCEL TAG
  • 以下范围内的码点：
    • C0 控制符 [U+0000...U+001F]
    • C1 控制符 [U+0080...U+009F]
    • 专用区 [U+E000...U+F8FF]
    • 特殊区 [U+FFF0...U+FFFF]
    • 补充专用区 [U+F0000...U+FFFFF]
    • 补充专用区 [U+100000...U+10FFFF]
  • . [U+002E FULL STOP]
  • 所有 Unicode 非字符码点，具体包括：
    • 基本多文种平面中的 32 个连续字符（U+FDD0 … U+FDEF）
    • 基本多文种平面的最后两个码点（U+FFFE 和 U+FFFF）
    • 补充平面末尾的最后两个码点（U+1FFFE、 U+1FFFF … U+EFFFE、U+EFFFF）

同一目录中的所有文件名 MUST 在经过 Unicode 规范等价归一化 [UAX15]，然后经过完全大小写 折叠 [Unicode] 后保持唯一。（更多信息请参阅 Unicode 规范大小写 折叠归一化步骤 [CHARMOD-NORM]。）

HTML 资源是包含标记和信息的文档，用于定义 MiniApp 页面及其用户界面，包括结构、 视觉组件和交互元素。

HTML 资源MUST 满足 以下所有条件：

语法和内容

HTML 资源MUST 使用 [HTML] 中定义的 HTML 语法。

文件名

HTML 资源SHOULD 具有 唯一文件名，用于标识单个 MiniApp 页面，并在存在时与页面的 对应 CSS 资源和 脚本 资源匹配。

文件扩展名

HTML 资源SHOULD 使用 文件扩展名 .html。

CSS 资源是描述 MiniApp 页面渲染和外观的样式表。CSS 资源可以是全局的， 影响 MiniApp 中的所有页面（即根 目录中的 app.css），也可以具有局部作用域，只影响 MiniApp 中的特定 页面。

本规范支持 [CSS-SNAPSHOT] 中定义的 CSS 模块。

CSS 资源 MUST 满足以下所有条件：

语法和内容

CSS 资源MUST 遵循 [CSS-SNAPSHOT] 中所描述的 CSS 语法和定义。

文件名

影响 MiniApp 中所有页面的全局 CSS 资源MUST 命名为 app.css，并存储在根 目录中。

与页面关联的局部 CSS 资源SHOULD 具有唯一文件名， 用于标识 MiniApp 页面，并在存在时与对应的 HTML 资源和 脚本 资源匹配。

文件扩展名

CSS 资源文件名SHOULD 使用文件扩展名 .css。

脚本资源是包含脚本元素和 数据的文档，用于控制应用的业务逻辑和功能，增加交互性并 管理 MiniApp 的生命周期。存在一个全局脚本 资源（即根 目录中的 app.js），其中包含适用于 MiniApp 所有 页面的数据和函数，并包含用于控制 应用生命周期的特定逻辑。每个 MiniApp 页面MAY 具有 关联的特定脚本资源，其作用域限于具体 页面。

脚本资源 MUST 满足以下所有条件：

语法和内容

脚本资源MUST 符合 ECMAScript 规范 [ECMA-262] 的要求。

全局脚本资源MUST 命名为 app.js，并存储在根 目录中。

与页面关联的局部 脚本资源SHOULD 具有唯一文件名， 用于标识 MiniApp 页面，并在存在时与对应的 HTML 资源和 CSS 资源匹配。

文件扩展名

脚本资源文件名SHOULD 使用文件扩展名 .js。

MiniApp 本地化资源是 MiniApp 包中的一种文档，作为 MiniApp 国际化机制的一部分，其中包含本地化内容。

多语言 MiniApp MAY 具有多个本地化资源，这些资源将在本地化过程中由用户代理使用，以根据系统区域设置或 用户的语言偏好渲染内容。这些资源包含带有键值对的 JSON 对象， 其中键值对包含可本地化术语或表达式的唯一标识符（键）以及 具体语言中的表示形式（值）。

{
        "title": "Cool MiniApp",
        "about": "About this MiniApp",
        "intro-page": {
            "title" : "Introduction",
            "main" : "This is the body of the page"
        }
    }

本地化资源MUST 满足以下所有条件：

文件扩展名

本地化资源文件名SHOULD 使用文件扩展名 .json。

格式

本地化资源MUST 是有效的 JSON 文档 [JSON]。

结构

本地化资源MUST 由键值对组成。每个键表示每个可本地化字符串 （值）的唯一标识符。

MiniApp ZIP 容器MAY 包含一个 签名块，其中包括一个或多个签名。 签名方案和密码机制取决于用户代理的具体实现。

签名方案由 魔数部分标识，该部分包含在 MiniApp ZIP 容器中，是一个 16 字节序列，位于 ZIP 包 中央目录的紧前方。

要处理数字签名，给定 MiniApp ZIP 容器 miniapp_zip_file，执行以下步骤：

1. 令 magic_numbers 为字节序列。
2. 令 eocd_pointer 为在 miniapp_zip_file 中定位字节序列 0x06054b50（按小端序读取）的结果，作为字节序列，该字节序列标记 中央目录的结束 [ZIP]。
3. 将 eocd_pointer 设置为 eocd_pointer + 0x00000010。
4. 令 cd_pointer 为读取 eocd_pointer 处 4 字节序列的结果。
5. 令 magic_numbers_pointer 为 eocd_pointer - 0x00000010。
6. 将 magic_numbers 设置为 magic_numbers_pointer 处的 16 字节块。
7. 使用 magic_numbers 和 miniapp_zip_file 处理数字签名。

用户代理MUST 验证 MiniApp 与其兼容，并且能够在其 平台中正常运行。此验证使用 MiniApp 清单中指定的元数据执行，包括平台支持版本，以及 检查执行中所需的页面和资源。

要验证平台兼容性，给定 MiniApp 包 miniapp_package 和 有序映射 manifest，执行以下步骤：

1. 将 platform_required 设置为 manifest["platform_version"]。
2. 如果 platform_required 与用户代理配置不兼容，则返回失败。
3. 对 manifest["pages"] 这个列表中的每个 page执行：
   1. 如果 page 不存在于 miniapp_package 中，则返回失败。
4. 如果 manifest["widgets"] 存在，则：
   对 manifest["widgets"] 这个列表中的每个 widget_path执行：
   1. 如果 widget_path 不存在于 miniapp_package 中，则返回失败。

默认情况下，用户代理MUST 在 MiniApp 启动时， 将 起始页作为入口点加载，该起始页在 MiniApp 清单中指明。若 MiniApp URI 中指定了有效的 页面，则默认的 起始页MUST 被覆盖，如以下 算法所规定。

要确定起始页，给定 MiniApp 包 miniapp_package、URL miniapp_uri 和 有序映射 manifest，执行以下步骤。它们返回一个 URL。

1. 令 start_page 为传入 miniapp_uri 并从 URI 提取起始页的结果。
2. 如果 start_page 未设置，或者 start_page 等于 null，或者 start_page 不存在于 miniapp_package 中，则：
   将 start_page 设置为传入 manifest 并从 清单提取起始页的结果。
3. 返回 start_page

要提取区域设置，给定 有序映射 manifest，执行以下步骤。它们返回一个 字符串。

1. 令 字符串 locale 为用户代理的 默认区域设置。
2. 如果 manifest["lang"] 存在，并且如果 manifest["lang"] 受用户代理支持，则：
   将 locale 设置为 manifest["lang"]。
3. 返回 locale。