Skip to content

D
Docs

(_灬幸福相伴 / Docs
与 Fork 源项目一致

Fork自 OpenHarmony / Docs

通知 1
Star 1
Fork 0
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

提交 8a11df57 编写于 作者: Z zengyawen
浏览文件
操作

application-models 

Signed-off-by: Nzengyawen <zengyawen1@huawei.com>
上级 832ea7b1
展开全部 隐藏空白更改
内联 并排
Showing with 1861 addition and 2003 deletion
zh-cn/application-dev/quick-start/Readme-CN.md
浏览文件 @ 8a11df57
# 入门
- 快速入门
- [开发准备](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
zh-cn/application-dev/quick-start/app-configuration-file.md 0 → 100644
浏览文件 @ 8a11df57
# 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 | 标识应用的包名，用于标识应用的唯一性。该标签不可缺省。标签的值命名规则&nbsp;：<br/>-&nbsp;字符串以字母、数字、下划线和符号“.”组成。<br/>-&nbsp;以字母开头。<br/>-&nbsp;最小长度7个字节，最大长度127个字节。<br/>推荐采用反域名形式命名（如com.example.demo，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。<br/>其中，随系统源码编译的应用建议命名为“com.ohos.demo”形式，&nbsp;ohos标识OpenHarmony系统应用。 | 字符串 | 该标签不可缺省。 |
| debug | 标识应用是否可调试，该标签由IDE编译构建时生成。<br/>-&nbsp;true：可调试。<br/>-&nbsp;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 | 标识应用版本号的文字描述，用于向用户展示。<br/>该标签仅由数字和点构成，推荐采用“A.B.C.D”四段式的形式。四段式推荐的含义如下所示。<br/>第一段：主版本号/Major，范围0-99，重大修改的版本，如实现新的大功能或重大变化。<br/>第二段：次版本号/Minor，范围0-99，表示实现较突出的特点，如新功能添加或大问题修复。<br/>第三段：特性版本号/Feature，范围0-99，标识规划的新版本特性。<br/>第四段：修订版本号/Patch，范围0-999，表示维护版本，修复bug。<br/>标签最大字节长度为127。 | 字符串 | 该标签不可缺省。 |
| minCompatibleVersionCode | 标识应用能够兼容的最低历史版本号，用于跨设备兼容性判断。 | 数值 | 该标签可缺省，缺省值等于versionCode标签值。 |
| minAPIVersion | 标识应用运行需要的SDK的API最小版本。 | 数值 | 由bundle-profile.json5中的compatibleSdkVersion生成。 |
| targetAPIVersion | 标识应用运行需要的API目标版本。 | 数值 | 由bundle-profile.json5中的compileSdkVersion生成。 |
| apiReleaseType | 标识应用运行需要的API目标版本的类型，采用字符串类型表示。取值为“CanaryN”、“BetaN”或者“Release”，其中，N代表大于零的整数。<br/>-&nbsp;Canary：受限发布的版本。<br/>-&nbsp;Beta：公开发布的Beta版本。<br/>-&nbsp;Release：公开发布的正式版本。<br/>该字段由DevEco&nbsp;Studio读取当前使用的SDK的Stage来生成。 | 字符串 | 该标签可缺省，由IDE生成并覆盖。 |
| distributedNotificationEnabled | 标识应用是否开启分布式通知，当开启分布式通知时，同一分布式组网下的两个设备(A和B)，当设备A收到一条消息时，设备B会收到一天分布式消息用于设备B的使用者去查看设备A的消息。<br/>-&nbsp;true：开启。<br/>-&nbsp;false：不开启。 | 布尔值 | 该标签可缺省，缺省值为false。 |
| entityType | 标识应用的类别，分别有：<br/>-&nbsp;game：游戏类。<br/>-&nbsp;media：影音类。<br/>-&nbsp;communication：社交通信类。<br/>-&nbsp;news：新闻类。<br/>-&nbsp;travel：出行类。<br/>-&nbsp;utility：工具类。<br/>-&nbsp;shopping：购物类。<br/>-&nbsp;education：教育类。<br/>-&nbsp;kids：少儿类。<br/>-&nbsp;business：商务类。<br/>-&nbsp;photography：拍摄类。<br/>-&nbsp;unspecified：不属于上述的任何一类。 | 字符串 | 该标签可以缺省，缺省为unspecified。 |
| multiProjects | 标识当前工程是否支持多个工程的联合开发。<br/>-&nbsp;true：当前工程支持多个工程的联合开发。<br/>-&nbsp;false：当前工程不支持多个工程的联合开发。 | 布尔值 | 可缺省，缺省值为false。 |
| tablet | 标识对tablet设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。<br/>如果使用该属性对tablet设备做了特殊配置，则应用在tablet设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省，缺省时tablet设备使用app.json5公共区域配置的属性值。 |
| tv | 标识对tv设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。<br/>如果使用该属性对tv设备做了特殊配置，则应用在tv设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省，缺省时tv设备使用app.json5公共区域配置的属性值。 |
| wearable | 标识对wearable设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。<br/>如果使用该属性对wearable设备做了特殊配置，则应用在wearable设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省，缺省时wearable设备使用app.json5公共区域配置的属性值。 |
| car | 标识对car设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。<br/>如果使用该属性对car设备做了特殊配置，则应用在car设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省，缺省时car设备使用app.json5公共区域配置的属性值。 |
| default | 标识对default设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled。<br/>如果使用该属性对default设备做了特殊配置，则应用在default设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。 | 对象 | 该标签可缺省，缺省时default设备使用app.json5公共区域配置的属性值。 |
zh-cn/application-dev/quick-start/app-structure.md 0 → 100644
浏览文件 @ 8a11df57
# app对象内部结构
app对象包含应用全局配置信息，内部结构如下：
**表1** **app对象内部结构说明**
| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| -------- | -------- | -------- | -------- |
| bundleName | 标识应用的包名，用于标识应用的唯一性。包名是由字母、数字、下划线（_）和点号（.）组成的字符串，必须以字母开头。支持的字符串长度为7~127字节。包名通常采用反向域名形式表示（例如，"com.example.myapplication"）。建议第一级为域名后缀"com"，第二级为厂商/个人名，也可以采用多级。 | 字符串 | 不可缺省。 |
| vendor | 标识对应用开发厂商的描述。字符串长度不超过255字节。 | 字符串 | 可缺省，缺省值为空。 |
|version | 标识应用的版本信息。 | 对象 | 不可缺省。 |
| apiVersion | 标识应用程序所依赖的OpenHarmony&nbsp;API版本。 | 对象 | 可缺省，缺省值为空。 |
| smartWindowSize | 标识应用在模拟器中运行时使用的屏幕尺寸。 | 字符串 | 可缺省，缺省值为空。 |
| smartWindowDeviceType | 标识应用在模拟器中运行时可以模拟的设备。 | 字符串数组 | 可缺省，缺省值为空。 |
**表2** **version对象内部结构说明**
| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
| -------- | -------- | -------- | -------- |
| name | 标识应用的版本号，用于向应用的终端用户呈现。取值可以自定义，长度不超过127字节。自定义规则如下：API5及更早的版本：推荐使用三段数字版本号（也兼容两段式版本号），如A.B.C(也兼容A.B)，其中A、B、C取值为0-999范围内的整数。除此之外不支持其他格式。<br/>A段，一般表示主版本号(Major)。<br/>B段，一般表示次版本号(Minor)。<br/>C段，一般表示修订版本号(Patch)。API6版本起：推荐采用四段式数字版本号，如A.B.C.D，其中A、B、C取值为0-99范围内的整数，D的取值为0-999范围内的整数。<br/>A段，一般表示主版本号(Major)。<br/>B段，一般表示次版本号(Minor)。<br/>C段，一般表示特性版本号(Feature)。<br/>D段，一般表示修订版本号(Patch)。 | 数值 | 不可缺省。 |
| code | 标识应用的版本号，仅用于OpenHarmony管理该应用，不对应用的终端用户呈现。取值规则如下：API5及更早版本：二进制32位以内的非负整数，需要从version.name的值转换得到。转换规则为：code值=A&nbsp;\*&nbsp;1,000,000&nbsp;+&nbsp;B&nbsp;\*&nbsp;1,000&nbsp;+&nbsp;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的状态。<br/>canary：面向特定开发者早期预览版本，不承诺质量，不承诺API稳定。<br/>beta：公开发布的Beta版本，早期Beta版本不承诺API稳定，经历若干次发布后，通过Release&nbsp;Notes对开发者声明该Beta版本为API稳定里程碑，后续版本的API冻结。<br/>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"
}
}
```
zh-cn/application-dev/quick-start/application-configuration-file-overview-fa.md 0 → 100644
浏览文件 @ 8a11df57
# 应用配置文件概述（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
}
}
]
}
}
```
zh-cn/application-dev/quick-start/application-configuration-file-overview-stage.md 0 → 100644
浏览文件 @ 8a11df57
# 应用配置文件概述（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组件的描述信息。
- 应用运行过程中所需的权限信息。
zh-cn/application-dev/quick-start/application-package-install-uninstall.md 0 → 100644
浏览文件 @ 8a11df57
# 应用程序包安装和卸载流程
OpenHarmony包管理服务模块对外提供安装、更新和卸载应用的功能，开发者可以调用包管理服务的安装和卸载接口来实现应用的安装、更新和卸载。开发者将应用上架应用市场后，用户可以在端侧设备上进行应用的安装和卸载。
**图1** 应用程序包安装和卸载流程  
![hap-intall-uninstall](figures/hap-intall-uninstall.png)
zh-cn/application-dev/quick-start/application-package-overview.md 0 → 100644
浏览文件 @ 8a11df57
# 应用程序包概述
用户应用程序泛指运行在设备的操作系统之上，为用户提供特定服务的程序，简称“应用”。一个应用所对应的软件包文件，称为“应用程序包”。
OpenHarmony提供了应用程序包开发、安装、查询、更新、卸载的管理机制，方便开发者开发和管理OpenHarmony应用，具体如下：
- 应用软件所涉及的文件多种多样，开发者可通过OpenHarmony提供的集成开发工具将其开发的可执行代码、资源、三方库等文件整合到一起制作成OpenHarmony应用程序包，便于开发者对应用程序的部署。
- 应用软件所涉及的设备类型多种多样，开发者可通过OpenHarmony提供的应用程序包配置文件指定其应用程序包的分发设备类型，便于应用市场对应用程序包的分发管理。
- 应用软件所包含的功能多种多样，将不同的功能特性按模块来划分和管理是一种良好的设计方式。OpenHarmony提供了同一应用程序的多包管理的机制，开发者可以将不同的功能特性聚合到不同的包中，方便后续的维护与扩展。
- 应用软件涉及的芯片平台多种多样，有x86、ARM等，还有32位、64位之分，OpenHarmony为应用程序包屏蔽了芯片平台的差异，使应用程序包在不同的芯片平台都能够安装运行。
- 应用软件涉及的软件信息多种多样，有应用版本、应用名称、组件、申请权限等的信息，OpenHarmony包管理为开发者提供了这些信息的查询接口，方便开发者在程序中查询所需要的包信息。
- 应用软件涉及的资源多种多样，有媒体资源、原生资源、字符资源以及国际化的资源等，OpenHarmony包管理将不同的资源归档到不同的目录中，并集成资源索引文件，方便应用对资源的查找和使用。
zh-cn/application-dev/quick-start/application-package-structure-fa.md 0 → 100644
浏览文件 @ 8a11df57
# 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)
zh-cn/application-dev/quick-start/application-package-structure-stage.md 0 → 100644
浏览文件 @ 8a11df57
# 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)
zh-cn/application-dev/quick-start/arkts-rendering-control.md
浏览文件 @ 8a11df57
......@@ -34,7 +34,7 @@ Column() {
通过循环渲染（ForEach）从数组中获取数据，并为每个数据项创建相应的组件，可减少代码复杂度。
```
```ts
ForEach(
arr: any[],
itemGenerator: (item: any, index?: number) => void,
......
zh-cn/application-dev/quick-start/deviceconfig-structure.md 0 → 100644
浏览文件 @ 8a11df57
# 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）。<br/>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"
}
]
}
}
}
}
}
```
zh-cn/application-dev/quick-start/full-sdk-switch-guide.md
浏览文件 @ 8a11df57
......@@ -60,7 +60,7 @@ full-SDK需要手动下载。请参考[版本说明书](../../release-notes/Open
`oh-uni-package.json`文件配置信息如下，其中，`apiVersion`的值以SDK对应的API version为准，`version`的值以SDK文件的版本号为准：
```
```json
{
"apiVersion": "X",
"displayName": "Ets",
......
zh-cn/application-dev/quick-start/har-structure.md 0 → 100644
浏览文件 @ 8a11df57
# 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模型）等。
zh-cn/application-dev/quick-start/module-structure.md 0 → 100644
浏览文件 @ 8a11df57
此差异已折叠。
zh-cn/application-dev/quick-start/multi-hap-build-view.md 0 → 100644
浏览文件 @ 8a11df57
# 多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为后缀的包文件），用于发布到应用市场。
zh-cn/application-dev/quick-start/multi-hap-objective.md 0 → 100644
浏览文件 @ 8a11df57
# 多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文件，也一定程度上可以减少应用程序包大小。
zh-cn/application-dev/quick-start/multi-hap-principles.md 0 → 100644
浏览文件 @ 8a11df57
# 多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内组件的通信方式相同。
zh-cn/application-dev/quick-start/multi-hap-release-deployment.md 0 → 100644
浏览文件 @ 8a11df57
# 多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)
zh-cn/application-dev/quick-start/multi-hap-rules.md 0 → 100644
浏览文件 @ 8a11df57
# 多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签名证书一致，否则会出现安装失败的问题。
zh-cn/application-dev/quick-start/syscap.md 已删除 100644 → 0
浏览文件 @ 832ea7b1
# 系统能力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，保证在不同设备上的兼容性。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或