MiniApp 生命周期

W3C 工作草案

关于本文档的更多详情
此版本：
https://www.w3.org/TR/2023/WD-miniapp-lifecycle-20230529/
最新发布版本：
https://www.w3.org/TR/miniapp-lifecycle/
最新编辑草案：
https://w3c.github.io/miniapp-lifecycle/
历史：
https://www.w3.org/standards/history/miniapp-lifecycle
提交历史
编辑：
Qing An (Alibaba)
Haoyang Xu (Alibaba)
前任编辑：
Xia Xu (Alibaba)
反馈：
GitHub w3c/miniapp-lifecycle （拉取请求， 新建议题， 开放议题）

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

摘要

本规范定义了 MiniApp 生命周期事件，以及管理 MiniApp 和各页面生命周期的过程。实现本规范使用户代理能够管理全局应用生命周期和页面生命周期的生命周期事件。

本文档状态

本节描述了本文档在其发布时的状态。当前 W3C 出版物列表以及本技术报告的最新修订版可在 W3C 技术 报告索引中找到，网址为 https://www.w3.org/TR/。

本文档由 MiniApps 工作 组作为 工作草案使用 推荐标准轨发布。

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

这是一份草案文档，可能随时由其他 文档更新、替换或废弃。除作为进行中的工作外，引用本文档是不合适的。

本文档由一个根据 W3C 专利 政策运作的工作组制作。 W3C 维护一份 任何专利披露的公开列表， 这些披露与该工作组的交付成果有关；该页面还包括 披露专利的说明。任何实际知晓某项专利且认为该专利包含 必要权利要求 的个人，必须根据 W3C 专利政策第 6 节 披露相关信息。

本文档受 2021 年 11 月 2 日 W3C 流程文档管辖。

1. 背景

如 MiniApp 标准化白皮书中所述，在 miniapp 中，视图层与逻辑层相互分离。视图层负责渲染 MiniApp 页面，包括 Web 渲染 和原生渲染，可将其视为混合渲染。逻辑 层使用 JavaScript Worker 实现。逻辑层负责 MiniApp 的事件 处理、API 调用和生命周期管理。

MiniApp 生命周期机制提供了一种方式，通过 MiniApp 全局应用生命周期 事件和 MiniApp 页面生命周期事件来管理 MiniApp 的视图层和逻辑层。掌握 MiniApp 全局应用生命周期状态和 MiniApp 页面生命周期状态来开发 MiniApp，可以带来更好的用户 体验。MiniApp 生命周期包含一组事件，MiniApp 可借助这些事件根据自身状态选择改变其行为。

2. MiniApp 全局应用 生命周期

2.1 MiniApp 全局 应用生命周期事件

本规范定义 MiniApp 全局应用的生命周期，并添加定义以使 MiniApp 能够响应 MiniApp 通常执行的五种重要全局应用生命周期事件：

对于每个 MiniApp，在初始化之后，它将要么在前台运行，要么在后台运行。

当用户通过点击 MiniApp 上的关闭按钮选择关闭 MiniApp，或进入移动 电话的主屏幕时，MiniApp 不会立即被销毁，而是切换为在后台运行。

当用户重新打开同一个 MiniApp 时，MiniApp 将从在后台运行切换为在前台运行。

卸载中标志着 MiniApp 会话的结束，以及从缓存中移除 所有临时资源。MiniApp 用户代理会在 MiniApp 满足条件后执行此移除。当 MiniApp 在后台运行超过特定时长（例如 5 分钟），或在后台占用过多系统资源时，应卸载该 MiniApp。

2.2 MiniApp 全局 应用生命周期状态

本规范形式化定义了五种全局应用生命周期状态，以支持上述全局应用生命周期事件：

launched
MiniApp 初始化的生命周期状态。这意味着 MiniApp 初始化已完成，并且只会触发 一次。通过此事件，开发者可以获取 MiniApp 的信息，例如 URI、来源 信息等。
shown
MiniApp 在前台运行的生命周期状态。它会在 MiniApp 进入 launched 状态后触发，或在 MiniApp 从在后台运行切换为在前台运行后触发。
hidden
MiniApp 在后台运行的生命周期状态。它会在 MiniApp 从在前台运行切换为在后台运行后触发。
error
MiniApp 处于错误状态的生命周期状态。它会在 MiniApp 遇到脚本错误时触发。
unloaded
MiniApp 卸载中的生命周期状态。它会在 MiniApp 被卸载后触发。

