MiniApp Widget Requirements

The MiniApp Widget runs in a host environment that is called the user agent. The MiniApp Widget user agent is largely the same as the MiniApp user agent, and shall meet the following requirements:

MiniApp Widget 需要在一个宿主环境中运行，这个环境被称为 user agent。MiniApp Widget 的 user agent 在较大程度下与 MiniApp 的 user agent 保持一致，应该满足如下一些需求：

1. The MiniApp Widget user agent should be able to parse the MiniApp URI and obtain the MiniApp package according to the process described in the MiniApp Addressing specification, and it shall conform to the requirements in the Dereferencing section of the MiniApp Addressing specification.

   MiniApp Widget 的 user agent 应当能根据 MiniApp Addressing 规范中描述的过程解析 MiniApp URI 并获取 MiniApp 包，该过程应当符合 MiniApp Addressing 规范中解引用一节描述。

2. The user agent should be able to parse the structure of the MiniApp package as described in the MiniApp Packaging specification.

   User agent 应当能按照 MiniApp Packaging 规范的描述解析 MiniApp 包结构。

3. The user agent should be able to parse the manifest file as described in the MiniApp Manifest specification, so as to load and run the MiniApp Widget. Some specific requirements related to the Widget are described in the Manifest File section of this document.

   User agent 应当能按照 MiniApp Manifest 规范的描述解析 manifest 文件，以加载运行 MiniApp Widget。在本文档的 Manifest 文件一节中描述了一些与 Widget 相关的特定需求。

4. The form of resources that the MiniApp Widget accesses in the package is consistent with a MiniApp page. Therefore, the user agent should be able to access the resource files in the MiniApp package in the same way.

   MiniApp Widget 访问到包中的资源形式与 MiniApp 页面保持一致。因此，user agent 应能以同样的方式访问 MiniApp 包中的资源文件。

5. When running the widget, the user agent should be able to provide necessary interface support. Some specific requirements related to the Widget are described in the MiniApp API section of this document.

   在运行过程中，user agent 应能提供必要的接口支持，在本文档的 MiniApp API 一节中描述与 Widget 相关的特定需求。

Specifically, in the MiniApp Widget scenario, as the Widget itself does not occupy the complete screen space, the user agent will have some specific requirements:

特定地，在 MiniApp Widget 场景下，由于 Widget 本身并不占据完整的屏幕空间，user agent 也会有一些特定的需求：

1. The user agent can integrate the MiniApp Widget with its own interface, to achieve a better integration experience.

   User agent 可以将 MiniApp Widget 与自身界面结合在一起显示，以达到更好的融合体验。

2. To better integrate the MiniApp Widget and the user agent interface, the user agent should provide its style information to the MiniApp Widget, so as to better support the requirements such as dark mode.

   为了更好地将 MiniApp Widget 与 user agent 的界面融合，user agent 应当为 MiniApp Widget 提供自身样式的信息，以更好的支持诸如深色模式等需求。

3. The user agent should be able to load and display multiple MiniApp Widgets concurrently, for example, display a relevant air ticket Widget and taxi Widget simultaneously on Intelligent Assistant.

   User agent 可以同时加载并显示多个 MiniApp Widget，例如在智能助理中同时显示相关的机票 Widget 和打车 Widget。

4. Some behaviors of the User agent may cause the Widget to show or hide, and in such a case, the lifecycle callback of the Widget should be triggered correctly.

   User agent 的一些行为可能会导致 Widget 的展现和消失，此时应该正确触发 Widget 的生命周期回调。

The MiniApp Widget URI should be consistent with the MiniApp Addressing specification, to ensure that:

MiniApp Widget 的 URI 规范应该与 MiniApp Addressing 规范保持一致，以确保：

1. The user agent can obtain the MiniApp package containing the MiniApp Widget using the same mechanism.

   User agent 能以相同的机制获取包含 MiniApp Widget 的 MiniApp 包。

2. The user agent can locate and load the MiniApp Widget using the same mechanism as the MiniApp Page.

   User agent 能以与 MiniApp 页面相同的机制定位并加载 MiniApp Widget。

Like MiniApp, the MiniApp Widget is also distributed in the form of a package. After the user agent acquires and verifies a MiniApp package, it will acquire the Widget information contained in the package, and load and display it correctly. The form and specification of the package should be consistent with the MiniApp Packaging specification, including but not limited to file organization, compression format, filename extension, digital signature, etc. The user agent should use the same form to verify and install the MiniApp Widget package.

