diff --git a/zh-cn/application-dev/quick-start/Readme-CN.md b/zh-cn/application-dev/quick-start/Readme-CN.md index 8564922f56546d78b3380b69d362c6f1b5d8ba10..1512e6a856e3d5c6e34de7a5793e0a2650db669c 100755 --- a/zh-cn/application-dev/quick-start/Readme-CN.md +++ b/zh-cn/application-dev/quick-start/Readme-CN.md @@ -1,22 +1,42 @@ # 入门 + - 快速入门 - [开发准备](start-overview.md) - [使用ArkTS语言开发(Stage模型)](start-with-ets-stage.md) - [使用ArkTS语言开发(FA模型)](start-with-ets-fa.md) - [使用JS语言开发(FA模型)](start-with-js-fa.md) - 开发基础知识 - - [应用包结构配置文件的说明(FA模型)](package-structure.md) - - [应用包结构配置文件的说明(Stage模型)](stage-structure.md) - - [SysCap说明](syscap.md) + - 应用程序包基础知识 + - [应用程序包概述](application-package-overview.md) + - 应用程序包结构 + - [Stage模型应用程序包结构](application-package-structure-stage.md) + - [FA模型应用程序包结构](application-package-structure-fa.md) + - [HAR包结构](har-structure.md) + - 应用程序包多HAP机制 + - [多HAP机制设计目标](multi-hap-objective.md) + - [多HAP构建视图](multi-hap-build-view.md) + - [多HAP发布部署流程](multi-hap-release-deployment.md) + - [多HAP使用规则](multi-hap-rules.md) + - [多HAP运行机制及数据通信方式](multi-hap-principles.md) + - [应用程序包安装和卸载流程](application-package-install-uninstall.md) + - 应用配置文件(Stage模型) + - [应用配置文件概述(Stage模型)](application-configuration-file-overview-stage.md) + - [app.json5配置文件](app-configuration-file.md) + - [module.json5配置文件](module-configuration-file.md) + - 应用配置文件(FA模型) + - [应用配置文件概述(FA模型)](application-configuration-file-overview-fa.md) + - [app对象内部结构](app-structure.md) + - [deviceConfig内部结构](deviceconfig-structure.md) + - [module对象内部结构](module-structure.md) - [资源分类与访问](resource-categories-and-access.md) - - 学习ArkTS语言 - - [初识ArkTS语言](arkts-get-started.md) - - ArkTS语法(声明式UI) - - [基本UI描述](arkts-basic-ui-description.md) - - 状态管理 - - [基本概念](arkts-state-mgmt-concepts.md) - - [页面级变量的状态管理](arkts-state-mgmt-page-level.md) - - [应用级变量的状态管理](arkts-state-mgmt-application-level.md) - - [动态构建UI元素](arkts-dynamic-ui-elememt-building.md) - - [渲染控制](arkts-rendering-control.md) - - [使用限制与扩展](arkts-restrictions-and-extensions.md) \ No newline at end of file +- 学习ArkTS语言 + - [初识ArkTS语言](arkts-get-started.md) + - ArkTS语法(声明式UI) + - [基本UI描述](arkts-basic-ui-description.md) + - 状态管理 + - [基本概念](arkts-state-mgmt-concepts.md) + - [页面级变量的状态管理](arkts-state-mgmt-page-level.md) + - [应用级变量的状态管理](arkts-state-mgmt-application-level.md) + - [动态构建UI元素](arkts-dynamic-ui-elememt-building.md) + - [渲染控制](arkts-rendering-control.md) + - [使用限制与扩展](arkts-restrictions-and-extensions.md) \ No newline at end of file diff --git a/zh-cn/application-dev/quick-start/app-configuration-file.md b/zh-cn/application-dev/quick-start/app-configuration-file.md new file mode 100644 index 0000000000000000000000000000000000000000..8c7195d724e22f55af15ba2e6d906f64f1f5ac6e --- /dev/null +++ b/zh-cn/application-dev/quick-start/app-configuration-file.md @@ -0,0 +1,56 @@ +# app.json5配置文件 + + +先通过一个示例,整体认识一下app.json5配置文件。 + +```json +{ + "app": { + "bundleName": "com.application.myapplication", + "vendor": "example", + "versionCode": 1000000, + "versionName": "1.0.0", + "icon": "$media:app_icon", + "label": "$string:app_name", + "description": "$string:description_application", + "distributedNotificationEnabled": true, + "minAPIVersion": 9, + "targetAPIVersion": 9, + "apiReleaseType": "Release", + "debug": false, + "entityType": "media", + "car": { + "minAPIVersion": 8, + } + }, +} +``` + + +app.json5配置文件包含以下标签。 + + + **表1** **app.json5文件配置标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| bundleName | 标识应用的包名,用于标识应用的唯一性。该标签不可缺省。标签的值命名规则 :
- 字符串以字母、数字、下划线和符号“.”组成。
- 以字母开头。
- 最小长度7个字节,最大长度127个字节。
推荐采用反域名形式命名(如com.example.demo,建议第一级为域名后缀com,第二级为厂商/个人名,第三级为应用名,也可以多级)。
其中,随系统源码编译的应用建议命名为“com.ohos.demo”形式, ohos标识OpenHarmony系统应用。 | 字符串 | 该标签不可缺省。 | +| debug | 标识应用是否可调试,该标签由IDE编译构建时生成。
- true:可调试。
- false:不可调式。 | 布尔值 | 该标签可以缺省,缺省为false。 | +| icon | 标识[应用的图标](../application-models/application-component-configuration-stage.md),标签值为图标资源文件的索引。 | 字符串 | 该标签不可缺省。 | +| label | 标识[应用的名称](../application-models/application-component-configuration-stage.md),标签值为字符串资源的索引。 | 字符串 | 该标签不可缺省。 | +| description | 标识应用的描述信息,标签值是字符串类型(最大255个字节)或对描述内容的字符串资源索引。 | 字符串 | 该标签可缺省,缺省值为空。 | +| 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。
标签最大字节长度为127。 | 字符串 | 该标签不可缺省。 | +| minCompatibleVersionCode | 标识应用能够兼容的最低历史版本号,用于跨设备兼容性判断。 | 数值 | 该标签可缺省,缺省值等于versionCode标签值。 | +| minAPIVersion | 标识应用运行需要的SDK的API最小版本。 | 数值 | 由bundle-profile.json5中的compatibleSdkVersion生成。 | +| targetAPIVersion | 标识应用运行需要的API目标版本。 | 数值 | 由bundle-profile.json5中的compileSdkVersion生成。 | +| apiReleaseType | 标识应用运行需要的API目标版本的类型,采用字符串类型表示。取值为“CanaryN”、“BetaN”或者“Release”,其中,N代表大于零的整数。
- Canary:受限发布的版本。
- Beta:公开发布的Beta版本。
- Release:公开发布的正式版本。
该字段由DevEco Studio读取当前使用的SDK的Stage来生成。 | 字符串 | 该标签可缺省,由IDE生成并覆盖。 | +| distributedNotificationEnabled | 标识应用是否开启分布式通知,当开启分布式通知时,同一分布式组网下的两个设备(A和B),当设备A收到一条消息时,设备B会收到一天分布式消息用于设备B的使用者去查看设备A的消息。
- true:开启。
- false:不开启。 | 布尔值 | 该标签可缺省,缺省值为false。 | +| entityType | 标识应用的类别,分别有:
- game:游戏类。
- media:影音类。
- communication:社交通信类。
- news:新闻类。
- travel:出行类。
- utility:工具类。
- shopping:购物类。
- education:教育类。
- kids:少儿类。
- business:商务类。
- photography:拍摄类。
- unspecified:不属于上述的任何一类。 | 字符串 | 该标签可以缺省,缺省为unspecified。 | +| multiProjects | 标识当前工程是否支持多个工程的联合开发。
- true:当前工程支持多个工程的联合开发。
- false:当前工程不支持多个工程的联合开发。 | 布尔值 | 可缺省,缺省值为false。 | +| tablet | 标识对tablet设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。
如果使用该属性对tablet设备做了特殊配置,则应用在tablet设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省,缺省时tablet设备使用app.json5公共区域配置的属性值。 | +| tv | 标识对tv设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。
如果使用该属性对tv设备做了特殊配置,则应用在tv设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省,缺省时tv设备使用app.json5公共区域配置的属性值。 | +| wearable | 标识对wearable设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。
如果使用该属性对wearable设备做了特殊配置,则应用在wearable设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省,缺省时wearable设备使用app.json5公共区域配置的属性值。 | +| car | 标识对car设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。
如果使用该属性对car设备做了特殊配置,则应用在car设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省,缺省时car设备使用app.json5公共区域配置的属性值。 | +| default | 标识对default设备做的特殊配置,可以配置的属性字段有上文提到的:minAPIVersion、distributedNotificationEnabled。
如果使用该属性对default设备做了特殊配置,则应用在default设备中会采用此处配置的属性值,并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省,缺省时default设备使用app.json5公共区域配置的属性值。 | diff --git a/zh-cn/application-dev/quick-start/app-structure.md b/zh-cn/application-dev/quick-start/app-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..9215808ea53459900ed0fc68cd0287bb4f4a7df2 --- /dev/null +++ b/zh-cn/application-dev/quick-start/app-structure.md @@ -0,0 +1,53 @@ +# app对象内部结构 + + +app对象包含应用全局配置信息,内部结构如下: + + + **表1** **app对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| bundleName | 标识应用的包名,用于标识应用的唯一性。包名是由字母、数字、下划线(_)和点号(.)组成的字符串,必须以字母开头。支持的字符串长度为7~127字节。包名通常采用反向域名形式表示(例如,"com.example.myapplication")。建议第一级为域名后缀"com",第二级为厂商/个人名,也可以采用多级。 | 字符串 | 不可缺省。 | +| vendor | 标识对应用开发厂商的描述。字符串长度不超过255字节。 | 字符串 | 可缺省,缺省值为空。 | +|version | 标识应用的版本信息。 | 对象 | 不可缺省。 | +| apiVersion | 标识应用程序所依赖的OpenHarmony API版本。 | 对象 | 可缺省,缺省值为空。 | +| smartWindowSize | 标识应用在模拟器中运行时使用的屏幕尺寸。 | 字符串 | 可缺省,缺省值为空。 | +| smartWindowDeviceType | 标识应用在模拟器中运行时可以模拟的设备。 | 字符串数组 | 可缺省,缺省值为空。 | + + + **表2** **version对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识应用的版本号,用于向应用的终端用户呈现。取值可以自定义,长度不超过127字节。自定义规则如下:API5及更早的版本:推荐使用三段数字版本号(也兼容两段式版本号),如A.B.C(也兼容A.B),其中A、B、C取值为0-999范围内的整数。除此之外不支持其他格式。
A段,一般表示主版本号(Major)。
B段,一般表示次版本号(Minor)。
C段,一般表示修订版本号(Patch)。API6版本起:推荐采用四段式数字版本号,如A.B.C.D,其中A、B、C取值为0-99范围内的整数,D的取值为0-999范围内的整数。
A段,一般表示主版本号(Major)。
B段,一般表示次版本号(Minor)。
C段,一般表示特性版本号(Feature)。
D段,一般表示修订版本号(Patch)。 | 数值 | 不可缺省。 | +| code | 标识应用的版本号,仅用于OpenHarmony管理该应用,不对应用的终端用户呈现。取值规则如下:API5及更早版本:二进制32位以内的非负整数,需要从version.name的值转换得到。转换规则为:code值=A \* 1,000,000 + B \* 1,000 + C例如,version.name字段取值为2.2.1,则code值为2002001。API6版本起:code的取值不与version.name字段的取值关联,开发者可自定义code取值,取值范围为2^31以内的非负整数,但是每次应用版本的更新,均需要更新code字段的值,新版本code取值必须大于旧版本code的值。 | 数值 | 不可缺省。 | +| minCompatibleVersionCode | 标识应用可兼容的最低版本号,用于跨设备场景下,判断其他设备上该应用的版本是否兼容。格式与version.code字段的格式要求相同。 | 数值 | 可缺省,缺省值为code标签值。 | + + + **表3** **apiVersion内部结构** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| compatible | 运行应用所需要的最低API版本,取值范围为0~2147483647。 | 数值 | 配置在build.profile中,打包时由IDE填充到config.json中。 | +| target | 用于标识应用运行时使用的API版本,取值范围为0~2147483647。 | 数值 | 配置在build.profile中,打包时由IDE填充到config.json中。 | +| releaseType | 用于标识应用运行时SDK的状态。
canary:面向特定开发者早期预览版本,不承诺质量,不承诺API稳定。
beta:公开发布的Beta版本,早期Beta版本不承诺API稳定,经历若干次发布后,通过Release Notes对开发者声明该Beta版本为API稳定里程碑,后续版本的API冻结。
release:正式发布版本,承诺质量,API不可变更。当版本处于此状态时版本号中不呈现Stage字段。 | 字符串 | 配置在build.profile中,打包时由IDE填充到config.json中。 | + + +app示例: + +```json +"app": { + "bundleName": "com.example.myapplication", + "vendor": "example", + "version": { + "code": 8, + "name": "8.0.1" + }, + "apiVersion": { + "compatible": 8, + "target": 9, + "releaseType": "Beta1" + } + } +``` diff --git a/zh-cn/application-dev/quick-start/application-configuration-file-overview-fa.md b/zh-cn/application-dev/quick-start/application-configuration-file-overview-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..37e00f3b56bc40b47cb9eb4e61048c6cc312aea9 --- /dev/null +++ b/zh-cn/application-dev/quick-start/application-configuration-file-overview-fa.md @@ -0,0 +1,118 @@ +# 应用配置文件概述(FA模型) + + +每个应用项目必须在项目的代码目录下加入配置文件,这些配置文件会向OpenHarmony的编译工具、OpenHarmony操作系统和应用市场提供描述应用的基本信息。 + + +应用配置文件需申明以下内容: + + +- 应用的软件包名称,应用的开发厂商,版本号等应用的基本配置信息,这些信息被要求设置在app这个字段下。 + +- 应用的组件的基本信息,包括所有的Ability,设备类型,组件的类型以及当前组件所使用的语法类型。 + +- 应用在具体设备上的配置信息,这些信息会影响应用在设备上的具体功能。 + + +在FA模型的应用开发过程中,需要在config.json配置文件中对应用的包结构进行声明。 + + +## 配置文件的内部结构 + +config.json由app、deviceConfig和module三个部分组成,缺一不可。 + + | 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| [app](app-structure.md) | 标识应用的全局配置信息。同一个应用的不同HAP的app配置必须保持一致。 | 对象 | 不可缺省。 | +| [deviceConfig](deviceconfig-structure.md) | 标识应用在具体设备上的配置信息。 | 对象 | 不可缺省。 | +| [module](module-structure.md) | 标识HAP的配置信息。该标签下的配置只对当前HAP生效。 | 对象 | 不可缺省。 | + +config.json示例: + + +```json +{ + "app": { + "vendor": "example", + "bundleName": "com.example.demo", + "version": { + "code": 1000000, + "name": "1.0.0" + } + }, + "deviceConfig": { + }, + "module": { + "mainAbility": ".MainAbility_entry", + "deviceType": [ + "tablet" + ], + "commonEvents": [ + { + "name": ".MainAbility", + "permission": "ohos.permission.GET_BUNDLE_INFO", + "data": [ + "com.example.demo", + "100" + ], + "events": [ + "install", + "update" + ] + } + ], + "abilities": [ + { + "skills": [ + { + "entities": [ + "entity.system.home" + ], + "actions": [ + "action.system.home" + ] + } + ], + "orientation": "unspecified", + "visible": true, + "srcPath": "MainAbility_entry", + "name": ".MainAbility_entry", + "srcLanguage": "ets", + "icon": "$media:icon", + // $string:MainAbility_entry_desc为资源索引 + "description": "$string:MainAbility_entry_desc", + "formsEnabled": false, + // $string:MainAbility_entry_label为资源索引 + "label": "$string:MainAbility_entry_label", + "type": "page", + "launchType": "standard" + } + ], + "distro": { + "moduleType": "entry", + "installationFree": false, + "deliveryWithInstall": true, + "moduleName": "myapplication" + }, + "package": "com.example.myapplication", + "srcPath": "", + "name": ".myapplication", + "js": [ + { + "mode": { + "syntax": "ets", + "type": "pageAbility" + }, + "pages": [ + "pages/index" + ], + "name": ".MainAbility_entry", + "window": { + "designWidth": 720, + "autoDesignWidth": false + } + } + ] + } +} +``` diff --git a/zh-cn/application-dev/quick-start/application-configuration-file-overview-stage.md b/zh-cn/application-dev/quick-start/application-configuration-file-overview-stage.md new file mode 100644 index 0000000000000000000000000000000000000000..c55b1e8efe9775472a5615002bc4116dd5078da9 --- /dev/null +++ b/zh-cn/application-dev/quick-start/application-configuration-file-overview-stage.md @@ -0,0 +1,25 @@ +# 应用配置文件概述(Stage模型) + + +每个应用项目必须在项目的代码目录下加入配置文件,这些配置文件会向编译工具、操作系统和应用市场提供应用的基本信息。 + + +在基于Stage模型开发的应用项目代码下,都存在一个app.json5及一个或多个module.json5这两种配置文件。 + + +[app.json5](app-configuration-file.md)主要包含以下内容: + + +- 应用的全局配置信息,包含应用的包名、开发厂商、版本号等基本信息。 + +- 特定设备类型的配置信息。 + + +[module.json5](module-configuration-file.md)主要包含以下内容: + + +- Module的基本配置信息,例如Module名称、类型、描述、支持的设备类型等基本信息。 + +- [应用组件](../application-models/stage-model-development-overview.md)信息,包含UIAbility组件和ExtensionAbility组件的描述信息。 + +- 应用运行过程中所需的权限信息。 diff --git a/zh-cn/application-dev/quick-start/application-package-install-uninstall.md b/zh-cn/application-dev/quick-start/application-package-install-uninstall.md new file mode 100644 index 0000000000000000000000000000000000000000..45b5b5547a272c486f81ba51065fb48e4a928b04 --- /dev/null +++ b/zh-cn/application-dev/quick-start/application-package-install-uninstall.md @@ -0,0 +1,8 @@ +# 应用程序包安装和卸载流程 + + +OpenHarmony包管理服务模块对外提供安装、更新和卸载应用的功能,开发者可以调用包管理服务的安装和卸载接口来实现应用的安装、更新和卸载。开发者将应用上架应用市场后,用户可以在端侧设备上进行应用的安装和卸载。 + + + **图1** 应用程序包安装和卸载流程   +![hap-intall-uninstall](figures/hap-intall-uninstall.png) diff --git a/zh-cn/application-dev/quick-start/application-package-overview.md b/zh-cn/application-dev/quick-start/application-package-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..0c01680a7d9b6b59f3810b23e0f1d225c11c95cf --- /dev/null +++ b/zh-cn/application-dev/quick-start/application-package-overview.md @@ -0,0 +1,18 @@ +# 应用程序包概述 + + +用户应用程序泛指运行在设备的操作系统之上,为用户提供特定服务的程序,简称“应用”。一个应用所对应的软件包文件,称为“应用程序包”。 + + + OpenHarmony提供了应用程序包开发、安装、查询、更新、卸载的管理机制,方便开发者开发和管理OpenHarmony应用,具体如下: +- 应用软件所涉及的文件多种多样,开发者可通过OpenHarmony提供的集成开发工具将其开发的可执行代码、资源、三方库等文件整合到一起制作成OpenHarmony应用程序包,便于开发者对应用程序的部署。 + +- 应用软件所涉及的设备类型多种多样,开发者可通过OpenHarmony提供的应用程序包配置文件指定其应用程序包的分发设备类型,便于应用市场对应用程序包的分发管理。 + +- 应用软件所包含的功能多种多样,将不同的功能特性按模块来划分和管理是一种良好的设计方式。OpenHarmony提供了同一应用程序的多包管理的机制,开发者可以将不同的功能特性聚合到不同的包中,方便后续的维护与扩展。 + +- 应用软件涉及的芯片平台多种多样,有x86、ARM等,还有32位、64位之分,OpenHarmony为应用程序包屏蔽了芯片平台的差异,使应用程序包在不同的芯片平台都能够安装运行。 + +- 应用软件涉及的软件信息多种多样,有应用版本、应用名称、组件、申请权限等的信息,OpenHarmony包管理为开发者提供了这些信息的查询接口,方便开发者在程序中查询所需要的包信息。 + +- 应用软件涉及的资源多种多样,有媒体资源、原生资源、字符资源以及国际化的资源等,OpenHarmony包管理将不同的资源归档到不同的目录中,并集成资源索引文件,方便应用对资源的查找和使用。 diff --git a/zh-cn/application-dev/quick-start/application-package-structure-fa.md b/zh-cn/application-dev/quick-start/application-package-structure-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..90b144c28a7aaaf96c1adaef26d051d6c5ea09ac --- /dev/null +++ b/zh-cn/application-dev/quick-start/application-package-structure-fa.md @@ -0,0 +1,24 @@ +# FA模型应用程序包结构 + + +基于[FA模型](application-configuration-file-overview-fa.md)开发的应用,其应用程序包结构如图[应用程序包结构(FA模型)](figures/FA_3.png)所示。开发者需要熟悉应用程序包结构相关的基本概念。 + + +FA模型与Stage模型不同之处在于HAP内部文件存放位置不同,FA模型将所有的资源文件、库文件和代码文件都放在assets文件夹中,在文件夹内部进一步区分。 + + +- config.json是应用配置文件,IDE会自动生成一部分模块代码,开发者按需修改其中的配置。详细字段请参见[应用配置文件](app-structure.md)。 + +- assets是HAP所有的资源文件、库文件和代码文件的集合,内部可以分为entry和js文件夹。entry文件夹中存放的是resources目录和resources.index文件。 + +- resources目录用于存放应用的资源文件(字符串、图片等),便于开发者使用和维护,详见[资源文件的使用](../key-features/multi-device-app-dev/resource-usage.md/)。 + +- resources.index是资源索引表,由IDE调用SDK工具生成。 + +- js文件夹中存放的是编译后的代码文件。 + +- pack.info是Bundle中用于描述每个HAP属性的文件,例如app中的bundleName和versionCode信息、module中的name、type和abilities等信息,由IDE工具生成Bundle包时自动生成。 + + +**图1** 应用程序包结构(FA模型)   +![FA_3](figures/FA_3.png) diff --git a/zh-cn/application-dev/quick-start/application-package-structure-stage.md b/zh-cn/application-dev/quick-start/application-package-structure-stage.md new file mode 100644 index 0000000000000000000000000000000000000000..9802e5b7ed37812ecd581afc24bb49a47c4ef38b --- /dev/null +++ b/zh-cn/application-dev/quick-start/application-package-structure-stage.md @@ -0,0 +1,30 @@ +# Stage模型应用程序包结构 + + +基于[Stage模型](application-configuration-file-overview-stage.md)开发的应用,经编译打包后,其应用程序包结构如图[应用程序包结构(Stage模型)](figures/Stage-.png)所示。开发者需要熟悉应用程序包结构相关的基本概念。 + + +- 在开发态,一个应用包含一个或者多个Module,可以在[DevEco Studio](https://developer.harmonyos.com/cn/develop/deveco-studio/)工程中[创建一个或者多个Module](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3)。Module是OpenHarmony应用/服务的基本功能单元,包含了源代码、资源文件、第三方库及应用/服务配置文件,每一个Module都可以独立进行编译和运行。Module分为“Ability”和“Library”两种类型,“Ability”类型的Module对应于编译后的HAP(Harmony Ability Package);“Library”类型的Module对应于[HAR](har-structure.md)(Harmony Ability Resources)包,即编译后的.tgz文件。 + 一个Module可以包含一个或多个[UIAbility](../application-models/uiability-overview.md)组件,如[Module与UIAbility组件关系示意图](figures/ability-and-module.png)所示。 + + **图1** Module与UIAbility组件关系示意图   + ![ability-and-module](figures/ability-and-module.png) + + 全文中介绍到的Module默认指的是“Ability”类型的Module。 + +- 开发者通过DevEco Studio把应用程序编译为一个或者多个.hap后缀的文件,即HAP。HAP是OpenHarmony应用安装的基本单位,包含了编译后的代码、资源、三方库及配置文件。HAP可分为Entry和Feature两种类型。 + - Entry类型的HAP:是应用的主模块,在[module.json5配置文件](module-configuration-file.md)中的type标签配置为“entry”类型。在同一个应用中,同一设备类型只支持一个Entry类型的HAP,通常用于实现应用的入口界面、入口图标、主特性功能等。 + - Feature类型的HAP:是应用的动态特性模块,在[module.json5配置文件](module-configuration-file.md)中的type标签配置为“feature”类型。一个应用程序包可以包含一个或多个Feature类型的HAP,也可以不包含;Feature类型的HAP通常用于实现应用的特性功能,可以配置成按需下载安装,也可以配置成随Entry类型的HAP一起下载安装(请参见[module对象内部结构](module-configuration-file.md)中的“deliveryWithInstall”)。 + +- 每个OpenHarmony应用可以包含多个.hap文件,一个应用中的.hap文件合在一起称为一个Bundle,而bundleName就是应用的唯一标识(请参见[app.json5配置文件](app-configuration-file.md)中的bundleName标签)。需要特别说明的是:在应用上架到应用市场时,需要把应用包含的所有.hap文件(即Bundle)打包为一个.app后缀的文件用于上架,这个.app文件称为App Pack(Application Package),其中同时包含了描述App Pack属性的pack.info文件;在云端分发和端侧安装时,都是以HAP为单位进行分发和安装的。 + +- 打包后的HAP包结构包括ets、libs、resources等文件夹和resources.index、module.json、pack.info等文件。 + - ets目录用于存放应用代码编译后的字节码文件。 + - libs目录用于存放库文件。库文件是OpenHarmony应用依赖的第三方代码(例如.so、.jar、.bin、.har等二进制文件)。 + - resources目录用于存放应用的资源文件(字符串、图片等),便于开发者使用和维护,详见[资源文件的使用](../key-features/multi-device-app-dev/resource-usage.md/)。 + - resources.index是资源索引表,由IDE编译工程时生成。 + - module.json是HAP的配置文件,内容由工程配置中的module.json5和app.json5组成,该文件是HAP中必不可少的文件。IDE会自动生成一部分默认配置,开发者按需修改其中的配置。详细字段请参见[应用配置文件](application-configuration-file-overview-stage.md)。 + - pack.info是Bundle中用于描述每个HAP属性的文件,例如app中的bundleName和versionCode信息、module中的name、type和abilities等信息,由IDE工具生成Bundle包时自动生成。 + + **图2** 应用程序包结构(Stage模型)   + ![Stage-](figures/Stage-.png) diff --git a/zh-cn/application-dev/quick-start/arkts-rendering-control.md b/zh-cn/application-dev/quick-start/arkts-rendering-control.md index 11066681cec9d1e13a10c4031dd407c9e72abb70..ca790fe5297a28cd749c4d9bb8904b311b18c631 100644 --- a/zh-cn/application-dev/quick-start/arkts-rendering-control.md +++ b/zh-cn/application-dev/quick-start/arkts-rendering-control.md @@ -34,7 +34,7 @@ Column() { 通过循环渲染(ForEach)从数组中获取数据,并为每个数据项创建相应的组件,可减少代码复杂度。 -``` +```ts ForEach( arr: any[], itemGenerator: (item: any, index?: number) => void, diff --git a/zh-cn/application-dev/quick-start/deviceconfig-structure.md b/zh-cn/application-dev/quick-start/deviceconfig-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..2cc6bff50cd16a1344098e02907ced6d1946584f --- /dev/null +++ b/zh-cn/application-dev/quick-start/deviceconfig-structure.md @@ -0,0 +1,78 @@ +# deviceConfig内部结构 + + +deviceConfig包含设备上的应用配置信息,可以包含default,tv,car,wearable等属性。default标签内的配置适用于所有通用设备,其他设备类型如果有特殊的需求,则需要在该设备类型的标签下进行配置。 + + + **表1** **deviceConfig对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| default | 能够使用全部系统能力的OpenHarmony设备。 | 对象 | 可缺省,缺省值为空。 | +| tablet | 标识平板的应用配置信息。 | 对象 | 可缺省,缺省值为空。 | +| tv | 标识智慧屏特有的应用配置信息。 | 对象 | 可缺省,缺省值为空。 | +| car | 标识车机特有的应用配置信息。 | 对象 | 可缺省,缺省值为空。 | +| wearable | 标识智能穿戴特有的应用配置信息。 | 对象 | 可缺省,缺省值为空。 | + + +上表中各类设备对象的内部结构说明请见表2。 + + + **表2** **deviceConfig设备对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| process | 标识应用或者Ability的进程名。如果在deviceConfig标签下配置了process标签,则该应用的所有Ability都运行在这个进程中。如果在abilities标签下也为某个Ability配置了process标签,则该Ability就运行在这个进程中。该标签最大长度为31。 | 字符串 | 可缺省,缺省值为空。 | +| keepAlive | 标识应用是否始终保持运行状态,仅支持系统应用配置,三方应用配置不生效。该标签为布尔类型,可缺省,缺省值为false,如果配置为true,应用将始终保持为运行状态,并在系统启动的时候被系统驱动起来,应用进程退出后,系统也会重新启动应用进程。 | 布尔值 | 可缺省,缺省值为false。 | +| supportBackup | 标识应用是否支持备份和恢复。如果配置为"false",则不支持为该应用执行备份或恢复操作。 | 布尔值 | 可缺省,缺省值为false。 | +| compressNativeLibs | 标识libs库是否以压缩存储的方式打包到HAP。如果配置为"false",则libs库以不压缩的方式存储,HAP在安装时无需解压libs,运行时会直接从HAP内加载libs库。 | 布尔值 | 可缺省,缺省值为false。 | +| network | 标识网络安全性配置。该标签允许应用通过配置文件的安全声明来自定义其网络安全,无需修改应用代码。 | 对象 | 可缺省,缺省值为空。 | + + + **表3** **network对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| cleartextTraffic | 标识是否允许应用使用明文网络流量(例如,明文HTTP)。
true:允许应用使用明文流量的请求。false:拒绝应用使用明文流量的请求。 | 布尔值 | 可缺省,缺省值为false。 | +| securityConfig | 标识应用的网络安全配置信息。 | 对象 | 可缺省,缺省为空。 | + + + **表4** **securityConfig对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| domainSettings | 标识自定义的网域范围的安全配置,支持多层嵌套,即一个domainSettings对象中允许嵌套更小网域范围的domainSettings对象。 | 对象类型 | 可缺省,缺省为空。 | + + + **表5** **domainSettings对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| cleartextPermitted | 标识自定义的网域范围内是否允许明文流量传输。当cleartextTraffic和security同时存在时,自定义网域是否允许明文流量传输以cleartextPermitted的取值为准。true:允许明文流量传输。false:拒绝明文流量传输。 | 布尔类型 | 可缺省,缺省值为空。 | +| domains | 标识域名配置信息,包含两个参数:subdomains和name。subdomains(布尔类型):表示是否包含子域名。如果为"true",此网域规则将与相应网域及所有子网域(包括子网域的子网域)匹配。否则,该规则仅适用于精确匹配项。name(字符串):表示域名名称。 | 对象数组 | 可缺省,缺省值为空。 | + + +deviceConfig示例: + +```json +"deviceConfig": { + "default": { + "process": "com.example.test.example", + "supportBackup": false, + "network": { + "cleartextTraffic": true, + "securityConfig": { + "domainSettings": { + "cleartextPermitted": true, + "domains": [ + { + "subdomains": true, + "name": "example.ohos.com" + } + ] + } + } + } + } +} +``` diff --git a/zh-cn/application-dev/quick-start/figures/20220329-103626.gif b/zh-cn/application-dev/quick-start/figures/20220329-103626.gif deleted file mode 100644 index 1f3a67796fd41dce99b4256a115fd1d0733ebb79..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/20220329-103626.gif and /dev/null differ diff --git a/zh-cn/application-dev/quick-start/figures/FA_3.png b/zh-cn/application-dev/quick-start/figures/FA_3.png new file mode 100644 index 0000000000000000000000000000000000000000..946f05500c4f325fe4a030fc54229fa891ec1d3b Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/FA_3.png differ diff --git a/zh-cn/application-dev/quick-start/figures/Stage-.png b/zh-cn/application-dev/quick-start/figures/Stage-.png new file mode 100644 index 0000000000000000000000000000000000000000..4db7d66ec6cb25cceed7807ec889b4334f76028f Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/Stage-.png differ diff --git a/zh-cn/application-dev/quick-start/figures/ability-and-module.png b/zh-cn/application-dev/quick-start/figures/ability-and-module.png new file mode 100644 index 0000000000000000000000000000000000000000..e81ec6ecacf456079f4d0ca0745513a40de47213 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/ability-and-module.png differ diff --git a/zh-cn/application-dev/quick-start/figures/hap-intall-uninstall.png b/zh-cn/application-dev/quick-start/figures/hap-intall-uninstall.png new file mode 100644 index 0000000000000000000000000000000000000000..cadc8c243bc18ec36b308cc4431f92c4d7fecdf1 Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/hap-intall-uninstall.png differ diff --git a/zh-cn/application-dev/quick-start/figures/hap-multi-view.png b/zh-cn/application-dev/quick-start/figures/hap-multi-view.png new file mode 100644 index 0000000000000000000000000000000000000000..9b176541c70f98cc4c7845e2a53187a8c7c9e27c Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/hap-multi-view.png differ diff --git a/zh-cn/application-dev/quick-start/figures/hap-release.png b/zh-cn/application-dev/quick-start/figures/hap-release.png new file mode 100644 index 0000000000000000000000000000000000000000..f8467537adf6d8982b3196e4bf66ebc25d2cef5f Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/hap-release.png 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 deleted file mode 100644 index 79bf756bc296a3f7129d6e646ab77248110abd06..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/image-20220326064841782.png and /dev/null 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 deleted file mode 100644 index a48d603f708ad817997a7d89128ff392b515ccd2..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/image-20220326064913834.png and /dev/null 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 deleted file mode 100644 index dc42bd80c803721d619354ccf0ac997fdeec83f0..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/image-20220326064955505.png and /dev/null 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 deleted file mode 100644 index 77f386e35358d0a7af65d11e95fb690c9754e992..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/image-20220326065043006.png and /dev/null 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 deleted file mode 100644 index ccb9ad8c7d95788d8734c6627ac12fd019ff7a4b..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/image-20220326065124911.png and /dev/null 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 deleted file mode 100644 index a7119d0acff9135517db82072009a599e51f1b12..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/image-20220326065201867.png and /dev/null 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 deleted file mode 100644 index 93919d2bcd509a00337af36386898d025fd774b4..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/quick-start/figures/image-20220326072448840.png and /dev/null differ diff --git a/zh-cn/application-dev/quick-start/full-sdk-switch-guide.md b/zh-cn/application-dev/quick-start/full-sdk-switch-guide.md index 2cd8fee3503ca7a0cc38a8e3d90fa3d7c51bada5..1e9c4022a1d3b23c0fb1c0f93cad77f096e0b83e 100644 --- a/zh-cn/application-dev/quick-start/full-sdk-switch-guide.md +++ b/zh-cn/application-dev/quick-start/full-sdk-switch-guide.md @@ -60,7 +60,7 @@ full-SDK需要手动下载。请参考[版本说明书](../../release-notes/Open `oh-uni-package.json`文件配置信息如下,其中,`apiVersion`的值以SDK对应的API version为准,`version`的值以SDK文件的版本号为准: - ``` + ```json { "apiVersion": "X", "displayName": "Ets", diff --git a/zh-cn/application-dev/quick-start/har-structure.md b/zh-cn/application-dev/quick-start/har-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..34a14a5b5ac987e2c19228ad537c44ef2a26a8f3 --- /dev/null +++ b/zh-cn/application-dev/quick-start/har-structure.md @@ -0,0 +1,10 @@ +# HAR包结构 + + +HAR(Harmony Ability Resources)包用于实现多个模块或多个工程间的代码共享。HAR包不同于HAP,不能独立安装运行在设备上,只能作为应用模块的依赖项被引用。 + + +HAR包对应DevEco Studio工程中的“Library”类型的[Module](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3)。 + + +OpenHarmony的HAR包复用标准的[npm包](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-development-npm-package-0000001222578434)发布方式,会打包成tar包(后缀为.tgz)。打包后的HAR包中包含源代码、资源文件、module.json文件(Stage模型)或config.json文件(FA模型)等。 diff --git a/zh-cn/application-dev/quick-start/module-configuration-file.md b/zh-cn/application-dev/quick-start/module-configuration-file.md new file mode 100644 index 0000000000000000000000000000000000000000..b87c63a5b12c92f357813e47db6af53efbc3f981 --- /dev/null +++ b/zh-cn/application-dev/quick-start/module-configuration-file.md @@ -0,0 +1,637 @@ +# module.json5配置文件 + + +先通过一个示例,整体认识一下module.json5配置文件。 + +```json +{ + "module": { + "name": "entry", + "type": "entry", + "description": "$string:module_desc", + "mainElement": "EntryAbility", + "deviceTypes": [ + "default", + "tablet" + ], + "deliveryWithInstall": true, + "installationFree": false, + "pages": "$profile:main_pages", + "virtualMachine": "ark", + "metadata": [ + { + "name": "string", + "value": "string", + "resource": "$profile:distrofilter_config" + } + ], + "abilities": [ + { + "name": "EntryAbility", + "srcEntrance": "./ets/entryability/EntryAbility.ts", + "description": "$string:EntryAbility_desc", + "icon": "$media:icon", + "label": "$string:EntryAbility_label", + "startWindowIcon": "$media:icon", + "startWindowBackground": "$color:start_window_background", + "visible": true, + "skills": [ + { + "entities": [ + "entity.system.home" + ], + "actions": [ + "action.system.home" + ] + } + ] + } + ], + "requestPermissions": [ + { + "name": "ohos.abilitydemo.permission.PROVIDER", + "reason": "$string:reason", + "usedScene": { + "abilities": [ + "FormAbility" + ], + "when": "inuse" + } + } + ] + } +} +``` + + +module.json5配置文件包含以下标签。 + + + **表1** **module.json5配置文件配置标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识当前Module的名称,标签值采用字符串表示(最大长度31个字节),该名称在整个应用要唯一。 | 字符串 | 该标签不可缺省。 | +| type | 标识当前Module的类型。类型有两种,分别:
- entry:应用的主模块。
- feature:应用的动态特性模块。 | 字符串 | 该标签不可缺省。 | +| srcEntrance | 标识当前Module所对应的代码路径,标签值为字符串(最长为127字节)。 | 字符串 | 该标签可缺省,缺省值为空。 | +| description | 标识当前Module的描述信息,标签值是字符串类型(最长255字节)或对描述内容的字符串资源索引。 | 字符串 | 该标签可缺省,缺省值为空。 | +| process | 标识当前Module的进程名,标签值为字符串类型(最长为31个字节)。如果在HAP标签下配置了process,该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。
**说明:**
- 仅支持系统应用配置,三方应用配置不生效。 | 字符串 | 可缺省,缺省为app.json5文件下app标签下的bundleName。 | +| mainElement | 标识当前Module的入口UIAbility名称或者ExtensionAbility名称。标签最大字节长度为255。 | 字符串 | 该标签可缺省,缺省值为空。 | +| [deviceTypes](#devicetypes标签) | 标识当前Module可以运行在哪类设备上,标签值采用字符串数组的表示。 | 字符串数组 | 该标签不可缺省,可以为空值。 | +| deliveryWithInstall | 标识当前Module是否在用户主动安装的时候安装,表示该Module对应的HAP是否跟随应用一起安装。
- true:主动安装时安装。
- false:主动安装时不安装。 | 布尔值 | 该标签不可缺省。 | +| installationFree | 标识当前Module是否支持免安装特性。
- true:表示支持免安装特性,且符合免安装约束。
- false:表示不支持免安装特性。
**说明:**
- 当应用的entry类型Module的该字段配置为true时,该应用的feature类型的该字段也需要配置为true。
- 当应用的entry类型Module的该字段配置为false时,该应用的feature类型的该字段根据业务需求配置true或false。 | 布尔值 | 该标签不可缺省。 | +| virtualMachine | 标识当前Module运行的目标虚拟机类型,供云端分发使用,如应用市场和分发中心。
该标签值为字符串。如果目标虚拟机类型为ArkTS引擎,则其值为“ark+版本号”。 | 字符串 | 该标签由IDE构建HAP的时候自动插入。 | +| uiSyntax(deprecated) | 标识当前Module syntax定义该JS Component的语法类型。
- hml:标识该JS Component使用hml/css/js进行开发。
- ets:标识该JS Component使用ArkTS声明式语法进行开发。 | 字符串 | 该标签可缺省,默认值为hml,该标签从API9开始废弃。 | +| [pages](#pages标签) | 标识当前Module的profile资源,用于列举JS Component中每个页面信息。该标签最大长度为255个字节。 | 字符串 | 在有UIAbility的场景下,该标签不可缺省。 | +| [metadata](#metadata标签) | 标识当前Module的自定义元信息,标签值为数组类型,只对当前Module、UIAbility、ExtensionAbility生效。 | 对象数组 | 该标签可缺省,缺省值为空。 | +| [abilities](#abilities标签) | 标识当前Module中UIAbility的配置信息,标签值为数组类型,只对当前UIAbility生效。 | 对象 | 该标签可缺省,缺省值为空。 | +| [extensionAbilities](#extensionabilities标签) | 标识当前Module中ExtensionAbility的配置信息,标签值为数组类型,只对当前ExtensionAbility生效。 | 对象 | 该标签可缺省,缺省值为空。 | +| [requestPermissions](#requestpermissions标签) | 标识当前应用运行时需向系统申请的权限集合。 | 对象 | 该标签可缺省,缺省值为空。 | +| [testRunner](#testrunner标签) | 标识当前Module用于支持对测试框架的配置。 | 对象 | 该标签可缺省,缺省值为空。 | + + +## deviceTypes标签 + + **表2** deviceType标签配置说明 + +| 设备类型 | 枚举值 | 说明 | +| -------- | -------- | -------- | +| 平板 | tablet | - | +| 智慧屏 | tv | - | +| 智能手表 | wearable | 系统能力较丰富的手表,具备电话功能。 | +| 车机 | car | - | +| 默认设备 | default | 能够使用全部系统能力的OpenHarmony设备。 | + +deviceTypes示例: + + +```json +{ + "module": { + "name": "myHapName", + "type": "feature", + "deviceTypes" : [ + "tablet" + ] + } +} +``` + + +## pages标签 + +该标签是一个profile文件资源,用于指定描述页面信息的配置文件。 + + +```json +{ + "module": { + // ... + "pages": "$profile:main_pages", // 通过profile下的资源文件配置 + } +} +``` + +在开发视图的resources/base/profile下面定义配置文件**main_pages**.json,其中文件名(**main_pages**)可自定义,需要和前文中pages标签指定的信息对应,配置文件中列举了当前应用组件中的页面信息。 + + +```json +{ + "src": [ + "pages/index/mainPage", + "pages/second/payment", + "pages/third/shopping_cart", + "pages/four/owner" + ] +} +``` + + +## metadata标签 + +该标签标识HAP的自定义元信息,标签值为数组类型,包含name,value,resource三个子标签。 + + **表3** **metadata标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 该标签标识数据项的键名称,字符串类型(最大长度255字节)。 | 字符串 | 该标签可缺省,缺省值为空。 | +| value | 该标签标识数据项的值,标签值为字符串(最大长度255字节)。 | 字符串 | 该标签可缺省,缺省值为空。 | +| resource | 该标签标识定义用户自定义数据格式,标签值为标识该数据的资源的索引值。该标签最大字节长度为255字节。 | 字符串 | 该标签可缺省,缺省值为空。 | + + +```json +{ + "module": { + "metadata": [{ + "name": "module_metadata", + "value": "a test demo for module metadata", + "resource": "$profile:shortcuts_config", + }], + + "abilities": [{ + "metadata": [{ + "name": "ability_metadata", + "value": "a test demo for ability", + "resource": "$profile:config_file" + }, + { + "name": "ability_metadata_2", + "value": "a string test", + "resource": "$profile:config_file" + }], + }], + + "extensionAbilities": [{ + "metadata": [{ + "name": "extensionAbility_metadata", + "value": "a test for extensionAbility", + "resource": "$profile:config_file" + }, + { + "name": "extensionAbility_metadata_2", + "value": "a string test", + "resource": "$profile:config_file" + }], + }] + } +} +``` + + +## abilities标签 + +ablities标签描述UIAbility组件的配置信息,标签值为数组类型,该标签下的配置只对当前UIAbility生效。 + + **表4** **abilities标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识当前UIAbility组件的名称,该名称在整个应用要唯一,标签值采用字符串表示(最大长度127个字节)。 | 字符串 | 该标签不可缺省。 | +| srcEntrance | 该标签标识入口UIAbility的代码路径,标签值为字符串(最长为127字节)。 | 字符串 | 该标签不可缺省。 | +| [launchType](../application-models/uiability-launch-type.md) | 标识当前UIAbility组件的启动模式,可选标签值:
- standard:标准实例模式,每次启动创建一个新的实例。
- singleton:单实例模式,仅第一次启动创建新实例。
- specified:指定实例模式,运行时由开发者决定是否创建新实例。 | 字符串 | 可缺省,该标签缺省为“singleton”。 | +| description | 标识当前UIAbility组件的描述信息,标签值是字符串类型(最长255字节)或对描述内容的资源索引,要求采用资源索引方式,以支持多语言。 | 字符串 | 该标签可缺省,缺省值为空。 | +| icon | 标识当前UIAbility组件的图标,标签值为图标资源文件的索引。 | 字符串 | 该标签可缺省,缺省值为空。
如果UIAbility被配置为MainElement,该标签必须配置。 | +| label | 标识当前UIAbility组件对用户显示的名称,标签值配置为该名称的资源索引以支持多语言。
如果UIAbility被配置当前Module的mainElement时,该标签必须配置,且应用内唯一。 | 字符串 | 该标签不可缺省。 | +| permissions | 标识当前UIAbility组件自定义的权限信息。当其他应用访问该UIAbility时,需要申请相应的权限信息。
一个数组元素为一个权限名称。通常采用反向域名格式(最大255字节),取值为系统预定义的权限。 | 字符串数组 | 该标签可缺省,缺省值为空。 | +| [metadata](#metadata标签) | 标识当前UIAbility组件的元信息。 | 对象数组 | 该标签可缺省,缺省值为空。 | +| visible | 标识当前UIAbility组件是否可以被其他应用调用。
- true:表示可以被其他应用调用。
- false:表示不可以被其他应用调用。 | 布尔值 | 该标签可缺省,缺省值为false。 | +| continuable | 标识当前UIAbility组件是否可以[迁移](../application-models/hop-cross-device-migration.md)。
- true:表示可以被迁移。
- false:表示不可以被迁移。 | 布尔值 | 该标签可缺省,缺省值为false。 | +| [skills](#skills标签) | 标识当前UIAbility组件或ExtensionAbility组件能够接收的[Want](../application-models/want-overview.md)的特征集,为数组格式。
配置规则:
- 对于Entry类型的HAP,OpenHarmony应用可以配置多个具有入口能力的skills标签(即配置了action.system.home和entity.system.home)。
- 对于Feature类型的HAP,只有OpenHarmony应用可以配置具有入口能力的skills标签,OpenHarmony服务不允许配置。 | 对象数组 | 该标签可缺省,缺省值为空。 | +| backgroundModes | 标识当前UIAbility组件的长时任务集合。指定用于满足特定类型的长时任务。
长时任务类型有如下:
- dataTransfer:通过网络/对端设备进行数据下载、备份、分享、传输等业务。
- audioPlayback:音频输出业务。
- audioRecording:音频输入业务。
- location:定位、导航业务。
- bluetoothInteraction:蓝牙扫描、连接、传输业务(穿戴)。
- multiDeviceConnection:多设备互联业务。
- wifiInteraction:Wi-Fi扫描、连接、传输业务(克隆多屏)。
- voip:音视频电话,VoIP业务。
- taskKeeping:计算业务。 | 字符串数组 | 该标签可缺省,缺省值为空。 | +| startWindowIcon | 标识当前UIAbility组件启动页面图标资源文件的索引。取值示例:$media:icon。
该标签最大字节长度为255。 | 字符串 | 不可缺省。 | +| startWindowBackground | 标识当前UIAbility组件启动页面背景颜色资源文件的索引。取值示例:$color:red。
改标签最大字节长度为255。 | 字符串 | 不可缺省。 | +| removeMissionAfterTerminate | 标识当前UIAbility组件销毁后是否从任务列表中移除任务,为布尔类型:
- true表示销毁后移除任务。
- false表示销毁后不移除任务。 | 布尔值 | 该标签可缺省,缺省值为false。 | +| orientation | 标识当前UIAbility组件启动时的方向。该方向的取值范围包括:
- unspecified:未指定方向,由系统自动判断显示方向。
- landscape:横屏。
- portrait:竖屏。
- landscape_inverted:反向横屏。
- portrait_inverted:反向竖屏。
- auto_rotation:随传感器旋转。
- auto_rotation_landscape:传感器横屏旋转,包括了横屏和反向横屏。
- auto_rotation_portrait:传感器竖屏旋转,包括了竖屏和反向竖屏。
- auto_rotation_restricted:传感器开关打开,方向可随传感器旋转。
- auto_rotation_landscape_restricted:传感器开关打开,方向可随传感器旋转为横屏, 包括了横屏和反向横屏。
- auto_rotation_portrait_restricted:传感器开关打开,方向随可传感器旋转为竖屏, 包括了横屏和反向横屏。
- locked:传感器开关关闭,方向锁定。 | 字符串 | 该标签可缺省,缺省值为unspecified。 | +| supportWindowMode | 标识当前UIAbility组件所支持的窗口模式,包含:
- fullscreen:全屏模式。
- split:分屏模式。
- floating:悬浮窗模式。 | 字符串数组 | 该标签可缺省,缺省值为
["fullscreen", "split", "floating"]。 | +| priority | 标识当前UIAbility组件的优先级,仅支持系统应用配置,三方应用配置不生效。[隐式查询](../application-models/explicit-implicit-want-mappings.md)时,优先级越高,UIAbility在返回列表越靠前。该标签取值为integer类型,取值范围0-10。数值越大,优先级越高。 | 数值 | 该标签可缺省,缺省值为0。 | +| maxWindowRatio | 标识当前UIAbility组件支持的最大的宽高比。该标签最小取值为0。 | 数值 | 该标签可缺省,缺省值为平台支持的最大的宽高比。 | +| minWindowRatio | 标识当前UIAbility组件支持的最小的宽高比。该标签最小取值为0。 | 数值 | 该标签可缺省,缺省值为平台支持的最小的宽高比。 | +| maxWindowWidth | 标识当前UIAbility组件支持的最大的窗口宽度,宽度单位为vp。该标签最小取值为0。 | 数值 | 该标签可缺省,缺省值为平台支持的最大的窗口宽度。 | +| minWindowWidth | 标识当前UIAbility组件支持的最小的窗口宽度, 宽度单位为vp。该标签最小取值为0。 | 数值 | 该标签可缺省,缺省值为平台支持的最小的窗口宽度。 | +| maxWindowHeight | 标识当前UIAbility组件支持的最大的窗口高度, 高度单位为vp。该标签最小取值为0。 | 数值 | 该标签可缺省,缺省值为平台支持的最大的窗口高度。 | +| minWindowHeight | 标识当前UIAbility组件支持的最小的窗口高度, 高度单位为vp。该标签最小取值为0。 | 数值 | 该标签可缺省,缺省值为平台支持的最小的窗口高度。 | +| excludeFromMissions | 标识当前UIAbility组件是否在最近任务列表中显示。
- true:表示不在任务列表中显示。
- false:表示在任务列表中显示。
**说明:**
- 仅支持系统应用配置,三方应用配置不生效。 | 布尔值 | 该标签可缺省,缺省值为false。 | + +abilities示例: + + +```json +{ + "abilities": [{ + "name": "EntryAbility", + "srcEntrance": "./ets/entryability/EntryAbility.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" + ], + "startWindowIcon": "$media:icon", + "startWindowBackground": "$color:red", + "removeMissionAfterTerminate": true, + "orientation": " ", + "supportWindowMode": ["fullscreen", "split", "floating"], + "maxWindowRatio": 3.5, + "minWindowRatio": 0.5, + "maxWindowWidth": 2560, + "minWindowWidth": 1400, + "maxWindowHeight": 300, + "minWindowHeight": 200, + "excludeFromMissions": false + }] +} +``` + + +## skills标签 + +该标签标识UIAbility组件或者ExtensionAbility组件能够接收的[Want](../application-models/want-overview.md)的特征。 + + **表5** **skills标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| actions | 标识能够接收的Want的[Action值的集合](../application-models/actions-entities.md),取值通常为系统预定义的action值,也允许自定义。 | 字符串数组 | 可缺省,缺省值为空。 | +| entities | 标识能够接收Want的[Entity值的集合](../application-models/actions-entities.md)。 | 字符串数组 | 可缺省,缺省值为空。 | +|uris | 标识与Want中URI(Uniform Resource Identifier)相匹配的集合。 | 对象数组 | 可缺省,缺省值为空。 | + + **表6** **uris对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| scheme | 标识URI的协议名部分,常见的有http、https、file、ftp等。 | 字符串 | uris中仅配置type时可以缺省,缺省值为空,否则不可缺省。 | +| host | 标识URI的主机地址部分,该字段要在schema存在时才有意义。常见的方式:
- 域名方式,如example.com。
- IP地址方式,如10.10.10.1。 | 字符串 | 可缺省,缺省值为空。 | +| port | 标识URI的端口部分。如http默认端口为80,https默认端口是443,ftp默认端口是21。该字段要在schema和host都存在时才有意义。 | 字符串 | 可缺省,缺省值为空。 | +| path \| pathStartWith \| pathRegex | 标识URI的路径部分,path、pathStartWith和pathRegex配置时三选一。path标识URI与want中的路径部分全匹配,pathStartWith标识URI与want中的路径部分允许前缀匹配,pathRegex标识URI与want中的路径部分允许正则匹配。该字段要在schema和host都存在时才有意义。 | 字符串 | 可缺省,缺省值为空。 | +| type | 标识与Want相匹配的数据类型,使用[MIME](https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com%E3%80%82)(Multipurpose Internet Mail Extensions)类型规范。可与schema同时配置,也可以单独配置。 | 字符串 | 可缺省,缺省值为空。 | + +skills示例: + + +```json +{ + "abilities": [ + { + "skills": [ + { + "actions": [ + "action.system.home" + ], + "entities": [ + "entity.system.home" + ], + "uris": [ + { + "scheme":"http", + "host":"example.com", + "port":"80", + "path":"path", + "type": "text/*" + } + ] + } + ] + } + ] +} +``` + + +## extensionAbilities标签 + +描述extensionAbilities的配置信息,标签值为数组类型,该标签下的配置只对当前extensionAbilities生效。 + + **表7** **extensionAbilities标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识当前ExtensionAbility组件的名称,标签值最大长度为127个字节,该名称在整个应用要唯一。 | 字符串 | 该标签不可缺省。 | +| srcEntrance | 标识当前ExtensionAbility组件所对应的代码路径,标签值最大长度为127字节。 | 字符串 | 该标签不可缺省。 | +| description | 标识当前ExtensionAbility组件的描述,标签值最大长度为255字节,标签也可以是描述内容的资源索引,用于支持多语言。 | 字符串 | 该标签可缺省,缺省值为空。 | +| icon | 标识当前ExtensionAbility组件的图标,标签值为资源文件的索引。如果ExtensionAbility组件被配置为MainElement,该标签必须配置。 | 字符串 | 该标签可缺省,缺省值为空。 | +| label | 标识当前ExtensionAbility组件对用户显示的名称,标签值配置为该名称的资源索引以支持多语言。
**说明:**
- 如果ExtensionAbility被配置当前Module的mainElement时,该标签必须配置,且应用内唯一。 | 字符串 | 该标签不可缺省。 | +| type | 标识当前ExtensionAbility组件的类型,取值为:
- form:卡片的ExtensionAbility。
- workScheduler:延时任务的ExtensionAbility。
- inputMethod:输入法的ExtensionAbility。
- service:后台运行的service组件。
- accessibility:辅助能力的ExtensionAbility。
- dataShare:数据共享的ExtensionAbility。
- fileShare:文件共享的ExtensionAbility。
- staticSubscriber:静态广播的ExtensionAbility。
- wallpaper:壁纸的ExtensionAbility。
- backup:数据备份的ExtensionAbility。
- window:该ExtensionAbility会在启动过程中创建一个window,为开发者提供界面开发。开发者开发出来的界面将通过abilityComponent控件组合到其他应用的窗口中。
- thumbnail:获取文件缩略图的ExtensionAbility,开发者可以对自定义文件类型的文件提供缩略。
- preview:该ExtensionAbility会将文件解析后在一个窗口中显示,开发者可以通过将此窗口组合到其他应用窗口中。
**说明:**
- 其中service和dataShare类型,仅支持系统应用配置,三方应用配置不生效。 | 字符串 | 该标签不可缺省。 | +| permissions | 标识当前ExtensionAbility组件自定义的权限信息。当其他应用访问该ExtensionAbility时,需要申请相应的权限信息。
一个数组元素为一个权限名称。通常采用反向域名格式(最大255字节),可以是系统预定义的权限,也可以是该应用自定义的权限。如果是后者,需与defPermissions标签中定义的某个权限的name标签值一致。 | 字符串数组 | 该标签可缺省,缺省值为空。 | +| uri | 标识当前ExtensionAbility组件提供的数据URI,为字符数组类型(最大长度255),用反向域名的格式表示。
**说明:**
- 该标签在type为dataShare类型的ExtensionAbility时,不可缺省。 | 字符串 | 该标签可缺省,缺省值为空。 | +|skills | 标识当前ExtensionAbility组件能够接收的[Want](../application-models/want-overview.md)的特征集,为数组格式。
配置规则:entry包可以配置多个具有入口能力的skills标签(配置了action.system.home和entity.system.home)的ExtensionAbility,其中第一个配置了skills标签的ExtensionAbility中的label和icon作为OpenHarmony服务或应用的label和icon。
**说明:**
- OpenHarmony服务的Feature包不能配置具有入口能力的skills标签。
- OpenHarmony应用的Feature包可以配置具有入口能力的skills标签。 | 数组 | 该标签可缺省,缺省值为空。 | +| [metadata](#metadata标签) | 标识当前ExtensionAbility组件的元信息。 | 对象 | 该标签可缺省,缺省值为空。 | +| visible | 标识当前ExtensionAbility组件是否可以被其他应用调用,为布尔类型。
- true:表示可以被其他应用调用。
- false:表示不可以被其他应用调用。 | 布尔值 | 该标签可缺省,缺省值为false。 | + +extensionAbilities示例: + + +```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.extension.form", + "resource": "$profile:form_config", + } + ] + } + ] +} +``` + + +## requestPermissions标签 + +该标签标识应用运行时需向系统申请的权限集合。 + + **表8** **requestPermissions标签说明** + +| 属性 | 含义 | 类型 | 取值范围 | 默认值 | +| -------- | -------- | -------- | -------- | -------- | +| name | 必须,填写需要使用的权限名称。 | 字符串 | 自定义。 | 无。 | +| reason | 可选,当申请的权限为user_grant权限时此字段必填,用于描述申请权限的原因。
**说明:**
- 当申请的权限为user_grant权限时,如果未填写该字段则不允许在应用市场上架,并且需要进行多语种适配。 | 字符串 | 使用string类资源引用。格式为$string: \*\*\*。 | 空。 | +| usedScene | 可选,当申请的权限为user_grant权限时此字段必填。描述权限使用的场景由abilities和when组成。其中abilities可以配置为多个UIAbility组件,when表示调用时机。
**说明:**
- 默认为可选,当申请的权限为user_grant权限时,abilities标签必填,when标签可选。 | abilities:UIAbility或者ExtensionAbility名称的字符串数组
when:字符串 | abilities:UIAbility或者ExtensionAbility组件的名称。
when:inuse(使用时)、always(始终)。 | abilities:空。
when:空。 | + +requestPermissions示例: + + +```json +{ + "module" : { + "requestPermissions": [ + { + "name": "ohos.abilitydemo.permission.PROVIDER", + "reason": "$string:reason", + "usedScene": { + "abilities": [ + "EntryFormAbility" + ], + "when": "inuse" + } + } + ] + } +} +``` + + +## shortcuts标签 + +shortcuts标识应用的快捷方式信息。标签值为数组,最多可以配置四个快捷方式。其包含四个子标签shortcutId、label、icon、wants。 + +metadata中指定shortcut信息,其中: + +- name:指定shortcuts的名称。使用ohos.ability.shortcuts作为shortcuts信息的标识。 + +- resource:指定shortcuts信息的资源位置。 + +| 属性 | 含义 | 类型 | 默认值 | +| -------- | -------- | -------- | -------- | +| shortcutId | 标识快捷方式的ID。字符串的最大长度为63字节。 | 字符串 | 该标签不可缺省。 | +| label | 标识快捷方式的标签信息,即快捷方式对外显示的文字描述信息。取值可以是描述性内容,也可以是标识label的资源索引。字符串最大长度为255字节。 | 字符串 | 该标签可缺省,缺省值为空。 | +| icon | 标识快捷方式的图标,标签值为资源文件的索引。 | 字符串 | 该标签可缺省,缺省值为空。 | +| [wants](../application-models/want-overview.md) | 标识快捷方式内定义的目标wants信息集合,每个wants可配置bundleName和abilityName两个子标签。
bundleName:表示快捷方式的目标包名,字符串类型。
abilityName:表示快捷方式的目标组件名,字符串类型。 | 对象 | 该标签可缺省,缺省为空。 | + + +1. 在/resource/base/profile/目录下配置shortcuts_config.json配置文件。 + + ```json + { + "shortcuts": [ + { + "shortcutId": "id_test1", + "label": "$string:shortcut", + "icon": "$media:aa_icon", + "wants": [ + { + "bundleName": "com.ohos.hello", + "abilityName": "EntryAbility" + } + ] + } + ] + } + ``` + +2. 在module.json5配置文件的abilities标签中,针对需要添加快捷方式的UIAbility进行配置metadata标签,使shortcut配置文件对该UIAbility生效。 + + ```json + { + "module": { + // ... + "abilities": [ + { + "name": "EntryAbility", + "srcEntrance": "./ets/entryability/EntryAbility.ts", + // ... + "skills": [ + { + "entities": [ + "entity.system.home" + ], + "actions": [ + "action.system.home" + ] + } + ], + "metadata": [ + { + "name": "ohos.ability.shortcuts", + "resource": "$profile:shortcuts_config" + } + ] + } + ] + } + } + ``` + + +## distroFilter标签 + +该标签下的子标签均为可选字段,在应用市场云端分发时做精准匹配使用,distroFilter用于定义HAP对应的细分设备规格的分发策略,以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括API Version、屏幕形状、屏幕尺寸、屏幕分辨率,设备的国家与地区码。在进行分发时,通过deviceType与这五个属性的匹配关系,唯一确定一个用于分发到设备的HAP。该标签需要配置在/resource/profile资源目录下。 + + **表9** **distroFilter标签配置说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| apiVersion | 标识支持的apiVersion范围。 | 对象数组 | 该标签可缺省,缺省值为空。 | +| 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](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/basic-resource-file-categories-0000001052066099)标准为准。支持多个国家和地区枚举定义。 | 对象数组 | 该标签可缺省,缺省值为空。 | + + **表10** **apiVersion标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 该标签不可缺省。 | +| value | 支持的取值为API Version存在的整数值,例如4、5、6。场景示例:某应用,针对相同设备型号,同时在网的为使用API 5和API 6开发的两个软件版本,则允许上架2个entry类型的安装包,分别支持到对应设备侧软件版本的分发。 | 数组 | 该标签不可缺省。 | + + **表11** **screenShape对象的内部结构** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 该标签不可缺省。 | +| value | 支持的取值为circle(圆形)、rect(矩形)。场景示例:针对智能穿戴设备,可为圆形表盘和矩形表盘分别提供不同的HAP。 | 字符串数组 | 该标签不可缺省。 | + + **表12** **screenWindow对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示该字段取值不包含value枚举值匹配规则的匹配该属性。
- include:表示该字段取值满足value枚举值匹配规则的匹配该属性。 | 字符串 | 该标签不可缺省。 | +| value | 单个字符串的取值格式为“宽 \* 高”,取值为整数像素值,例如“454 \* 454”。 | 字符串数组 | 该标签不可缺省。 | + + **表13** **screenDensity对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 该标签不可缺省。 | +| value | 该标签标识屏幕的像素密度(dpi :Dot Per Inch)。 | 字符串数组 | 该标签不可缺省。 | + + **表14** **countryCode对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 该标签不可缺省。 | +| value | 标识应用需要分发的国家地区码。 | 字符串数组 | 该标签不可缺省。 | + +在开发视图的resources/base/profile下面定义配置文件distro_filter_config.json,文件名可以自定义。 + + +```json +{ + "distroFilter": { + "apiVersion": { + "policy": "include", + "value": [ + 3, + 4 + ] + }, + "screenShape": { + "policy": "include", + "value": [ + "circle", + "rect" + ] + }, + "screenWindow": { + "policy": "include", + "value": [ + "454*454", + "466*466" + ] + }, + "screenDensity": { + "policy": "exclude", + "value": [ + "ldpi", + "xldpi" + ] + }, + "countryCode": { // 支持中国和香港地区分发 + "policy": "include", + "value": [ + "CN", + "HK" + ] + } + } +} +``` + +在module.json5配置文件的module标签中定义metadata信息。 + + +```json +{ + "module": { + // ... + "metadata": [ + { + "name": "ohos.module.distro", + "resource": "$profile:distro_filter_config", + } + ] + } +} +``` + + +## testRunner标签 + +此标签用于支持对测试框架的配置。 + + **表15** **testRunner标签说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识测试框架对象名称。该标签最大字节长度为255个字节。 | 字符串 | 不可缺省。 | +| srcPath | 标识测试框架代码路径。该标签最大字节长度为255个字节。 | 字符串 | 不可缺省。 | + +testRunner标签示例: + + +```json +{ + "module": { + // ... + "testRunner": { + "name": "myTestRunnerName", + "srcPath": "etc/test/TestRunner.ts" + } + } +} +``` diff --git a/zh-cn/application-dev/quick-start/module-structure.md b/zh-cn/application-dev/quick-start/module-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..02d233c9d70c4e78e0d3679a4af23a31386dcbd1 --- /dev/null +++ b/zh-cn/application-dev/quick-start/module-structure.md @@ -0,0 +1,676 @@ +# module对象内部结构 + + +module对象包含HAP的配置信息。 + + + **表1** **module对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| mainAbility | 服务中心图标露出的Ability,常驻进程拉起时会启动mainAbility。 | 字符串 | 可缺省,缺省值为空。 | +| package | 标识HAP的包结构名称,在应用内保证唯一性。采用反向域名格式(建议与HAP的工程目录保持一致)。字符串长度为1-127个字节。 | 字符串 | 不可缺省。 | +| name | 标识HAP的类名。采用反向域名方式标识,前缀要与同级的package标签指定的包名一致,也可采用"."开头的命名方式。字符串长度不超过255字节。 | 字符串 | 可缺省,缺省值为空。 | +| description | 标识HAP的描述信息。字符串长度不超过255字节。如果字符串超出长度或者需要支持多语言,可以采用资源索引的方式添加描述内容。 | 字符串 | 可缺省,缺省值为空。 | +| supportedModes | 标识应用支持的运行模式,当前只定义了驾驶模式(drive)。该标签只适用于车机。 | 字符串数组 | 可缺省,缺省值为空。 | +|deviceType | 标识允许Ability运行的设备类型。系统预定义的设备类型包括:tablet(平板)、tv(智慧屏)、car(车机)、wearable(智能穿戴)等。 | 字符串数组 | 不可缺省。 | +|distro | 标识HAP发布的具体描述。 | 对象 | 不可缺省。 | +|metaData | 标识HAP的元信息。 | 对象 | 可缺省,缺省值为空。 | +| abilities | 标识当前模块内的所有Ability。采用对象数据格式。 | 对象数组 | 可缺省,缺省值为空。 | +| js | 标识基于ArkUI框架开发的JS模块集合,其中的每个元素代表一个JS模块的信息。 | 对象数组 | 可缺省,缺省值为空。 | +| shortcuts | 标识应用的快捷方式信息。采用对象数组格式,其中的每个元素表示一个快捷方式对象。 | 对象数组 | 可缺省,缺省值为空。 | +| reqPermissions | 标识应用运行时向系统申请的权限。 | 对象数组 | 可缺省,缺省值为空。 | +| colorMode | 标识应用自身的颜色模式,目前支持如下三种模式:
- dark:表示按照深色模式选取资源。
- light:表示按照浅色模式选取资源。
- auto:表示跟随系统的颜色模式值选取资源。 | 字符串 | 可缺省,缺省值为"auto"。 | +| distroFilter | 标识应用的分发规则。该标签用于定义HAP对应的细分设备规格的分发策略,以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括API Version、屏幕形状、屏幕分辨率。在进行分发时,通过deviceType与这三个属性的匹配关系,唯一确定一个用于分发到设备的HAP。 | 对象 | 可缺省,缺省值为空。但当应用中包含多个entry模块时,必须配置该标签。 | +|commonEvents | 定义了公共事件静态订阅者的信息,该字段中需要声明静态订阅者的名称、权限要求及订阅事件列表信息,当订阅的公共事件发送时,该公共事件静态订阅者将被拉起。这里的静态订阅者区分于常用的动态订阅者,前者无需在业务代码中主动调用订阅事件的接口,在公共事件发布时可能未被拉起,而动态订阅者则在业务代码中主动调用公共事件订阅的相关API,因此需要应用处于活动状态。 | 对象数组 | 可缺省,缺省为空。 | +| entryTheme | 此标签标识OpenHarmony内部主题的关键字。将标记值设置为名称的资源索引。 | 字符串 | 可缺省,缺省值为空。 | +|testRunner | 此标签用于支持对测试框架的配置。 | 对象 | 可缺省,缺省值为空。 | + + +module示例: + + + +```json +{ + "module": { + "mainAbility": ".MainAbility", + "deviceType": [ + "default", + "tablet" + ], + "abilities": [ + { + "skills": [ + { + "entities": [ + "entity.system.home" + ], + "actions": [ + "action.system.home" + ] + } + ], + "orientation": "unspecified", + "visible": true, + "srcPath": "MainAbility", + "name": ".MainAbility", + "srcLanguage": "ets", + "icon": "$media:icon", + "description": "$string:MainAbility_desc", + "formsEnabled": false, + "label": "$string:MainAbility_label", + "type": "page", + "launchType": "standard" + } + ], + "distro": { + "moduleType": "entry", + "installationFree": false, + "deliveryWithInstall": true, + "moduleName": "entry" + }, + "package": "com.example.entry", + "srcPath": "", + "name": ".entry", + "js": [ + { + "mode": { + "syntax": "ets", + "type": "pageAbility" + }, + "pages": [ + "pages/Index" + ], + "name": ".MainAbility", + "window": { + "designWidth": 720, + "autoDesignWidth": false + } + } + ] + } +} +``` + + + **表2** **distro对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| moduleName | 标识当前HAP的名称,最大长度为31个字节。 | 字符串 | 不可缺省。 | +| moduleType | 标识当前HAP的类型,包括三种类型:entry、feature和har。 | 字符串 | 不可缺省。 | +| installationFree | 标识当前HAP是否支持免安装特性。true:表示支持免安装特性,且符合免安装约束。false:表示不支持免安装特性。另外还需注意:当entry.hap该字段配置为true时,与该entry.hap相关的所有feature.hap该字段也需要配置为true。当entry.hap该字段配置为false时,与该entry.hap相关的各feature.hap该字段可按业务需求配置true或false。 | 布尔值 | 不可缺省。 | +| deliveryWithInstall | 标识当前HAP是否在用户主动安装HAP所在应用的时候一起安装。true: 安装应用时当前HAP随应用一起下载安装。false:安装应用时当前HAP并不下载安装,后续使用是按需下载。 | 布尔值 | 不可缺省。 | + + +distro示例: + + + +```json +"distro": { + "moduleName": "ohos_entry", + "moduleType": "entry", + "installationFree": true, + "deliveryWithInstall": true +} +``` + + + **表3** **metadata对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| parameters | 标识调用Ability时所有调用参数的元信息。每个调用参数的元信息由以下三个标签组成:description、name、type。 | 对象数组 | 可缺省,缺省值为空 | +| results | 标识Ability返回值的元信息。每个返回值的元信息由以下三个标签组成:description、name、type。 | 对象数组 | 可缺省,缺省值为空。 | +| customizeData | 该标签标识父级组件的自定义元信息,Parameters和results在application不可配。 | 对象数组 | 可缺省,缺省值为空。 | + + + **表4** **parameters对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| description | 标识对调用参数的描述,可以是表示描述内容的字符串,也可以是对描述内容的资源索引以支持多语言。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | +| name | 标识调用参数的名称。该标签最大长度为255个字节。 | 字符串 | 不可缺省。 | +| type | 标识调用参数的类型,如Integer。 | 字符串 | 不可缺省。 | + + + **表5** **results对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| description | 标识对返回值的描述,可以是表示描述内容的字符串,也可以是对描述内容的资源索引以支持多语言。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | +| name | 标识返回值的名字。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | +| type | 标识返回值的类型,如Integer。 | 字符串 | 不可缺省 | + + + **表6** **customizeData对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识数据项的键名称,字符串类型(最大长度255字节)。 | 字符串 | 可缺省,缺省值为空。 | +| value | 标识数据项的值名称,字符串类型(最大长度255字节)。 | 字符串 | 可缺省,缺省值为空。 | +| extra | 标识用户自定义数据格式,标签值为标识该数据的资源的索引值。 | 字符串 | 可缺省,缺省值为空。 | + + +metadata对象示例: + + + +```json +"metaData": { + "parameters" : [{ + "name" : "a test for metadata parameter", + "type" : "Float", + // "$string:parameters_description"为文件资源索引值 + "description" : "$string:parameters_description" + }], + "results" : [{ + "name" : "a test for metadata result", + "type" : "Float", + "description" : "$string:results_description" + }], + "customizeData" : [{ + "name" : "a customizeData", + "value" : "string", + "extra" : "$string:customizeData_description" + }] +} +``` + + + **表7** **deviceType标签配置说明** + +| 设备类型 | 枚举值 | 说明 | +| -------- | -------- | -------- | +| 平板 | tablet | - | +| 智慧屏 | tv | - | +| 智能手表 | wearable | 系统能力较丰富的手表,具备电话功能。 | +| 车机 | car | - | +| 默认设备 | default | 能够使用全部系统能力的OpenHarmony设备。 | + + + **表8** **abilities对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| process | 运行应用程序或Ability的进程名称。如果在deviceConfig标记中配置了进程,则应用程序的所有能力都在此进程中运行。您还可以为特定能力设置流程属性,以便该能力可以在此流程中运行。如果此属性设置为与其他应用程序相同的进程名称,则所有这些应用程序可以在同一进程中运行,前提是他们具有相同的联合用户ID和相同的签名。该标签最大字节数为31个字节。 | 字符串 | 可缺省,缺省值为空。 | +| name | 标识Ability名称。取值可采用反向域名方式表示,由包名和类名组成,如"com.example.myapplication.MainAbility";也可采用"."开头的类名方式表示,如".MainAbility"。
Ability的名称,需在一个应用的范围内保证唯一。说明:在使用DevEco Studio新建项目时,默认生成首个Ability的配置,即"config.json"中"MainAbility"的配置。如使用其他IDE工具,可自定义名称。该标签最大长度为127个字节。 | 字符串 | 不可缺省 | +| description | 标识对Ability的描述。取值可以是描述性内容,也可以是对描述性内容的资源索引,以支持多语言。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | +| icon | 标识Ability图标资源文件的索引。取值示例:$media:ability_icon。如果在该Ability的skills属性中,actions的取值包含 "action.system.home",entities取值中包含"entity.system.home",则该Ability的icon将同时作为应用的icon。如果存在多个符合条件的Ability,则取位置靠前的Ability的icon作为应用的icon。
说明:应用的"icon"和"label"是用户可感知配置项,需要区别于当前所有已有的应用"icon"或"label"(至少有一个不同)。 | 字符串 | 可缺省,缺省值为空。 | +| label | 标识Ability对用户显示的名称。取值可以是Ability名称,也可以是对该名称的资源索引,以支持多语言。如果在该Ability的skills属性中,actions的取值包含 "action.system.home",entities取值中包含"entity.system.home",则该Ability的label将同时作为应用的label。如果存在多个符合条件的Ability,则取位置靠前的Ability的label作为应用的label。
说明: 应用的"icon"和"label"是用户可感知配置项,需要区别于当前所有已有的应用"icon"或"label"(至少有一个不同)。该标签为资源文件中定义的字符串的引用,或以"{}"包括的字符串。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | +| uri | 标识Ability的统一资源标识符。该标签最大长度为255个字节。 | 字符串 | 可缺省,对于data类型的Ability不可缺省。 | +| launchType | 标识Ability的启动模式,支持"standard"和"singleton"两种模式:
standard:表示该Ability可以有多实例。该模式适用于大多数应用场景。
singleton:表示该Ability在所有任务栈中仅可以有一个实例。例如,具有全局唯一性的呼叫来电界面即采用"singleton"模式。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。 | 字符串 | 可缺省,缺省值为"singleton"。 | +| visible | 标识Ability是否可以被其他应用调用。
true:可以被其他应用调用。
false:不能被其他应用调用。 | 布尔类型 | 可缺省,缺省值为"false"。 | +| permissions | 标识其他应用的Ability调用此Ability时需要申请的权限集合,一个数组元素为一个权限名称。通常采用反向域名格式(最大255字节),取值为系统预定义的权限。 | 字符串数组 | 可缺省,缺省值为空。 | +|skills | 标识Ability能够接收的want的特征。 | 对象数组 | 可缺省,缺省值为空。 | +| deviceCapability | 标识Ability运行时要求设备具有的能力,采用字符串数组的格式表示。该标签为数组,支持最多配置512个元素,单个元素最大字节长度为64。 | 字符串数组 | 可缺省,缺省值为空。 | +| metaData | 元数据。 | 对象 | 可缺省,缺省值为空。 | +| type | 标识Ability的类型。取值范围如下:
page:表示基于Page模板开发的FA,用于提供与用户交互的能力。
service:表示基于Service模板开发的PA,用于提供后台运行任务的能力。
data:表示基于Data模板开发的PA,用于对外部提供统一的数据访问对象。
CA:表示支持其他应用以窗口方式调起该Ability。 | 字符串 | 不可缺省。 | +| orientation | 标识该Ability的显示模式。该标签仅适用于page类型的Ability。取值范围如下:
unspecified:由系统自动判断显示方向。
landscape:横屏模式。
portrait:竖屏模式。
followRecent:跟随栈中最近的应用。 | 字符串 | 可缺省,缺省值为"unspecified"。 | +| backgroundModes | 标识后台服务的类型,可以为一个服务配置多个后台服务类型。该标签仅适用于service类型的Ability。取值范围如下:
dataTransfer:通过网络/对端设备进行数据下载、备份、分享、传输等业务。
audioPlayback:音频输出业务。
audioRecording:音频输入业务。
pictureInPicture:画中画、小窗口播放视频业务。
voip:音视频电话、VOIP业务。
location:定位、导航业务。
bluetoothInteraction:蓝牙扫描、连接、传输业务。
wifiInteraction:WLAN扫描、连接、传输业务。
screenFetch:录屏、截屏业务。
multiDeviceConnection:多设备互联业务 | 字符串数组 | 可缺省,缺省值为空。 | +| grantPermission | 指定是否可以向Ability内任何数据授予权限。 | 布尔值 | 可缺省,缺省值为空。 | +| readPermission | 标识读取Ability的数据所需的权限。该标签仅适用于data类型的Ability。取值为长度不超过255字节的字符串。该标签仅适用于默认设备、平板、智慧屏、车机、智能穿戴。 | 字符串 | 可缺省,缺省为空。 | +| writePermission | 标识向Ability写数据所需的权限。该标签仅适用于data类型的Ability。取值为长度不超过255字节的字符串。 | 字符串 | 可缺省,缺省为空。 | +| configChanges | 标识Ability关注的系统配置集合。当已关注的配置发生变更后,Ability会收到onConfigurationUpdated回调。取值范围:
mcc:表示IMSI移动设备国家/地区代码(MCC)发生变更。典型场景:检测到SIM并更新MCC。
mnc:IMSI移动设备网络代码(MNC)发生变更。典型场景:检测到SIM并更新MNC。
locale:表示语言区域发生变更。典型场景:用户已为设备文本的文本显示选择新的语言类型。
layout:表示屏幕布局发生变更。典型场景:当前有不同的显示形态都处于活跃状态。
fontSize:表示字号发生变更。典型场景:用户已设置新的全局字号。
orientation:表示屏幕方向发生变更。典型场景:用户旋转设备。
density:表示显示密度发生变更。典型场景:用户可能指定不同的显示比例,或当前有不同的显示形态同时处于活跃状态。
size:显示窗口大小发生变更。
smallestSize:显示窗口较短边的边长发生变更。
colorMode:颜色模式发生变更。 | 字符串数组 | 可缺省,缺省为空。 | +| mission | 标识Ability指定的任务栈。该标签仅适用于page类型的Ability。默认情况下应用中所有Ability同属一个任务栈。 | 字符串 | 可缺省,缺省为应用的包名。 | +| targetAbility | 标识当前Ability重用的目标Ability。该标签仅适用于page类型的Ability。如果配置了targetAbility属性,则当前Ability(即别名Ability)的属性中仅name、icon、label、visible、permissions、skills生效,其他属性均沿用targetAbility中的属性值。目标Ability必须与别名Ability在同一应用中,且在配置文件中目标Ability必须在别名之前进行声明。 | 字符串 | 可缺省,缺省值为空。表示当前Ability不是一个别名Ability。 | +| formsEnabled | 标识Ability是否支持卡片(forms)功能。该标签仅适用于page类型的Ability。
true:支持卡片能力。
false:不支持卡片能力。 | 布尔值 | 可缺省,缺省值为false。 | +| forms | 标识服务卡片的属性。该标签仅当formsEnabled为"true"时,才能生效。 | 对象数组 | 可缺省,缺省值为空。 | +| srcLanguage | Ability开发语言的类型,开发者创建工程时由开发者手动选择开发语言。 | 字符串 | 可缺省,缺省值为“js”。 | +| srcPath | 该标签标识Ability对应的JS组件代码路径,该标签最大长度为127字节。 | 字符串 | 不可缺省。 | +| uriPermission | 标识该Ability有权访问的应用程序数据。此属性由模式和路径子属性组成。此属性仅对类型提供者的能力有效。 | 对象 | 可缺省,缺省值为空。 | +| startWindowIcon | 标识该Ability启动页面图标资源文件的索引。该标签仅适用于page类型的Ability。取值示例:$media:icon。 | 字符串 | 可缺省,缺省值为空。 | +| startWindowBackground | 标识该Ability启动页面背景颜色资源文件的索引。该标签仅适用于page类型的Ability。取值示例:$color:red。 | 字符串 | 可缺省,缺省值为空。 | +| removeMissionAfterTerminate | 该标签标识Ability销毁后是否从任务列表中移除任务。该标签仅适用于page类型的Ability。true表示销毁后移除任务, false表示销毁后不移除任务。 | 布尔值 | 可缺省,缺省值为false。 | + + + **表9** **uriPermission对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| path | uriPermission标识的路径,该标签最大字节长度为255个字节。 | 字符串 | 不可缺省。 | +| mode | uriPermission的匹配模式。 | 字符串 | 可缺省,缺省值为default。 | + + +abilities示例: + +```json +"abilities": [ + { + "name": ".MainAbility", + "description": "test main ability", + // $media:ic_launcher 为媒体类资源 + "icon": "$media:ic_launcher", + // $string:example 为字符串类资源 + "label": "$string:example", + "launchType": "standard", + "orientation": "unspecified", + "permissions": [], + "visible": true, + "skills": [ + { + "actions": [ + "action.system.home" + ], + "entities": [ + "entity.system.home" + ] + } + ], + "configChanges": [ + "locale", + "layout", + "fontSize", + "orientation" + ], + "type": "page", + "startWindowIcon": "$media:icon", + "startWindowBackground": "$color:red", + "removeMissionAfterTerminate": true + }, + { + "name": ".PlayService", + "description": "example play ability", + "icon": "$media:ic_launcher", + "label": "$string:example", + "launchType": "standard", + "orientation": "unspecified", + "visible": false, + "skills": [ + { + "actions": [ + "action.play.music", + "action.stop.music" + ], + "entities": [ + "entity.audio" + ] + } + ], + "type": "service", + "backgroundModes": [ + "audioPlayback" + ] + }, + { + "name": ".UserADataAbility", + "type": "data", + "uri": "dataability://com.example.world.test.UserADataAbility", + "visible": true + } +] +``` + + + **表10** **skills对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| actions | 标识能够接收的want的action值,可以包含一个或多个action。取值通常为系统预定义的action值。 | 字符串数组 | 可缺省,缺省值为空。 | +| entities | 标识能够接收的want的Ability的类别(如视频、桌面应用等),可以包含一个或多个entity。 | 字符串数组 | 可缺省,缺省值为空。 | +| uris | 该标签标识向want过滤器添加数据规范集合。该规范可以是只有数据类型(mimeType属性),可以是只有URI,也可以是既有数据类型又有URI。
URI由其各个部分的单独属性指定:<scheme>://<host>:<port>[<path>\|<pathStartWith>\|<pathRegex>]。该标签可缺省,缺省值为空。
其中,scheme字段配置为uri时必配;当只设置数据类型(mimeType)时,则scheme字段为非必配项。 | 对象数组 | 可缺省,缺省值为空。 | + + + **表11** **uris对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| scheme | 标识uri的scheme值。 | 字符串 | 不可缺省。 | +| host | 标识uri的host值。 | 字符串 | 可缺省,缺省值为空。 | +| port | 标识uri的port值。 | 字符串 | 可缺省,缺省值为空。 | +| pathStartWith | 标识uri的pathStartWith值。 | 字符串 | 可缺省,缺省值为空。 | +| path | 标识uri的path值。 | 字符串 | 可缺省,缺省值为空。 | +| pathRegx | 标识uri的pathRegx值。 | 字符串 | 可缺省,缺省值为空。 | +| type | 标识uri的type值。type为MIME-TYPE属性,为资源的媒体类型,常见的类型有"audio/aac","text/css"等。 | 字符串 | 可缺省,缺省值为空。 | + + +skills示例: + +```json +"skills": [ + { + "actions": [ + "action.system.home" + ], + "entities": [ + "entity.system.home" + ], + "uris": [ + { + "scheme": "http", + "host": "www.example.com", + "port": "8080", + "path": "query/student/name", + "type": "text/*" + } + ] + } +] +``` + + + **表12** **reqPermissions权限申请字段说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 需要使用的权限名称。 | 字符串 | 否 | +| reason | 描述申请权限的原因。需要做多语种适配。 | 字符串 | 分情况:当申请的权限为user_grant时,必须填写此字段,否则不允许在应用市场上架;其他权限可缺省,缺省为空 | +| usedScene | 描述权限使用的场景和时机。场景类型如下两种:
- ability:ability的名称,可配置多个。
- when:调用时机,可填的值有inuse(使用时)、always(始终)。 | 对象 | 可缺省,缺省值为空。
when可缺省,缺省值为"inuse" | + + + **表13** **usedScene对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| ability | 标识哪些Ability需要此权限,里面配置Ability的名称。 | 字符串数组 | 可以缺省,缺省表示所有Ability都需要此权限。 | +| when | 标识此权限的使用时间:
inuse: 使用时需要此权限。
always: 所有时间都需要此权限。 | 枚举值 | 可缺省,缺省值为空。 | + + + **表14** **js对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识JS Component的名字。该标签不可缺省,默认值为default。 | 字符串 | 不可缺省。 | +| pages | 标识JS Component的页面用于列举JS Component中每个页面的路由信息[页面路径+页面名称]。该标签不可缺省,取值为数组,数组第一个元素代表JS FA首页。 | 字符串数组 | 不可缺省。 | +| window | 用于定义与显示窗口相关的配置。 | 对象 | 可缺省,缺省值见表15。 | +| type | 标识JS应用的类型。取值范围如下:
normal:标识该JS Component为应用实例。
form:标识该JS Component为卡片实例。 | 字符串 | 可缺省,缺省值为"normal"。 | +|mode | 定义JS组件的开发模式。 | 对象 | 可缺省,缺省值为空。 | + + + **表15** **window对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| designWidth | 标识页面设计基准宽度。以此为基准,根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省,缺省值为720px。 | +| autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时,designWidth将会被忽略,设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省,缺省值为false。 | + + + **表16** **mode对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| type | 定义JS组件的功能类型。 | 字符串,取值为"pageAbility"、"form" | 可缺省,缺省值为pageAbility。 | +| syntax | 定义JS组件的语法类型。 | 字符串,取值为"hml","ets" | 可缺省,默认值为"hml"。 | + + +js示例: + +```json +"js": [ + { + "name": "default", + "pages": [ + "pages/index/index", + "pages/detail/detail" + ], + "window": { + "designWidth": 720, + "autoDesignWidth": false + }, + "type": "form" + } +] +``` + + + **表17** **shortcuts对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| shortcutId | 标识快捷方式的ID。字符串的最大长度为63字节。 | 字符串 | 不可缺省。 | +| label | 标识快捷方式的标签信息,即快捷方式对外显示的文字描述信息。取值可以是描述性内容,也可以是标识label的资源索引。字符串最大长度为63字节。 | 字符串 | 可缺省,缺省为空。 | +| icon | 标识快捷方式的图标信息。取值为表示icon的资源索引。 | 字符串 | 可缺省,缺省为空。 | +| intents | 标识快捷方式内定义的目标intent信息集合,每个intent可配置两个子标签,targetClass, targetBundle。 | 对象数组 | 可缺省,缺省为空。 | + + + **表18** **intents对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| targetClass | 标识快捷方式目标类名。 | 字符串 | 可缺省,缺省值为空。 | +| targetBundle | 标识快捷方式目标Ability所在应用的包名。 | 字符串 | 可缺省,缺省值为空。 | + + +shortcuts示例: + +```json +"shortcuts": [ + { + "shortcutId": "id", + // $string:shortcut 为配置的字符串资源值 + "label": "$string:shortcut", + "intents": [ + { + "targetBundle": "com.example.world.test", + "targetClass": "com.example.world.test.entry.MainAbility" + } + ] + } +] +``` + + + **表19** **forms对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识卡片的类名。字符串最大长度为127字节。 | 字符串 | 不可缺省。 | +| description | 标识卡片的描述。取值可以是描述性内容,也可以是对描述性内容的资源索引,以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省,缺省为空。 | +| isDefault | 标识该卡片是否为默认卡片,每个Ability有且只有一个默认卡片。
true:默认卡片。
false:非默认卡片。 | 布尔值 | 不可缺省。 | +| type | 标识卡片的类型。取值范围如下:
JS:JS卡片。 | 字符串 | 不可缺省。 | +| colorMode | 标识卡片的主题样式,取值范围如下:
auto:自适应。
dark:深色主题。
light:浅色主题。 | 字符串 | 可缺省,缺省值为"auto"。 | +| supportDimensions | 标识卡片支持的外观规格,取值范围:
1 \* 2:表示1行2列的二宫格。
2 \* 1:表示2行1列的二宫格。
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 | 标识用于调整卡片的设施或活动的名称。 | 字符串 | 可缺省,缺省值为空。 | +| jsComponentName | 标识JS卡片的Component名称。字符串最大长度为127字节。仅当卡片类型为JS卡片时,需要配置该标签。 | 字符串 | 不可缺省。 | +| metaData | 标识卡片的自定义信息,包含customizeData数组标签。 | 对象 | 可缺省,缺省值为空。 | +| customizeData | 标识自定义的卡片信息。 | 对象数组 | 可缺省,缺省值为空。 | + + + **表20** **customizeData对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识数据项的键名称。字符串最大长度为255字节。 | 字符串 | 可缺省,缺省值为空。 | +| value | 标识数据项的值。字符串最大长度为255字节。 | 字符串 | 可缺省,缺省值为空。 | +| extra | 标识当前custom数据的格式,取值为表示extra的资源值。 | 字符串 | 可缺省,缺省值为空。 | + + +forms示例: + +```json +"forms": [ + { + "name": "Form_Js", + "description": "It's Js Form", + "type": "JS", + "jsComponentName": "card", + "colorMode": "auto", + "isDefault": true, + "updateEnabled": true, + "scheduledUpdateTime": "11:00", + "updateDuration": 1, + "defaultDimension": "2*2", + "supportDimensions": [ + "2*2", + "2*4", + "4*4" + ] + }, + { + "name": "Form_Js", + "description": "It's JS Form", + "type": "Js", + "colorMode": "auto", + "isDefault": false, + "updateEnabled": true, + "scheduledUpdateTime": "21:05", + "updateDuration": 1, + "defaultDimension": "1*2", + "supportDimensions": [ + "1*2" + ], + "landscapeLayouts": [ + "$layout:ability_form" + ], + "portraitLayouts": [ + "$layout:ability_form" + ], + "formConfigAbility": "ability://com.example.myapplication.fa/.MainAbility", + "metaData": { + "customizeData": [ + { + "name": "originWidgetName", + "value": "com.example.weather.testWidget" + } + ] + } + } +] +``` + + + **表21** **distroFilter对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| apiVersion | 标识支持的apiVersion范围。 | 对象数组 | 可缺省,缺省值为空。 | +|screenShape | 标识屏幕形状的支持策略。 | 对象数组 | 可缺省,缺省值为空。 | +| screenWindow | 标识应用运行时窗口的分辨率支持策略。该字段仅支持对轻量级智能穿戴设备进行配置。 | 对象数组 | 可缺省,缺省值为空。 | +|screenDensity | 标识屏幕的像素密度(dpi:Dots Per Inch)。 | 对象数组 | 可缺省,缺省值为空。 | +| countryCode | 标识分发应用时的国家码。具体值参考ISO-3166-1的标准,支持多个国家和地区的枚举定义。 | 对象数组 | 可缺省,缺省值为空。 | + + + **表22** **apiVersion对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 不可缺省。 | +| value | 支持的取值为API Version存在的整数值,例如4、5、6。场景示例:某应用,针对相同设备型号,同时在网的为使用API 5和API 6开发的两个软件版本,则允许上架2个entry类型的安装包,分别支持到对应设备侧软件版本的分发。 | 数组 | 不可缺省。 | + + + **表23** **screenShape对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 不可缺省。 | +| value | 支持的取值为API Version存在的整数值,例如4、5、6。场景示例:某应用,针对相同设备型号,同时在网的为使用API 5和API 6开发的两个软件版本,则允许上架2个entry类型的安装包,分别支持到对应设备侧软件版本的分发。 | 数组 | 不可缺省。 | + + + **表24** **screenWindow对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 不可缺省。 | +| value | 支持的取值为API Version存在的整数值,例如4、5、6。场景示例:某应用,针对相同设备型号,同时在网的为使用API 5和API 6开发的两个软件版本,则允许上架2个entry类型的安装包,分别支持到对应设备侧软件版本的分发。 | 数组 | 不可缺省。 | + + + **表25** **screenDensity对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 不可缺省。 | +| value | 取值范围如下:
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]的设备。 | 数组 | 不可缺省。 | + + + **表26** **countryCode对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| policy | 标识该子属性取值规则。配置为“exclude”或“include”。
- exclude:表示需要排除的value属性。
- include:表示需要包含的value属性。 | 字符串 | 不可缺省。 | +| value | 该标签标识应用需要分发的国家码,标签为字符串数组,子串表示支持的国家或地区,由两个大写字母表示。 | 字符串数组 | 不可缺省。 | + + +distroFilter示例: + +```json +"distroFilter": { + "apiVersion": { + "policy": "include", + "value": [4,5] + }, + "screenShape": { + "policy": "include", + "value": ["circle","rect"] + }, + "screenWindow": { + "policy": "include", + "value": ["454*454","466*466"] + }, + "screenDensity":{ + "policy": "exclude", + "value": ["ldpi","xldpi"] + }, + "countryCode": { + "policy":"include", + "value":["CN","HK"] + } +} +``` + + + **表27** **commonEvents对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识静态公共事件名称,该标签最大长度为127字节。 | 字符串 | 不可缺省。 | +| permission | 此标签标识实现静态公共事件所需要申请的权限,该标签最大长度为255字节。 | 字符串 | 可缺省,缺省值为空。 | +| data | 标识配置当前静态公共事件要携带的附加数据数组。 | 字符串数组 | 可缺省,缺省值为空。 | +| type | 该标签用于配置当前静态公共事件的分类数组。 | 字符串数组 | 可缺省,缺省值为空。 | +| events | 此标签标识可接收的意图的一组事件值。一般由系统预定义,也可以自定义。 | 字符串数组 | 不可缺省。 | + + +commonEvents示例: + +```json +"commonEvents": [ + { + "name": ".MainAbility", + "permission": "ohos.permission.GET_BUNDLE_INFO", + "data": [ + "com.example.demo", + "100" + ], + "events": [ + "install", + "update" + ] + } +] +``` + + + **表28** **testRunner对象的内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识测试框架对象名称,该标签最大长度为255字节。 | 字符串 | 不可缺省。 | +| srcPath | 标识测试框架代码路径,该标签最大长度为255字节。 | 字符串 | 不可缺省。 | + +```json +"testRunner": { + "name": "myTestRunnerName", + "srcPath": "etc/test/TestRunner.ts" +} +``` + + +definePermission仅支持系统应用配置,三方应用配置不生效。 + + + **表29** **definePermissions对象内部结构说明** + +| 属性名称 | 含义 | 数据类型 | 是否可缺省 | +| -------- | -------- | -------- | -------- | +| name | 标识权限的名称,该标签最大长度为255字节。 | 字符串 | 不可缺省。 | +| grantMode | 标识权限的授予方式,支持如下两种授予模式如下:
- system_grant:安装后系统自动授予该权限。
- user_grant:使用时动态申请,用户授权后才可使用。 | 字符串 | 可缺省,缺省值为system_grant。 | +| availableLevel | 标识权限限制类别,可选值如下:
- system_core:系统核心权限。
- system_basic:系统基础权限。
- normal:普通权限。所有应用允许申请的权限。 | 字符串 | 可缺省,缺省值为normal。 | +| provisionEnable | 标识权限是否支持证书方式申请权限,包括高级别的权限。配置为true标识开发者可以通过provision方式申请权限。 | 布尔值 | 可缺省,缺省值为true。 | +| distributedSceneEnabled | 标识权限是否支持分布式场景下使用该权限。 | 布尔值 | 可缺省,缺省值为false。 | +| label | 标识权限的简短描述,配置为对描述内容的资源索引。 | 字符串 | 可缺省,缺省值为空。 | +| description | 标识权限的详细描述,可以是字符串(最大长度为255字节),或者为对描述内容的资源索引。 | 字符串 | 可缺省,缺省值为空。 | diff --git a/zh-cn/application-dev/quick-start/multi-hap-build-view.md b/zh-cn/application-dev/quick-start/multi-hap-build-view.md new file mode 100644 index 0000000000000000000000000000000000000000..35255cd1a9f579149b4dbc3ee98cb6f6d26b8e90 --- /dev/null +++ b/zh-cn/application-dev/quick-start/multi-hap-build-view.md @@ -0,0 +1,28 @@ +# 多HAP构建视图 + + +IDE支持在一个应用工程中进行多个HAP的开发与构建,如[多HAP构建视图](figures/hap-multi-view.png)所示。 + + + **图1** 多HAP构建视图   +![hap-multi-view](figures/hap-multi-view.png) + + +1. IDE开发态视图 + - AppScope目录 + - [app.json5](app-configuration-file.md):配置应用全局描述信息,例如应用包名、版本号、应用图标、应用名称和依赖的SDK版本号等。 + - resources目录:放置应用的图标资源和应用名称字符串资源。 + + **说明:** + - 该目录由IDE自动生成,名称不可更改。 + - AppScope目录下面的文件名与Entry、Feature模块下面的文件名不能重复,否则IDE会报错。 + - entry或者featrue目录(名称可由开发者自定义) + - 由IDE引导开发者创建的Module,在该Module中实现应用的业务逻辑;可以创建多个Module,图中entry和featrue即是创建的两个Module。 + - resources目录:放置该Module中所使用到的资源。 + - ets目录:开发者的业务逻辑。 + - [module.json5](module-configuration-file.md):配置该Module的描述信息,如:Module的名称、Module的入口代码路径、包含的组件信息等。 + +2. 编译打包后的视图 + - 一个开发态的Module编译后生成一个部署态的HAP,Module和HAP一一对应。 + - HAP中的module.json由开发视图中的app.json5和module.json5合成。 + - 所有的HAP最终会编译到一个App Pack中(以.app为后缀的包文件),用于发布到应用市场。 diff --git a/zh-cn/application-dev/quick-start/multi-hap-objective.md b/zh-cn/application-dev/quick-start/multi-hap-objective.md new file mode 100644 index 0000000000000000000000000000000000000000..3ddc106ec74822cff7a32bc672d040e2d3bf7767 --- /dev/null +++ b/zh-cn/application-dev/quick-start/multi-hap-objective.md @@ -0,0 +1,10 @@ +# 多HAP机制设计目标 + + +- 方便开发者模块化的管理应用,好的应用一般都是模块化管理,模块之间属于松耦合关系。多HAP方便了开发者将业务划分成多个模块,每个模块放到独立的HAP中。例如支付类应用,有统一的主界面,主界面管理“扫一扫”、“收付款”、“消息”、“理财”等各个模块。其中主界面管理其他模块的逻辑在Entry包中实现,而“扫一扫”、“收付款”、“消息”和“理财”等模块在不同的Feature包中实现。可以同时开发多个Feature包,能够实现Feature包单独的开发测试,最终由Entry包统一集成Feature包的特性。 + +- 方便开发者将多HAP合理地组合并部署到不同的设备上。例如应用程序包含一个Entry包和两个Featrue包(Feature1和Feature2)。其中Entry包可以部署到设备A和设备B,Feature1只能部署到设备A,Feature2包只部署到设备B上,那么开发者就可以方便的组合Entry和Feature1部署到设备A上,组合Entry和Feature2部署到设备B上。 + +- 方便开发者按需加载所需模块,减少包大小。开发者可以将一个应用的某些HAP配置成按需加载。应用在启动阶段初始用不到的特性,可以配置暂不加载,当用户用到这些特性的时候,可由应用自动下载这些特性HAP,一定程度上减少应用包的大小。 + +- 方便应用资源共享,减少程序包大小。多个HAP都需要用到的资源(包括公共资源文件、公共页面等)以及so(shared object)文件可以放到单独的HAP中,其他HAP可以到该HAP中访问资源和so文件,也一定程度上可以减少应用程序包大小。 diff --git a/zh-cn/application-dev/quick-start/multi-hap-principles.md b/zh-cn/application-dev/quick-start/multi-hap-principles.md new file mode 100644 index 0000000000000000000000000000000000000000..0587c5bd8e324a668940bbeba98deb12b4611b6f --- /dev/null +++ b/zh-cn/application-dev/quick-start/multi-hap-principles.md @@ -0,0 +1,21 @@ +# 多HAP运行机制及数据通信方式 + + +多HAP机制主要是为方便开发者进行模块化管理。HAP和应用运行时的进程并不是一一对应的,具体运行机制如下: + + +- 默认情况下,应用中(同一包名)的所有UIAbility、ServiceExtensionAbility、DataShareExtensionAbility运行在同一个独立进程中,其他同类型ExtensionAbility分别运行在单独的进程。 + +- HAP支持在module.json5(Stage模型)或者config.json(FA模型)中通过process标签配置单独的进程(仅系统应用支持,三方应用不支持)。配置了process的HAP,其组件运行在单独的process进程中,多个HAP可以配置相同的process,则这些HAP运行在相同进程中,process配置的详细说明请参见[module.json5配置文件](module-configuration-file.md)。 + +- 应用运行时,同一进程中的UIAbility组件被启动时,才加载对应HAP的资源和代码。 + + +基于上述机制,多HAP数据通信方式如下: + + +- 同一进程内的数据通信,请参见[线程间通信](../application-models/thread-model-stage.md)。 + +- 跨进程的数据通信,请参见[进程间通信](../application-models/process-model-stage.md)。。 + +- 多HAP如果运行在同一进程,则多HAP间组件的通信方式与同一HAP内组件的通信方式相同。 diff --git a/zh-cn/application-dev/quick-start/multi-hap-release-deployment.md b/zh-cn/application-dev/quick-start/multi-hap-release-deployment.md new file mode 100644 index 0000000000000000000000000000000000000000..cdff86728aa7a63a86fae866e458f7c59bc7a1b9 --- /dev/null +++ b/zh-cn/application-dev/quick-start/multi-hap-release-deployment.md @@ -0,0 +1,19 @@ +# 多HAP发布部署流程 + + +多HAP发布部署流程如下: + + +1. 开发者通过IDE按照业务的需要创建多个Module,在相应的Module中完成自身业务的开发。 + +2. 通过IDE编译打包,生成App包。 + +3. 将该App包上架到应用市场云端,应用市场会对上架的App包校验签名,校验签名通过后会将App包中的HAP拆分出来,同时对拆分出的HAP重新添加签名,接着对HAP进行分发。 + +4. 用户在设备上的应用市场客户端能够看到各种各样的应用,这些应用均由云端分发而来,有些是多HAP应用,有些是单HAP应用。用户选择某个应用后,应用市场将下载应用包含的全部HAP。 + +5. 下载完成后,应用市场客户端再调用系统中包管理服务的安装接口安装下载的HAP,包管理服务以应用为单位将其中所有HAP部署到指定目录下,以完成应用的安装。 + + + **图1** 多HAP发布部署流程   +![hap-release](figures/hap-release.png) diff --git a/zh-cn/application-dev/quick-start/multi-hap-rules.md b/zh-cn/application-dev/quick-start/multi-hap-rules.md new file mode 100644 index 0000000000000000000000000000000000000000..df77b090d6dd40f522b6c9d779a22104aff5d7de --- /dev/null +++ b/zh-cn/application-dev/quick-start/multi-hap-rules.md @@ -0,0 +1,14 @@ +# 多HAP使用规则 + + +- App Pack包不能直接安装到设备上,只是上架应用市场的单元。 + +- App Pack包中所有HAP的配置文件中的bundleName标签必须一致。 + +- App Pack包中所有HAP的配置文件中的versionCode标签必须一致。 + +- App Pack包中同一设备类型的所有HAP中必须有且只有一个entry类型的HAP,featrue类型的HAP可以有一个或者多个,也可以没有。 + +- App Pack包中的每个HAP必须配置moduleName标签,同一设备类型的所有HAP对应的moduleName标签必须唯一。 + +- 同一应用的所有HAP签名证书要保持一致。上架应用市场是以App Pack的形式上架,并对其进行了签名。应用市场分发时会将所有HAP从App Pack中拆分出来,同时对其中的所有HAP进行重签名,这样保证了所有HAP签名证书的一致性。在调试阶段,开发者通过命令行或IDE将HAP安装到设备上时要保证所有HAP签名证书一致,否则会出现安装失败的问题。 diff --git a/zh-cn/application-dev/quick-start/package-structure.md b/zh-cn/application-dev/quick-start/package-structure.md deleted file mode 100755 index 60c0c6891bdaaa6015d19b5a0cab0cd738b5e386..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/quick-start/package-structure.md +++ /dev/null @@ -1,863 +0,0 @@ - - -# 应用包结构配置文件的说明(FA模型) - -在FA模型的应用开发的工程中,需要在config.json配置文件中对应用的包结构进行声明。 - -## 配置文件的内部结构 - -“config.json”由app,deviceConfig和module三个部分组成,缺一不可。配置文件的内部结构说明参见表1。 - -表1 配置文件的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------ | ------------------------------------------------------------ | -------- | ---------- | -| app | 标识应用的全局配置信息。同一个应用的不同HAP包的app配置必须保持一致。参考[app对象内部结构](#app对象内部结构)。 | 对象 | 不可缺省。 | -| deviceConfig | 标识应用在具体设备上的配置信息。参考[deviceConfig对象内部结构](#deviceconfig对象的内部结构)。 | 对象 | 不可缺省。 | -| module | 标识HAP包的配置信息。该标签下的配置只对当前HAP包生效。参考[module对象的内部结构](#module对象的内部结构)。 | 对象 | 不可缺省。 | - -config.json示例: - -```json -{ - "app": { - "bundleName": "com.example.myapplication", - "vendor": "example", - "version": { - "code": 1000000, - "name": "1.0.0" - } - }, - "deviceConfig": {}, - "module": { - "package": "com.example.myapplication", - "name": ".entry", - "mainAbility": ".MainAbility", - "deviceType": [ - "default", - "tablet" - ], - "distro": { - "deliveryWithInstall": true, - "moduleName": "entry", - "moduleType": "entry", - "installationFree": false - }, - "abilities": [ - { - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ], - "orientation": "unspecified", - "formsEnabled": false, - "name": ".MainAbility", - "srcLanguage": "ets", - "srcPath": "MainAbility", - "icon": "$media:icon", - "description": "$string:ability_desc", - "label": "$string:ability_label", - "type": "page", - "visible": true, - "launchType": "standard" - } - ], - "js": [ - { - "mode": { - "syntax": "ets", - "type": "pageAbility" - }, - "pages": [ - "pages/LoginPage", - "pages/MinePage", - "pages/RegistrationSuccessPage", - "pages/PrivacyPage", - "pages/CustomerServicePage" - ], - "name": ".MainAbility", - "window": { - "designWidth": 720, - "autoDesignWidth": false - } - } - ] - } -} -``` - -### app对象内部结构 - -app对象包含应用全局配置信息,内部结构说明参见表2。 - -表2 app对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ----------------- | ------------------------------------------------------------ | -------- | --------------------------- | -| bundleName | 标识应用的包名,用于标识应用的唯一性。包名是由字母、数字、下划线(_)和点号(.)组成的字符串,必须以字母开头。支持的字符串长度为7~127字节。
包名通常采用反向域名形式表示(例如,"com.example.myapplication")。建议第一级为域名后缀"com",第二级为厂商/个人名,也可以采用多级。 | 字符串 | 不可缺省。 | -| vendor | 标识对应用开发厂商的描述。字符串长度不超过255字节。 | 字符串 | 可缺省,缺省值为空。 | -| version | 标识应用的版本信息。参考表3。 | 对象 | 不可缺省。 | -| apiVersion | 标识应用程序所依赖的OpenHarmony API版本。参考表4。 | 对象 | 可缺省,缺省值为空。 | -| smartWindowSize | 标识应用在模拟器中运行时使用的屏幕尺寸。 | 字符串 | 可缺省,缺省值为空。 | -| smartWindowDeviceType | 标识应用在模拟器中运行时可以模拟的设备。 | 字符串数组 | 可缺省,缺省值为空。 | - -表3 version内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------------------ | ------------------------------------------------------------ | -------- | -------------------------- | -| name | 标识应用的版本号,用于向应用的终端用户呈现。取值可以自定义,长度不超过127字节。自定义规则如下:
API5及更早的版本:推荐使用三段数字版本号(也兼容两段式版本号),如A.B.C(也兼容A.B),其中A、B、C取值为0-999范围内的整数。除此之外不支持其他格式。
A段,一般表示主版本号(Major)。
B段,一般表示次版本号(Minor)。
C段,一般表示修订版本号(Patch)。
API6版本起:推荐采用四段式数字版本号,如A.B.C.D,其中A、B、C取值为0-99范围内的整数,D的取值为0-999范围内的整数。
A段,一般表示主版本号(Major)。
B段,一般表示次版本号(Minor)。
C段,一般表示特性版本号(Feature)。
D段,一般表示修订版本号(Patch)。 | 数值 | 不可缺省。 | -| code | 标识应用的版本号,仅用于OpenHarmony管理该应用,不对应用的终端用户呈现。取值规则如下:
API5及更早版本:二进制32位以内的非负整数,需要从version.name的值转换得到。转换规则为:
code值=A * 1,000,000 + B * 1,000 + C 例如,version.name字段取值为2.2.1,则code值为2002001。
API6版本起:code的取值不与version.name字段的取值关联,开发者可自定义code取值,取值范围为2^31以内的非负整数,
但是每次应用版本的更新,均需要更新code字段的值,新版本code取值必须大于旧版本code的值。 | 数值 | 不可缺省。 | -| minCompatibleVersionCode | 标识应用可兼容的最低版本号,用于跨设备场景下,判断其他设备上该应用的版本是否兼容。
格式与version.code字段的格式要求相同。 | 数值 | 可缺省,缺省值为code标签值。 | - -表4 apiVersion内部结构 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ----------- | ----------------------------------------------------------- | -------- | ---------- | -| compatible | 运行应用所需要的最低API版本,取值范围为0~2147483647。 | 数值 | 配置在build.profile中,打包时由IDE填充到config.json中。 | -| target | 用于标识应用运行所需的目标API版本,取值范围为0~2147483647。 | 数值 | 配置在build.profile中,打包时由IDE填充到config.json中。 | -| releaseType | 用于标识应用运行时SDK的状态。
canary:面向特定开发者早期预览版本,不承诺质量,不承诺API稳定。
beta:公开发布的Beta版本,早期Beta版本不承诺API稳定,经历若干次发布后,通过Release Notes对开发者声明该Beta版本为API稳定里程碑,后续版本的API冻结。
release:正式发布版本,承诺质量,API不可变更。当版本处于此状态时版本号中不呈现Stage字段。 | 字符串 | 配置在build.profile中,打包时由IDE填充到config.json中。 | - -app实例: - -```json -{ - "app": { - "bundleName": "com.example.myapplication", - "vendor": "example", - "version": { - "code": 1000000, - "name": "1.0.0" - }, - "apiVersion": { - "compatible": 9, - "target": 9, - "releaseType": "Beta1" - } - } -} -``` - -### deviceConfig对象的内部结构 - -deviceConfig包含设备上的应用配置信息,可以包含default,tv,car,wearable等属性。default标签内的配置适用于所有通用设备,其他设备类型如果有特殊的需求,则需要在该设备类型的标签下进行配置。内部结构说明参见表5。 - -表5 deviceConfig对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ----------------------------------------- | -------- | ------------------ | -| default | 能够使用全部系统能力的OpenHarmony设备。 | 对象 | 可缺省,缺省值为空。 | -| tablet | 标识平板的应用配置信息。 | 对象 | 可缺省,缺省值为空。 | -| tv | 标识智慧屏特有的应用配置信息。 | 对象 | 可缺省,缺省值为空。 | -| car | 标识车机特有的应用配置信息。 | 对象 | 可缺省,缺省值为空。 | -| wearable | 标识智能穿戴特有的应用配置信息。| 对象 | 可缺省,缺省值为空。 | - -default、tablet、tv、car、wearable等对象的内部结构说明如下: - -表6 deviceConfig设备对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------------ | ------------------------------------------------------------ | -------- | ----------------------- | -| process | 标识应用或者Ability的进程名。如果在deviceConfig标签下配置了process标签,则该应用的所有Ability都运行在这个进程中。如果在abilities标签下也为某个Ability配置了process标签,
则该Ability就运行在这个进程中。该标签最大长度为31。 | 字符串 | 可缺省,缺省值为空。 | -| keepAlive | 标识应用是否始终保持运行状态,仅支持系统应用配置,三方应用配置不生效。该标签为布尔类型,可缺省,缺省值为false,如果配置为true,应用将始终保持为运行状态,
并在系统启动的时候被系统驱动起来,应用进程退出后,系统也会重新启动应用进程。 | 布尔值 | 可缺省,缺省值为false。 | -| supportBackup | 标识应用是否支持备份和恢复。如果配置为false,则不支持为该应用执行备份或恢复操作。 | 布尔值 | 可缺省,缺省值为false。 | -| compressNativeLibs | 标识libs库是否以压缩存储的方式打包到HAP包。如果配置为false,则libs库以不压缩的方式存储,HAP包在安装时无需解压libs,运行时会直接从HAP内加载libs库。 | 布尔值 | 可缺省,缺省值为false。 | -| network | 标识网络安全性配置。该标签允许应用通过配置文件的安全声明来自定义其网络安全,无需修改应用代码。参考表7。 | 对象 | 可缺省,缺省值为空。 | - -表7 network对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ---------------- | ------------------------------------------------------------ | -------- | ----------------------- | -| cleartextTraffic | 标识是否允许应用使用明文网络流量(例如,明文HTTP)。
true:允许应用使用明文流量请求。
false:拒绝应用使用明文流量的请求。 | 布尔值 | 可缺省,缺省值为false。 | -| securityConfig | 标识应用的网络安全配置信息。参考表8。 | 对象 | 可缺省,缺省值为空。 | - -表8 securityConfig对象的内部结构说明 - -| 属性名称 | 子属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------------- | ------------------ | ------------------------------------------------------------ | -------- | ---------------- | -| domainSettings | - | 标识自定义的网域范围的安全配置,支持多层嵌套,即一个domainSettings对象中允许嵌套更小网域范围的domainSettings对象。 | 对象 | 可缺省,缺省值为空。 | -| | cleartextPermitted | 标识自定义的网域范围内是否允许明文流量传输。当cleartextTraffic和security同时存在时,自定义网域是否允许明文流量传输以cleartextPermitted的取值为准。
true:允许明文流量传输。
false:拒绝明文流量传输。 | 布尔值 | 可缺省,缺省值为空。 | -| | domains | 标识域名配置信息,包含两个参数:subdomains和name。
subdomains(布尔类型):表示是否包含子域名。如果为true,此网域规则将与相应网域及所有子网域(包括子网域的子网域)匹配。
否则,该规则仅适用于精确匹配项。name(字符串):表示域名名称。 | 对象数组 | 可缺省,缺省值为空。 | - -deviceConfig示例: - -```json -{ - "deviceConfig": { - "default": { - "process": "com.example.myapplication", - "supportBackup": false, - "network": { - "cleartextTraffic": true, - "securityConfig": { - "domainSettings": { - "cleartextPermitted": true, - "domains": [ - { - "subdomains": true, - "name": "example.ohos.com" - } - ] - } - } - } - } - } -} -``` - -### module对象的内部结构 - -module对象包含HAP包的配置信息,内部结构说明参见表9。 - -表9 module对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ----------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | -| mainAbility | 服务中心图标露出的ability,常驻进程拉起时会启动mainAbility。 | 字符串 | 可缺省,缺省值为空。 | -| package | 标识HAP的包结构名称,在应用内保证唯一性。采用反向域名格式(建议与HAP的工程目录保持一致)。字符串长度为1-127个字节。 | 字符串 | 不可缺省。 | -| name | 标识HAP的类名。采用反向域名方式标识,前缀要与同级的package标签指定的包名一致,也可采用"."开头的命名方式。字符串长度不超过255字节。 | 字符串 | 可缺省,缺省值为空。 | -| description | 标识HAP的描述信息。字符串长度不超过255字节。如果字符串超出长度或者需要支持多语言,可以采用资源索引的方式添加描述内容。 | 字符串 | 可缺省,缺省值为空。 | -| supportedModes | 标识应用支持的运行模式,当前只定义了驾驶模式(drive)。该标签只适用于车机。 | 字符串数组 | 可缺省,缺省值为空。 | -| deviceType | 标识允许Ability运行的设备类型。系统预定义的设备类型包括:tablet(平板)、tv(智慧屏)、car(车机)、wearable(智能穿戴)等。 | 字符串数组 | 不可缺省。 | -| distro | 标识HAP发布的具体描述。参考表10。 | 对象 | 不可缺省。 | -| metaData | 标识HAP的元信息。参考表11。 | 对象 | 可缺省,缺省值为空。 | -| abilities | 标识当前模块内的所有Ability。采用对象数据格式。参考表15。 | 对象数组 | 可缺省,缺省值为空。 | -| js | 标识基于ArkUI框架开发的JS模块集合,其中的每个元素代表一个JS模块的信息。参考表21。 | 对象数组 | 可缺省,缺省值为空。 | -| shortcuts | 标识应用的快捷方式信息。采用对象数组格式,其中的每个元素表示一个快捷方式对象。参考表24。 | 对象数组 | 可缺省,缺省值为空。 | -| reqPermissions | 标识应用运行时向系统申请的权限。参考表19。 | 对象数组 | 可缺省,缺省值为空。 | -| colorMode | 标识应用自身的颜色模式。
dark:表示按照深色模式选取资源。
light:表示按照浅色模式选取资源。
auto:表示跟随系统的颜色模式值选取资源。 | 字符串 | 可缺省,缺省值为"auto"。 | -| distroFilter | 标识应用的分发规则。
该标签用于定义HAP包对应的细分设备规格的分发策略,以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括:
API Version、屏幕形状、屏幕尺寸、屏幕分辨率、国家和地区码。
在进行分发时,通过deviceType与这五个属性的匹配关系,唯一确定一个用于分发到设备的HAP。参考表27。 | 对象 | 可缺省,缺省值为空。但当应用中包含多个entry模块时,必须配置该标签。 | -| commonEvents | 定义了公共事件静态订阅者的信息,该字段中需要声明静态订阅者的名称、权限要求及订阅事件列表信息,当订阅的公共事件发送时,
该公共事件静态订阅者将被拉起。这里的静态订阅者区分于常用的动态订阅者,前者无需在业务代码中主动调用订阅事件的接口,
在公共事件发布时可能未被拉起,而动态订阅者则在业务代码中主动调用公共事件订阅的相关API,因此需要应用处于活动状态。参考表33。 | 对象数组 | 可缺省,缺省值为空。 | -| entryTheme | 此标签标识OpenHarmony内部主题的关键字。将标记值设置为名称的资源索引。 | 字符串 | 可缺省,缺省值为空。 | -| testRunner | 此标签用于支持对测试框架的配置,参考表34。 | 对象 | 可缺省,缺省值为空。 | - -module示例: - -```json -{ - "module": { - "package": "com.example.myapplication", - "name": ".entry", - "mainAbility": ".MainAbility", - "deviceType": [ - "default", - "tablet" - ], - "distro": { - "deliveryWithInstall": true, - "moduleName": "entry", - "moduleType": "entry", - "installationFree": false - }, - "abilities": [ - { - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ], - "orientation": "unspecified", - "formsEnabled": false, - "name": ".MainAbility", - "srcLanguage": "ets", - "srcPath": "MainAbility", - "icon": "$media:icon", - "description": "$string:ability_desc", - "label": "$string:ability_label", - "type": "page", - "visible": true, - "launchType": "standard" - } - ], - "js": [ - { - "mode": { - "syntax": "ets", - "type": "pageAbility" - }, - "pages": [ - "pages/LoginPage", - "pages/MinePage", - "pages/RegistrationSuccessPage", - "pages/PrivacyPage", - "pages/CustomerServicePage" - ], - "name": ".MainAbility", - "window": { - "designWidth": 720, - "autoDesignWidth": false - } - } - ] - } -} -``` - -表10 distro对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ---------------- | ------------------------------------------------------------ | -------- | ---------- | -| moduleName | 标识当前HAP的名称,最大长度为31个字节。 | 字符串 | 不可缺省。 | -| moduleType | 标识当前HAP的类型,包括三种类型:entry、feature和har。 | 字符串 | 不可缺省。 | -| installationFree | 标识当前HAP是否支持免安装特性。
true:表示支持免安装特性,且符合免安装约束。
false:表示不支持免安装特性。
另外还需注意:
当entry.hap该字段配置为true时,与该entry.hap相关的所有feature.hap该字段也需要配置为true。
当entry.hap该字段配置为false时,与该entry.hap相关的各feature.hap该字段可按业务 需求配置true或false。 | 布尔值 | 不可缺省。 | -| deliveryWithInstall | 标识当前HAP是否在用户主动安装HAP所在应用的时候一起安装。
true:安装应用时当前HAP随应用一起下载安装。
false:安装应用时当前HAP并不下载安装,后续使用时按需下载。| 布尔值 | 不可缺省。 | - -distro示例: - -```json -{ - "module": { - "distro": { - "deliveryWithInstall": true, - "moduleName": "entry", - "moduleType": "entry", - "installationFree": false - } - } -} -``` - -表11 metaData对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------- | ------------------------------------------------------------ | -------- | -------------------- | -| parameters | 标识调用Ability时所有调用参数的元信息。每个调用参数的元信息由以下三个标签组成:description、name、type。参考表12。 | 对象数组 | 可缺省,缺省值为空。 | -| results | 标识Ability返回值的元信息。每个返回值的元信息由以下三个标签组成:description、name、type。参考表13。 | 对象数组 | 可缺省,缺省值为空。 | -| customizeData | 该标签标识父级组件的自定义元信息,Parameters和results在application不可配。参考表14 | 对象数组 | 可缺省,缺省值为空。 | - -表12 parameters对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ----------- | ------------------------------------------------------------ | -------- | ------------------ | -| description | 标识对调用参数的描述,可以是表示描述内容的字符串,也可以是对描述内容的资源索引以支持多语言。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | -| name | 标识调用参数的名称。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | -| type | 标识调用参数的类型,如Integer。 | 字符串 | 不可缺省。 | - -表13 results对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ----------- | ------------------------------------------------------------ | -------- | -------------------- | -| description | 标识对返回值的描述,可以是表示描述内容的字符串,也可以是对描述内容的资源索引以支持多语言。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | -| name | 标识返回值的名字。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | -| type | 标识返回值的类型,如Integer。 | 字符串 | 不可缺省。 | - -表14 customizeData对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ---------------------------------------------------------- | -------- | -------------------- | -| name | 标识数据项的键名称,字符串类型(最大长度255字节)。 | 字符串 | 可缺省,缺省值为空。 | -| value | 标识数据项的值名称,字符串类型(最大长度255字节)。 | 字符串 | 可缺省,缺省值为空。 | -| extra | 标识用户自定义数据格式,标签值为标识该数据的资源的索引值。 | 字符串 | 可缺省,缺省值为空。 | - -metaData示例: - -```json -{ - "module": { - "metaData": { - "parameters": [ - { - "name": "string", - "type": "Float", - "description": "$string:parameters_desc" - } - ], - "results": [ - { - "name": "string", - "type": "Float", - "description": "$string:results_desc" - } - ], - "customizeData": [ - { - "name": "string", - "value": "string", - "extra": "$string:customizeData_desc" - } - ] - } - } -} -``` - -表15 abilities对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ---------------- | ------------------------------------------------------------ | ---------- | -------------------------------------------------------- | -| process | 运行应用程序或Ability的进程名称。如果在deviceConfig标记中配置了进程,则应用程序的所有能力都在此进程中运行。您还可以为特定能力设置流程属性,以便该能力可以在此流程中运行。如果此属性设置为与其他应用程序相同的进程名称,则所有这些应用程序可以在同一进程中运行,前提是他们具有相同的联合用户ID和相同的签名。运行OHOS的设备不支持此属性。该标签最大字节数为31个字节。 | 字符串 | 可缺省,缺省值为空。 | -| name | 标识Ability名称。取值可采用反向域名方式表示,由包名和类名组成,如“com.example.myapplication.MainAbility”;也可采用“.”开头的类名方式表示,如“.MainAbility”。
Ability的名称,需在一个应用的范围内保证唯一。
说明:在使用DevEco Studio新建项目时,默认生成首个Ability的配置,即“config.json”中“MainAbility”的配置。如使用其他IDE工具,可自定义名称。该标签最大长度为127。 | 字符串 | 不可缺省。 | -| description | 标识对Ability的描述。取值可以是描述性内容,也可以是对描述性内容的资源索引,以支持多语言。该标签最大长度为255个字节。 | 字符串 | 可缺省,缺省值为空。 | -| icon | 标识Ability图标资源文件的索引。取值示例:$media:ability_icon。如果在该Ability的skills属性中,actions的取值包含 “action.system.home”,entities取值中包含“entity.system.home”,则该Ability的icon将同时作为应用的icon。如果存在多个符合条件的Ability,则取位置靠前的Ability的icon作为应用的icon。
说明:应用的“icon”和“label”是用户可感知配置项,需要区别于当前所有已有的应用“icon”或“label”(至少有一个不同)。 | 字符串 | 可缺省,缺省值为空。 | -| label | 标识Ability对用户显示的名称。取值可以是Ability名称,也可以是对该名称的资源索引,以支持多语言。如果在该Ability的skills属性中,actions的取值包含 “action.system.home”,entities取值中包含“entity.system.home”,则该Ability的label将同时作为应用的label。如果存在多个符合条件的Ability,则取位置靠前的Ability的label作为应用的label。
说明: 应用的“icon”和“label”是用户可感知配置项,需要区别于当前所有已有的应用“icon”或“label”(至少有一个不同)。该标签为资源文件中定义的字符串的引用,或以"{}"包括的字符串。该标签最大长度为255。 | 字符串 | 可缺省,缺省值为空。 | -| uri | 标识Ability的统一资源标识符。该标签最大长度为255。 | 字符串 | 可缺省,对于data类型的Ability不可缺省。 | -| launchType | 标识Ability的启动模式,支持“standard”和“singleton”两种模式:
standard:表示该Ability可以有多实例。该模式适用于大多数应用场景。
singleton:表示该Ability在所有任务栈中仅可以有一个实例。例如,具有全局唯一性的呼叫来电界面即采用“singleton”模式。 | 字符串 | 可缺省,缺省值为“singleton”。 | -| visible | 标识Ability是否可以被其他应用调用。
true:可以被其他应用调用。
false:不能被其他应用调用。 | 布尔值 | 可缺省,缺省值为false。 | -| permissions | 标识其他应用的Ability调用此Ability时需要申请的权限集合,一个数组元素为一个权限名称。通常采用反向域名格式(最大255字节),取值为系统预定义的权限。 | 字符串数组 | 可缺省,缺省值为空。 | -| skills | 标识Ability能够接收的want的特征。参考表17。 | 对象数组 | 可缺省,缺省值为空。 | -| deviceCapability | 标识Ability运行时要求设备具有的能力,采用字符串数组的格式表示。该标签为数组,支持最多配置512个元素,单个元素最大字节长度为64。 | 字符串数组 | 可缺省,缺省值为空。 | -| metaData | 元数据,参考表11。 | 对象 | 可缺省,缺省值为空。 | -| type | 标识Ability的类型。取值范围如下:
page:表示基于Page模板开发的FA,用于提供与用户交互的能力。
service:表示基于Service模板开发的PA,用于提供后台运行任务的能力。
data:表示基于Data模板开发的PA,用于对外部提供统一的数据访问抽象。
CA:表示支持其他应用以窗口方式调起该Ability。 | 字符串 | 不可缺省。 | -| orientation | 标识该Ability的显示模式。该标签仅适用于page类型的Ability。取值范围如下:
unspecified:由系统自动判断显示方向。
landscape:横屏模式。
portrait:竖屏模式。
followRecent:跟随栈中最近的应用。 | 字符串 | 可缺省,缺省值为“unspecified”。 | -| backgroundModes | 标识后台服务的类型,可以为一个服务配置多个后台服务类型。该标签仅适用于service类型的Ability。取值范围如下:
dataTransfer:通过网络/对端设备进行数据下载、备份、分享、传输等业务。
audioPlayback:音频输出业务。
audioRecording:音频输入业务。
pictureInPicture:画中画、小窗口播放视频业务。
voip:音视频电话、VOIP业务。
location:定位、导航业务。
bluetoothInteraction:蓝牙扫描、连接、传输业务。
wifiInteraction:WLAN扫描、连接、传输业务。
screenFetch:录屏、截屏业务。
multiDeviceConnection:多设备互联业务 | 字符串数组 | 可缺省,缺省值为空。 | -| grantPermission | 指定是否可以向Ability内任何数据授予权限。 | 布尔值 | 可缺省,缺省值为空。 | -| readPermission | 标识读取Ability的数据所需的权限。该标签仅适用于data类型的Ability。取值为长度不超过255字节的字符串。 | 字符串 | 可缺省,缺省值为空。 | -| writePermission | 标识向Ability写数据所需的权限。该标签仅适用于data类型的Ability。取值为长度不超过255字节的字符串。 | 字符串 | 可缺省,缺省值为空。 | -| configChanges | 标识Ability关注的系统配置集合。当已关注的配置发生变更后,Ability会收到onConfigurationUpdated回调。取值范围:
mcc:表示IMSI移动设备国家/地区代码(MCC)发生变更。典型场景:检测到SIM并更新MCC。
mnc:IMSI移动设备网络代码(MNC)发生变更。典型场景:检测到SIM并更新MNC。
locale:表示语言区域发生变更。典型场景:用户已为设备文本的文本显示选择新的语言类型。
layout:表示屏幕布局发生变更。典型场景:当前有不同的显示形态都处于活跃状态。
fontSize:表示字号发生变更。典型场景:用户已设置新的全局字号。
orientation:表示屏幕方向发生变更。典型场景:用户旋转设备。
density:表示显示密度发生变更。典型场景:用户可能指定不同的显示比例,或当前有不同的显示形态同时处于活跃状态。
size:显示窗口大小发生变更。
smallestSize:显示窗口较短边的边长发生变更。
colorMode:颜色模式发生变更。 | 字符串数组 | 可缺省,缺省值为空。 | -| mission | 标识Ability指定的任务栈。该标签仅适用于page类型的Ability。默认情况下应用中所有Ability同属一个任务栈。 | 字符串 | 可缺省,缺省为应用的包名。 | -| targetAbility | 标识当前Ability重用的目标Ability。该标签仅适用于page类型的Ability。如果配置了targetAbility属性,则当前Ability(即别名Ability)的属性中仅name、icon、label、visible、permissions、skills生效,其它属性均沿用targetAbility中的属性值。目标Ability必须与别名Ability在同一应用中,且在配置文件中目标Ability必须在别名之前进行声明。 | 字符串 | 可缺省,缺省值为空。表示当前Ability不是一个别名Ability。 | -| formsEnabled | 标识Ability是否支持卡片(forms)功能。该标签仅适用于page类型的Ability。
true表示支持卡片能力,false表示不支持卡片能力。 | 布尔值 | 可缺省,缺省值为false。 | -| forms | 标识服务卡片的属性。该标签仅当formsEnabled为true时,才能生效。参考表26。 | 对象数组 | 可缺省,缺省值为空。 | -| srcLanguage | Ability开发语言的类型,开发者创建工程时由开发者手动选择开发语言。 | 字符串 | 可缺省,取值为"js"或"ets" | -| srcPath | 该标签标识Ability对应的JS组件代码路径,该标签最大长度为127字节。 | 字符串 | 可缺省,缺省值为空。 | -| uriPermission | 标识该Ability有权访问的应用程序数据。此属性由模式和路径子属性组成。此属性仅对类型提供者的能力有效。运行OHOS的设备不支持此属性。参考表16。 | 对象 | 可缺省,缺省值为空。 | -| startWindowIcon | 标识该Ability启动页面图标资源文件的索引。该标签仅适用于page类型的ability。取值示例:$media:icon。 | 字符串 | 可缺省,缺省值为空。| -| startWindowBackground | 标识该Ability启动页面背景颜色资源文件的索引。该标签仅适用于page类型的ability。取值示例:$color:red。 | 字符串 | 可缺省,缺省值为空。| -| removeMissionAfterTerminate | 该标签标识ability销毁后是否从任务列表中移除任务。该标签仅适用于page类型的ability。true表示销毁后移除任务, false表示销毁后不移除任务。 | 布尔值 | 可缺省,缺省值为false。 | - -表16 uriPermission对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ----------------------- | -------- | ------------------------- | -| path | uriPermission标识的路径,该标签最大字节长度为255个字节。 | 字符串 | 不可缺省。 | -| mode | uriPermission的匹配模式 | 字符串 | 可缺省,缺省值为"default"。 | - -abilities示例: - -```json -{ - "module": { - "abilities": [ - { - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ], - "orientation": "unspecified", - "formsEnabled": false, - "name": ".MainAbility", - "srcLanguage": "ets", - "srcPath": "MainAbility", - "icon": "$media:icon", - "description": "$string:ability_desc", - "label": "$string:ability_label", - "type": "page", - "visible": true, - "launchType": "standard" - } - ] - } -} -``` - -表17 skills对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | ---------- | -------------------- | -| actions | 标识能够接收的want的action值,可以包含一个或多个action。取值通常为系统预定义的action值。 | 字符串数组 | 可缺省,缺省值为空。 | -| entities | 标识能够接收的want的Ability的类别(如视频、桌面应用等),可以包含一个或多个entity。 | 字符串数组 | 可缺省,缺省值为空。 | -| uris | 该标签标识向want过滤器添加数据规范集合。该规范可以是只有数据类型(mimeType属性),可以是只有URI,也可以是既有数据类型又有URI。
URI由其各个部分的单独属性指定:\://\:\/[\\|\\|\]。其中,scheme字段配置为uri时必配;当只设置数据类型(mimeType)时,则scheme字段为非必配项。参考表18。 | 对象数组 | 可缺省,缺省值为空。 | - -表18 uris对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------------- | -------------------------- | -------- | -------------------- | -| scheme | 标识uri的scheme值。 | 字符串 | 不可缺省。 | -| host | 标识uri的host值。 | 字符串 | 可缺省,缺省值为空。 | -| port | 标识uri的port值。 | 字符串 | 可缺省,缺省值为空。 | -| pathStartWith | 标识uri的pathStartWith值。 | 字符串 | 可缺省,缺省值为空。 | -| path | 标识uri的path值。 | 字符串 | 可缺省,缺省值为空。 | -| pathRegx | 标识uri的pathRegx值。 | 字符串 | 可缺省,缺省值为空。 | -| type | 标识uri的type值。 | 字符串 | 可缺省,缺省值为空。 | - -skills示例: - -```json -{ - "module": { - "abilities": [ - { - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ], - "uris": [ - { - "scheme": "http", - "host": "www.example.com", - "port": "8080", - "path": "query/student/name", - "type": "text/*" - } - ] - } - ] - } - ] - } -} -``` - -表19 reqPermissions权限申请字段说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ---------- | ------------------------------------------------------------ | -------- | ------------------ | -| name | 需要使用的权限名称。 | 字符串 | 不可缺省。 | -| reason | 描述申请权限的原因。需要做多语种适配。 | 字符串 | 分情况:当申请的权限为user_grant时,必须填写此字段,否则不允许在应用市场上架;其它权限可缺省,缺省值为空。 | -| usedScene | 描述权限使用的场景和时机。场景类型如下两种:
ability:ability的名称,可配置多个。
when:调用时机,可填的值有inuse(使用时)、always(始终) | 对象 | 可缺省,缺省值为空。when可缺省,缺省值为“inuse”。 | -具体示例可参考[访问控制开发指导](../security/accesstoken-guidelines.md#fa模型)。 - -表20 usedScene对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------- | --------------------| -------- | ------ | -| ability | 标识哪些Ability需要此权限,里面配置Ability的名称。| 字符串数组 | 可缺省,缺省表示所有Ability都需要此权限。 | -| when | 标识使用此权限的使用时间:
inuse:使用时需要此权限。
always:所有时间都需要此权限。 | 枚举值 | 可缺省,缺省值为空。 | - -表21 js对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | ------------------------ | -| name | 标识JS Component的名字。该标签不可缺省,默认值为default。 | 字符串 | 不可缺省。 | -| pages | 标识JS Component的页面用于列举JS Component中每个页面的路由信息[页面路径+页面名称]。该标签不可缺省,取值为数组,数组第一个元素代表JS FA首页。 | 字符串数组 | 不可缺省。 | -| window | 用于定义与显示窗口相关的配置。参考表22。 | 对象 | 可缺省,缺省值参考表22。 | -| type | 标识JS应用的类型。取值范围如下:
normal:标识该JS Component为应用实例。
form:标识该JS Component为卡片实例。 | 字符串 | 可缺省,缺省值为“normal” | -| mode | 定义JS组件的开发模式。参考表23。 | 对象 | 可缺省,缺省值为空。 | - -表22 window对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| --------------- | ------------------------------------------------------------ | -------- | ----------------------- | -| designWidth | 标识页面设计基准宽度。以此为基准,根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省,缺省值为720px。 | -| autoDesignWidth | 标识页面设计基准宽度是否自动计算。当配置为true时,designWidth将会被忽略,设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省,缺省值为false。 | - -表23 mode对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | -------------------- | ----------------------------------- | --------------------------- | -| type | 定义JS组件的功能类型 | 字符串,取值为"pageAbility"、"form" | 可缺省,缺省值为"pageAbility"。 | -| syntax | 定义JS组件的语法类型 | 字符串,取值为"hml","ets" | 可缺省,缺省值为"hml"。 | - -js示例: - -```json -{ - "module": { - "js": [ - { - "mode": { - "syntax": "ets", - "type": "pageAbility" - }, - "pages": [ - "pages/LoginPage", - "pages/MinePage", - "pages/RegistrationSuccessPage", - "pages/PrivacyPage", - "pages/CustomerServicePage" - ], - "name": ".MainAbility", - "window": { - "designWidth": 720, - "autoDesignWidth": false - } - } - ] - } -} -``` - -表24 shortcuts对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ---------- | ------------------------------------------------------------ | -------- | ------------------ | -| shortcutId | 标识快捷方式的ID。字符串的最大长度为63字节。 | 字符串 | 不可缺省。 | -| label | 标识快捷方式的标签信息,即快捷方式对外显示的文字描述信息。取值可以是描述性内容,也可以是标识label的资源索引。字符串最大长度为63字节。 | 字符串 | 可缺省,缺省值为空。 | -| icon | 标识快捷方式的图标信息。取值为表示icon的资源索引。 | 字符串 | 可缺省,缺省值为空。 | -| intents | 标识快捷方式内定义的目标intent信息集合,每个intent可配置两个子标签,targetClass, targetBundle。参考表25。 | 对象数组 | 可缺省,缺省值为空。 | - -表25 intents对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------------ | --------------------------------------- | -------- | -------------------- | -| targetClass | 标识快捷方式目标类名。 | 字符串 | 可缺省,缺省值为空。 | -| targetBundle | 标识快捷方式目标Ability所在应用的包名。 | 字符串 | 可缺省,缺省值为空。 | - -shortcuts示例: - -```json -{ - "module": { - "shortcuts": [ - { - "shortcutId": "id", - "label": "$string:shortcut", - "intents": [ - { - "targetBundle": "com.example.myapplication", - "targetClass": "com.example.myapplication.MainAbility" - } - ] - } - ] - } -} -``` - -表26 forms对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | -| name | 标识卡片的类名。字符串最大长度为127字节。 | 字符串 | 不可缺省。 | -| description | 标识卡片的描述。取值可以是描述性内容,也可以是对描述性内容的资源索引,以支持多语言。字符串最大长度为255字节。 | 字符串 | 可缺省,缺省值为空。 | -| isDefault | 标识该卡片是否为默认卡片,每个Ability有且只有一个默认卡片。
true:默认卡片。
false:非默认卡片。 | 布尔值 | 不可缺省。 | -| type | 标识卡片的类型。取值范围如下:
JS:JS卡片。 | 字符串 | 不可缺省。 | -| colorMode | 标识卡片的主题样式,取值范围如下:
auto:自适应。
dark:深色主题。
light:浅色主题。 | 字符串 | 可缺省,缺省值为“auto”。 | -| supportDimensions | 标识卡片支持的外观规格,取值范围:
1 * 2:表示1行2列的二宫格。
2 * 1:表示2行1列的二宫格。
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 | 标识是否允许卡片使用卡片可见性通知 | 字符串 | 可缺省,缺省值为空。 | -| jsComponentName | 标识JS卡片的Component名称。字符串最大长度为127字节。仅当卡片类型为JS卡片时,需要配置该标签。 | 字符串 | 不可缺省。 | -| metaData | 标识卡片的自定义信息,包含customizeData数组标签。参考表11。 | 对象 | 可缺省,缺省值为空。 | -| customizeData | 标识自定义的卡片信息。参考表14。 | 对象数组 | 可缺省,缺省值为空。 | - - -forms示例: - -```json -{ - "module": { - "abilities": [ - { - "forms": [ - { - "name": "Form_Js", - "description": "It's Js Form", - "type": "JS", - "jsComponentName": "card", - "colorMode": "auto", - "isDefault": true, - "updateEnabled": true, - "scheduledUpdateTime": "11:00", - "updateDuration": 1, - "defaultDimension": "2*2", - "supportDimensions": [ - "2*2", - "2*4", - "4*4" - ] - }, - { - "name": "Form_Js", - "description": "It's JS Form", - "type": "Js", - "colorMode": "auto", - "isDefault": false, - "updateEnabled": true, - "scheduledUpdateTime": "21:05", - "updateDuration": 1, - "defaultDimension": "1*2", - "supportDimensions": [ - "1*2" - ], - "landscapeLayouts": [ - "$layout:ability_form" - ], - "portraitLayouts": [ - "$layout:ability_form" - ], - "formConfigAbility": "ability://com.example.myapplication.fa/.MainAbility", - "metaData": { - "customizeData": [ - { - "name": "originWidgetName", - "value": "com.example.myapplication.testWidget" - } - ] - } - } - ] - } - } -} -``` - -表27 distroFilter对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------- | ------------------------------------------------------------ | -------- | -------------------- | -| apiVersion | 标识支持的apiVersion范围。参考表28。 | 对象 | 可缺省,缺省值为空。 | -| screenShape | 标识屏幕形状的支持策略。参考表29。 | 对象数组 | 可缺省,缺省值为空。 | -| screenWindow | 标识应用运行时窗口的分辨率支持策略。该字段仅支持对轻量级智能穿戴设备进行配置。参考表30。 | 对象数组 | 可缺省,缺省值为空。 | -| screenDensity | 标识屏幕的像素密度(dpi:Dots Per Inch)。参考表31。 | 对象数组 | 可缺省,缺省值为空。 | -| countryCode | 标识分发应用时的国家码。具体值参考ISO-3166-1的标准,支持多个国家和地区的枚举定义。参考表32。 | 对象数组 | 可缺省,缺省值为空。 | - -表28 apiVersion对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 支持的取值为API Version存在的整数值,例如4、5、6。场景示例:某应用,针对相同设备型号,
同时在网的为使用API 5和API 6开发的两个软件版本,则允许上架2个entry类型的安装包,分别支持到对应设备侧软件版本的分发。 | 数组 | 可缺省,缺省值为空。 | - -表29 screenShape对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 支持的取值为circle(圆形)、rect(矩形)。场景示例:针对智能穿戴设备,可为圆形表盘和矩形表盘分别提供不同的HAP。 | 数组 | 可缺省,缺省值为空。 | - -表30 screenWindow对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 单个字符串的取值格式为:“宽 * 高”,取值为整数像素值,例如“454 * 454”。 | 数组 | 可缺省,缺省值为空。 | - -表31 screenDensity对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 取值范围如下:
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]的设备。 | 数组 | 可缺省,缺省值为空。 | - -表32 countryCode对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | ---------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为“exclude”或“include”。“include”表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 该标签标识应用需要分发的国家码,标签为字符串数组,子串表示支持的国家或地区,由两个大写字母表示。 | 字符串数组 | 可缺省,缺省值为空。 | - -distroFilter示例: - -```json -{ - "module": { - "distroFilter": { - "apiVersion": { - "policy": "include", - "value": [ - 4, - 5 - ] - }, - "screenShape": { - "policy": "include", - "value": [ - "circle", - "rect" - ] - }, - "screenWindow": { - "policy": "include", - "value": [ - "454*454", - "466*466" - ] - }, - "screenDensity": { - "policy": "exclude", - "value": [ - "ldpi", - "xldpi" - ] - }, - "countryCode": { - "policy": "include", - "value": [ - "CN", - "HK" - ] - } - } - } -} -``` - -表33 commonEvents对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ---------- | ------------------------------------------------------------ | ---------- | ------------------ | -| name | 标识静态公共事件名称,该标签最大长度为127字节。 | 字符串 | 不可缺省。 | -| permission | 此标签标识实现静态公共事件所需要申请的权限,该标签最大长度为127字节。 | 字符串 | 可缺省,缺省值为空。 | -| data | 标识配置当前静态公共事件要携带的附加数据数组。 | 字符串数组 | 可缺省,缺省值为空。 | -| type | 该标签用于配置当前静态公共事件的分类数组。 | 字符串数组 | 可缺省,缺省值为空。 | -| events | 此标签标识可接收的意图的一组事件值。一般由系统预定义,也可以自定义。 | 字符串数组 | 不可缺省。 | - -commonEvents示例: - -```json -{ - "module": { - "commonEvents": [ - { - "name": "MainAbility", - "permission": "string", - "data": [ - "string", - "string" - ], - "events": [ - "string", - "string" - ] - } - ] - } -} -``` - -表34 testRunner对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | -------------------- | -------- | ---------- | -| name | 标识测试框架对象名称,该标签最大长度为255字节。 | 字符串 | 不可缺省。 | -| srcPath | 标识测试框架代码路径,该标签最大长度为255字节。 | 字符串 | 不可缺省。 | - -```json -{ - "module": { - "testRunner": { - "name": "myTestRunnerName", - "srcPath": "etc/test/TestRunner.ts" - } - } -} -``` - -表35 definePermissions对象内部结构说明 - -definePermission仅支持系统应用配置,三方应用配置不生效。 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ----------------------- | ------------------------------------------------------------ | -------- | ---------- | -| name | 标识权限的名称,该标签最大长度为255字节。 | 字符串 | 不可缺省。 | -| grantMode | 标识权限的授予方式,支持如下两种授予模式:
system_grant:安装后系统自动授予该权限。
user_grant:使用时动态申请,用户授权后才可使用。 | 字符串 | 可缺省,缺省值为"system_grant"。 | -| availableLevel | 标识权限限制类别。可选值如下:
system_core:系统核心权限。
system_basic:系统基础权限。
normal:普通权限。所有应用允许申请的权限。 | 字符串 | 可缺省,缺省值为"normal"。 | -| provisionEnable | 标识权限是否支持证书方式申请权限,包括高级别的权限。配置为true标识需要开发者可以通过provision方式申请权限。 | 布尔值 | 可缺省,缺省值为true。 | -| distributedSceneEnabled | 标识权限是否支持分布式场景下使用该权限。 | 布尔值 | 可缺省,缺省值为false。 | -| label | 标识权限的简短描述,配置为对描述内容的资源索引。 | 字符串 | 可缺省,缺省值为空。 | -| description | 标识权限的详细描述,可以是字符串(最大长度255字节),或者为对描述内容的资源索引。 | 字符串 | 可缺省,缺省值为空。 | diff --git a/zh-cn/application-dev/quick-start/stage-structure.md b/zh-cn/application-dev/quick-start/stage-structure.md deleted file mode 100755 index ef9484e72405e25fe423fa0ee9ba4c5b3f836788..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/quick-start/stage-structure.md +++ /dev/null @@ -1,961 +0,0 @@ - - -# 应用包结构配置文件的说明(Stage模型) - -在开发stage模型的应用程序时,需要在app.json5和module.json5配置文件中对应用的包结构进行声明。 - -## 配置文件内部结构 - -配置文件由app.json5和module.json5两部分组成。配置文件的内部结构参见表1。 - -表1 配置文件的内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | ---------- | -| app | 标识应用的全局配置信息。参考[app对象内部结构](#app对象内部结构)。 | 对象 | 不可缺省。 | -| module | 标识HAP包的配置信息。该标签下的配置只对当前HAP包生效。参考[module对象内部结构](#module对象内部结构)。 | 对象 | 不可缺省。 | - -### app对象内部结构 - -该标签为整个应用的属性,影响应用中所有HAP及组件。该标签的内部结构参见表2。 - -表2 app对象的内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------------------------ | ------------------------------------------------------------ | -------- | ------------------------------------------- | -| bundleName | 该标签标识应用的包名,用于标识应用的唯一性。标签的值命名规则 :
1)字符串以字母、数字、下划线和符号”.”组成;
2)以字母开头;
3)最小长度7字节,最大长度127个字节。
推荐采用反域名形式命名(如 :com.example.xxx,建议第一级为域名后缀com,第二级为厂商/个人名,第三级为应用名,也可以多级)。 | 字符串 | 不可缺省。 | -| debug | 该标签标识应用是否可调试。该标签由IDE编译构建时产生。 | 布尔值 | 可缺省,缺省值为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 | 该标签标识该app能够兼容的最低历史版本号,用于跨设备兼容性判断。 | 数值 | 可缺省。缺省值等于versionCode标签值。| -| minAPIVersion | 该标签标识应用运行需要的SDK的API最小版本。 | 数值 | 可缺省,缺省值为bundle-profile.json5中的compatibleSdkVersion。| -| targetAPIVersion | 该标签标识应用运行需要的API目标版本。 | 数值 | 可缺省,缺省值为bundle-profile.json5中的compileSdkVersion。| -| apiReleaseType | 该标签标识应用运行需要的API目标版本的类型,采用字符串类型表示。取值为“CanaryN”、“BetaN”或者“Release”,其中,N代表大于零的整数。
Canary :受限发布的版本。
Beta :公开发布的Beta版本。
Release :公开发布的正式版本。
该字段由IDE读取当前使用的SDK的stage来生成。 | 字符串 | 可缺省,由IDE生成并覆盖。 | -| distributedNotificationEnabled | 该标签标记该应用是否开启分布式通知。 | 布尔值 | 可缺省,缺省值为true。 | -| entityType | 该标签标记该应用的类别,具体有 :游戏类(game),影音类(media)、社交通信类(communication)、新闻类(news)、
出行类(travel)、工具类(utility)、购物类(shopping)、教育类(education)、少儿类(kids)、商务类(business)、拍摄类(photography)、未指定(unspecified)。 | 字符串 | 可缺省,缺省值为"unspecified"。 | -| multiProjects | 标识当前工程是否支持多工程。 | 布尔值 | 可缺省,缺省值为false。 | -| 设备类型 | 该标签可以配置多个,表示具体设备上的特殊配置信息,具体的设备类型有:"tablet"、"tv"、"wearable"、"car"、"default",可包含的字段有:minAPIVersion、distributedNotificationEnabled。 | 对象 | 可缺省,缺省值使用app下面相关的字段。 | - -app.json示例 : - -```json -{ - "app": { - "bundleName": "com.example.myapplication", - "vendor": "example", - "versionCode": 1000000, - "versionName": "1.0.0", - "icon": "$media:app_icon", - "label": "$string:app_name", - "distributedNotificationEnabled": true, - "minCompatibleVersionCode": 9, - "minAPIVersion": 9, - "targetAPIVersion": 9, - "apiReleaseType": "Canary1", - "debug": false, - "description": "$string:app_description", - "entityType": "game", - "car": { - "minAPIVersion": 9 - } - } -} - -``` - -### module对象内部结构 - -HAP包的配置信息,该标签下的配置只对当前HAP包生效。 - -表3 module对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | -| name | 该标签标识当前module的名字。module打包成HAP后,表示HAP的名称,标签值采用字符串表示(最大长度31字节),该名称在整个应用要唯一。 | 字符串 | 不可缺省。 | -| type | 该标签标识当前module的类型。类型有两种,分别是entry、feature。 | 字符串 | 不可缺省。 | -| srcEntrance | 该标签标识HAP所对应的入口js代码路径,标签值为字符串(最大长度127字节)。 | 字符串 | 可缺省,缺省值为空。 | -| description | 该标签标识HAP包的描述信息,标签值是是字符串类型或对描述内容的字符串资源索引。 | 字符串 | 可缺省,缺省值为空。 | -| process | 该标签标识HAP的进程名,标签值为字符串类型(最大长度31字节)。如果在HAP标签下配置了process,该应用的所有ability都运行在该进程中。该标签只支持系统应用配置。 | 字符串 | 可缺省,缺省值为app标签下的bundleName。 | -| mainElement | 该标签标识HAP的入口Ability名称或者Extension名称。只有配置为mainElement的Ability或者Extension才允许在服务中心露出。 | 字符串 | 创建OpenHarmony原子化服务时,不可缺省。OpenHarmony应用下,可缺省,缺省值为空。 | -| deviceTypes | 该标签标识HAP可以运行在哪类设备上,标签值采用字符串数组的表示,系统预定义的设备类型见表4。 | 字符串数组 | 不可缺省。 | -| deliveryWithInstall | 该标签标识当前HAP是否在用户主动安装的时候安装,true表示主动安装时安装,false表示主动安装时不安装。 | 布尔值 | 不可缺省。 | -| installationFree | 标识当前HAP是否支持免安装特性。所有Hap包都需要配置不可缺省。
true :表示支持免安装特性,且符合免安装约束。
false :表示不支持免安装特性。

当entry.hap该字段配置为true时,与该entry.hap相关的所有feature.hap该字段也需要配置为true。
当entry.hap该字段配置为false时,与该entry.hap相关的各feature.hap该字段可按业务需求配置true或false。 | 布尔值 | 不可缺省。 | -| virtualMachine | 该标签用于标识当前HAP运行的目标虚拟机类型,供云端分发使用,如应用市场和分发中心。
该标签值为字符串。如果目标虚拟机类型为方舟虚拟机,则其值为"ark + 版本号"。 该标签由IDE构建HAP的时候自动插入。 | 字符串 | 该标签由IDE构建HAP的时候自动插入。 | -| uiSyntax(deprecated) | uiSyntax定义该JS Component的语法类型。
hml标识该JS Component使用hml/css/js进行开发;
ets标识该JS Component使用ArkUI声明式语法进行开发。 | 字符串 | 可缺省,缺省值为"hml",该字段从API9开始废弃。 | -| pages | 标识当前Module的profile资源,用于列举JS Component中每个页面信息。该标签最大长度为255个字节。 | 字符串 | 在有ability的场景下,不可缺省。 | -| metadata | 该标签标识Hap的自定义元信息。参考[metadata对象内部结构](#metadata对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| abilities | 描述元能力的配置信息,该标签下的配置只对当前ability生效。参考[abilities对象内部结构](#abilities对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| extensionAbilities | 描述extensionAbilities的配置信息,该标签下的配置只对当前extensionAbility生效。参考[extensionAbilities对象内部结构](#extensionabilities对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| definePermissions | 标识HAP定义的权限,仅支持系统应用配置,三方应用配置不生效。参考[definePermissions对象内部结构](#definepermissions对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| requestPermissions | 该标签标识应用运行时需向系统申请的权限集合。参考[requestPermissions对象内部结构](#requestpermissions对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| testRunner | 该标签用于支持对测试框架的配置,参考[testRunner对象内部结构说明](#testrunner对象内部结构)。 | 对象 | 可缺省,缺省值为空。 | - - -module.json5示例: - -```json -{ - "module": { - "name": "entry", - "type": "entry", - "description": "$string:module_desc", - "mainElement": "EntryAbility", - "deviceTypes": [ - "default", - "tablet" - ], - "deliveryWithInstall": true, - "installationFree": false, - "pages": "$profile:main_pages", - "metadata": [ - { - "name": "name1", - "value": "value1", - "resource": "$profile:config_file1" - }, - { - "name": "name2", - "value": "value2", - "resource": "$profile:config_file2" - } - ], - "abilities": [ - { - "name": "EntryAbility", - "srcEntrance": "./ets/entryability/EntryAbility.ts", - "description": "$string:ability_desc", - "icon": "$media:icon", - "label": "$string:ability_label", - "startWindowIcon": "$media:icon", - "startWindowBackground": "$color:start_window_background", - "visible": true, - "backgroundModes": [ - "dataTransfer", - "audioPlayback", - "audioRecording", - "location", - "bluetoothInteraction", - "multiDeviceConnection", - "wifiInteraction", - "voip", - "taskKeeping" - ], - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ] - } - ], - "requestPermissions": [ - { - "name": "permissionName", - "reason": "$string:reason", - "usedScene": { - "abilities": [ - "EntryFormAbility" - ], - "when": "inuse" - } - } - ], - "extensionAbilities": [ - { - "name": "EntryFormAbility", - "srcEntrance": "./ets/entryformability/EntryFormAbility.ts", - "label": "$string:EntryFormAbility_label", - "description": "$string:EntryFormAbility_desc", - "type": "form", - "metadata": [ - { - "name": "ohos.extension.form", - "resource": "$profile:form_config" - } - ] - } - ] - } -} -``` - -pages示例 : - -1.在开发视图的resources/base/profile下面定义配置文件main_pages.json(文件名称可由开发者定义): - -```json -{ - "src": [ - "pages/LoginPage", - "pages/MinePage", - "pages/RegistrationSuccessPage", - "pages/PrivacyPage", - "pages/CustomerServicePage" - ] -} -``` - -2.在module.json5的module标签下定义pages信息 : - -```json -{ - "module": { - "pages": "$profile:main_pages" - } -} -``` - -表4 deviceTypes对象的系统预定义设备 - -| 设备类型 | 枚举值 | 说明 | -| -------- | ----------- | -------- | -| 平板 | tablet | - | -| 智慧屏 | tv | - | -| 智能手表 | wearable | 系统能力较丰富的手表,具备电话功能。 | -| 车机 | car | - | -| 默认设备 | default | 能够使用全部系统能力的OpenHarmony设备。 | - -deviceTypes示例 : - -```json -{ - "module": { - "deviceTypes": [ - "default", - "tablet" - ] - } -} -``` - -#### metadata对象内部结构 - -描述的module、ability、extensionAbility配置信息,标签值为数组类型,该标签下的配置只对当前module、或者ability、或者extensionAbility生效。 - -表5 metadata对象内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------------- | -| name | 该标签标识数据项的键名称,最大长度255字节。 | 字符串 | 可缺省,缺省值为空。 | -| value | 该标签标识数据项的值,最大长度255字节。 | 字符串 | 可缺省,缺省值为空。 | -| resource | 该标签标识定义用户自定义数据格式,标签值为标识该数据的资源的索引值。 | 字符串 | 可缺省,缺省值为空。 | - -metadata示例: - -```json -{ - "module": { - "metadata": [ - { - "name": "name1", - "value": "value1", - "resource": "$profile:config_file1" - }, - { - "name": "name2", - "value": "value2", - "resource": "$profile:config_file2" - } - ] - } -} -``` - -#### distroFilter对象内部结构 - -标识应用的分发规则。 - -该标签用于定义HAP包对应的细分设备规格的分发策略,以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括API Version、屏幕形状、窗口分辨率、屏幕分辨率、国家码。在进行分发时,通过deviceType与这五个属性的匹配关系,唯一确定一个用于分发到设备的HAP。
-配置方式如下:
-module标签配置metadata信息。name :"ohos.module.distro"。resource :指定distroFilter信息的资源位置。 - -表6 distroFilter对象内部结构 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------------- | ------------------------------------------------------------ | -------- | -------------------------- | -| apiVersion | 标识支持的apiVersion。 | 对象 | 可缺省,缺省值为空。 | -| screenShape | 标识屏幕形状的支持策略。仅支持liteWearable设备配置。 | 对象 | 可缺省,缺省值为空。 | -| screenWindow | 标识应用运行时窗口的分辨率支持策略。仅支持liteWearable设备配置。 | 对象 | 可缺省,缺省值为空。 | -| screenDensity | 标识屏幕的像素密度(dpi : Dot Per Inch)。 | 对象 | 可缺省,缺省值为空。 | -| countryCode | 标识应用需要分发的国家地区码。具体值以ISO-3166-1标准为准。 | 对象 | 可缺省,缺省值为空。 | - -表7 apiVersion对象内部结构 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为"exclude"或"include"。"include"表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 支持的取值为API Version存在的整数值,例如4、5、6,最小取值为3。场景示例 :某应用,针对相同设备型号,同时在网的为使用API 5和API 6开发的两个软件版本,
则允许上架2个entry类型的安装包,分别支持到对应设备侧软件版本的分发。 | 数值数组 | 可缺省,缺省值为空。 | - -表8 screenShape对象内部结构 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为"exclude"或"include"。"include"表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 支持的取值为circle(圆形屏幕)、rect(矩形屏幕)。场景示例:针对智能穿戴设备,可为圆形表盘和矩形表盘分别提供不同的HAP。 | 字符串数组 | 可缺省,缺省值为空。 | - -表9 screenWindow对象内部结构 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为"include"。"include"表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 单个字符串的取值格式为 :“宽 * 高”,取值为整数像素值,例如“454 * 454”。 | 字符串数组 | 可缺省,缺省值为空。 | - -表10 screenDensity对象内部结构 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为"exclude"或"include"。"include"表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 字符串范围如下:
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]的设备。 | 字符串数组 | 可缺省,缺省值为空。 | - -表11 countryCode对象内部结构 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | 标识该子属性取值的黑白名单规则。配置为"exclude"或"include"。"include"表示该字段取值为白名单,满足value枚举值匹配规则的表示匹配该属性。 | 字符串 | 可缺省,缺省值为空。 | -| value | 支持多个国家和地区枚举定义。字符串表示所支持的国家或地区,由两个大写字母组成。 | 字符串数组 | 可缺省,缺省值为空。 | - -distroFilter示例 : - -1.在开发视图的resources/base/profile下面定义配置文件distro_filter_config.json(文件名称可由开发者定义): - -```json -{ - "distroFilter": { - "apiVersion": { - "policy": "include", - "value": [ - 4, - 5 - ] - }, - "screenShape": { - "policy": "include", - "value": [ - "circle", - "rect" - ] - }, - "screenWindow": { - "policy": "include", - "value": [ - "454*454", - "466*466" - ] - }, - "screenDensity": { - "policy": "exclude", - "value": [ - "ldpi", - "xldpi" - ] - }, - "countryCode": { - "policy": "include", - "value": [ - "CN", - "HK" - ] - } - } -} -``` - -2.在module.json5的module标签下配置metadata信息: - -```json -{ - "module": { - "metadata": [ - { - "name": "ohos.module.distro", - "resource": "$profile:distro_filter_config" - } - ] - } -} -``` - -#### skills对象内部结构 - -该标签标识ability或者extension能够接收的意图的特征。 - -表12 skill对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------------------------------------------------ | ---------- | -------------------- | -| actions | 该标签标识能够接收的意图的action值的集合,取值通常为系统预定义的action值,也允许自定义。 | 字符串数组 | 可缺省,缺省值为空。 | -| entities | 该标签标识能够接收Want的元能力的类别集合,取值通常为系统预定义的类别,也允许自定义。 | 字符串数组 | 可缺省,缺省值为空。 | -| uris | 该标签标识与意图中URI(Uniform Resource Identifier)相匹配的集合。uris内部结构参考表13。 | 对象数组 | 可缺省,缺省值为空。 | - -表13 uris对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| -------- | ------------------- | -------- | -------------------- | -| scheme | 标识URI的协议名部分,常见的有http、https、file、ftp等。 | 字符串 | 当配置type时可缺省,缺省值为空。没有配置type时不可缺省。 | -| host | 标识URI的主机地址部分,常见的有域名的方式,如example.com,ip地址的方式,如192.0.0.1。该字段要在scheme存在时才有意义。 | 字符串 | 可缺省,缺省值为空。 | -| port | 标识URI的端口部分。如http默认端口为80,https默认端口是443,ftp默认端口是21。该字段要在scheme和host都存在时才有意义。| 字符串 | 可缺省,缺省值为空。 | -| path \| pathStartWith \|
pathRegex | 标识URI的路径部分,path、pathStartWith和pathRegex配置时三选一。path标识URI与want中的路径部分全匹配,
pathStartWith标识URI与want中的路径部分允许前缀匹配,pathRegex标识URI与want中的路径部分允许正则匹配。
该字段要在scheme和host都存在时才有意义。| 字符串 | 可缺省,缺省值为空。 | -| type | 标识数据类型,使用MIME(Multipurpose Internet Mail Extensions)类型规范。可与scheme同时配置,也可以单独配置。| 字符串 | 可缺省,缺省值为空。 | - -skills示例 : - -```json -{ - "module": { - "abilities": [ - { - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ], - "uris": [ - { - "scheme": "https", - "host": "www.example.com", - "port": "8080", - "path": "query/student/name", - "pathStartWith": "query/student", - "pathRegex": "query/.*/name", - "type": "text/*" - } - ] - } - ] - } - ], - "extensionAbilities": [ - { - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ], - "uris": [ - { - "scheme": "https", - "host": "www.example.com", - "port": "8080", - "path": "query/student/name", - "pathStartWith": "query/student", - "pathRegex": "query/.*/name", - "type": "text/*" - } - ] - } - ] - } - ] - } -} -``` - -#### abilities对象内部结构 - -abilities描述Ability组件的配置信息,标签值为数组类型。 - -表14 ability对象内部结构说明 - -| 属性 | 含义 | 数据类型
| 是否可缺省 | -| --------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | -| name | 该标签标识当前Ability组件的逻辑名,该名称在整个应用要唯一,标签值采用字符串表示(最大长度127字节)。 | 字符串 | 不可缺省。 | -| srcEntrance | 该标签标识Ability组件所对应的js代码路径,标签值为字符串(最大长度127字节)。 | 字符串 | 不可缺省。 | -| launchType | 该标签标识Ability组件的启动模式,可选标签值:
"standard":多实例,每次启动创建一个新的实例。
"singleton":单实例,仅第一次启动创建新实例。
"specified":运行时由开发者决定是否创建新实例。 | 字符串 | 可缺省,缺省值为"singleton"。 | -| description | 该标签标识Ability组件的描述信息,标签值是是字符串类型或对描述内容的资源索引,要求采用资源索引方式,以支持多语言。 | 字符串 | 可缺省,缺省值为空。 | -| icon | 该标签标识Ability组件的图标,标签值为图标资源文件的索引。 | 字符串 | 可缺省,缺省值为空。
如果Ability组件被配置为MainElement,该标签必须配置。 | -| permissions | 该标签标识被其它应用的Ability组件调用时需要申请的权限的集合,一个数组元素为一个权限名称。通常采用反向域名格式(最大长度255字节),
取值为系统预定义的权限。 | 字符串数组 | 可缺省,缺省值为空。 | -| metadata | 该标签标识Ability组件的元信息。参考[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对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| backgroundModes | 该标签标识Ability组件的长时任务集合。指定用于满足特定类型的长时任务。
长时任务类型有如下 :
dataTransfer :通过网络/对端设备进行数据下载、备份、分享、传输等业务。
audioPlayback :音频输出业务。
audioRecording :音频输入业务。
location :定位、导航业务。
bluetoothInteraction :蓝牙扫描、连接、传输业务(穿戴)。
multiDeviceConnection :多设备互联业务。
wifiInteraction :Wifi扫描、连接、传输业务(克隆 多屏)。
voip :音视频电话,VOIP业务。
taskKeeping :计算业务。
| 字符串数组 | 可缺省,缺省值为空。 | -| startWindowIcon | 标识该Ability组件启动页面图标资源文件的索引。取值示例:$media:icon。 | 字符串 | 不可缺省。| -| startWindowBackground | 标识该Ability组件启动页面背景颜色资源文件的索引。取值示例:$color:red。 | 字符串 | 不可缺省。| -| removeMissionAfterTerminate | 该标签标识Ability组件销毁后是否从任务列表中移除任务。true表示销毁后移除任务, false表示销毁后不移除任务。 | 布尔值 | 可缺省,缺省值为false。| -| orientation | 标识该Ability组件启动时的方向。取值范围包括:
unspecified: 未指定方向,由系统自动判断显示方向,
landscape:横屏,
portrait:竖屏,
landscape_inverted: 反向横屏,
portrait_inverted: 反向竖屏,
auto_rotation: 随传感器旋转,
auto_rotation_landscape: 传感器横屏旋转,包括了横屏和反向横屏,
auto_rotation_portrait: 传感器竖屏旋转,包括了竖屏和反向竖屏,
auto_rotation_restricted: 传感器开关打开,方向可随传感器旋转,
auto_rotation_landscape_restricted: 传感器开关打开,方向可随传感器旋转为横屏, 包括了横屏和反向横屏,
auto_rotation_portrait_restricted: 传感器开关打开,方向随可传感器旋转为竖屏, 包括了横屏和反向横屏,
locked: 传感器开关关闭,方向锁定。 | 字符串 | 可缺省,缺省值为"unspecified"。| -|supportWindowMode|标识该Ability组件所支持的窗口模式,取值范围包括:
fullscreen: 全屏模式,
split: 分屏模式,
floating: 悬浮窗模式。 |字符串数组 | 可缺省,缺省值为
["fullscreen", "split", "floating"]。| -|maxWindowRatio|标识该Ability组件支持的最大的宽高比。| 数值 |可缺省,缺省值为平台支持的最大的宽高比。| -|minWindowRatio|标识该Ability组件支持的最小的宽高比。| 数值 |可缺省,缺省值为平台支持的最小的宽高比。| -|maxWindowWidth|标识该Ability组件支持的最大的窗口宽度,宽度单位为vp。| 数值 |可缺省,缺省值为平台支持的最大的窗口宽度。| -|minWindowWidth|标识该Ability组件支持的最小的窗口宽度, 宽度单位为vp。| 数值 |可缺省,缺省值为平台支持的最小的窗口宽度。| -|maxWindowHeight|标识该Ability组件支持的最大的窗口高度, 高度单位为vp。| 数值 |可缺省,缺省值为平台支持的最大的窗口高度。| -|minWindowHeight|标识该Ability组件支持的最小的窗口高度, 高度单位为vp。| 数值 |可缺省,缺省值为平台支持的最小的窗口高度。| - -abilities示例 : - -```json -{ - "module": { - "abilities": [ - { - "name": "EntryAbility", - "srcEntrance": "./ets/entryability/EntryAbility.ts", - "description": "$string:ability_desc", - "icon": "$media:icon", - "label": "$string:ability_label", - "startWindowIcon": "$media:icon", - "startWindowBackground": "$color:start_window_background", - "visible": true, - "backgroundModes": [ - "dataTransfer", - "audioPlayback", - "audioRecording", - "location", - "bluetoothInteraction", - "multiDeviceConnection", - "wifiInteraction", - "voip", - "taskKeeping" - ], - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ], - "orientation": "landscape", - "supportWindowMode": [ - "fullscreen", - "split", - "floating" - ], - "maxWindowRatio": 3.5, - "minWindowRatio": 0.5, - "maxWindowWidth": 2560, - "minWindowWidth": 1400, - "maxWindowHeight": 300, - "minWindowHeight": 200 - } - ] - } -} -``` - -#### shortcuts对象内部结构 - -标识应用的快捷方式信息。最多可以配置四个快捷方式。
-配置方式如下:
-ability标签配置metadata信息。name :"ohos.ability.shortcuts"。resource :指定shortcuts信息的资源位置。 - -表15 shortcut对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ---------- | ------------------------------------------------------------ | -------- | -------------------------- | -| shortcutId | 标识快捷方式的ID。最大长度为63字节。 | 字符串 | 不可缺省。 | -| label | 标识快捷方式的标签信息,即快捷方式对外显示的文字描述信息。取值可以是描述性内容,也可以是标识label的资源索引。字符串最大长度为63字节。 | 字符串 | 可缺省,缺省值为空。 | -| icon | 该标签标识shortcut的图标,标签值为资源文件的索引。 | 字符串 | 可缺省,缺省值为空。 | -| wants | 该标签标识快捷方式内定义的目标wants信息集合,每个want可配置两个子标签,bundleName,abilityName。
bundleName :快捷方式目标包名,字符串类型。
abilityName :快捷方式的目标组件名,字符串类型。 | 对象数组 | 可缺省,缺省值为空。 | - -shortcuts示例 : - -1.在开发视图的resources/base/profile下面定义配置文件shortcuts_config.json(文件名称可由开发者定义): - -```json -{ - "shortcuts": [ - { - "shortcutId": "shortcut_id", - "label": "$string:label", - "icon": "$media:icon", - "wants": [ - { - "bundleName": "com.example.myapplication", - "abilityName": "abilityName" - } - ] - } - ] -} -``` - -2.在module.json5的abilities标签下配置metadata信息: - -```json -{ - "module": { - "abilities": [ - { - "name": "EntryAbility", - "srcEntrance": "./ets/entryability/EntryAbility.ts", - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ], - "metadata": [ - { - "name": "ohos.ability.shortcuts", - "resource": "$profile:shortcuts_config" - } - ] - } - ] - } -} -``` - -#### extensionAbilities对象内部结构 - -extensionAbilities描述extensionAbility的配置信息,标签值为数组类型。 - -表16 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、backup、window、enterpriseAdmin、thumbnail、preview其中之一。 | 字符串 | 不可缺省。 | -| 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对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| metadata | 该标签标识ExtensionAbility组件的元信息。参考[metadata对象内部结构](#metadata对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| visible | 该标签标识ExtensionAbility组件是否可以被其它应用调用。true表示可以被其它应用调用, false表示不可以被其它应用调用。 | 布尔值 | 可缺省,缺省值为false。 | -| readPermission | 该标签标识读取ExtensionAbility组件的数据所需的权限。最大长度255字节。type为dataShare类型的ExtensionAbility组件支持该配置。该标签只对系统应用生效。 | 字符串 | 可缺省,缺省值为空。 | -| writePermission | 该标签标识向ExtensionAbility组件写数据所需的权限。最大长度255字节。type为dataShare类型的ExtensionAbility组件支持该配置。该标签只对系统应用生效。 | 字符串 | 可缺省,缺省值为空。 | - -extensionAbilities示例 : - -```json -{ - "module": { - "extensionAbilities": [ - { - "name": "EntryFormAbility", - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ], - "srcEntrance": "./ets/entryformability/EntryFormAbility.ts", - "label": "$string:EntryFormAbility_label", - "description": "$string:EntryFormAbility_desc", - "type": "form", - "metadata": [ - { - "name": "ohos.extension.form", - "resource": "$profile:form_config" - } - ] - } - ] - } -} -``` - -#### forms对象内部结构 - -forms标签标识卡片的配置,form卡片是可以嵌入桌面上并接收定期更新的应用简要视图。
-配置方式如下:
-extensionAbility标签配置type为form,并配置metadata信息:name :"ohos.extension.form"。resource :指定form信息的资源位置。 - -表17 form对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------------------- | ------------------------------------------------------------ | ---------- | ----------------------------- | -| name | 标识卡片的名称。最大长度为127字节。 | 字符串 | 不可缺省。 | -| description | 标识卡片的描述。取值可以是描述性内容,也可以是对描述性内容的资源索引,以支持多语言。最大长度为255字节。 | 字符串 | 可缺省,缺省值为空。 | -| src | 该标签标识JS卡片对应的UI代码。建议开发者通过自适应布局显示不同规格卡片,如果不同规格卡片布局相差较大,建议通过不同卡片来区分。 | 字符串 | 可缺省,缺省值为空。 | -| window | 该标签标识JS卡片的自适应能力。参考[window对象内部结构](#window对象内部结构)。 | 对象 | 可缺省,缺省值为空。 | -| isDefault | 标识该卡片是否为默认卡片,每个Ability有且只有一个默认卡片。 true :默认卡片。 false :非默认卡片。 | 布尔值 | 不可缺省。 | -| colorMode | 标识卡片的主题样式,取值范围如下 :
auto :自适应。
dark :深色主题。
light :浅色主题。
| 字符串 | 可缺省,缺省值为“auto”。 | -| supportDimensions | 标识卡片支持的外观规格,取值范围 :
1 * 2 :表示1行2列的二宫格。
2 * 1 :表示2行1列的二宫格。
2 * 2 :表示2行2列的四宫格。
2 * 4 :表示2行4列的八宫格。
4 * 4 :表示4行4列的十六宫格。 | 字符串数组 | 不可缺省。 | -| defaultDimension | 标识卡片的默认外观规格,取值必须在该卡片supportDimensions配置的列表中。 | 字符串 | 不可缺省。 | -| updateEnabled | 该标签标识该卡片是否支持实时刷新,true标识卡片支持实时刷新,false表示不支持。 | 布尔值 | 不可缺省。 | -| scheduledUpdateTime | 该标签标识卡片定点刷新的时间,采用24小时计数,精确到分钟。 | 字符串 | 可缺省,缺省值为空。 | -| updateDuration | 该标签标识卡片定时刷新的更新频率,单位为30分钟,取值为30的倍数。卡片的最高频率为每30分钟刷新一次,和定点刷新二选一,二者都配置的情况下,定时优先。 | 数值 | 可缺省,缺省值为空。 | -| metadata | 该标签标识卡片的元信息。参考[metadata对象内部结构](#metadata对象内部结构)。 | 对象数组 | 可缺省,缺省值为空。 | -| formConfigAbility | 该标签标识卡片调整的Ability名称。最大长度127字节。该标签值必须满足下面的格式 :
ability://单个ability名字。
单个ability名字必须为本应用的ability。 | 字符串 | 可缺省,缺省值为空。 | -| formVisibleNotify | 该标签标识卡片是否被允许使用卡片可见性通知。 | 布尔值 | 可缺省,缺省值为false。 | - -form示例 : - -1.在开发视图的resources/base/profile下面定义配置文件form_config.json(文件名称可由开发者定义): - -```json -{ - "forms": [ - { - "name": "widget", - "description": "This is a service widget.", - "src": "./js/widget/pages/index/index", - "window": { - "designWidth": 720, - "autoDesignWidth": true - }, - "colorMode": "auto", - "isDefault": true, - "updateEnabled": true, - "scheduledUpdateTime": "10:30", - "updateDuration": 1, - "defaultDimension": "2*2", - "supportDimensions": [ - "2*2" - ] - } - ] -} -``` - -2.在module.json5的extensionAbilities标签下配置metadata信息: - -```json -{ - "module": { - "extensionAbilities": [ - { - "type": "form", - "metadata": [ - { - "name": "ohos.extension.form", - "resource": "$profile:form_config" - } - ] - } - ] - } -} -``` - -#### window对象内部结构 - -定义与显示窗口相关的配置。 - -表18 window对象内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ------------------------------------------------------------ | -------- | -------------------------- | -| designWidth | 定义页面设计基准宽度,根据实际设备宽度来缩放元素大小。 | 数值 | 可缺省,缺省值为750。 | -| autoDesignWidth | 定义页面设计基准宽度是否自动计算,当设置为true时,designWidth将被忽略,设计基准宽度由设备宽度与屏幕密度计算得出。 | 布尔值 | 可缺省,缺省值为false。 | - -window示例 : - -```json -{ - "forms": [ - { - "window": { - "designWidth": 720, - "autoDesignWidth": true - } - } - ] -} -``` - -#### commonEvents对象内部结构 - -commonEvents标签标识注册静态公共事件信息。
-配置方式如下:
-extensionAbility标签配置type为staticSubscriber,并配置metadata信息:name :"ohos.extability.staticSubscriber"。resource :指定commonEvents信息的资源位置。 - -表19 commonEvent对象内部结构 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ---------- | ------------------------------------------------------------ | ---------- | -------------------------- | -| name | 该标签指明当前静态公共事件对应的ability名,该类需要在ability中标明。 | 字符串 | 不可缺省。 | -| permission | 该标签标识实现该静态公共事件需要申请的权限,以字符串类型表示一个权限名称,通常采用反向域名方式表示(最大长度255字节)。 | 字符串 | 可缺省,缺省值为空。 | -| types | 该标签配置当前静态公共事件的类别数组,字符串数组类型,每个数组元素为一个类别名称。 | 字符串数组 | 可缺省,缺省值为空。 | -| events | 该标签标识能够接收的意图的event值的集合,取值通常为系统预定义的event值,也允许自定义。 | 字符串数组 | 不可缺省。 | - -commonEvents示例 : - -1.在开发视图的resources/base/profile下面定义配置文件common_event_config.json(文件名称可由开发者定义): - -```json -{ - "commonEvents": [ - { - "name": "abilityName", - "permission": "permissionName", - "types": [ - "type1", - "type2" - ], - "events": [ - "event1", - "event2" - ] - } - ] -} -``` - -2.在module.json5的extensionAbilities标签下配置metadata信息: - -```json -{ - "module": { - "extensionAbilities": [ - { - "name": "subscriber", - "srcEntrance": "./ets/subscriber/Subscriber.ts", - "type": "staticSubscriber", - "metadata": [ - { - "name": "ohos.extability.staticSubscriber", - "resource": "$profile:common_event_config" - } - ] - } - ] - } -} -``` - -#### definePermissions对象内部结构 - -该标签标识HAP定义的权限。该标签只支持系统应用配置。 - -表20 definePermission对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ---------------------- | ------------------------------------------------------------ | -------- | ------------------------------ | -| name | 标识权限的名称。 | 字符串 | 不可缺省。 | -| grantMode | 标识权限的授予方式,授予模式如下:
system_grant:安装后系统自动授予该权限。
user_grant:应用动态申请,用户授权后才可使用。 | 字符串 | 可缺省,缺省值为"system_grant"。 | -| availableLevel | 标识权限限制门限,可选值为system_core、system_basic、normal。
system_core:系统核心权限。
system_basic:系统基础权限。
normal:普通权限。所有应用允许申请的权限。 | 字符串 | 可缺省,缺省值为"normal"。 | -| provisionEnable | 标识权限是否支持证书方式申请权限,包括高级别的权限,true标识需要开发者可以通过provision证书acls方式申请权限。 | 布尔值 | 可缺省,缺省值为true。 | -| distributedSceneEnable | 标识权限是否支持分布式场景下使用该权限。 | 布尔值 | 可缺省,缺省值为false。 | -| label | 标识权限的简短描述,配置为对描述内容的资源索引。 | 字符串 | 可缺省,缺省值为空。 | -| description | 标识权限的详细描述,可以是表示描述内容的字符串,也可以是对描述内容的资源索引。 | 字符串 | 可缺省,缺省值为空。 | - -definePermissions示例 : - -```json -{ - "module": { - "definePermissions": [ - { - "name": "permissionName", - "grantMode": "user_grant", - "availableLevel": "system_basic", - "provisionEnable": false, - "distributedSceneEnable": true, - "label": "$string:label", - "description": "$string:description" - } - ] - } -} -``` - -#### requestPermissions对象内部结构 - -该标签标识应用运行时需向系统申请的权限集合。 - -表21 requestPermission对象内部结构说明 - -| 属性名称 | 含义 | 数据类型
| 是否可缺省 | -| ------| ------| -------- | ------------------------------ | -| name | 需要申请的权限名称。| 字符串 | 不可缺省。 | -| reason | 申请权限的原因。配置为描述内容的资源索引,以支持多语言。 | 字符串 | 可缺省,缺省值为空。当申请权限的grantMode为user_grant时不可缺省。 | -| usedScene | 权限使用的场景和时机。参考[usedScene对象内部结构](#usedscene对象内部结构)。| 对象 | 可缺省,缺省值为空。当申请权限的grantMode为user_grant时不可缺省。 | - -requestPermissions示例 : - -```json -{ - "module": { - "requestPermissions": [ - { - "name": "permissionName", - "reason": "$string:reason", - "usedScene": { - "abilities": [ - "EntryAbility" - ], - "when": "inuse" - } - } - ] - } -} -``` - -权限访问的更多说明,可参考[访问控制开发指导](../security/accesstoken-guidelines.md) - -#### usedScene对象内部结构 - -该标签标识权限使用的场景和时机。 - -表22 usedScene对象内部结构说明 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| ------- | --------------------| -------- | ------ | -| abilities | 标识需要使用到该权限的ability。| 字符串数组 | 不可缺省。 | -| when | 标识使用该权限的时机,可选值为inuse和always。inuse表示仅前台使用,always表示前后台都可使用。 | 字符串 | 可缺省,缺省值为空。 | - - -usedScene示例 : - -```json -{ - "module": { - "requestPermissions": [ - { - "usedScene": { - "abilities": [ - "EntryAbility" - ], - "when": "inuse" - } - } - ] - } -} -``` - -#### testRunner对象内部结构 - -该标签用于支持对测试框架的配置 - -表23 testRunner对象内部结构 - -| 属性名称 | 含义 | 数据类型 | 是否可缺省 | -| -------- | ---------------------- | -------- | ---------- | -| name | 标识测试框架对象名称。 | 字符串 | 不可缺省。 | -| srcPath | 标识测试框架代码路径。 | 字符串 | 不可缺省。 | - -testRunner示例 : - -```json -{ - "module": { - "testRunner": { - "name": "testRunnerName", - "srcPath": "ets/test/TestRunner.ts" - } - } -} -``` - diff --git a/zh-cn/application-dev/quick-start/syscap.md b/zh-cn/application-dev/quick-start/syscap.md deleted file mode 100644 index fc98c0e05570f40281523fb766a525b070c47e49..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/quick-start/syscap.md +++ /dev/null @@ -1,163 +0,0 @@ -# 系统能力SystemCapability使用指南 - -## 概述 - -### 系统能力与 API - -SysCap,全称SystemCapability,即系统能力,指操作系统中每一个相对独立的特性,如蓝牙,WIFI,NFC,摄像头等,都是系统能力之一。每个系统能力对应多个API,随着目标设备是否支持该系统能力共同存在或消失,也会随着DevEco Studio一起提供给开发者做联想。 - -![image-20220326064841782](figures/image-20220326064841782.png) - -开发者可以在[SysCap列表](../reference/syscap-list.md)中查询OpenHarmony的能力集。 - -### 支持能力集,联想能力集与要求能力集 - -支持能力集,联想能力集与要求能力集都是系统能力的集合。 -支持能力集描述的是设备能力,要求能力集描述的是应用能力。若应用A的要求能力集是设备N的支持能力集的子集,则应用A可分发到设备N上安装运行,否则不能分发。 -联想能力集是该应用开发时,DevEco Studio可联想的API所在的系统能力集合。 - -![image-20220326064913834](figures/image-20220326064913834.png) - -### 设备与支持能力集 - -每个设备根据其硬件能力,对应不同的支持能力集。 -SDK将设备分为两组,典型设备和自定义设备,典型设备的支持能力集由OpenHarmony来定义,自定义设备由设备厂商给出。 - -![image-20220326064955505](figures/image-20220326064955505.png) - -### 设备与SDK能力的对应 - -SDK向DevEco Studio提供全量API,DevEco Studio识别开发者项目中选择的设备形态,找到该设备的支持能力集,筛选支持能力集包含的API并提供API联想。 - -![image-20220326065043006](figures/image-20220326065043006.png) - -## SysCap开发指导 - -### PCID获取 - -PCID,全称Product Compatibility ID,包含当前设备支持的SysCap信息。获取所有设备PCID的认证中心正在建设中,目前需要找对应设备的厂商获取该设备的PCID。 - -### PCID导入 - -DevEco Studio工程支持PCID的导入。导入的PCID文件解码后输出的SysCap会被写入syscap.json文件中。 - -在工程目录右键后选择Import Product Compatibility ID,即可上传PCID文件并导入至syscap.json中。 - -![20220329-103626](figures/20220329-103626.gif) - -### 配置联想能力集和要求能力集 - -DevEco Studio会根据创建的工程所支持的设置自动配置联想能力集和要求能力集,开发者也可以自行修改。 -对于联想能力集,开发者通过添加更多的系统能力,在DevEco Studio中可以使用更多的API,但要注意这些API可能在设备上不支持,使用前需要判断。 -对于要求能力集,开发者修改时要十分慎重,修改不当会导致应用无法分发到目标设备上。 - -```json -// syscap.json -{ - "devices": { - "general": [ // 每一个典型设备对应一个syscap支持能力集,可配置多个典型设备 - "default", - "car" - ], - "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 是否可以使用 - -- 方法1:OpenHarmony定义了API canIUse帮助开发者来判断该工程是否支持某个特定的syscap。 - - ``` - if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { - console.log("该应用支持SystemCapability.ArkUI.ArkUI.Full"); - } else { - console.log("该应用不支持SystemCapability.ArkUI.ArkUI.Full"); - } - ``` - -- 方法2:开发者可通过 import 的方式将模块导入,若当前设备不支持该模块,import 的结果为 undefined,开发者在使用其 API 时,需要判断其是否存在。 - - ``` - import geolocation from '@ohos.geolocation'; - - if (geolocation) { - geolocation.getCurrentLocation((location) => { - console.log(location.latitude, location.longitude); - }); - } else { - console.log('该设备不支持位置信息'); - } - ``` -除此之外,开发者可以通过API参考文档查询API接口所属的SysCap。 - -### 不同设备相同能力的差异检查 - -即使是相同的系统能力,在不同的设备下,也会有能力的差异。比如同是摄像头的能力,平板设备优于智能穿戴设备。 - -``` -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,保证在不同设备上的兼容性。