MiniApp Manifest

1.1 Requirements

The following members MUST be set in the MiniAppManifest.

The following members MUST be set in the MiniAppManifest.

• appID
• name
• icons
• versionName
• versionCode
• minPlatformVersion
• pages

The following members MUST be set in an ImageResource.

The following members MUST be set in an ImageResource.

• src
• sizes

The following members MUST be set in a MiniAppWidgetResource.

The following members MUST be set in a MiniAppWidgetResource.

• name
• path

The following member MUST be set in a MiniAppPermissionResource.

The following member MUST be set in a MiniAppPermissionResource.

• name

The priority of all other members is OPTIONAL, but MAY be modified by implementations of the manifest format in the case of specific MiniApp extensions.

1.2 Summary of Members

The following table is a summary of each member:

下表是manifest中每个属性的总结：

2.1 Members inherited from the WebAppManifest dictionary

2.2 Members supplemented from the Application Information

The members listed in this section are defined in Web App Manifest - Application Information [manifest-app-info].

2.3 Supplementary manifest members

appIDrule = ALPHA 1*( ALPHA / DIGIT / "_" / "." )

3.1 navigationBarBackgroundColor member

The MiniAppWindowResource.navigationBarBackgroundColor member specifies the color of the navigation bar background. 导航栏背景颜色

3.2 navigationBarTextStyle member

The MiniAppWindowResource.navigationBarTextStyle member specifies the text color of the navigation bar title.

3.3 navigationBarTitleText member

The MiniAppWindowResource.navigationBarTitleText member specifies the title text of the navigation bar 导航栏标题文字内容

3.4 navigationStyle member

The MiniAppWindowResource.navigationStyle member specifies the style of the navigation bar: default (default style) and custom (customized navigation bar). Note: The capsule button at the right corner is not customizable. 导航栏样式：default（默认样式）和custom（自定义导航栏）。注意：右上角胶囊按钮不可自定义。

3.5 backgroundColor member

The MiniAppWindowResource.backgroundColor member specifies the background color of the window. This member is equivalent to background_color. 窗口的背景颜色

3.6 backgroundTextStyle member

The MiniAppWindowResource.backgroundTextStyle member specifies the background text style. 背景文字样式，。

3.7 enablePullDownRefresh member

The MiniAppWindowResource.enablePullDownRefresh member specifies if the pull-to-refresh event is enabled. 是否开启下拉刷新

3.8 onReachBottomDistance member

The MiniAppWindowResource.onReachBottomDistance member specifies the distance from the bottom when page pull-up bottom event is triggered. The value is a non-negative integer and the unit is in pixel unit. 页面上拉触底事件触发时距页面底部距离。取值应为非负整数，单位为 px。

3.9 orientation member

The MiniAppWindowResource.orientation member specifies the screen orientation settings to which a screen can be locked. The two supported values are portrait and landscape, defined in OrientationLockType [screen-orientation]. This member is equivalent to orientation. 屏幕方向设置

3.10 fullscreen member

The MiniAppWindowResource.fullscreen member indicates the full screen display. true is equivalent to the display fullscreen, and false to minimal-ui.

3.11 designWidth member

The MiniAppWindowResource.designWidth member indicates the baseline width of the page design in pixel unit, based on which the size of the components on the page would be adjusted accordingly. The value is a non-negative integer. 以px为单位的页面设计基准宽度，元素大小将根据实际设备宽度来缩放。取值应为非负整数。

3.12 autoDesignWidth member

The MiniAppWindowResource.autoDesignWidth member indicates whether the designWidth of the page is auto-calculated. When it's true, the value of the designWidth is ignored, and the baseline width is determined by the system automatically according to the pixel density of the screen. 页面设计基准宽度是否自动计算，当设为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出。

4.1 name member

The MiniAppWidgetResource.name member describes the Widget name Widget名字

4.2 path member

The MiniAppWidgetResource.path member indicates the corresponding page path of a Widget. It follows the same path route format as defined in pages. Widget对应页面路径，采用与pages中相同页面路由的格式。

4.3 minPlatformVersion member

The MiniAppWidgetResource.minPlatformVersion member indicates the minimum platform version supported 支持最小平台版本

There are certain differences between the Widget-related APIs and the MiniApp APIs, hence, the declaration of the minimum platform version may be different. If the minPlatformVersion field of a widget is not set explicitly, it is then identical to the minPlatformVersion of the MiniApp by default.

Widget 涉及的API与MiniApp API有一定差别，因此最小平台版本声明可能不同。如不单独设置Widget的minPlatformVersion字段，则默认与MiniApp平台版本相同。

5.1 name member

The MiniAppPermissionResource.name member indicates the permission name 权限名称

5.2 reason member

The MiniAppPermissionResource.reason member indicates the reason to use this permission 该权限的使用目的

6.1 Localizable members 可本地化属性

The following members are localizable and share the same default configuration of dir and lang if not otherwise specified.

如下属性为可本地化属性。无特别规定的情况下，共享默认的dir和lang配置。

• name
• short_name
• description
• MiniAppWindowResource.navigationBarTitleText
• MiniAppWidgetResource.name

6.2 I18n Solution I18n方案

To support the multiple languages, attributes such as name, short_name, and description can be set as a reference to a string resource. Typically, string resources are stored in the corresponding multi-language JSON file in the MiniApp package's i18n directory. The multi-language file’s name complies with IETF BCP 47.

