diff --git a/en/application-dev/ability/figures/lifecycle.png b/en/application-dev/ability/figures/lifecycle.png deleted file mode 100644 index 694238d99c7e70d16d6bd1a37c86bcd599a9b2f3..0000000000000000000000000000000000000000 Binary files a/en/application-dev/ability/figures/lifecycle.png and /dev/null differ diff --git a/en/application-dev/quick-start/start-overview.md b/en/application-dev/quick-start/start-overview.md index 4d345e40f3dd34961f6fdbb123927bdaf9aa09df..b9919a6d7257b09bcaaf3538e023175e720fa4ed 100644 --- a/en/application-dev/quick-start/start-overview.md +++ b/en/application-dev/quick-start/start-overview.md @@ -34,7 +34,7 @@ Abilities are classified into two types: [Feature Ability (FA)](../../glossary.m ![en-us_image_0000001215206886](figures/en-us_image_0000001215206886.png) -This document provides a Page ability instance with two pages. For more information about ability development, see [Ability Development](../ability/ability-brief.md). +This document provides a Page ability instance with two pages. For more information about ability development, see [Ability Development](../ability/fa-brief.md). ## Tool Preparation diff --git a/zh-cn/application-dev/ability/figures/lifecycle.png b/zh-cn/application-dev/ability/figures/lifecycle.png deleted file mode 100644 index 694238d99c7e70d16d6bd1a37c86bcd599a9b2f3..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/ability/figures/lifecycle.png and /dev/null differ diff --git a/zh-cn/application-dev/ability/figures/page-ability-lifecycle-callbacks.png b/zh-cn/application-dev/ability/figures/page-ability-lifecycle-callbacks.png deleted file mode 100644 index 4c94556b5c2516ad2978a9a31d833cfb2cf3dd01..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/ability/figures/page-ability-lifecycle-callbacks.png and /dev/null differ diff --git a/zh-cn/application-dev/ability/stage-formextension.md b/zh-cn/application-dev/ability/stage-formextension.md deleted file mode 100644 index 5abde38a3b5922ca102bd9d3c94da651239b7292..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/ability/stage-formextension.md +++ /dev/null @@ -1,340 +0,0 @@ -# Stage卡片开发指导 - -## 卡片概述 - -卡片是一种界面展示形式，可以将应用的重要信息或操作前置到卡片，以达到服务直达，减少体验层级的目的。 - -卡片常用于嵌入到其他应用（当前只支持系统应用）中作为其界面的一部分显示，并支持拉起页面，发送消息等基础的交互功能。卡片使用方负责显示卡片。 - -卡片的基本概念： - -- 卡片提供方 - 提供卡片显示内容原子化服务，控制卡片的显示内容、控件布局以及控件点击事件。 -- 卡片使用方 - 显示卡片内容的宿主应用，控制卡片在宿主中展示的位置。 -- 卡片管理服务 - 用于管理系统中所添加卡片的常驻代理服务，包括卡片对象的管理与使用，以及卡片周期性刷新等。 - -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> 卡片使用方和提供方不要求常驻运行，在需要添加/删除/请求更新卡片时，卡片管理服务会拉起卡片提供方获取卡片信息。 - -开发者仅需作为卡片提供方进行卡片内容的开发，卡片使用方和卡片管理服务由系统自动处理。 - -卡片提供方控制卡片实际显示的内容、控件布局以及点击事件。 - -## 场景介绍 - -Stage卡片开发，即基于[Stage模型综述](stage-brief.md)的卡片提供方开发，主要涉及如下功能逻辑： - -- 卡片生命周期回调函数FormExtension开发。 -- 创建卡片数据FormBindingData对象。 -- 通过FormProvider更新卡片。 -- 卡片页面开发。 - -## 接口说明 - -FormExtension功能如下：FormExtension类，拥有context属性，具体的API详见[接口文档](../reference/apis/js-apis-formextension.md)。 - -**表1** FormExtension API接口功能介绍 - -| 接口名 | 描述 | -| :----------------------------------------------------------- | :------------------------------------------- | -| onCreate(want: Want): formBindingData.FormBindingData | 卡片提供方接收创建卡片的通知接口。 | -| onCastToNormal(formId: string): void | 卡片提供方接收临时卡片转常态卡片的通知接口。 | -| onUpdate(formId: string): void | 卡片提供方接收更新卡片的通知接口。 | -| onVisibilityChange(newStatus: { [key: string]: number }): void | 卡片提供方接收修改可见性的通知接口。 | -| onEvent(formId: string, message: string): void | 卡片提供方接收处理卡片事件的通知接口。 | -| onDestroy(formId: string): void | 卡片提供方接收销毁卡片的通知接口。 | -| onConfigurationUpdated(config: Configuration): void; | 当系统配置更新时调用。 | - -FormExtension类拥有context属性，context属性为FormExtensionContext类，具体的API详见[接口文档](../reference/apis/js-apis-formextensioncontext.md)。 - -**表2** FormExtensionContext API接口功能介绍 - -| 接口名 | 描述 | -| :----------------------------------------------------------- | :------------------------ | -| updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void | 回调形式主动更新卡片。 | -| updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise\ | Promise形式主动更新卡片。 | - -FormProvider类具体的API详见[接口文档](../reference/apis/js-apis-formprovider.md)。 - -**表3** FormProvider API接口功能介绍 - -| 接口名 | 描述 | -| :----------------------------------------------------------- | :------------------------------------------------ | -| setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void; | 设置指定卡片的下一次更新时间。 | -| setFormNextRefreshTime(formId: string, minute: number): Promise<void>; | 设置指定卡片的下一次更新时间，以promise方式返回。 | -| updateForm(formId: string, formBindingData: FormBindingData, callback: AsyncCallback<void>): void; | 更新指定的卡片。 | -| updateForm(formId: string, formBindingData: FormBindingData): Promise<void>; | 更新指定的卡片，以promise方式返回。 | - -## 开发步骤 - -### 创建卡片FormExtension - -创建Stage模型的卡片，需实现FormExtension生命周期接口。具体示例代码如下： - -1. 导入相关模块 - - ```javascript - import FormExtension from '@ohos.application.FormExtension' - import formBindingData from '@ohos.application.formBindingData' - import formInfo from '@ohos.application.formInfo' - import formProvider from '@ohos.application.formProvider' - ``` - -2. 实现FormExtension生命周期接口 - - ```javascript - export default class FormAbility extends FormExtension { - onCreate(want) { - console.log('FormAbility onCreate'); - // 由开发人员自行实现，将创建的卡片信息持久化，以便在下次获取/更新该卡片实例时进行使用 - let obj = { - "title": "titleOnCreate", - "detail": "detailOnCreate" - }; - let formData = formBindingData.createFormBindingData(obj); - return formData; - } - onCastToNormal(formId) { - // 使用方将临时卡片转换为常态卡片触发，提供方需要做相应的处理 - console.log('FormAbility onCastToNormal'); - } - onUpdate(formId) { - // 若卡片支持定时更新/定点更新/卡片使用方主动请求更新功能，则提供方需要覆写该方法以支持数据更新 - console.log('FormAbility onUpdate'); - let obj = { - "title": "titleOnUpdate", - "detail": "detailOnUpdate" - }; - let formData = formBindingData.createFormBindingData(obj); - formProvider.updateForm(formId, formData).catch((error) => { - console.log('FormAbility updateForm, error:' + JSON.stringify(error)); - }); - } - onVisibilityChange(newStatus) { - // 使用方发起可见或者不可见通知触发，提供方需要做相应的处理 - console.log('FormAbility onVisibilityChange'); - } - onEvent(formId, message) { - // 若卡片支持触发事件，则需要覆写该方法并实现对事件的触发 - console.log('FormAbility onEvent'); - } - onDestroy(formId) { - // 删除卡片实例数据 - console.log('FormAbility onDestroy'); - } - onAcquireFormState(want) { - console.log('FormAbility onAcquireFormState'); - return formInfo.FormState.READY; - } - } - ``` - -### 配置卡片配置文件 - -Form需要在应用配置文件module.json中进行配置。 - -- extensionAbility模块，内部字段结构说明： - - | 属性名称 | 含义 | 数据类型 | 是否可缺省 | - | ----------- | ------------------------------------------------------------ | ---------- | -------------------- | - | name | 表示extensionAbility的名字。该标签不可缺省。 | 字符串 | 否 | - | srcEntrance | 表示extensionAbility所对应的JS的代码路径。该标签不可缺省。 | 字符串 | 否 | - | description | 表示extensionAbility的描述。可以是表示描述内容的字符串，也可以是对描述内容的资源索引以支持多语言。 | 字符串 | 可缺省，缺省值为空。 | - | icon | 表示extensionAbility的图标资源文件的索引。 | 字符串 | 可缺省，缺省值为空。 | - | label | 表示extensionAbility的标签信息，即extensionAbility对外显示的文字描述信息。取值可以是描述性内容，也可以是标识label的资源索引。 | 字符串 | 可缺省，缺省值为空。 | - | type | 表示extensionAbility的类型。取值form、service等 | 字符串 | 否 | - | permissions | 表示其他应用的Ability调用此Ability时需要申请的权限。 | 字符串数组 | 可缺省，缺省值为空。 | - | metadata | 表示extensionAbility的元信息。用于描述extensionAbility的配置信息。 | 对象 | 可缺省，缺省值为空 | - - 对于FormExtensionAbility来说，type需要配置为form，并且需要填写metadata元信息，用于配置卡片的具体信息。 - - 配置示例如下： - - ```json - "extensionAbilities": [{ - "name": "FormAbility", - "srcEntrance": "./ets/FormAbility/FormAbility.ts", - "label": "$string:form_FormAbility_label", - "description": "$string:form_FormAbility_desc", - "type": "form", - "metadata": [{ - "name": "ohos.extension.form", - "resource": "$profile:form_config" - }] - }] - ``` - -- 卡片profile模块。在 FormExtensionAbility 的元信息中，需要使用 ohos.extension.form 指定的资源文件的路径，如使用 $profile:form_config 指定开发视图的 resources/base/profile/ 目录下的 form_config.json 作为卡片profile配置文件。 - - 内部字段结构说明： - - | 属性名称 | 含义 | 数据类型 | 是否可缺省 | - | ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | - | name | 表示卡片的类名。字符串最大长度为127字节。 | 字符串 | 否 | - | description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 | - | src | 表示卡片对应的UI代码的完整路径。 | 字符串 | 否 | - | window | 用于定义与显示窗口相关的配置。 | 对象 | 可缺省 | - | isDefault | 表示该卡片是否为默认卡片，每个Ability有且只有一个默认卡片。
true：默认卡片。
false：非默认卡片。 | 布尔值 | 否 | - | colorMode | 表示卡片的主题样式，取值范围如下：
auto：自适应。
dark：深色主题。
light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 | - | supportDimensions | 表示卡片支持的外观规格，取值范围：
1 * 2：表示1行2列的二宫格。
2 * 2：表示2行2列的四宫格。
2 * 4：表示2行4列的八宫格。
4 * 4：表示4行4列的十六宫格。 | 字符串数组 | 否 | - | defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 | - | updateEnabled | 表示卡片是否支持周期性刷新，取值范围：
true：表示支持周期性刷新，可以在定时刷新（updateDuration）和定点刷新（scheduledUpdateTime）两种方式任选其一，优先选择定时刷新。
false：表示不支持周期性刷新。 | 布尔类型 | 否 | - | scheduledUpdateTime | 表示卡片的定点刷新的时刻，采用24小时制，精确到分钟。 | 字符串 | 可缺省，缺省值为“0:0”。 | - | updateDuration | 表示卡片定时刷新的更新周期，单位为30分钟，取值为自然数。
当取值为0时，表示该参数不生效。
当取值为正整数N时，表示刷新周期为30*N分钟。 | 数值 | 可缺省，缺省值为“0”。 | - | formConfigAbility | 表示用于调整卡片的设施或活动的名称。 | 字符串 | 可缺省，缺省值为空。 | - | formVisibleNotify | 标识是否允许卡片使用卡片可见性通知 | 字符串 | 可缺省，缺省值为空。 | - | metaData | 表示卡片的自定义信息，包含customizeData数组标签。 | 对象 | 可缺省，缺省值为空。 | - - 配置示例如下： - - ```json - { - "forms": [{ - "name": "widget", - "description": "This is a service widget.", - "src": "./js/widget/pages/index/index", - "window": { - "autoDesignWidth": true, - "designWidth": 720 - }, - "isDefault": true, - "colorMode": "auto", - "supportDimensions": ["2*2"], - "defaultDimension": "2*2", - "updateEnabled": true, - "scheduledUpdateTime": "10:30", - "updateDuration": 1 - }] - } - ``` - - -### 卡片信息的持久化 - -因大部分卡片提供方都不是常驻服务，只有在需要使用时才会被拉起获取卡片信息，且卡片管理服务支持对卡片进行多实例管理，卡片ID对应实例ID，因此若卡片提供方支持对卡片数据进行配置，则需要对卡片的业务数据按照卡片ID进行持久化管理，以便在后续获取、更新以及拉起时能获取到正确的卡片业务数据。 - -```javascript - onCreate(want) { - console.log('FormAbility onCreate'); - - let formId = want.parameters["ohos.extra.param.key.form_identity"]; - let formName = want.parameters["ohos.extra.param.key.form_name"]; - let tempFlag = want.parameters["ohos.extra.param.key.form_temporary"]; - // 由开发人员自行实现，将创建的卡片信息持久化，以便在下次获取/更新该卡片实例时进行使用 - storeFormInfo(formId, formName, tempFlag, want); - - let obj = { - "title": "titleOnCreate", - "detail": "detailOnCreate" - }; - let formData = formBindingData.createFormBindingData(obj); - return formData; - } -``` - -且需要适配onDestroy卡片删除通知接口，在其中实现卡片实例数据的删除。 - -```javascript - onDestroy(formId) { - // 删除卡片实例数据 - deleteFormInfo(formId); - console.log('FormAbility onDestroy'); - } -``` - -具体的持久化方法可以参考[轻量级数据存储开发指导](../database/database-storage-guidelines.md)。 - -需要注意的是，卡片使用方在请求卡片时传递给提供方应用的Want数据中存在临时标记字段，表示此次请求的卡片是否为临时卡片： - -常态卡片：卡片使用方会持久化的卡片； - -临时卡片：卡片使用方不会持久化的卡片； - -由于临时卡片的数据具有非持久化的特殊性，某些场景比如卡片服务框架死亡重启，此时临时卡片数据在卡片管理服务中已经删除，且对应的卡片ID不会通知到提供方，所以卡片提供方需要自己负责清理长时间未删除的临时卡片数据。同时对应的卡片使用方可能会将之前请求的临时卡片转换为常态卡片。如果转换成功，卡片提供方也需要对对应的临时卡片ID进行处理，把卡片提供方记录的临时卡片数据转换为常态卡片数据，防止提供方在清理长时间未删除的临时卡片时，把已经转换为常态卡片的临时卡片信息删除，导致卡片信息丢失。 - -### 开发卡片页面 -开发者可以使用hml+css+json开发JS卡片页面： - -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> 当前仅支持JS扩展的类Web开发范式来实现卡片的UI页面。 - - - hml: - ```html -
- -
- -
-
- {{title}} - {{detail}} -
- -
- ``` - - - css: - - ```css -.container { - flex-direction: column; - justify-content: center; - align-items: center; -} - -.bg-img { - flex-shrink: 0; - height: 100%; -} - -.container-inner { - flex-direction: column; - justify-content: flex-end; - align-items: flex-start; - height: 100%; - width: 100%; - padding: 12px; -} - -.title { - font-size: 19px; - font-weight: bold; - color: white; - text-overflow: ellipsis; - max-lines: 1; -} - -.detail_text { - font-size: 16px; - color: white; - opacity: 0.66; - text-overflow: ellipsis; - max-lines: 1; - margin-top: 6px; -} - ``` - - - json: - ```json - { - "data": { - "title": "TitleDefault", - "detail": "TextDefault" - }, - "actions": { - "routerEvent": { - "action": "router", - "abilityName": "com.example.MyApplication.hmservice.FormAbility", - "params": { - "message": "add detail" - } - } - } - } - ``` - -最终可以得到，如下卡片： - -![fa-form-example](figures/fa-form-example.png) \ No newline at end of file diff --git a/zh-cn/application-dev/quick-start/Readme-CN.md b/zh-cn/application-dev/quick-start/Readme-CN.md index 781b8d4ad6bab50e887e5388e34a0c4859f074ea..f86eb55f4a2701fef2c24eeb8b8901ef965c0c75 100755 --- a/zh-cn/application-dev/quick-start/Readme-CN.md +++ b/zh-cn/application-dev/quick-start/Readme-CN.md @@ -8,4 +8,5 @@ - 开发基础知识 - [包结构说明](package-structure.md) - [资源文件的分类](basic-resource-file-categories.md) + - [SysCap说明](syscap.md) diff --git a/zh-cn/application-dev/quick-start/figures/20220329-103626.gif b/zh-cn/application-dev/quick-start/figures/20220329-103626.gif new file mode 100644 index 0000000000000000000000000000000000000000..1f3a67796fd41dce99b4256a115fd1d0733ebb79 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/20220329-103626.gif differ diff --git a/zh-cn/application-dev/quick-start/figures/SysCap_Overview.jpg b/zh-cn/application-dev/quick-start/figures/SysCap_Overview.jpg new file mode 100644 index 0000000000000000000000000000000000000000..8886b48158dff6792e55ece07158390b626cb8f1 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/SysCap_Overview.jpg differ diff --git a/zh-cn/application-dev/quick-start/figures/image-20220326064841782.png b/zh-cn/application-dev/quick-start/figures/image-20220326064841782.png new file mode 100644 index 0000000000000000000000000000000000000000..79bf756bc296a3f7129d6e646ab77248110abd06 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/image-20220326064841782.png differ diff --git a/zh-cn/application-dev/quick-start/figures/image-20220326064913834.png b/zh-cn/application-dev/quick-start/figures/image-20220326064913834.png new file mode 100644 index 0000000000000000000000000000000000000000..a48d603f708ad817997a7d89128ff392b515ccd2 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/image-20220326064913834.png differ diff --git a/zh-cn/application-dev/quick-start/figures/image-20220326064955505.png b/zh-cn/application-dev/quick-start/figures/image-20220326064955505.png new file mode 100644 index 0000000000000000000000000000000000000000..22a260f5c88a8baa9a8d41c9d64de6c462751e04 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/image-20220326064955505.png differ diff --git a/zh-cn/application-dev/quick-start/figures/image-20220326065043006.png b/zh-cn/application-dev/quick-start/figures/image-20220326065043006.png new file mode 100644 index 0000000000000000000000000000000000000000..77f386e35358d0a7af65d11e95fb690c9754e992 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/image-20220326065043006.png differ diff --git a/zh-cn/application-dev/quick-start/figures/image-20220326065124911.png b/zh-cn/application-dev/quick-start/figures/image-20220326065124911.png new file mode 100644 index 0000000000000000000000000000000000000000..ccb9ad8c7d95788d8734c6627ac12fd019ff7a4b Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/image-20220326065124911.png differ diff --git a/zh-cn/application-dev/quick-start/figures/image-20220326065201867.png b/zh-cn/application-dev/quick-start/figures/image-20220326065201867.png new file mode 100644 index 0000000000000000000000000000000000000000..a7119d0acff9135517db82072009a599e51f1b12 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/image-20220326065201867.png differ diff --git a/zh-cn/application-dev/quick-start/figures/image-20220326072448840.png b/zh-cn/application-dev/quick-start/figures/image-20220326072448840.png new file mode 100644 index 0000000000000000000000000000000000000000..93919d2bcd509a00337af36386898d025fd774b4 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/image-20220326072448840.png differ diff --git a/zh-cn/application-dev/quick-start/module-structure.md b/zh-cn/application-dev/quick-start/module-structure.md deleted file mode 100644 index f6171cf402b57d56facc02818164990babd466f7..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/quick-start/module-structure.md +++ /dev/null @@ -1,831 +0,0 @@ - - -# module.json字段说明 - -在开发FA模型下的应用程序时，需要在config.json文件中对应用的包结构进行申明；同样的，在开发stage模型下的应用程序时，需要在module.json配置文件中对应用的包结构进行声明。 - -## 配置文件内部结构 - -module.json由app和module这两个部分组成，缺一不可。配置文件的内部结构参见表1。 - -表1 配置文件的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | ---------- | -| app | 表示应用的全局配置信息。同一个应用的不同HAP包的app配置必须保持一致。参考[app对象内部结构](#app对象内部结构)。 | 对象 | 否 | -| module | 表示HAP包的配置信息。该标签下的配置只对当前HAP包生效。参考[module对象内部结构](#module对象内部结构)。 | 对象 | 否 | - -module.json示例： - -```json -{ -    "app": { - "bundleName": "com.application.music", -        "vendor": "application", -        "versionCode": 1, -        "versionName": "1.0", -        "minCompatibleVersionCode": 1, -        "apiCompatibleVersion": 7, -        "apiTargetVersion": 8, -        "apiReleaseType": "Release", -        "debug": false, -        "icon" : "$media:app_icon", -        "label": "$string:app_name", -        "description": "$string:description_application", -        "distributedNotificationEnabled": true, -        "entityType": "game", -        "car": { -            "apiCompatibleVersion": 8 -         } -    }, - "module": { - "name": "myHapName", - "type": "entry|feature|har", - "srcEntrance" : "./MyAbilityStage.js", - "description" : "$string:description_application", - "process": "string", - "mainElement": "MainAbility", - "deviceTypes": [ - "phone", - "tablet", - "tv", - "wearable", - "liteWearable", - "ar", - "vr", - "car", - "earphones", - "pc", - "speaker", - "smartVision", - "linkIoT", - "router", - ], - "deliveryWithInstall": true, - "installationFree": false, - "virtualMachine": "ark | default", - "metadata": [ - { - "name": "string", - "value": "string", - "resource": "$profile:config_file1" - }, - { - "name": "string", - "value": "string", - "resource": "$profile:config_file2" - } - ], - "metadata": [ - { - "name": "string", - "value": "string", - "resource": "$profile:config_file1" - }, - { - "name": "string", - "value": "string", - "resource": "$profile:config_file2" - } - ], - "abilities": [ - { - "name": "MainAbility", - "srcEntrance" : "./login/MyMainAbility.ts", - "description": "$string:description_main_ability", - "icon": "$media:icon", - "label": "HiMusic", - "visible": true, - "skills": [ - { - "actions": [ - "action.system.home" - ], - "entities": [ - "entity.system.home" - ], - "uris": [ ] - } - ], - "backgroundModes": [ - "dataTransfer", - "audioPlayback", - "audioRecording", - "location", - "bluetoothInteraction", - "multiDeviceConnection", - "wifiInteraction", - "voip", - "taskKeeping" - ], - } - ], - "abilities": [ - { - "name": "MainAbility", - "srcEntrance" : "./login/MyMainAbility.ts", - "description": "$string:description_main_ability", - "icon": "$media:icon", - "label": "HiMusic", - "visible": true, - "skills": [ - { - "actions": [ - "action.system.home" - ], - "entities": [ - "entity.system.home" - ], - "uris": [ ] - } - ], - "backgroundModes": [ - "dataTransfer", - "audioPlayback", - "audioRecording", - "location", - "bluetoothInteraction", - "multiDeviceConnection", - "wifiInteraction", - "voip", - "taskKeeping" - ], - } - ], - "requestPermissions": [ - { - "name": "ohos.abilitydemo.permission.PROVIDER", - "reason": "$string:reason", - "usedScene": { - "abilities": [ - "FormAbility" - ], - "when": "inuse" - } - } - ] - } -} -``` - -### app对象内部结构 - -该标签为整个应用的属性，影响应用中左右hap及组件，不会被hap或组件所替换。该标签的内部结构参见表2。 - -表2 app对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------------------------------ | ------------------------------------------------------------ | -------- | ------------------------------------------- | -| bundleName | 该标签表示应用的包名，用于标识应用的唯一性。该标签不可缺省。标签的值命名规则：
1）字符串以字母、数字、下划线和符号”.”组成；
2）以字母开头；
3）最小长度7个字节，最大长度127个字节。
推荐采用反域名形式命名（如：com.example.xxx，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。
其中，随系统源码编译的应用需命名为”com.ohos.xxx”形式， ohos标识OpenHarmony系统应用。 | 字符串 | 否 | -| debug | 该标签标识应用是否可调试。 | 布尔值 | 该标签可以缺省，缺省为false。 | -| icon | 该标签标识应用的图标，标签值为资源文件的索引。 | 字符串 | 该标签不可缺省。 | -| label | 该标签标识应用的的名称，标签值为资源文件的索引，以支持多语言。 | 字符串 | 该标签不可缺省。 | -| description | 该标签标识App的描述信息，标签值是是字符串类型或对描述内容的资源索引，以支持多语言。 | 字符串 | 该标签可缺省，缺省值为空。 | -| vendor | 该标签是对应用开发厂商的描述。该标签的值是字符串类型（最大255个字节）。 | 字符串 | 该标签可以缺省，缺省为空。 | -| versionCode | 该标签标识应用的版本号，该标签值为32位非负整数。此数字仅用于确定某个版本是否比另一个版本更新，数值越大表示版本越高。开发者可以将该值设置为任何正整数，但是必须确保应用的新版本都使用比旧版本更大的值。该标签不可缺省，versionCode 值应小于2的31方。 | 数值 | | -| versionName | 该标签标识版本号的文字描述，用于向用户展示。
该标签仅由数字和点构成，推荐采用“A.B.C.D”四段式的形式。四段式推荐的含义如下所示。
第一段：主版本号/Major，范围0-99，重大修改的版本，如实现新的大功能或重大变化。
第二段：次版本号/Minor，范围0-99，表示实现较突出的特点，如新功能添加和大问题修复。
第三段：特性版本号/Feature，范围0-99，标识规划的新版本特性。
第四段：修订版本号/Patch，范围0-999，表示维护版本，修复bug。 | 字符串 | 该标签不可缺省 | -| minCompatibleVersionCode | 该标签标识应用运行需要的API最小版本。 | 数值 | 该标签可缺省。缺省值等于versionCode标签值。 | -| minAPIVersion | 该标签标识应用运行需要的API目标版本。 | 数值 | 该标签不可缺省。 | -| targetAPIVersion | 该标签标识应用运行需要的API目标版本。 | 整形 | 该标签不可缺省。 | -| apiReleaseType | 该标签标识应用运行需要的API目标版本的类型，采用字符串类型表示。取值为“CanaryN”、“BetaN”或者“Release”，其中，N代表大于零的整数。
Canary：受限发布的版本。
Beta：公开发布的Beta版本。
Release：公开发布的正式版本。 | 字符串 | 该标签可缺省，缺省为“Release”。 | -| distributedNotificationEnabled | 该标签标记该应用是否开启分布式通知。 | 布尔值 | 该标签可缺省，缺省值为true。 | -| entityType | 该标签标记该应用的类别，具体有：游戏类(game)，影音类（media）、社交通信类（communication）、新闻类（news）、出行类（travel）、工具类（utility）、购物类（shopping）、教育类（education）、少儿类（kids）、商务类（business）、拍摄类（photography）。 | 字符串 | 该标签可以缺省，缺省为unspecified。 | - -### module对象内部结构 - -hap包的配置信息，该标签下的配置只对当前hap包生效。 - -表3 module对象内部结构 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------------------- | -| name | 该标签标识当前module的名字，module打包成hap后，表示hap的名称，标签值采用字符串表示（最大长度31个字节），该名称在整个应用要唯一。 | 字符串 | 该标签不可缺省。 | -| type | 该标签表示当前hap的类型。类型有三种，分别是entry、feature和har。 | 字符串 | 该标签不可缺省。 | -| srcEntrance | 该标签表示hap所对应的入口js代码路径，标签值为字符串（最长为127字节）。 | 字符串 | 该标签可缺省。 | -| description | 该标签标识hap包的描述信息，标签值是是字符串类型或对描述内容的资源索引，以支持多语言。 | 字符串 | 该标签可缺省，缺省值为空。 | -| process | 该标签标识hap的进程名，标签值为字符串类型（最长为31个字节）。如果在hap标签下配置了process，该应用的所有ability都运行在该进程中。 | 字符串 | 可缺省，缺省为hap的名称。 | -| mainElement | 该标签标识hap的入口ability名称或者extension名称。只有配置为mainElement的ability或者extension才允许在服务中心露出。创建OpenHarmony原子化服务时，该标签不可缺省。 | 字符串 | OpenHarmony应用下，该标签可缺省。 | -| deviceTypes | 该标签标识hap可以运行在哪类设备上，标签值采用字符串数组的表示，系统预定义的设备类型见表4。
与syscap不同的是，deviceTypes是以设备类型为粒度，而syscap是以设备能力(例如蓝牙、wifi)为粒度。 | 字符串数组 | 该标签不可缺省，可以为空值。 | -| deliveryWithInstall | 该标签标识当前hap是否在用户主动安装的时候安装，true表示主动安装时安装，false表示主动安装时不安装。 | 布尔值 | 该标签不可缺省。 | -| installationFree | 表示当前HAP是否支持免安装特性。所有Hap包都需要配置不可缺省。
true：表示支持免安装特性，且符合免安装约束。
false：表示不支持免安装特性。

当entry.hap该字段配置为true时，与该entry.hap相关的所有feature.hap该字段也需要配置为ture。
当entry.hap该字段配置为false时，与该entry.hap相关的各feature.hap该字段可按业务需求配置ture或false。 | 布尔值 | 该标签不可缺省。 | -| virtualMachine | 该标签用于标识当前hap运行的目标虚拟机类型，供云端分发使用，如应用市场和分发中心。
该标签值为字符串。如果目标虚拟机类型为方舟虚拟机，则其值为”ark”； 如果目标虚拟机类型不是方舟虚拟机，则其值为”default”。该标签由IDE构建hap的时候自动插入。解包工具解析时，如果hap包没有该标签，设置该标签值为”default”。 | 字符串 | 该标签可缺省，缺省值为“default”。 | -| uiSyntax | syntax定义该JS Component的语法类型。
hml标识该JS Component使用hml/css/js进行开发；
ets标识该JS Component使用ets声明式语法进行开发。 | 字符串 | 该标签可缺省，默认值为hml | -| pages | 该标签是一个profile资源，用于列举JS Component中每个页面信息。pages使用参考pages示例。 | 对象 | 在有ability的场景下，该标签不可缺省。 | -| metadata | 该标签标识Hap的自定义元信息，标签值为数组类型，该标签下的配置只对当前module、或者ability、或者extensionAbility生效。metadata参考[metadata对象内部结构](#metadata对象内部结构)。 | 数组 | 该标签可缺省，缺省值为空。 | -| abilities | 描述元能力的配置信息，标签值为数组类型，该标签下的配置只对当前ability生效。abilities参考[abilities对象内部结构](#abilities对象内部结构)。 | 对象 | 该标签可缺省，缺省值为空。 | -| extensionAbilities | 描述extensionAbilities的配置信息，标签值为数组类型，该标签下的配置只对当前extensionAbility生效。extensionAbilities参考[extensionAbility对象的内部结构说明](#extensionAbility对象的内部结构说明)。 | 对象 | 该标签可缺省，缺省值为空。 | -| requestPermissions | 该标签标识应用运行时需向系统申请的权限集合，标签值为数组类型。requestPermissions参考[requestPermissions对象内部结构](#requestPermissions对象内部结构)。 | 对象 | 该标签可缺省，缺省值为空。 | - -表4 deviceTypes对象的系统预定义设备 - -| 中文 | 英文 | 枚举值 | 设备类型 | -| ------------ | ------------ | ------------ | -------------------------------------------------------- | -| 智能手机 | smartphone | phone | 手机 | -| 平板 | tablet | tablet | 平板，带屏音箱 | -| 智慧屏 | smart TV | tv | | -| 智能手表 | smart watch | wearable | 智能手表，儿童手表，特指资源较丰富的的手表，具备电话功能 | -| 运动手表 | basic watch | liteWearable | 基本功能手表，运动手表 | -| 增强现实 | AR | ar | | -| 虚拟现实 | VR | vr | | -| 车机 | head unit | car | | -| 耳机 | earphones | earphones | | -| 个人计算机 | PC | pc | | -| 音箱 | speaker | speaker | 无屏音箱，有屏音箱，通过硬件profile | -| 智慧视觉设备 | Smart Vision | smartVision | 带摄像头的设备，通过硬件profile分开是否 | -| 联接类模组 | linkiot | linkIoT | Wi-Fi模组，蓝牙模组 | -| 路由器 | router | router | 路由器 | - -deviceTypes示例： - -```json -{ - "module": { - "name": "myHapName", -        "type": "har", - "deviceTypes" : [ - "phone" - ] - } -} -``` - -pages示例： - -```json -{ - "module": { -       "name": "myHapName", -        "type": "har", - "deviceTypes" : [ - "phone" - ], -        "pages": "$profile:pages_config" -    } -} -``` - -pages_config配置文件 - -```json -{ -    "src": [ -        "pages/index/index", -        "pages/second/second", -        "pages/third/third", -        "pages/four/four" -    ] -} -``` - - - -#### metadata对象内部结构 - -描述的module、ability、extensionAbility配置信息，标签值为数组类型，该标签下的配置只对当前module、或者ability、或者extensionAbility生效。 - -表5 metadata对象内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------------- | -| name | 该标签表示数据项的键名称，字符串类型（最大长度255字节）。 | 字符串 | 该标签可缺省，缺省值为空。 | -| value | 该标签表示数据项的值，标签值为字符串（最大长度255字节）。 | 字符串 | 可缺省，缺省为空。 | -| resource | 该标签标识定义用户自定义数据格式，标签值为标识该数据的资源的索引值。 | 字符串 | 可缺省，缺省为空。 | - -metadata示例： - -```json -{  -    "module": { -        "metadata": [ -            { -                "name": "string", -                "value": "string", -                "resource": "$profile:config_file" -            }, -            { -                "name": "string", -                "value": "string", -                "resource": "$profile:config_file" -            } -        ] -    } -} -``` - -#### abilities对象内部结构 - -abilities描述ability的配置信息，标签值为数组类型。 - -表6 abilities对象内部结构说明 - -| 属性 | 含义 | 数据类型 | 是否可缺省 | -| --------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | -| name | 该标签标识当前ability的逻辑名，该名称在整个应用要唯一，标签值采用字符串表示（最大长度127个字节）。 | 字符串 | 该标签不可缺省。 | -| srcEntrance | 该标签表示ability所对应的js代码路径，标签值为字符串（最长为127字节）。。 | 字符串 | 该标签不可缺省。 | -| launchType | 该标签标示ability的启动模式，标签值可选"standard"、“singleton”、‘’‘specified“。该标签缺省为"standard"。standard表示普通多实例，spcified表示该ability内部根据业务自己置顶多实例，singleton表示单实例。 | 字符串 | 可缺省，该标签缺省为"standard" | -| description | 该标签标识ability的描述，标签值是是字符串类型或对描述内容的资源索引，要求采用用资源索引方式，以支持多语言。 | 字符串 | 该标签可缺省，缺省值为空。 | -| icon | 该标签标识ability图标，标签值为资源文件的索引。该标签可缺省，缺省值为空。
如果ability被配置为MainElement，该标签必须配置。 | 字符串 | 该标签可缺省，缺省值为空。
如果ability被配置为MainElement，该标签必须配置。 | -| permissions | 该标签标识被其它应用的ability调用时需要申请的权限的集合，字符串数组类型，每个数组元素为一个权限名称，通常采用反向域名方式表示（最大255字节），可以是系统预定义的权限，也可以是该应用自定义的权限。如果是后者，需与defPermissions标签中定义的某个权限的name标签值一致。该标签可缺省，缺省值为空。 | 字符串数组 | 该标签可缺省，缺省值为空。 | -| metadata | 该标签表示ability的元信息。metadata参考[metadata对象内部结构](#metadata对象内部结构)。 | 数组 | 该标签可缺省，缺省值为空。 | -| visible | 该标签标识ability是否可以被其它应用调用，为布尔类型，true表示可以被其它应用调用， false表示不可以被其它应用调用。 | 布尔值 | 该标签可缺省，缺省值为false。 | -| continuable | 该标签标识ability是否可以迁移，为布尔类型，true表示可以被迁移， false表示不可以被迁移。 | 布尔值 | 该标签可缺省，缺省值为false。 | -| skills | 该标签标识ability能够接收的意图的特征集，为数组格式。
配置规则： entry包可以配置多个具有入口能力的skills标签（配置了action.system.home和entity.system.home）的ability，其中第一个配置了skills标签的ability中的label和icon作为OpenHarmony服务或应用的label和icon。
OpenHarmony服务的Feature包不能配置具有入口能力的skills标签。
OpenHarmony应用的Feature包可以配置具有入口能力的skills标签。
skills内部结构参考[skills对象内部结构](#skills对象内部结构)。 | 数组 | 该标签可缺省，缺省值为空。 | -| backgroundModes | 该标签标识ability长时任务集合。指定用于满足特定类型的长时任务。
长时任务类型有如下：
dataTransfer：通过网络/对端设备进行数据下载、备份、分享、传输等业务。
audioPlayback：音频输出业务。
audioRecording：音频输入业务。
location：定位、导航业务。
bluetoothInteraction：蓝牙扫描、连接、传输业务（穿戴）。
multiDeviceConnection：多设备互联业务。
wifiInteraction：Wifi扫描、连接、传输业务（克隆 多屏）。
voip：音视频电话，VOIP业务。
taskKeeping：计算业务。
| 字符串 | 可缺省，缺省为空。 | - -abilities示例 - -```json -{ -    "abilities": [{ -        "name": "MainAbility", -        "srcEntrance": "./ets/login/MyLoginAbility.ts", -        "launchType":"standard" -        "description": "$string:description_main_ability", -        "icon": "$media:icon", -        "label": "Login", -        "permissions": [], -        "metadata": [], -        "visible": true, -        "continuable": true, -        "skills": [{ -            "actions": ["action.system.home"], -            "entities": ["entity.system.home"], -            "uris": [] -        }], -        "backgroundModes": [ -            "dataTransfer", -            "audioPlayback", -            "audioRecording", -            "location", -            "bluetoothInteraction", -            "multiDeviceConnection", -            "wifiInteraction", -            "voip", -            "taskKeeping" -        ], -    }], -} -``` - -#### skills对象内部结构 - -该标签标识ability或者extension能够接收的意图的特征。 - -表7 skills内部结构示例 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | ---------- | -------------------- | -| actions | 该标签标识能够接收的意图的action值的集合，取值通常为系统预定义的action值，也允许自定义。 | 字符串数组 | 可缺省，缺省值为空。 | -| entities | 该标签标识能够接收的Intent的元能力的类别集合，取值通常为系统预定义的类别，也允许自定义。 | 字符串数组 | 可缺省，缺省值为空。 | -| uris | 该标签标识向 want过滤器添加数据规范集合。该规范可以是只有数据类型（mimeType 属性），可以是只有 URI，也可以是既有数据类型又有 URI。uris内部结构参考表8。 | 对象数组 | 可缺省，缺省值为空。 | - -表8 uris对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------- | -------- | -------------------- | -| scheme | 表示uri的scheme值。 | 字符串 | 不可缺省。 | -| host | 表示uri的host值。 | 字符串 | 可缺省，缺省值为空。 | -| port | 表示uri的port值。 | 字符串 | 可缺省，缺省值为空。 | -| path | 表示uri的path值。 | 字符串 | 可缺省，缺省值为空。 | -| type | 表示uri的type值。 | 字符串 | 可缺省，缺省值为空。 | - -skills示例 - -```json -{ -    "abilities": [ -        { -            "skills": [ -                { -                    "actions": [ -                        "action.system.home" -                    ], -                    "entities": [ -                        "entity.system.home" -                    ], -                    "uris": [ -                        { -                            "scheme":"uri2", -                            "host":"host2", -                            "port":"port2", -                            "pathStartWith":"path2", -                            "pathRegex":"/query/.*", -                            "path":"path", -                            "type": "text/*" -                        }, -                    ] -                } -            ], -        } -    ], -    "extensionAbilities": [ -        { -            "skills": [ -                { -                    "actions": [ -                    ], -                    "entities": [ -                    ], -                    "uris": [ -                        { -                            "scheme":"uri2", -                            "host":"host2", -                            "port":"port2", -                            "pathStartWith":"path2", -                            "pathRegex":"/query/.*", -                            "path":"path", -                            "type": "text/*" -                        }, -                    ] -                } -            ], -        } -    ], -} -``` - -#### extensionAbility对象的内部结构说明 - -描述extensionAbility的配置信息，标签值为数组类型，该标签下的配置只对当前extensionAbility生效。 - -表9 extensionAbility对象内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ----------- | ------------------------------------------------------------ | ---------- | ----------------------------- | -| name | 该标签标识当前extensionAbility的逻辑名，标签值采用字符串表示（最大长度127个字节），该名称在整个应用要唯一。 | 字符串 | 该标签不可缺省。 | -| srcEntrance | 该标签表示extensionAbility所对应的js代码路径，标签值为字符串（最长为127字节）。 | 字符串 | 该标签不可缺省。 | -| description | 该标签标识extensionAbility的描述，标签值是是字符串类型或对描述内容的资源索引，以支持多语言。 | 字符串 | 该标签可缺省，缺省值为空。 | -| icon | 该标签标识extensionAbility图标，标签值为资源文件的索引。如果extensionAbility被配置为MainElement，该标签必须配置。 | 字符串 | 该标签可缺省，缺省值为空。 | -| label | 该标签标识extensionAbility对用户显示的名称，标签值配置为该名称的资源索引以支持多语言。
如果extensionAbility被配置为MainElement，该标签必须配置，且应用内唯一。 | 字符串 | 该标签不可缺省。 | -| type | 该标签标识extensionAbility的类型，取值为form、workScheduler、inputMethod、service、accessibility、dataShare、fileShare、staticSubscriber、wallpaper其中之一。 | 字符串 | 该标签不可缺省。 | -| permissions | 该标签标识被其它应用的ability调用时需要申请的权限的集合，字符串数组类型，每个数组元素为一个权限名称，通常采用反向域名方式表示（最大255字节），可以是系统预定义的权限，也可以是该应用自定义的权限。如果是后者，需与defPermissions标签中定义的某个权限的name标签值一致。 | 字符串数组 | 该标签可缺省，缺省值为空。 | -| uri | 该标签标识ability提供的数据uri，为字符数组类型（最大长度255），用反向域名的格式表示。该标签在type为dataShare类型的extensionAbility时，不可缺省。 | 字符串 | 该标签可缺省，缺省值为空。 | -| skills | 该标签标识ability能够接收的意图的特征集，为数组格式。
配置规则： entry包可以配置多个具有入口能力的skills标签（配置了action.system.home和entity.system.home）的ability，其中第一个配置了skills标签的ability中的label和icon作为OpenHarmony服务或应用的label和icon。
OpenHarmony服务的Feature包不能配置具有入口能力的skills标签。
OpenHarmony应用的Feature包可以配置具有入口能力的skills标签。
skills内部结构参考[skills对象内部结构](#skills对象内部结构)。 | 数组 | 该标签可缺省，缺省值为空。 | -| metadata | 该标签表示extensionAbility的元信息。metadata内部结构参考[metadata对象内部结构](#metadata对象内部结构)。 | 对象 | 该标签可缺省，缺省值为空。 | -| visible | 该标签标识extensionAbility是否可以被其它应用调用，为布尔类型。true表示可以被其它应用调用， false表示不可以被其它应用调用。 | | 该标签可缺省，缺省值为false。 | - -extensionAbility示例： - -```json -{ -    "extensionAbilities": [ -        { -            "name": "FormName", -            "srcEntrance": "./form/MyForm.ts", -            "icon": "$media:icon", -            "label" : "$string:extension_name", -            "description": "$string:form_description", -            "type": "form",  -            "permissions": ["ohos.abilitydemo.permission.PROVIDER"], -            "readPermission": "", -            "writePermission": "", -            "visible": true, -            "uri":"scheme://authority/path/query" -            "skills": [{ -                "actions": [], -                "entities": [], -                "uris": [] -            }], -            "metadata": [ -                { -                    "name": "ohos.extability.form", -                    "resource": "$profile:form_config",  -                } -            ], -        } -    ] -} - -``` - -#### requestPermissions对象内部结构 - -该标签标识应用运行时需向系统申请的权限集合。 - -表10 requestPermissions权限申请字段说明 - -| 属性名称 | 含义 | **类型** | **取值范围** | **默认值** | **规则约束** | -| --------- | ------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------- | ---------------------- | ------------------------------------------------------------ | -| name | 必须，填写需要使用的权限名称。 | 字符串 | 自定义 | 无 | 未填写时，解析失败。 | -| reason | 可选，当申请的权限为user_grant权限时此字段必填。描述申请权限的原因。 | 字符串 | 显示文字长度不能超过256个字节。 | 空 | user_grant权限必填，否则不允许在应用市场上架。需做多语种适配。 | -| usedScene | 可选，当申请的权限为user_grant权限时此字段必填。描述权限使用的场景和时机。场景类型有：ability、when（调用时机）。可配置多个ability。 | ability：字符串数组when：字符串 | ability：ability的名称when：inuse（使用时）、always（始终） | ability：空when：inuse | user_grant权限必填ability，可选填when。 | - -requestPermissions示例： - -```json -{ -    "usedScene": { -        "abilities": [ -            "AudioAbility", -            "VedioAbility", -        ], -        "when": "inuse" -    } -} -``` - -#### form对象内部结构 - -forms标签表示卡片的配置，form卡片是可以嵌入桌面上并接收定期更新的应用简要视图。在以下场景中可以包含form标签。 - -1. extensions中指定type为form。 - -2. metadata中指定form信息，其中： - name：指定form的名称。使用ohos.extability.form作为form信息的标识。 - resource：指定form信息的资源位置。 - -表11 forms对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ----------------- | ------------------------------------------------------------ | ---------- | ----------------------------- | -| name | 表示卡片的类名。字符串最大长度为127字节。 | 字符串 | 否 | -| description | 表示卡片的描述。取值可以是描述性内容，也可以是对描述性内容的资源索引，以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省，缺省为空。 | -| src | 该标签标识JS卡片对应的UI代码。建议开发者通过自适应布局显示不同规格卡片，如果不同规格卡片布局相差较大，建议通过不同卡片来区分。 | 字符串 | 可缺省，缺省为空。 | -| window | 该标签标识JS卡片的自适应能力。window结构参考表12。 | 对象 | 可缺省，缺省为空。 | -| isDefault | 表示该卡片是否为默认卡片，每个Ability有且只有一个默认卡片。 true：默认卡片。 false：非默认卡片。 | 布尔值 | 否 | -| colorMode | 表示卡片的主题样式，取值范围如下： auto：自适应。 dark：深色主题。 light：浅色主题。 | 字符串 | 可缺省，缺省值为“auto”。 | -| supportDimensions | 表示卡片支持的外观规格，取值范围： 1 * 2：表示1行2列的二宫格。 2 * 2：表示2行2列的四宫格。 2 * 4：表示2行4列的八宫格。 4 * 4：表示4行4列的十六宫格。 | 字符串数组 | 否 | -| defaultDimension | 表示卡片的默认外观规格，取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 否 | -| updateDuration | 该标签标识卡片定时刷新的更新频率，单位为30分钟，取值为30的倍数值。卡片的最高频率为每30分钟刷新一次，和定点刷新二选一，二者都配置的情况下，定时优先。 | 数值 | 可缺省，缺省为空。 | -| metadata | 该标签表示卡片的自定义信息。metadata内部结构参考表5。 | 对象 | 可缺省，缺省为空。 | -| formConfigAbility | 该标签标识卡片调整的Ability名称。标签值为字符串类型（最长127字符）。该标签值必须满足下面的格式：
ability://单个ability名字
单个ability名字必须为本应用的ability。 | 字符串 | 可缺省，缺省为空。 | -| formVisibleNotify | 该标签标识卡片是否被允许使用卡片可见性通知。标签值为true或false | 布尔值 | 该标签可缺省，默认值为false。 | - -表12 window内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| --------------- | ------------------------------------------------------------ | -------- | -------------------- | -| designWidth | 指示页面设计的基线宽度，以像素为单位。 元素的大小由实际设备宽度缩放。 这个标签是一个整数。 | 数值 | 可缺省，缺省值为空。 | -| autoDesignWidth | 指定是否自动计算页面设计的基线宽度。 如果设置为true，则designWidth属性无效。基线宽度根据设备宽度和屏幕密度计算。 | 布尔值 | 可缺省，缺省值为空。 | - -form示例： - -在开发视图的resources/base/profile下面定义配置文件form_config.json（文件名称可由开发者定义） - -```json -{ -    "forms": [ -        { -            "name": "Form_Js", -            "description": "$string:form_description", -            "src": "./js/pages/card/index", -            "window": { -                "designWidth": 720, -                "autoDesignWidth": true -            }, -            "colorMode": "auto", -            "formConfigAbility": "ability://xxxxx", -            "formVisibleNotify": false, -            "isDefault": true, -            "updateEnabled": true, -            "scheduledUpdateTime": "10:30", -            "updateDuration": 1, -            "defaultDimension": "2*2", -            "supportDimensions": [ -                "2*2" -            ], -           "metadata": [ -             { -                "name": "string", -                "value": "string", -                "resource": "$profile:config_file" -             } -           ]  -        } -    ] -} -``` - -在module.json的extension组件下面定义metadata信息 - -```json -{ - "extensionAbilities": [ - { - "name": "MyForm", - "type": "form",  - "metadata": [ - { - "name": "ohos.extability.form", - "resource": "$profile:form_config", - } - ], - } - ] -} -``` - -#### shortcuts对象内部结构 - -标识应用的快捷方式信息。标签值为数组，最多可以配置四个快捷方式。其包含四个子标签shortcutId、label、icon、intents。 - -metadata中指定shortcut信息，其中： -1）name：指定shortcuts的名称。使用ohos.ability.shortcut作为shortcuts信息的标识。 -2）resource：指定shortcuts信息的资源位置。 - -表13 shortcuts对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ---------- | ------------------------------------------------------------ | -------- | -------------------------- | -| shortcutId | 表示快捷方式的ID。字符串的最大长度为63字节。 | 字符串 | 否 | -| label | 表示快捷方式的标签信息，即快捷方式对外显示的文字描述信息。取值可以是描述性内容，也可以是标识label的资源索引。字符串最大长度为63字节。 | 字符串 | 可缺省，缺省为空。 | -| icon | 该标签标识shortcut的图标，标签值为资源文件的索引。 | 字符串 | 该标签可缺省，缺省值为空。 | -| wants | 该标签标识快捷方式内定义的目标wants信息集合，每个want可配置两个子标签，bundleName，abilityName。
bundleName：快捷方式目标包名，字符串类型。
abilityName：快捷方式的目标组件名，字符串类型。 | 对象 | 该标签可缺省，缺省为空。 | - -在开发视图的resources/base/profile下面定义配置文件shortcut_config.json（文件名称可由开发者定义）。 - -```json -{ -        "shortcuts": [ -            { -                "shortcutId": "id_test1", -                "label": "$string:shortcut", -                "icon": "$media:aa_icon", -                "wants": [ -                    { -                       "bundleName": "com.ohos.hello" -                       "abilityName": "MainAbility" -                    } -                ] -            } -        ] -} -``` - -在config.json的module下面定义metadata信息，如下： - -```json -{ -    "module": { -        "name": "MyAbilityStage", -        "abilities" : [ -            { -                "name" : "MyAbility", -                "srcEntrance": "./abilities/MyAbility.ts", -                "skills": [{ -                            "actions": ["action.system.home"], -                            "entities": ["entity.system.home"], -                            "uris": [] -                }], -                "metadata": [ -                    { -                        "name": "ohos.ability.shortcut", -                        "resource": "$profile:shortcuts_config",  -                    } -                ], -            } -        ] -    } -} -``` - -#### commonEvents对象内部结构 - -commonEvents标签标识注册静态公共事件信息。标签值为数组。 -metadata中指定commonEvent信息，其中： - -1. name：指定commonEvent的名称。使用ohos.extability.staticSubscriber作为commonEvent信息的标识。 - -2. resource：指定commonEvent信息的资源位置。 - -表14 commonEvents对象内部结构 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ---------- | ------------------------------------------------------------ | ---------- | -------------------------- | -| name | 该标签指明当前静态公共事件对应的ability名，该类需要在ability中标明。 | 字符串 | 该标签不可缺省。 | -| permission | 该标签标识实现该静态公共事件需要申请的权限，以字符串类型表示一个权限名称，通常采用反向域名方式表示（最大255字节）。 | 字符串 | 可缺省，缺省值为空。 | -| types | 该标签配置当前静态公共事件的类别数组，字符串数组类型，每个数组元素为一个类别名称。 | 字符串数组 | 该标签可缺省，缺省值为空。 | -| events | 该标签标识能够接收的意图的event值的集合，取值通常为系统预定义的event值，也允许自定义。 | 字符串数组 | 该标签不可缺省。 | - -在开发视图的resources/base/profile下面定义配置文件common_event_config.json（文件名称可由开发者定义）。 - -```json -{ -    "commonEvents": [ -            { -                "name": "abilityName", -                "permission": "string", -                "types": [ -                    "string", -                    "string" -                ], -                "events": [ -                    "string", -                    "string" -                ] -            } -    ] -} -``` - -在module.json的extension组件下面定义metadata信息，如下： - -```json -"extensionAbilities": [ -    { -        "name": "mySubscriber", -        "srcEntrance": "./extension/my_subscriber.js", -        "type": "staticSubscriber", -        "metadata": [ -            { -                "name": "ohos.extability.staticSubscriber", -                "resource": "$profile:common_event_config",  -            } -        ], -    } -] -``` - -#### distroFilter对象内部结构 - -表示应用的分发规则。 - -该标签用于定义HAP包对应的细分设备规格的分发策略，以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括API Verion、屏幕形状、屏幕分辨率。在进行分发时，通过deviceType与这三个属性的匹配关系，唯一确定一个用于分发到设备的HAP。 - -表15 distroFilter对象内部结构 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------------- | ------------------------------------------------------------ | -------- | -------------------------- | -| apiVersion | 表示支持的apiVersion范围。参考表16。 | 对象数组 | 该标签可缺省，缺省值为空。 | -| screenShape | 表示屏幕形状的支持策略。 | 对象数组 | 该标签可缺省，缺省值为空。 | -| screenWindow | 表示应用运行时窗口的分辨率支持策略。该字段仅支持对轻量级智能穿戴设备进行配置。 | 对象数组 | 该标签可缺省，缺省值为空。 | -| screenDensity | 该标签表示屏幕的像素密度（dpi：Dot Per Inch）。该字段可选，如果配置了该字段，取值必须合法。该标签为字符串数组，字符串范围如下。
sdpi：表示小规模的屏幕密度（Small-scale Dots per Inch），适用于dpi取值为（0,120]的设备。
mdpi：表示中规模的屏幕密度(Medium-scale Dots Per Inch)，适用于dpi取值为(120,160]的设备。
ldpi：表示大规模的屏幕密度(Large-scale Dots Per Inch)，适用于dpi取值为(160,240]的设备。
xldpi：表示大规模的屏幕密度(Extra Large-scale Dots Per Inch)，适用于dpi取值为(240,320]的设备。
xxldpi：表示大规模的屏幕密度(Extra Extra Large-scale Dots Per Inch)，适用于dpi取值为(320，480]的设备。
xxxldpi：表示大规模的屏幕密度(Extra Extra Extra Large-scale Dots Per Inch)，适用于dpi取值为(480, 640]的设备。 | 对象数组 | 该标签可缺省，缺省值为空。 | -| countryCode | 该标签表示应用需要分发的国家地区码，具体值以ISO-3166-1标准为准。支持多个国家和地区枚举定义。该字段可选，如果配置了该字段，取值必须合法。标签值字符串数组，子串表示所支持的国家或地区，由两个大写字母组成。 | 对象数组 | 该标签可缺省，缺省值为空。 | - -表16 apiVersion对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 表示该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单，满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省，缺省值为空。 | -| value | 支持的取值为API Version存在的整数值，例如4、5、6。场景示例：某应用，针对相同设备型号，同时在网的为使用API 5和API 6开发的两个软件版本，则允许上架2个entry类型的安装包，分别支持到对应设备侧软件版本的分发。 | 数组 | 可缺省，缺省值为空。 | - -表17 screenShape对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 表示该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单，满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省，缺省值为空。 | -| value | 支持的取值为circle（圆形）、rect（矩形）。场景示例：针对智能穿戴设备，可为圆形表盘和矩形表盘分别提供不同的HAP。 | 数组 | 可缺省，缺省值为空。 | - -表18 screenWindow对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 表示该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单，满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省，缺省值为空。 | -| value | 单个字符串的取值格式为：“宽 * 高”，取值为整数像素值，例如“454 * 454”。 | 数组 | 可缺省，缺省值为空。 | - -表19 screenDensity对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 表示该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单，满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省，缺省值为空。 | -| value | 该标签表示屏幕的像素密度（dpi：Dot Per Inch）。 | 数组 | 可缺省，缺省值为空。 | - -表20 countryCode对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 表示该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单，满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省，缺省值为空。 | -| value | 该标签表示应用需要分发的国家地区码。 | 数组 | 可缺省，缺省值为空。 | - -distroFilter示例： - -在开发视图的resources/base/profile下面定义配置文件distroFilter_config.json（文件名称可由开发者定义）。 - -```json -"distroFilter": [ - { - "apiVersion": { - "policy": "include", - "value": [4,5] - }, - "screenShape": { - "policy": "include", - "value": ["circle","rect"] - }, - "screenWindow": { - "policy": "include", - "value": ["454*454","466*466"] - } - } -] -``` - -在module.json的extensionAbilities组件下面定义metadata信息，如下： - -```json -"extensionAbilities": [ -    { -        "name": "mySubscriber", -        "srcEntrance": "./extension/my_subscriber.js", -        "type": "staticSubscriber",  -        "metadata": [ -            { -                "name": "ohos.extability.staticSubscriber", -                "resource": "$profile:distroFilter_config",  -            } -        ], -    } -] - -``` - diff --git a/zh-cn/application-dev/quick-start/start-overview.md b/zh-cn/application-dev/quick-start/start-overview.md index a5997fff869e3a7fcdb9471e2816bd829d95c96f..f1b73a5644d6925f51fa32bdf1fd03eebaa49657 100644 --- a/zh-cn/application-dev/quick-start/start-overview.md +++ b/zh-cn/application-dev/quick-start/start-overview.md @@ -34,7 +34,7 @@ Ability可以分为[FA（Feature Ability）](../../glossary.md#f)和[PA（Partic ![zh-cn_image_0000001215206886](figures/zh-cn_image_0000001215206886.png) -快速入门提供了一个含有两个页面的Page Ability实例。更多Ability的开发内容及指导，请参见[Ability开发](../ability/ability-brief.md)。 +快速入门提供了一个含有两个页面的Page Ability实例。更多Ability的开发内容及指导，请参见[Ability开发](../ability/fa-brief.md)。 ## 工具准备 diff --git a/zh-cn/application-dev/quick-start/syscap.md b/zh-cn/application-dev/quick-start/syscap.md new file mode 100644 index 0000000000000000000000000000000000000000..fc087039685ab1f03abe432b469c9e9c26c53511 --- /dev/null +++ b/zh-cn/application-dev/quick-start/syscap.md @@ -0,0 +1,180 @@ +# SysCap使用指南 + +## 概述 + +### 系统能力与 API + +SysCap，全称SystemCapability，即系统能力，指操作系统中每一个相对独立的特性，如蓝牙，WIFI，NFC，摄像头等，都是系统能力之一。每个系统能力对应多个 API，这些 API 绑定在一起，随着目标设备是否支持该系统能力共同存在或消失，也会随着 IDE 一起提供给开发者做联想。 + +![image-20220326064841782](figures/image-20220326064841782.png) + + + +### 支持能力集，联想能力集与要求能力集 + +支持能力集，联想能力集与要求能力集都是系统能力的集合。 +支持能力集描述的是设备能力，要求能力集描述的是应用能力。若应用A的要求能力集是设备N的支持能力集的子集，则应用A可分发到设备N上安装运行，否则不能分发。 +联想能力集是该应用开发时，IDE 可联想的 API 所在的系统能力集合。 + +![image-20220326064913834](figures/image-20220326064913834.png) + + + +### 设备与支持能力集 + +每个设备根据其硬件能力，对应不同的支持能力集。 +SDK 将设备分为两组，爆款设备和自定义设备，爆款设备的支持能力集由 OpenHarmony 来定义，自定义设备由设备厂商给出。 + +![image-20220326064955505](figures/image-20220326064955505.png) + + + +### 设备与SDK能力的对应 + +SDK 提供全量的 API 给 IDE，IDE 通过开发者的项目支持的设备，找到该设备的支持能力集，筛选支持能力集包含的 API 提供给开发者做联想。 + +![image-20220326065043006](figures/image-20220326065043006.png) + + + +## SysCap开发指导 + +### PCID导入 + +DevEco Studio 工程支持 PCID 的导入。导入的 PCID 文件解码后输出的 syscap 会被写入 syscap.json 文件中。 + +在工程目录右键后选择 Import Product Compatibility ID，即可上传 PCID 文件并导入至 syscap.json 中。 + +![20220329-103626](figures/20220329-103626.gif) + + + +### 配置联想能力集和要求能力集 + +IDE 会根据创建的工程所支持的设置自动配置联想能力集和要求能力集，开发者也可以自行修改。 +对于联想能力集，开发者通过添加更多的系统能力，在 IDE 中可以使用更多的 API，但要注意这些 API 可能在设备上不支持，使用前需要判断。 +对于要求能力集，开发者修改时要十分慎重，修改不当会导致应用无法分发到目标设备上。 + +``` +/* syscap.json */ +{ + devices: { + general: [ /*每一个爆款设备对应一个syscap支持能力集，可配置多个爆款设备*/ + “phone”, + "car, + "pc", + ... + ], + custom: [ /*厂家自定义设备*/ + { + "某自定义设备": [ + "SystemCapability.Communication.SoftBus.Core", + ... + ] + }, + ... + ] + }, + development: { /*addedSysCaps内的sycap集合与devices中配置的各设备支持的syscap集合的并集共同构成联想能力集*/ + addedSysCaps: [ + "SystemCapability.Location.Location.Lite", + ... + ] + }, + production: { /*用于生成rpcid，慎重添加，可能导致应用无法分发到目标设备上*/ + addedSysCaps: [], //devices中配置的各设备支持的syscap集合的交集，添加addedSysCaps集合再除去removedSysCaps集合，共同构成要求能力集 + removedSysCaps: [] //当该要求能力集为某设备的子集时，应用才可被分发到该设备上 + } +} +``` + + + +### 单设备应用开发 + +默认应用的联想能力集、要求系统能力集和设备的支持系统能力集相等，开发者修改要求能力集需要慎重。 + +![image-20220326065124911](figures/image-20220326065124911.png) + + + +### 跨设备应用开发 + +默认应用的联想能力集是多个设备支持能力集的并集，要求能力集则是交集。 + +![image-20220326065201867](figures/image-20220326065201867.png) + + + +### 判断 API 是否可以使用 + +首先我们定义了 API canIUse 帮助开发者来判断该工程是否支持某个特定的syscap。 + +``` +if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { + console.log("该应用支持SystemCapability.ArkUI.ArkUI.Full"); +} else { + console.log("该应用不支持SystemCapability.ArkUI.ArkUI.Full"); +} +``` + +开发者可通过 import 的方式将模块导入，若当前设备不支持该模块，import 的结果为 undefined，开发者在使用其 API 时，需要判断其是否存在。 + +``` +import geolocation from '@ohos.geolocation'; + +if (geolocation) { + geolocation.getCurrentLocation((location) => { + console.log(location.latitude, location.longitude); + }); +} else { + console.log('该设备不支持位置信息')； +} +``` + + + +### 不同设备相同能力的差异检查 + +即使是相同的系统能力，在不同的设备下，也会有能力的差异。比如同是摄像头的能力，手机比手表要强很多。 + +``` +import userAuth from '@ohos.userIAM.userAuth'; + +const authenticator = userAuth.getAuthenticator(); +const result = authenticator.checkAbility('FACE_ONLY', 'S1'); + +if (result == authenticator.CheckAvailabilityResult.AUTH_NOT_SUPPORT) { + console.log('该设备不支持人脸识别'); +} +//强行调用不支持的 API 会返回错误信息，但不会出现语法错误。 +authenticator.execute('FACE_ONLY', 'S1', (err, result) => { + if (err) { + console.log(err.message); + return; + } +}) +``` + + +### 设备间的SysCap差异如何产生的 + +设备的SysCap因产品解决方案厂商拼装的部件组合不同而不同，整体流程如下图： + +![image-20220326072448840](figures/image-20220326072448840.png) + +1、一套 OpenHarmony 源码由可选和必选部件集组成，不同的部件为对外体现的系统能力不同，即部件与 SysCap 之间映射关系。 + +2、发布归一化的 SDK，API 与 SysCap 之间存在映射关系。 + +3、产品解决方案厂商按硬件能力和产品诉求，可按需拼装部件。 + +4、产品配置的部件可以是 OpenHarmony 的部件，也可以是三方开发的私有部件，由于部件与SysCap间存在映射，所有拼装后即可得到该产品的SysCap集合。 + +5、SysCap集编码生成 PCID (Product Compatibility ID， 产品兼容性标识)，应用开发者可将 PCID 导入 IDE解码成SysCap ，开发时对设备的SysCap差异做兼容性处理。 + +6、部署到设备上的系统参数中包含了 SysCap 集，系统提供了native的接口和应用接口，可供系统内的部件和应用查询某个 SysCap 是否存在。 + +7、应用开发过程中，应用必要的 SysCap 将被编码成 RPCID（Required Product Compatibility ID），并写入应用安装包中。应用安装时，包管理器将解码 RPCID 得到应用需要的 SysCap，与设备当前具备的 SysCap 比较，若应用要求的 SysCap 都被满足，则安装成功。 + +8、应用运行时，可通过 canIUse 接口查询设备的 SysCap，保证在不同设备上的兼容性。