与 MiniApp 保持一致，MiniApp Widget 同样以包的形式分发，User agent 获取到 MiniApp 包并进行校验后，获取包中包含的Widget信息，并正确地加载和显示。包的形式和规范应当与 MiniApp Packaging 规范保持一致。包括不限于文件组织形式、压缩格式、文件后缀名、数字签名等。User agent 会以同样的形式对 MiniApp Widget 的包进行校验、安装等过程。

In the MiniApp Widget scenario, the specific requirements are as follows:

在 MiniApp Widget 场景下，特定的需求：

1. A MiniApp package may contain both the MiniApp Pages and Widgets. In some cases, MiniApp expects to display a Widget on the user agent, however, when the user clicks the content on the Widget, a MiniApp Page is provided as the landing page with richer content.

   一个 MiniApp 包中应该可以同时包含 MiniApp 页面和 Widget。在某些情况下，MiniApp 希望能在 user agent 上 显示一个 Widget，并在用户点击Widget上的内容时，提供 MiniApp 页面作为承载更丰富内容的落地页。

2. A MiniApp package may contain only Widgets without Pages. Some MiniApp providers just want to provide simplest functions on the Widget to meet the users’ specific needs.

   一个 MiniApp 包中应该可以只包含 Widget，不包含 Page。某些 MiniApp 的提供方只希望在 Widget 上提供最简单的功能，以满足用户的特定需求。

The configuration file must be included in the MiniApp Widget package. Developers can set the basic information, style, and routing of the Widget through the Manifest file. The format of the Widget Manifest file should be consistent with that of the MiniApp Manifest file. Specifically, there will be some changes in the Widget environment.

MiniApp Widget 包中需要包含配置文件，开发者可通过 Manifest 文件设置 Widget 的基本信息、样式和路由等信息。Widget 的 Manifest 文件应当与 MiniApp Manifest 文件的格式保持一致。特定地，在 Widget 环境中，会有一些变化：

The Manifest file should include a widgets property (similar to the pages property), used for designating relevant information and configuration of widget contained in MiniApp, and should include the following:

Manifest 文件中需要包含 widgets 字段（类似于 pages 字段），用于指定 MiniApp 中包含的 widget 的相关信息和配置，应当包含以下：

1. Name of the MiniApp Widget

   MiniApp Widget 的名字

2. File path of the MiniApp Widget – used for locating the file where the MiniApp Widget is located

   MiniApp Widget 的文件路径，用于定位 MiniApp Widget 所在的文件

3. Minimum platform version. Different minimum platform version declarations may exist as there may be differences between the Widget API and MiniApp API. As the Widget is loaded independently, the minimum platform version declaration can be directed for a single widget

   最小平台版本，因为 Widget 涉及的 API 与 MiniApp API 有一定差别，可能会存在不同的最小平台版本声明。且因为 Widget 是独立加载的，最小平台版本声明可以针对单个 widget 声明

Due to some features of the widget, some configuration information in the Manifest file will not take effect in widgets. For example, the fullScreen property of window describes whether the MiniApp Page is displayed in fullscreen, however, as the widget has no fullscreen mode, this property will be ignored.

因为 widget 的一些特点，Manifest 文件中的一些配置信息，在 Widget 中不会生效。例如 window 的 fullScreen 属性，描述了 MiniApp 页面是否以全屏形式显示，由于 widget 并没有对应的形式，因此会忽略这个信息。

The lifecycle of the MiniApp Widget should be consistent with the MiniApp Lifecyle, wherein the trigger timing of onShow/onHide lifecycle callback will have some changes. As the Widget may also show or hide when the user agent slides the Widget off the screen or conducts a collapse action, the onShow/onHide of the Widget should also be triggered correctly at this time. Due to the form of the Widget and the form it runs in the user agent, the Widget also needs to support some new lifecycle API:

MiniApp Widget 的生命周期应该与 MiniApp 页面的生命周期保持一致，其中 onShow/onHide 生命周期回调的触发时机会有一些变化。因为 Widget 的出现和消失也可能发生在 user agent 将 Widget 滑出屏幕或者进行折叠操作时，此时 Widget 的 onShow/onHide 也应该被正确的触发。因为 Widget 的形态和在宿主环境中运行的形式，Widget 也需要支持一些新的生命周期 API：