为了支持多语言能力name, short_name, description等参数可以被设置为字符串资源的索引。通常情况下字符串资源被保存在MiniApp包i18n目录下相应的多语言文件中。多语言文件命名规范符合IETF BCP 47。

The following example describes two simple multi-language files:

以下例子描述2个简单的多语言文：

i18n/en-US.json

{
 "strings": { 
    "name":"miniapp demo",
    "short_name":"MD",
    "description_application":"MiniApp Demo",
    },
    "files": {
    "images":"image/en_picture.PNG",
    },  
   }

i18n/zh-Hans.json

{
  "strings": { 
    "name":"小程序试用版",
    "short_name":"小程序",
    "description_application":"迷你程序试用版本",
  },
  "files": {
    "images":"image/zh_picture.PNG",
  },  
}

Developers can refer to a resource using the syntax $string:‹resource-name›, for example, "decscription": "$string:description_application".

用户可以使用$string:‹resource-name›的方式引用字符串资源，例如："decscription": "$string:description_application".

The following example describes a simple manifest fragment that supports multiple languages capability:

以下例子描述一个简单的支持多语言的manifest片段：

{
  "dir": "ltr",
  "lang": "en-US",
  "appID": "org.w3c.miniapp",
  "name": "$string:name",
  "short_name": "string:short_name",
  "versionName": "1.0.0",
  "versionCode": 1,
  "description": "$string:description_application",
  "icons": [
    {
      "src": "common/icons/icon.png",
      "sizes": "48x48"
    }
  ]
}

In this way, when reading the MiniApp Manifest, the MiniApp processor, such as marketplace, can extract the string resource information from the corresponding language file in the MiniApp package's i18n directory according to the configuration information of itself and generates the localized description. For example, if the configuration information of the marketplace is simplified Chinese, the marketplace parses the "name": "$string: name" statement in the manifest and extracts string: name information from the zh-Hans.json file in the MiniApp package's i18n directory. And then it generates the localized name of the MiniApp: 小程序试用版。

通过上述方式，应用市场在读取应用manifest时，会根据自身的配置信息，从i18n目录下相应的语言文件，提取字符串信息，生成本地描述。例如 应用市场配置信息为汉语简体，则应用市场会解析manifest中"name": "$string:name"语句，从i18n目录的zh-Hans.json文件，提取string:name信息：小程序试用版，并在应用市场生成该应用的本地化名称：小程序试用版。

9.1 Content constraint 内容限制

As the manifest is a JSON file and will commonly be encoded using [UNICODE], the security considerations described in [ECMA-404] and [UTR36] apply. In order to prevent developers from including custom/unrestrained data in a manifest, implementors may use a more strict schema than that defined in JSON Schema to impose their own implementation-specific limits on the member names, types and value ranges, e.g. to guard against memory overflow, or to meet platform-specific limitations.

Manifest作为一个JSON文件，通常以[UNICODE]方式编码，因此[ECMA-404]和[UTR36]中所定义的安全措施同样适用。为了防止开发者在manifest中添加任意不受限的数据，开发者可在其具体实现中采用比JSON Schema中所定义的更加严格的schema来约束文件中的成员元素名称、类型和取值范围等，从而防止内存耗尽或满足平台特有的限制。

9.2 Local resource access 本地资源访问

Members like icons, pages, widgets contain paths referring to local resources on the hosting platform. Implementors and the hosting platform should check the validity of those paths to ensure no illegal access outside the scope of the MiniApp package. On the other hand, the MiniApp itself (e.g. in JS code) may provide means to jump to external resources either on the hosting platform, or on a remote web site (e.g. through a uri). In this case, the hosting platform is responsible for providing clear indication to an end-user about such context switch.

icons, pages, widgets等属性包含了宿主平台上的本地资源引用路径，开发者和宿主平台应该检查这些路径的合法性以确保没有MiniApp package之外的非法访问。另一方面，MiniApp自身（如JS代码中）可能提供跳转到其他外部资源的方式，包括宿主平台或远程网站上的外部资源（比如通过uri)。此时，宿主平台应该负责向用户提供明确的上下文切换的指示信息。

In addition, the reqPermissions member provides a specific means to control the access to the local software, hardware and data resources on the user's device. User's consent should be asked when it comes to privacy-related or high-level privileged resources.

此外，reqPermissions属性提供了具体的控制访问用户设备上的本地软硬件及数据资源的方法。当涉及隐私或者高级权限相关的资源访问时，应该征询用户的同意。

9.3 Integrity 完整性

The integrity of the manifest document is protected by a cryptographic hash mechanism as part of the whole MiniApp package. Details are specified in the MiniApp Packaging specification.

Manifest文档的完整性作为MiniApp package的一部分被密码哈希机制所保护。详细定义见MiniApp Packaging specification。

9.4 Transparency 信息透明

It is RECOMMENDED that the hosting platform makes the necessary meta information in the manifest available to the end-user, such as appID, name, short_name, icons, versionName, description. This is to give an end-user an opportunity to make a conscious decision to approve the installation and use of the MiniApp. This could also help to identify a spoofing MiniApp.

建议宿主平台将manifest中的必要元数据信息提供给用户，比如appID, name, short_name, icons, versionName, description。这样可以给用户一个机会来对MiniApp的安装和使用提供清晰的判断依据，也可以帮助用户来识别伪装的恶意MiniApp。