与现有 Web 规范（例如 Service Workers）的映射列在 MiniApp Lifecycle Explainer 中。

2.3 GlobalState 枚举

MiniApp 全局应用 生命周期状态通过 GlobalState 枚举反映在 API 中。

WebIDLenum GlobalState {
    "launched", "shown", "hidden", "error", "unloaded"
};

GlobalState 枚举用于表示 全局应用生命周期状态。

“launched”枚举值表示 launched 全局应用生命周期状态。

“shown”枚举值表示 shown 全局应用生命周期状态。

“hidden”枚举值表示 hidden 全局应用生命周期状态。

“error”枚举值表示 error 全局应用生命周期状态。

“unloaded”枚举值表示 unloaded 全局应用生命周期状态。

2.4 MiniApp 全局 应用生命周期接口

WebIDL[Exposed=Window]
interface Global {
 readonly attribute GlobalState globalState;
 readonly attribute InputObject inputObject;
 readonly attribute LifecycleError lifecycleError;
 attribute EventHandler ongloballaunched;
 attribute EventHandler onglobalshown;
 attribute EventHandler onglobalhidden;
 attribute EventHandler onglobalerror;
 attribute EventHandler onglobalunloaded;
};

2.4.1 globalState 属性

获取时，globalState 属性必须 返回 GlobalState。

2.4.2 inputObject 属性

inputObject 包含 MiniApp 的基本信息，例如 MiniApp 的页面路径、MiniApp 的来源信息。

2.4.3 lifecycleError 属性

lifecycleError 包含处于错误状态事件类型的错误指示 信息。

2.4.4 ongloballaunched 事件处理器属性

ongloballaunched 属性是事件 处理器 IDL 属性，用于初始化事件类型。一旦此 事件被触发，globalState 将被设置为 launched。

2.4.5 onglobalshown 事件处理器属性

onglobalshown 属性是事件 处理器 IDL 属性，用于在前台运行事件类型。一旦此事件 被触发，globalState 将被设置为 shown。

2.4.6 onglobalhidden 事件处理器属性

onglobalhidden 属性是事件 处理器 IDL 属性，用于在后台运行事件类型。一旦此事件 被触发，globalState 将被设置为 hidden。

2.4.7 onglobalerror 事件处理器属性

onglobalerror 属性是事件 处理器 IDL 属性，用于处于错误状态事件类型。一旦此事件被 触发，globalState 将被设置为 error。

2.4.8 onglobalunloaded 事件处理器属性

onglobalunloaded 属性是事件 处理器 IDL 属性，用于卸载中事件类型。一旦此事件被 触发，globalState 将被设置为 unloaded。

2.5 InputObject 接口 

WebIDL[Exposed=Window]
interface InputObject {
    readonly attribute DOMString pagePath;
    readonly attribute DOMString referrerInfo;
    readonly attribute DOMString lang;
    readonly attribute TextDirection dir;
};
TextDirection 枚举

WebIDLenum TextDirection {    
    "auto",
    "ltr",    
    "rtl"
};

文本方向值如下，表示人类可读成员的值默认为：

auto
方向性由 Unicode 双向算法 [UAX9] 算法确定。
ltr
从左到右的文本。
rtl
从右到左的文本。

2.5.1 pagePath 属性

获取时，pagePath 属性必须 返回当前 MiniApp 的页面路径。

注

2.5.2 referrerInfo 属性

referrerInfo 属性包含 MiniApp 的来源信息，包括 MiniApp ID，以及包括人类可读值在内的可选额外数据。

2.5.3 lang 属性

lang 属性的值必须是 [BCP47] 定义的格式良好的语言标签。

2.5.4 dir 属性

dir 属性指定 referrerInfo 属性值的基本方向，如果 该属性包含人类可读值。

2.6 LifecycleError 接口 

WebIDL[Exposed=Window]
interface LifecycleError {
    readonly attribute DOMString errorDescription;
    readonly attribute DOMString lang;
    readonly attribute TextDirection dir;
};

2.6.1 errorDescription 属性