1. In case of changes in system language, window size, color scheme etc., the Widget needs to receive the changed information to change the interface.

   当系统语言/窗口大小/Darkmode 等发生变化时，Widget 需要接收到变化后的信息，以改变界面。

2. The user agent may update the status of the Widget interface in the form of incoming data; Widget reinitialization should not be triggered at this time.

   宿主环境可能会通过传入数据的形式更新 Widget 界面的状态，此时不应该触发 Widget 的重新初始化。

The API that developers can use in the MiniApp Widget should be consistent with the [MiniApp API specification] as much as possible, however, some APIs need to be adjusted for specific MiniApp Widget scenarios. The content in this section should be adjusted based on the [MiniApp API specification].

开发者在 MiniApp Widget 中可以使用的API 应当与 [MiniApp API 规范] 尽量保持一致，但有一些 API 需要针对 MiniApp Widget 场景进行调整，本节内容应根据 [MiniApp API 规范] 内容调整。

Some APIs that could be used on MiniApp Page need to be adjusted in Widget scenario, such as:

在 Widget 场景下，一些原先在 MiniApp 页面上可以使用的 API 需要调整，例如：

1. API with background persistence or API passively triggered, e.g. background location and push. As the Widget runs in the user agent, it does not exist as an independent unit in terms of user perception, and these APIs are prone to cause user confusion between calling the Widget and the user agent.

   具备后台持续能力或者被动触发的 API，例如持续定位和推送，因为 Widget 在 user agent 环境中运行，在用户认知上并不作为独立运行的单元存在，这些 API 易造成用户将 Widget 的调用与 user agent 混淆。

2. API that can capture user attention and cause misunderstanding by the user, e.g. launching the camera interface. As multiple Widgets may be displayed on the same interface, if these Widgets directly call the API to open the interface concurrently, it will cause the user to misunderstand.

   会抢占用户注意力，造成用户错误认知的 API，例如打开拍照界面等，由于多个 Widget 可能会同时显示在一个界面上，如果多个 Widget 均直接调用打开界面的 API，会造成用户理解上的错误。

The User agent should provide some new APIs suitable for the Widget, for example:

User agent 会提供一些适用于 Widget 的新 API，例如：

1. API to obtain the current window size (viewport width)

   获取当前窗口大小的 API（视口宽度）

2. API to obtain the current user agent information, to enable the Widget to adapt to the specific user agent

   获取当前 user agent 信息的 API，以支持 Widget 针对特定的 user agent 进行适配

3. Pre-authorized APIs in a batch. As there may be multiple MiniApp Widgets on the user agent concurrently, multiple APIs that dynamically obtain permission will cause user confusion. Thus, the user agent should provide pre-authorized APIs in a batch.

   批量预授权的 API，由于 user agent 上可能同时存在多个 MiniApp Widget，出现多个动态获取权限的 API 会对用户造成困扰，user agent 应提供批量预授权的 API

4. Extended APIs for specific user agents, e.g., request to obtain the latest version of the Widget

   特定宿主环境的拓展 API，例如请求获取到最新版本的 Widget

The components that developers can use in the Widget should be consistent with the [MiniApp component specification] as much as possible, however, some components need to be adjusted for specific Widget scenarios. The content in this section should be adjusted based on the [MiniApp component specification].

开发者在 Widget 中可以使用的组件应当与 [MiniApp 组件规范] 尽量保持一致，但有一些组件需要针对 Widget 场景进行调整，本节内容应根据 [MiniApp 组件规范] 内容调整。

The behavior of some components may conflict with the behavior of the user agent, for example:

一些组件的行为可能与 user agent 的行为发生冲突，例如：

1. If some Widgets include a relatively long scrollable list, it may conflict with the sliding up and down operation of the user agent

   某些 Widget 中如果包含较长的滚动列表，可能与 user agent 的上下滑动操作发生冲突

Under certain circumstances, the Widget needs to maintain certain data communication with MiniApp, for example:

在一定情况下，Widget 需要与 MiniApp 保持一定的数据通信，例如：

1. If already logged in MiniApp, the same login status is maintained in the Widget.

   在 MiniApp 中已经登录，在 Widget 保持同一登录状态

2. If a MiniApp is playing music, the Widget gets the playing status to show playback control.

   MiniApp 播放音乐，Widget 获取播放状态以显示播放控件

Therefore, the specifications should include a description of data communication between the MiniApp Widget and MiniApp.

因此规范中应补充 MiniApp Widget 与 MiniApp 之间数据通信的描述。