errorDescription 属性是对error 全局应用生命周期状态的 开发者友好型文本描述。

2.6.2 lang 属性

lang 属性的值必须是 [BCP47] 定义的格式良好的语言标签。

2.6.3 dir 属性

dir 属性指定 errorDescription 属性值的基本方向。

3. MiniApp 页面生命周期

3.1 MiniApp 页面生命周期事件

本规范定义 MiniApp 页面的生命周期，并添加定义以使 MiniApp 能够 响应 MiniApp 通常执行的五种重要页面生命周期事件：

注

  1. 当用户首次打开 MiniApp 时，MiniApp 初始化开始。视图层和逻辑层 将同时开始初始化。

  2. 一旦逻辑层初始化完成，它会创建一个 MiniApp 实例。同时，一旦视图层 初始化完成，它会开始 MiniApp 页面 加载，以在视图层和 逻辑层之间建立通信通道。

  3. 通信通道建立后，逻辑层 向视图层发送初始数据，以开始首次渲染。

  4. 如果视图层基于来自逻辑层输入的初始数据完成页面 UI 更新，则首次渲染被认为已完成，随后视图层通知逻辑层， 以触发 MiniApp 页面首次渲染就绪。

  5. 之后，用户可以与 MiniApp 交互。视图层可 被触发以将用户事件传递给逻辑层 进行进一步处理，随后逻辑层将结果数据返回给视图层以重新渲染。

  6. 如果用户离开当前 MiniApp 页面（例如，通过导航到另一个 MiniApp 页面），MiniApp 页面在后台运行会被触发。 如果 MiniApp 页面被重新打开，MiniApp 页面在前台运行会被触发。

  7. 如果用户关闭当前 MiniApp 页面，MiniApp 页面 卸载中会被触发。

3.2 MiniApp 页面生命周期状态

本规范形式化定义了五种 MiniApp 页面 生命周期状态，以支持上述页面 生命周期事件：

页面已加载
MiniApp 页面加载的生命周期状态。这意味着 MiniApp 页面加载已完成。此时，逻辑层已获得初始化数据，开发者 可以获取当前 MiniApp 页面的路径以及该路径的查询。
页面就绪
MiniApp 页面首次渲染就绪的生命周期状态。它 会在 MiniApp 页面首次渲染完成后触发。此 时可以配置页面 UI。
页面已显示
MiniApp 页面在前台运行的生命周期状态。它会在 页面从页面在后台运行切换为页面在前台运行后触发。此时， 开发者可以更新数据并刷新页面。
页面已隐藏
MiniApp 页面在后台运行的生命周期状态。它会在 MiniApp 页面从页面在前台运行切换到页面在后台运行时触发。
页面已卸载
MiniApp 页面卸载中的生命周期状态。它会在 MiniApp 页面关闭后触发。

与现有 Web 规范（例如 Page Visibility）的映射列在 MiniApp Lifecycle Explainer 中。

3.3 PageState 枚举

MiniApp 页面生命周期状态通过 PageState 枚举反映在 API 中。 

WebIDLenum PageState {
    "loaded", "ready", "shown", "hidden", "unloaded"
};

PageState 枚举用于 表示 MiniApp 页面生命周期状态。

“loaded”枚举值表示页面已加载 页面生命周期状态。

“ready”枚举值表示页面就绪 页面生命周期状态。

“shown”枚举值表示页面已显示 页面生命周期状态。

“hidden”枚举值表示页面已隐藏 页面生命周期状态。

“unloaded”枚举值表示页面已卸载 页面生命周期状态。

3.4 MiniApp 页面生命周期 接口

WebIDL[Exposed=Window]
interface Page {
    readonly attribute PageState pageState;
    readonly attribute PageInputObject pageInputObject;
    attribute EventHandler onpageloaded;
    attribute EventHandler onpageready;
    attribute EventHandler onpageshown;
    attribute EventHandler onpagehidden;
    attribute EventHandler onpageunloaded;
};

3.4.1 pageState 属性

获取时，pageState 属性必须 返回 PageState。

3.4.2 pageInputObject 属性

pageInputObject 包含用于加载 MiniApp 页面的pageInputQuery。

3.4.3 onpageloaded 事件处理器属性

onpageloaded 属性是事件 处理器 IDL 属性，用于页面加载事件类型。一旦此事件 被触发，pageState 将被设置为页面已加载。

3.4.4 onpageready 事件处理器属性

onpageready 属性是事件 处理器 IDL 属性，用于页面首次渲染就绪事件类型。一旦此 事件被触发，pageState 将被设置为页面就绪。

3.4.5 onpageshown 事件处理器属性

onpageshown 属性是事件 处理器 IDL 属性，用于页面在前台运行事件类型。一旦 此事件被触发，pageState 将被设置为页面已显示。

3.4.6 onpagehidden 事件处理器属性

onpagehidden 属性是事件 处理器 IDL 属性，用于页面在后台运行事件类型。一旦 此事件被触发，pageState 将被设置为页面已隐藏。

3.4.7 onpageunloaded 事件处理器属性

onpageunloaded 属性是事件 处理器 IDL 属性，用于页面卸载中事件类型。一旦此 事件被触发，pageState 将被设置为页面 已卸载。

3.5 PageInputObject 接口 

WebIDL[Exposed=Window]
interface PageInputObject {
    readonly attribute DOMString pageInputQuery;
};

3.5.1 pageInputQuery 属性

pageInputQuery 属性包含 MiniApp 页面的输入查询。

注

4. 使用示例

本节是非规范性的。

处理 MiniApp 全局生命周期的示例：

示例 1 
const doGlobalLaunched = (inputObject) => {
    console.log(inputObject.pagePath);
};

global.addEventListener('globallaunched', doGlobalLaunched);

处理 MiniApp 页面生命周期的示例：

示例 2 
const doPageLoaded = (pageInputObject) => {
    console.log(pageInputObject.pageInputQuery);
};

page.addEventListener('pageloaded', doPageLoaded);

5. 安全注意事项

本节是非规范性的。

MiniApp 在前台运行和在后台运行事件使开发者能够知道 MiniApp 何时可见。通过使用页面在前台运行事件， 开发者可以选择在 MiniApp 页面切换为页面在前台运行之前处理并隐藏敏感数据； 页面已卸载 事件提供页面正在 卸载的通知。

6. 隐私注意事项

本节是非规范性的。

MiniApp 全局应用生命周期接口 Global 引入了 inputObject，它涉及对 MiniApp 的输入查询、当前 MiniApp 的页面路径以及来源信息的处理。MiniApp 页面 生命周期接口 Page 引入了 pageInputObject，它涉及对 MiniApp 页面的输入查询的处理。为了保护用户免受任何潜在的未经批准的跟踪 威胁，不建议在本地存储这些值。如果存储了这些值，则当用户打算清除它们时， 应清除这些存储。

如果 MiniApp 的输入查询或 MiniApp 页面的输入查询包含隐私敏感 信息（例如用户个人数据），则隐私敏感信息不得以明文形式存在。

7. 无障碍注意事项

本节是非规范性的。

MiniApp 生命周期涉及（有时）响应用户交互，例如，GlobalState 指示 MiniApp 是shown 还是hidden；PageState 指示 MiniApp 页面是页面已显示还是页面已隐藏。用户 代理应与 MiniApp 生命周期状态的无障碍服务进行充分通信，例如， 获取时，GlobalState 和 PageState 应分别向无障碍服务返回 MiniApp 全局应用生命周期状态和 MiniApp 页面生命周期状态。

A. 参考文献

A.1 资料性参考文献

[BCP47]
用于标识语言的标签。A. Phillips 编；M. Davis 编。IETF。2009 年 9 月。最佳现行实践。URL：https://www.rfc-editor.org/rfc/rfc5646
[html]
HTML 标准。Anne van Kesteren； Domenic Denicola；Ian Hickson；Philip Jägenstedt；Simon Pieters。WHATWG。现行标准。URL：https://html.spec.whatwg.org/multipage/
[UAX9]
Unicode 双向 算法。Mark Davis；Ken Whistler。Unicode Consortium。2022 年 8 月 16 日。Unicode 标准附录 #9。URL：https://www.unicode.org/reports/tr9/tr9-46.html
[webidl]
Web IDL 标准。Edgar Chen；Timothy Gu。 WHATWG。现行标准。URL：https://webidl.spec.whatwg.org/