未验证 提交 42d39606 编写于 作者: O openharmony_ci 提交者: Gitee

!13563 翻译完成13023+12705+12504+12389+13364+12389+12504

Merge pull request !13563 from ester.zhou/C2-0113
...@@ -5,11 +5,30 @@ ...@@ -5,11 +5,30 @@
- [Getting Started with ArkTS in FA Model](start-with-ets-fa.md) - [Getting Started with ArkTS in FA Model](start-with-ets-fa.md)
- [Getting Started with JavaScript in FA Model](start-with-js-fa.md) - [Getting Started with JavaScript in FA Model](start-with-js-fa.md)
- Development Fundamentals - Development Fundamentals
- [Application Package Structure Configuration File (FA Model)](package-structure.md) - Application Package Fundamentals
- [Application Package Structure Configuration File (Stage Model)](stage-structure.md) - [Application Package Overview](application-package-overview.md)
- [SysCap](syscap.md) - Application Package Structure
- [Application Package Structure in Stage Model](application-package-structure-stage.md)
- [Application Package Structure in FA Model](application-package-structure-fa.md)
- [HAR File Structure](har-structure.md)
- Multi-HAP Mechanism
- [Multi-HAP Design Objectives](multi-hap-objective.md)
- [Multi-HAP Build View](multi-hap-build-view.md)
- [Multi-HAP Development, Debugging, Release, and Deployment Process](multi-hap-release-deployment.md)
- [Multi-HAP Usage Rules](multi-hap-rules.md)
- [Multi-HAP Operation Mechanism and Data Communication Modes](multi-hap-principles.md)
- [Application Installation and Uninstallation Process](application-package-install-uninstall.md)
- Application Configuration Files in Stage Model
- [Application Configuration File Overview (Stage Model)](application-configuration-file-overview-stage.md)
- [app.json5 Configuration File](app-configuration-file.md)
- [module.json5 Configuration File](module-configuration-file.md)
- Application Configuration Files in FA Model
- [Application Configuration File Overview (FA Model)](application-configuration-file-overview-fa.md)
- [Internal Structure of the app Tag](app-structure.md)
- [Internal Structure of deviceConfig Tag](deviceconfig-structure.md)
- [Internal Structure of the module Tag](module-structure.md)
- [Resource Categories and Access](resource-categories-and-access.md) - [Resource Categories and Access](resource-categories-and-access.md)
- Learning ArkTS - Learning ArkTS
- [Getting Started with ArkTS](arkts-get-started.md) - [Getting Started with ArkTS](arkts-get-started.md)
- ArkTS Syntax (Declarative UI) - ArkTS Syntax (Declarative UI)
- [Basic UI Description](arkts-basic-ui-description.md) - [Basic UI Description](arkts-basic-ui-description.md)
......
# app.json5 Configuration File
This document gives an overview of the **app.json5** configuration file. To start with, let's go through an example of what this file contains.
```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,
}
},
}
```
As shown above, the **app.json5** file contains several tags.
**Table 1** Tags in the app.json5 file
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| bundleName | Bundle name, which uniquely identifies an application. The value must comply with the following rules:<br>- Consists of letters, digits, underscores (_), and periods (.).<br>- Starts with a letter.<br>- Contains 7 to 127 bytes.<br>You are advised to use the reverse domain name notation, for example, *com.example.demo*, where the first part is the domain suffix **com**, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels.<br>If an application is built with the system source code, you are advised to name it in *com.ohos.demo* notation, where **ohos** signifies that the application is an OpenHarmony system application.| String| No|
| debug | Whether the application can be debugged. This tag is generated during compilation and building in DevEco Studio.<br>- **true**: The application can be debugged.<br>- **false**: The application cannot be debugged.| Boolean| Yes (initial value: **false**)|
| icon | [Icon of the application](../application-models/application-component-configuration-stage.md). The value is an icon resource index. | String| No|
| label | [Name of the application](../application-models/application-component-configuration-stage.md). The value is a string resource index. | String| No|
| description | Description of the application. The value is a string with a maximum of 255 bytes or a resource index to the description. | String| Yes (initial value: left empty)|
| vendor | Vendor of the application. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)|
| versionCode | Version number of the application. The value is a 32-bit non-negative integer less than 2 to the power of 31. It is used only to determine whether a version is later than another version. A larger value indicates a later version. Ensure that a new version of the application uses a value greater than any of its predecessors. | Number| No|
| versionName | Version number of the application displayed to users.<br>The value consists of only digits and dots. The four-part format *A.B.C.D* is recommended, wherein:<br>Part 1 (*A*): major version number, which ranges from 0 to 99. A major version consists of major new features or large changes.<br>Part 2 (*B*): minor version number, which ranges from 0 to 99. A minor version consists of some new features and large bug fixes.<br>Part 3 (*C*): feature version number, which ranges from 0 to 99. A feature version consists of scheduled new features.<br>Part 4 (*D*): maintenance release number or patch number, which ranges from 0 to 999. A maintenance release or patch consists of resolution to security flaws or minor bugs.<br>The value contains a maximum of 127 bytes.| String| No|
| minCompatibleVersionCode | Minimum compatible version of the application. It is used to check whether the application is compatible with a version on other devices in the cross-device scenario.| Number| Yes (initial value: value of **versionCode**)|
| minAPIVersion | Minimum API version required for running the application.| Number| Yes (initial value: value of **compatibleSdkVersion** in **bundle-profile.json5**)|
| targetAPIVersion | Target API version required for running the application.| Number| Yes (initial value: value of **compileSdkVersion** in **bundle-profile.json5**)|
| apiReleaseType | Type of the target API version required for running the application. The value can be **"CanaryN"**, **"BetaN"**, or **"Release"**, where **N** represents a positive integer.<br>- **Canary**: indicates a restricted release.<br>- **Beta**: indicates a publicly released beta version.<br>- **Release**: indicates a publicly released official version.<br>The value is set by DevEco Studio reading the stage of the SDK in use.| String| Yes (initial value: set by DevEco Studio)|
| distributedNotificationEnabled | Whether distributed notification is enabled for the application. When distributed notification is enabled and device A and device B where the application is installed are on the same distributed network, the devices behave in this way: If device A receives a message, device B will receive a distributed notification prompting the user to check the message received on device A.<br>- **true**: Distributed notification is enabled.<br>- **false**: Distributed notification is not enabled.| Boolean| Yes (initial value: **false**)|
| entityType | Type of the application. The options are as follows:<br>- game<br>- media<br>- communication<br>- news<br>- travel<br>- utility<br>- shopping<br>- education<br>- kids<br>- business<br>- photography<br>- unspecified| String| Yes (initial value: **"unspecified"**)|
| multiProjects | Whether the application supports joint development of multiple projects.<br>- **true**: The application supports joint development of multiple projects.<br>- **false**: The application does not support joint development of multiple projects.| Boolean| Yes (initial value: **false**)|
| tablet | Tablet-specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on tablets, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
| tv | TV-specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on TVs, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
| wearable | Wearable-specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on wearables, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
| car | Head unit–specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on head units, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
| default | Default device–specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on default devices, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
# HarmonyAppProvision Configuration File
The **HarmonyAppProvision** configuration file (also called profile) is the file where you declare permission and signature information for your application.
## Configuration File Internal Structure
The **HarmonyAppProvision** file consists of several parts, which are described in the table below.
**Table 1** Internal structure of the HarmonyAppProvision file
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| ----------- | ---------------------------------------------------------------------------------------- | -------- | -------- | -------- |
| version-code | Version number of the **HarmonyAppProvision** file format. The value is a positive integer containing 32 or less digits.| Number | Yes| No |
| version-name | Description of the version number. It is recommended that the value consist of three segments, for example, **A.B.C**. | String | Yes| No|
| uuid | Unique ID of the **HarmonyAppProvision** file. | String | Yes| No|
| type | Type of the **HarmonyAppProvision** file. The value can be **debug** (for application debugging) or **release** (for application release). The recommended value is **debug**.| String | Yes| No|
| issuer | Issuer of the **HarmonyAppProvision** file. | String | Yes| No|
| validity | Validity period of the **HarmonyAppProvision** file. For details, see [Internal Structure of the validity Object](#internal-structure-of-the-validity-object). | Object | Yes | No |
| bundle-info | Information about the application bundle and developer. For details, see [Internal Structure of the bundle-info Object](#internal-structure-of-the-bundle-info-object). | Object | Yes| No |
| acls | Information about the Access Control Lists (ACLs). For details, see [Internal Structure of the acls Object](#internal-structure-of-the-acls-object). | Object | No| No |
| permissions | Permissions required for your application. For details, see [Internal Structure of the permissions Object](#internal-structure-of-the-permissions-object). | Object | No| No |
| debug-info | Additional information for application debugging. For details, see [Internal Structure of the debug-info Object](#internal-structure-of-the-debug-info-object). | Object | No| No |
An example of the **HarmonyAppProvision** file is as follows:
```json
{
"version-code": 1,
"version-name": "1.0.0",
"uuid": "string",
"type": "debug",
"validity": {
"not-before": 1586422743,
"not-after": 1617958743
},
"bundle-info" : {
"developer-id": "OpenHarmony",
"development-certificate": "Base64 string",
"distribution-certificate": "Base64 string",
"bundle-name": "com.OpenHarmony.app.test",
"apl": "normal",
"app-feature": "hos_normal_app"
},
"acls": {
"allowed-acls": ["string"]
},
"permissions": {
"restricted-permissions": ["string"]
},
"debug-info" : {
"device-id-type": "udid",
"device-ids": ["string"]
},
"issuer": "OpenHarmony"
}
```
### Internal Structure of the validity Object
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| ---------- | ------------------------------- | ------- | ------- | --------- |
| not-before | Start time of the file validity period. The value is a Unix timestamp, which is a non-negative integer.| Number | Yes| No |
| not-after | End time of the file validity period. The value is a Unix timestamp, which is a non-negative integer.| Number | Yes| No |
### Internal Structure of the bundle-info Object
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| ------------------------ | ------------------------------- | ------- | -------- | --------- |
| developer-id | Unique ID of the developer.| String | Yes| No |
| development-certificate | Information about the [debug certificate](../security/hapsigntool-guidelines.md).| Number | Yes if **type** is set to **debug** and no otherwise | No |
| distribution-certificate | Information about the [release certificate](../security/hapsigntool-guidelines.md).| Number | Yes if **type** is set to **release** and no otherwise| No |
| bundle-name | Bundle name of the application.| String | Yes| No |
| apl | [Ability privilege level (APL)](../security/accesstoken-overview.md) of your application. The value can be **normal**, **system_basic**, or **system_core**.| String | Yes| No |
| app-feature | Type of your application. The value can be **hos_system_app** (system application) or **hos_normal_app** (non-system application).| String | Yes| No |
### Internal Structure of the acls Object
The **acls** object contains the [ACLs](../security/accesstoken-overview.md) configured for your application. It should be noted that you still need to fill the ACL information in the **reqPermissions** attribute in the [config.json](package-structure.md) file.
**Table 4** Internal structure of the acls object
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| ------------------------ | ------------------------------- | ------- | ------- | --------- |
| allowed-acls | [ACLs](../security/accesstoken-overview.md) configured for your application.| String array | No| No |
### Internal Structure of the permissions Object
The **permissions** object contains restricted permissions required for your application. Different from the ACLs set in the **acls** object, these permissions need user authorization during the running of your application. It should be noted that you still need to fill the permission information in the **reqPermissions** attribute in the [config.json](package-structure.md) file.
**Table 5** Internal structure of the permissions object
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| ------------------------ | ------------------------------- | ------- | ------- | --------- |
| restricted-permissions | [Restricted permissions](../security/accesstoken-overview.md) required for your application.| String array | No| No |
### Internal Structure of the debug-info Object
The **debug-info** object contains debugging information of your application, mainly device management and control information.
**Table 6** Internal structure of the debug-info object
| Name | Description | Data Type| Mandatory| Initial Value Allowed|
| ------------------------ | ------------------------------- | ------- | ------- | --------- |
| device-id-type | Type of the device ID. Currently, only the udid type is supported.| String | No| No |
| device-ids | IDs of devices on which your application can be debugged.| String array | No| No |
# Internal Structure of the app Tag
The **app** tag contains application-wide configuration. The internal structure is as follows:
### Internal Structure of the app Tag
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| bundleName | Bundle name, which uniquely identifies an application. The bundle name must start with a letter and can contain only letters, digits, underscores (_), and periods (.). The bundle name is a string with 7 to 127 bytes of a reverse domain name, for example, **"com.example.myapplication"**. It is recommended that the first level be the domain suffix "com" and the second level be the vendor/individual name. More levels are also accepted.| String| No|
| vendor | Vendor of the application. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)|
|version | Version of the application.| Object| No|
| apiVersion | OpenHarmony API version on which the application depends.| Object| Yes (initial value: left empty)|
| smartWindowSize | Screen size used when the application runs in the emulator.| String| Yes (initial value: left empty)|
| smartWindowDeviceType | Types of emulated devcies on which the application can run.| String array| Yes (initial value: left empty)|
#### Internal Structure of the version Atttribute
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| name | Application version number displayed to users. The value can be customized and cannot exceed 127 bytes. The configuration rules are as follows:<br>For API version 5 and earlier versions, use the three-part format *A.B.C* (compatible with a two-part format *A.B*), where A, B, and C are integers ranging from 0 to 999.<br>*A* indicates the major version number.<br>*B* indicates the minor version number.<br>*C* indicates the patch version number. For API version 6 and later versions, the four-part format *A.B.C.D* is recommended, where A, B, and C are integers ranging from 0 to 99, and D is an integer ranging from 0 to 999.<br>*A* indicates the major version number.<br>*B* indicates the minor version number.<br>*C* indicates the feature version number.<br>*D* indicates the patch version number.| Number| No|
| code | Application version number used only for application management by OpenHarmony. This version number is not visible to users of the application. The configuration rules are as follows:<br>API version 5 and earlier versions: The value is a non-negative integer within 32 binary digits, which needs to be converted from the value of **version.name**. The conversion rule is as follows: Value of **code** = A * 1,000,000 + B * 1,000 + C. For example, if the value of **version.name** is 2.2.1, the value of **code** is 2002001. API version 6 and later versions: The value of **code** is not associated with the value of **version.name** and can be customized. The value is a non-negative integer less than 2 to the power of 31. Note that the value must be updated each time the application version is updated, and the value for a later version must be greater than that for an earlier version.| Number| No|
| minCompatibleVersionCode | Earliest version compatible with the application. It is used in the cross-device scenario to check whether the application is compatible with a specific version on other devices. The value rules are the same as those of **version.code**.| Number| No (initial value: value of **code**)|
#### Internal Structure of the apiVersion Attribute
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| compatible | Minimum API version required for running the application. The value ranges from 0 to 2147483647.| Number| Yes (initial value: configured in **build.profile** and filled in **config.json** by DevEco Studio during packaging)|
| target | Target API version required for running the application. The value ranges from 0 to 2147483647.| Number| Yes (initial value: configured in **build.profile** and filled in **config.json** by DevEco Studio during packaging)|
| releaseType | SDK status when the application is running.<br>**canary**: preliminary release open only to specific developers. This release does not promise API stability and may require tolerance of instability.<br>**beta**: release open to all developers. This release does not promise API stability and may require tolerance of instability. After several releases, the beta version is declared as an API stability milestone through Release Notes, and APIs of later versions are frozen.<br>**release**: official release open to all developers. This release promises that all APIs are stable. When a version is in this state, the **Stage** field is not displayed in the version number.| String| Yes (initial value: configured in **build.profile** and filled in **config.json** by DevEco Studio during packaging)|
### Example of the **app** Tag
```json
"app": {
"bundleName": "com.example.myapplication",
"vendor": "example",
"version": {
"code": 8,
"name": "8.0.1"
},
"apiVersion": {
"compatible": 8,
"target": 9,
"releaseType": "Beta1"
}
}
```
# Application Configuration File Overview (FA Model)
Each application project must have configuration files in its code directory. These configuration files provide basic application information for OpenHarmony build tools, the operating system, and application markets.
The application configuration file must contain the following information:
- Basic information of the application, including the bundle name, vendor, and version number. Such information must be set under the **app** tag.
- Component information of the application, including all abilities, device types, component types, and syntax types in use.
- Device-specific information of the application. Such information affects the functioning of the application on the device.
When developing an application in the Feature Ability (FA) model, you must declare the package structure of the application in the **config.json** file.
## Configuration File Internal Structure
The **config.json** file consists of three mandatory tags, namely, **app**, **deviceConfig**, and **module**.
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| [app](app-structure.md) | Application-wide configuration. Different HAP files of an application must use the same **app** configuration. | Object| No|
| [deviceConfig](deviceconfig-structure.md) | Device-specific configuration. | Object| No|
| [module](module-structure.md) | HAP configuration. It is valid only for the current HAP file.| Object| No|
Example of the **config.json** file:
```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 is a resource index.
"description": "$string:MainAbility_entry_desc",
"formsEnabled": false,
// $string:MainAbility_entry_label is a resource index.
"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
}
}
]
}
}
```
# Application Configuration File Overview (Stage Model)
Each application project must have configuration files in its code directory. These configuration files provide basic application information for build tools, operating systems, and application markets.
In the code directory of an application project developed in stage model, there are two types of configuration files: one **app.json5** file and one or more **module.json5** files.
The [app.json5](app-configuration-file.md) file contains the following contents:
- Application-wide configuration, including the bundle name, developer, and version number.
- Device-specific configuration.
The [module.json5](module-configuration-file.md) file contains the following contents:
- Basic module configuration, such as the name, type, description, and supported device types of the module.
- Information about the [application components](../application-models/stage-model-development-overview.md), including the descriptions of the UIAbility and ExtensionAbility components.
- Information about the permissions required during application running.
# Application Installation and Uninstallation Process
The OpenHarmony bundle manager service module provides APIs for installing, updating, and uninstalling applications. You can call these APIs when needed. After you release your application to the application market, users can install and uninstall it on their device.
**Figure 1** Process of installing and uninstalling an application
![hap-intall-uninstall](figures/hap-intall-uninstall.png)
# Application Package Overview
A user application, also known as an application or app, runs on the operating system of devices and provides particular services for users. The software package corresponding to an application is called an application package.
OpenHarmony provides an efficient management mechanism for application packages. By harnessing this mechanism, you can easily develop, install, query, update, and uninstall application packages.
- To accelerate application deployment, you can use the integrated development tool provided by OpenHarmony to integrate executable code, resources, and third-party libraries into an OpenHarmony application package.
- To distribute your application package by device type, you can specify the device types for distribution in the application package configuration file provided by OpenHarmony.
- An application may provide a wide range of features. It is a good practice to divide and manage application features by module. OpenHarmony provides a multi-package management mechanism on an application-by-application basis. You can aggregate different application features into different packages to facilitate subsequent maintenance and expansion.
- To allow an application to run across various chip platforms, such as x86, Arm, and other 32-bit or 64-bit platforms, OpenHarmony abstracts away the differences between chip platforms for application packages.
- With a myriad of query APIs in OpenHarmony, you can quickly check the information about applications, including the application versions, names, components, and permissions.
- To facilitate resource search and use, the bundle management service in OpenHarmony archives resources by type (media, native, string, internationalization, and more) in different directories and integrates resource index files.
# Application Package Structure in FA Model
To develop an application based on the [FA model](application-configuration-file-overview-fa.md), it is essential to understand the application package structure in this model.
The difference between the application package structures in the FA model and stage model lies in where the internal files of a HAP file are stored. In the FA model, all the resource files, library files, and code files are stored in the **assets** folder, where the files are further organized.
- **config.json** is an application configuration file, where the template code is automatically created by DevEco Studio. You can modify the configuration as required. For details about the fields in this file, see [Internal Structure of the app Tag](app-structure.md).
- The **assets** folder is a collection of all the resource files, library files, and code files in a HAP file. It can be further organized into the **entry** folder and the **js** folder. The **entry** folder stores the **resources** folder and the **resources.index** file.
- The **resources** folder stores resource files (such as strings and images) of the application.
- The **resources.index** file provides a resource index table, which is generated by DevEco Studio invoking the specific SDK tool.
- The **js** folder stores code files created after compilation.
- The **pack.info** file describes the HAP attributes in the bundle, for example, **bundleName** and **versionCode** in **app** and **name**, **type**, and **abilities** in **module**. The file is automatically generated when DevEco Studio generates the bundle.
**Figure 1** Application package structure in FA model
![app-pack-fa](figures/app-pack-fa.png)
\ No newline at end of file
# Application Package Structure in Stage Model
To develop an application based on the [stage model](application-configuration-file-overview-stage.md), it is essential to understand the structure of the application package created after the application is built and packaged.
- In development, an application contains one or more modules. You can [create modules](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3) in the application project in [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio/). As a basic functional unit of an OpenHarmony application/service, a module contains source code, resource files, third-party libraries, and application/service configuration files, and can be built and run independently. Modules can be classified as Ability or Library. A module of the Ability type is built into a Harmony Ability Package (HAP) file in .hap format, and a module of the Library type is built into a [Harmony Ability Resources (HAR) file](har-structure.md) in .tgz format.
A module can contain one or more [UIAbility](../application-models/uiability-overview.md) components, as shown in the figure below.
**Figure 1** Relationship between modules and UIAbility components
![ability-and-module](figures/ability-and-module.png)
Unless otherwise specified, the modules described in this document refer to the modules of the Ability type.
- As aforementioned, you can build an application into one or more HAP files. The HAP file is the basic unit for installing an application. It provides code, resources, third-party libraries, and a configuration file. HAP files can be classified as Entry or Feature.
- HAP of the entry type: main module of the application, whose **type** field is set to **"entry"** in the [module.json5](module-configuration-file.md) file. In an application, each type of device supports only one HAP of the entry type, which is typically used to implement the application's entry screen, entry icon, or headline feature.
- HAP of the feature type: dynamic feature module of the application, whose **type** field is set to **"feature"** in the [module.json5](module-configuration-file.md) file. Each application can contain zero, one, or more HAP files of the feature type, which are used to implement the application features. You can configure this type of HAP file to be downloaded and installed independently as required or to be downloaded and installed together with the HAP file of the entry type. For details, see **deliveryWithInstall** in [module.json5 Configuration File](module-configuration-file.md).
- All the HAP files in an application are integrated into a bundle, and the bundle name is the unique identifier of the application. For details, see **bundleName** tag in [app.json5 Configuration File](app-configuration-file.md). Note that to release an application to the application market, all HAP files (that is, the bundle) contained in the application must be packed into an Application Package (App Pack) in .app format, which also contains the **pack.info** file that describes the attributes of the App Pack. The App Pack is distributed and installed on the cloud and on the device on a HAP-by-HAP basis.
- The HAP file includes folders such as **ets**, **libs**, and **resources** and files such as **resources.index**, **module.json**, and **pack.info**.
- The **ets** folder stores bytecode files generated after application code build.
- The **libs** folder stores library files, which are .so binary files that contain third-party code on which the OpenHarmony application depends.
- The **resources** folder stores resource files (such as strings and images) of the application.
- The **resources.index** file provides a resource index table, which is generated when the application project is built in DevEco Studio.
- The **module.json** file is the configuration file indispensable in a HAP file. It consists of **module.json5** and **app.json5** in the project configuration. While DevEco Studio provides default configuration, you must modify the configuration as needed. For details about the configuration fields, see [Application Configuration Files in Stage Model](application-configuration-file-overview-stage.md).
- The **pack.info** file describes the HAP attributes in the bundle, for example, **bundleName** and **versionCode** in **app** and **name**, **type**, and **abilities** in **module**. The file is automatically generated when DevEco Studio generates the bundle.
**Figure 2** Application package structure in stage model
![app-pack-stage](figures/app-pack-stage.png)
...@@ -132,7 +132,7 @@ Events supported by components are configured using event methods, which each fo ...@@ -132,7 +132,7 @@ Events supported by components are configured using event methods, which each fo
```ts ```ts
Button('add counter') Button('add counter')
.onClick(function () { .onClick(function () {
this.counter += 2 this.counter += 2;
}.bind(this)) }.bind(this))
``` ```
......
...@@ -60,26 +60,15 @@ struct ComponentA { ...@@ -60,26 +60,15 @@ struct ComponentA {
this.label = (this.languageCode === 'en') ? 'Number' : 'Count' this.label = (this.languageCode === 'en') ? 'Number' : 'Count'
}) })
} }
.margin({ bottom: 50 }) .margin({ top: 50, bottom: 50 })
Row() { Row() {
Button (`Change @StorageLink decorated variable: ${this.varA}`).height(40).fontSize(14) Button (`Change @StorageLink decorated variable: ${this.varA}`).height(40).fontSize(14)
.onClick(() => { .onClick(() => {
this.varA++ this.varA++
}) })
}.margin({ bottom: 50 })
Row() {
Button (`Change @StorageProp decorated variable: ${this.languageCode}`).height(40).fontSize(14)
.onClick(() => {
if (this.languageCode === 'zh') {
this.languageCode = 'en'
} else {
this.languageCode = 'zh'
}
})
}
} }
}.width('100%')
} }
} }
``` ```
...@@ -110,7 +99,7 @@ One-way data binding can be established between a component and the **LocalStora ...@@ -110,7 +99,7 @@ One-way data binding can be established between a component and the **LocalStora
> **NOTE** > **NOTE**
> >
> If a **LocalStorage** instance has initial values assigned when being created, these values will be used for the **@LocalStorageLink** and **@LocalStorageProp** decorated state variables in the component. Otherwise, the initial values assigned for **@LocalStorageLink** and **@LocalStorageProp** will be used instead. > If a **LocalStorage** instance does not have an initial value assigned when being created, it can use the initial value defined by **@LocalStorageLink** or **@LocalStorageProp** in the component.
### Example 1: Creating a LocalStorage Instance in an Ability ### Example 1: Creating a LocalStorage Instance in an Ability
......
...@@ -15,8 +15,8 @@ In the multi-dimensional state management mechanism for ArkUI, UI-related data c ...@@ -15,8 +15,8 @@ In the multi-dimensional state management mechanism for ArkUI, UI-related data c
| @Link | Primitive data types, classes, and arrays | This decorator is used to establish two-way data binding between the parent and child components. The internal state data of the parent component is used as the data source. Any changes made to one component will be reflected to the other.| | @Link | Primitive data types, classes, and arrays | This decorator is used to establish two-way data binding between the parent and child components. The internal state data of the parent component is used as the data source. Any changes made to one component will be reflected to the other.|
| @Observed | Class | This decorator is used to indicate that the data changes in the class will be managed by the UI page. | | @Observed | Class | This decorator is used to indicate that the data changes in the class will be managed by the UI page. |
| @ObjectLink | Objects of **@Observed** decorated classes| When the decorated state variable is modified, the parent and sibling components that have the state variable will be notified for UI re-rendering.| | @ObjectLink | Objects of **@Observed** decorated classes| When the decorated state variable is modified, the parent and sibling components that have the state variable will be notified for UI re-rendering.|
| @Consume | Primitive data types, classes, and arrays | When the **@Consume** decorated variable detects the update of the **@Provide** decorated variable, the re-rendering of the current custom component is triggered.|
| @Provide | Primitive data types, classes, and arrays | As the data provider, **@Provide** can update the data of child nodes and trigger page re-rendering.| | @Provide | Primitive data types, classes, and arrays | As the data provider, **@Provide** can update the data of child nodes and trigger page re-rendering.|
| @Consume | Primitive data types, classes, and arrays | When the **@Consume** decorated variable detects the update of the **@Provide** decorated variable, the re-rendering of the current custom component is triggered.|
## State Management with Application-level Variables ## State Management with Application-level Variables
...@@ -25,5 +25,8 @@ In the multi-dimensional state management mechanism for ArkUI, UI-related data c ...@@ -25,5 +25,8 @@ In the multi-dimensional state management mechanism for ArkUI, UI-related data c
- **@StorageLink**: works in a way similar to that of **@Consume**. The difference is that the target object is obtained from the **AppStorage** based on the given name. **@StorageLink** establishes two-way binding between the decorated UI component and **AppStorage** to synchronize data. - **@StorageLink**: works in a way similar to that of **@Consume**. The difference is that the target object is obtained from the **AppStorage** based on the given name. **@StorageLink** establishes two-way binding between the decorated UI component and **AppStorage** to synchronize data.
- **@StorageProp**: synchronizes UI component attributes with the **AppStorage** unidirectionally. That is, the value change in the **AppStorage** will trigger an update of the corresponding UI component, but the change of the UI component will not cause an update of the attribute value in the **AppStorage**. - **@StorageProp**: synchronizes UI component attributes with the **AppStorage** unidirectionally. That is, the value change in the **AppStorage** will trigger an update of the corresponding UI component, but the change of the UI component will not cause an update of the attribute value in the **AppStorage**.
- Service logic implementation API: adds, reads, modifies, or deletes the state data of applications. The changes made by this API will be synchronized to the UI component for UI update. - Service logic implementation API: adds, reads, modifies, or deletes the state data of applications. The changes made by this API will be synchronized to the UI component for UI update.
- **LocalStorage**: provides ability-specific storage.
- **@LocalStorageLink**: establishes two-way data binding between a component and the **LocalStorage**. Specifically, this is achieved by decorating the component's state variable with **@LocalStorageLink(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**.
- **@LocalStorageProp**: establishes one-way data binding between a component and the **LocalStorage**. Specifically, this is achieved by decorating the component's state variable with **@LocalStorageProp(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**.
- **PersistentStorage**: provides a set of static methods for managing persistent data of applications. Persistent data with specific tags can be linked to the **AppStorage**, and then the persistent data can be accessed through the **AppStorage** APIs. Alternatively, the **@StorageLink** decorator can be used to access the variable that matches the specific key. - **PersistentStorage**: provides a set of static methods for managing persistent data of applications. Persistent data with specific tags can be linked to the **AppStorage**, and then the persistent data can be accessed through the **AppStorage** APIs. Alternatively, the **@StorageLink** decorator can be used to access the variable that matches the specific key.
- **Environment**: provides the **AppStorage** with an array of environment state attributes that are required by the application and describe the device environment where the application runs. It is a singleton object created by the framework when the application is started. - **Environment**: provides the **AppStorage** with an array of environment state attributes that are required by the application and describe the device environment where the application runs. It is a singleton object created by the framework when the application is started.
...@@ -82,14 +82,18 @@ struct MyComponent { ...@@ -82,14 +82,18 @@ struct MyComponent {
## @Prop ## @Prop
**@Prop** and **@State** have the same semantics but different initialization modes. Variables decorated by **@Prop** must be initialized using the **@State** decorated variable provided by their parent components. The **@Prop** decorated variable can be modified in the component, but the modification is not updated to the parent component; that is, **@Prop** uses one-way data binding. **@Prop** and **@State** have the same semantics but different initialization modes. A **@Prop** decorated variable in a component must be initialized using the **@State** decorated variable in its parent component. The **@Prop** decorated variable can be modified in the component, but the modification is not updated to the parent component; the modification to the **@State** decorated variable is synchronized to the **@Prop** decorated variable. That is, **@Prop** establishes one-way data binding.
The **@Prop** decorated state variable has the following features: The **@Prop** decorated state variable has the following features:
- Support for simple types: The number, string, and boolean types are supported. - Support for simple types: The number, string, and boolean types are supported.
- Private: Data is accessed only within the component. - Private: Data is accessed only within the component.
- Support for multiple instances: A component can have multiple attributes decorated by **@Prop**. - Support for multiple instances: A component can have multiple attributes decorated by **@Prop**.
- Support for initialization with a value passed to the @Prop decorated variable: When a new instance of the component is created, all **@Prop** decorated variables must be initialized. Initialization inside the component is not supported. - Support for initialization with a value passed to the @Prop decorated variable: When a new instance of the component is created, all **@Prop** variables must be initialized. Initialization inside the component is not supported.
> **NOTE**
>
> A **@Prop** decorated variable cannot be initialized inside the component.
**Example** **Example**
...@@ -152,13 +156,13 @@ Two-way binding can be established between the **@Link** decorated variable and ...@@ -152,13 +156,13 @@ Two-way binding can be established between the **@Link** decorated variable and
- Support for multiple types: The **@Link** decorated variables support the data types the same as the **@State** decorated variables; that is, the value can be of the following types: class, number, string, boolean, or arrays of these types. - Support for multiple types: The **@Link** decorated variables support the data types the same as the **@State** decorated variables; that is, the value can be of the following types: class, number, string, boolean, or arrays of these types.
- Private: Data is accessed only within the component. - Private: Data is accessed only within the component.
- Single data source: The variable of the parent component used for initializing the **@Link** decorated variable must be a **@State** decorated variable. - Single data source: The variable used to initialize the **@Link** decorated variable in a component must be a state variable defined in the parent component.
- **Two-way binding**: When a child component changes the **@Link** decorated variable, the **@State** decorated variable of its parent component is also changed. - **Two-way binding**: When a child component changes the **@Link** decorated variable, the **@State** decorated variable of its parent component is also changed.
- Support for initialization with the variable reference passed to the @Link decorated variable: When creating an instance of the component, you must use the naming parameter to initialize all **@Link** decorated variables. **@Link** decorated variables can be initialized by using the reference of the **@State** or **@Link** decorated variable. Wherein, the **@State** decorated variables can be referenced using the **'$'** operator. - Support for initialization with the variable reference passed to the @Link decorated variable: When creating an instance of the component, you must use the naming parameter to initialize all **@Link** decorated variables. **@Link** decorated variables can be initialized by using the reference of the **@State** or **@Link** decorated variable. Wherein, the **@State** decorated variables can be referenced using the **'$'** operator.
> **NOTE** > **NOTE**
> >
> **@Link** decorated variables cannot be initialized within the component. > A **@Link** decorated variable cannot be initialized inside the component.
**Simple Type Example** **Simple Type Example**
...@@ -391,13 +395,13 @@ struct ViewB { ...@@ -391,13 +395,13 @@ struct ViewB {
``` ```
## @Consume and @Provide ## @Provide and @Consume
As the data provider, **@Provide** can update the data of child nodes and trigger page rendering. After **@Consume** detects that the **@Provide** decorated variable is updated, it will initiate re-rendering of the current custom component. As the data provider, **@Provide** can update the data of child nodes and trigger page rendering. After **@Consume** detects that the **@Provide** decorated variable is updated, it will initiate re-rendering of the current custom component.
> **NOTE** > **NOTE**
> >
> To avoid infinite loops caused by circular reference, exercise caution when using **@Provide** and **@Consume**. > When using **@Provide** and **@Consume**, avoid circular reference that may lead to infinite loops.
### @Provide ### @Provide
......
# Internal Structure of deviceConfig Tag
The **deviceConfig** tag contains device-specific configuration of the application, including attributes such as **default**, **tv**, **car**, and **wearable**. The **default** configuration applies to all types of devices. You need to declare the peculiar configuration of a specific device type in the associated sub-tag of this type.
### Table 1 Internal Structure of the deviceConfig Tag
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| default | Application configuration specific to the OpenHarmony device that provides full access to system capabilities.| Object| Yes (initial value: left empty)|
| tablet | Application configuration specific to tablets.| Object| Yes (initial value: left empty)|
| tv | Application configuration specific to smart TVs.| Object| Yes (initial value: left empty)|
| car | Application configuration specific to head units.| Object| Yes (initial value: left empty)|
| wearable | Application configuration specific to wearables.| Object| Yes (initial value: left empty)|
Table 2 describes the internal structure of the **deviceConfig** attributes.
#### Table 2 Internal Structure of the deviceConfig Attributes
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| process | Name of the process running the application or ability. If the **process** attribute is configured in the **deviceConfig** tag, all abilities of the application run in this process. You can set the **process** attribute for a specific ability in the **abilities** attribute, so that the ability can run in the particular process. The value can contain a maximum of 31 characters.| String| Yes (initial value: left empty)|
| keepAlive | Whether the application is always running. This attribute applies only to system applications and does not take effect for third-party applications. The value **true** means that the application will start during the OS startup and keep alive. If the application process exits, the OS will restart it.| Boolean| Yes (initial value: **false**)|
| supportBackup | Whether the application supports backup and restoration. The value **false** means that the application does not support backup or restoration.| Boolean| Yes (initial value: **false**)|
| compressNativeLibs | Whether the **libs** libraries are packaged in the HAP file after being compressed. The value **false** means that the **libs** libraries are stored without being compressed and will be directly loaded during the installation of the HAP file.| Boolean| Yes (initial value: **false**)|
| network | Network security configuration. You can customize the network security settings of the application in the security statement of the configuration file without modifying the application code.| Object| Yes (initial value: left empty)|
#### Table 3 Internal Structure of the network Attribute
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| cleartextTraffic | Whether to allow the application to use plaintext traffic, for example, plaintext HTTP traffic.<br>**true**: The application is allowed to use plaintext traffic. **false**: The application is not allowed to use plaintext traffic.| Boolean| Yes (initial value: **false**)|
| securityConfig | Network security configuration of the application.| Object| Yes (initial value: left empty)|
#### Table 4 Internal Structure of the securityConfig Attribute
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| domainSettings | Security settings of the custom network domain. This attribute allows nested domains. That is, the **domainSettings** object of a network domain can be nested with the **domainSettings** objects of smaller network domains.| Object| Yes (initial value: left empty)|
#### Table 5 Internal Structure of the domainSettings Attribute
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| cleartextPermitted | Whether plaintext traffic can be transmitted in the custom network domain. If both **cleartextTraffic** and **security** are declared, whether plaintext traffic can be transmitted in the custom network domain is determined by the **cleartextPermitted** attribute. **true**: Plaintext traffic can be transmitted. **false**: Plaintext traffic cannot be transmitted.| Boolean| Yes (initial value: left empty)|
| domains | Domain name. This attribute consists of two sub-attributes: **subdomains** and **name**. **subdomains** (boolean): specifies whether the domain name contains subdomains. If this sub-attribute is set to **true**, the domain naming convention applies to all related domains and subdomains (including the lower-level domains of the subdomains). Otherwise, the convention applies only to exact matches. **name** (string): indicates the domain name.| Object array| Yes (initial value: left empty)|
### Example of the deviceConfig Tag
```json
"deviceConfig": {
"default": {
"process": "com.example.test.example",
"supportBackup": false,
"network": {
"cleartextTraffic": true,
"securityConfig": {
"domainSettings": {
"cleartextPermitted": true,
"domains": [
{
"subdomains": true,
"name": "example.ohos.com"
}
]
}
}
}
}
}
```
...@@ -4,7 +4,7 @@ Both the public SDK and full SDK are toolkits for application development. <br>T ...@@ -4,7 +4,7 @@ Both the public SDK and full SDK are toolkits for application development. <br>T
The full SDK is intended for original equipment manufacturers (OEMs) and provided separately. It contains system APIs. The full SDK is intended for original equipment manufacturers (OEMs) and provided separately. It contains system APIs.
The SDK of API version 8 provided in DevEco Studio is a public SDK. If your project depends on any system API, such as the **animator** component, **xcomponent** component, or APIs in **@ohos.application.abilityManager.d.ts**, **@ohos.application.formInfo.d.ts**, or **@ohos.bluetooth.d.ts**, switch to the full SDK by performing the following steps. The SDK of API version 8 provided in DevEco Studio is a public SDK. If your project depends on any system API, such as the **animator** component, **XComponent**, or APIs in **@ohos.application.abilityManager.d.ts**, **@ohos.application.formInfo.d.ts**, or **@ohos.bluetooth.d.ts**, switch to the full SDK by performing the following steps.
> **NOTE** > **NOTE**
> >
...@@ -16,7 +16,8 @@ Manually download the system-specific full SDK package from the mirror. For deta ...@@ -16,7 +16,8 @@ Manually download the system-specific full SDK package from the mirror. For deta
## Checking the Local SDK Location ## Checking the Local SDK Location
In this example, an ArkTS project is used. For a JS project, replace **ets** with **js**. In this example, an eTS project is used. For a JS project, replace **ets** with **js**.
In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the location of the local SDK. In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the location of the local SDK.
...@@ -35,11 +36,15 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo ...@@ -35,11 +36,15 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo
b. Verify that the SDK contains system APIs (such as APIs defined in **@ohos.application.abilityManager.d.ts**, **@ohos.application.formInfo.d.ts**, and **@ohos.bluetooth.d.ts**). b. Verify that the SDK contains system APIs (such as APIs defined in **@ohos.application.abilityManager.d.ts**, **@ohos.application.formInfo.d.ts**, and **@ohos.bluetooth.d.ts**).
Note: The criteria for identifying system APIs are subject to the released API documentation. Note: The criteria for identifying system APIs are subject to the official API documentation.
2. Replace the SDK. The following uses public-SDK-3.x.x.x for Windows as an example. 2. Replace the SDK. The following uses public-SDK-3.x.x.x for Windows as an example.
a. Decompress the downloaded full SDK file: `ets-windows-3.x.x.x-Release.zip`
a. Decompress the downloaded full SDK file: **ets-windows-3.x.x.x-Release.zip**
![image-20220613165018184](figures/en-us_image_0000001655129264.png) ![image-20220613165018184](figures/en-us_image_0000001655129264.png)
...@@ -51,13 +56,13 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo ...@@ -51,13 +56,13 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo
![image-20220613161352157](figures/en-us_image_0000001655129041.png) ![image-20220613161352157](figures/en-us_image_0000001655129041.png)
Note: The name of the backup version directory must be different from the value of **version** field in the **oh-uni-package.json** file. In the example below, the name of the backup version directory is **3.x.x.x_backup**. Note: The name of the backup version directory must be different from the value of the **version** field in the **oh-uni-package.json** file. In the example below, the name of the backup version directory is **3.1.6.6_backup**.
![image-20220613165018184](figures/en-us_image_0000001655129398.png) ![image-20220613165018184](figures/en-us_image_0000001655129398.png)
The configuration in the **oh-uni-package.json** file is as follows, where the value of `apiVersion` is subject to the API version of the SDK, and the value of `version` is subject to the version number in the SDK file. The configuration in the **oh-uni-package.json** file is as follows, where the value of **apiVersion** is subject to the API version of the SDK, and the value of **version** is subject to the version number in the SDK file.
``` ```json
{ {
"apiVersion": "X", "apiVersion": "X",
"displayName": "Ets", "displayName": "Ets",
...@@ -71,19 +76,19 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo ...@@ -71,19 +76,19 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo
``` ```
Delete all files in the original SDK (3.x.x.x) directory. Failure to do so may result in some files being unable to be overwritten. **Delete all files in the original SDK (3.x.x.x) directory.** Failure to do so may result in some files being unable to be overwritten.
Copy the full SDK to the location of the local SDK. Copy the full SDK to the location of the local SDK.
Copy all files in the **ets** directory in the full SDK to the **ets\*3.x.x.x*** directory in the location of the local SDK. Copy all files in the **ets** directory in the full SDK to the **ets\3.x.x.x** directory in the location of the local SDK.
Change the value of **version** in the **oh-uni-package.json** file to the current SDK version number. Change the value of **version** in the **oh-uni-package.json** file to the current SDK version number.
In the ***3.x.x.x*\build-tools\ets-loader** directory, open the **cmd/powerShell** window and run the `npm install` command to download the **node_modules** dependency package. In the ***3.x.x.x*\build-tools\ets-loader** directory, open the **cmd/powerShell** window and run the **npm install** command to download the **node_modules** dependency package.
![image-20220613171111405](figures/en-us_image_0000001655129333.png) ![image-20220613171111405](figures/en-us_image_0000001655129333.png)
...@@ -92,3 +97,21 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo ...@@ -92,3 +97,21 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo
c. Check for system APIs. c. Check for system APIs.
![image-20220613213038104](figures/en-us_image_0000001655129372.png) ![image-20220613213038104](figures/en-us_image_0000001655129372.png)
## Appendix: macOS Security Alarm Handling
After the SDK is switched to the full SDK in DevEco Studio on macOS, an alarm is generated when the Previewer is opened.
![alarm](figures/alarm.png)
To clear the alarm, perform the following steps:
1. Start the Terminal application.
2. In Terminal, run **sudo spctl -- master - disable**.
3. In **System Preferences**, choose **Security & Privacy**, click the **General** tab and select **Anywhere** under **Allow apps downloaded from**.
![alarmHand](figures/alarmHand.png)
Now, applications downloaded from third-party sources will not be blocked, meaning that you can open the Previewer. For security purposes, change the **Allow apps downloaded from** settings back to the original option when the Previewer is not in use.
# HAR File Structure
The Harmony Ability Resources (HAR) file enables code to be shared among multiple modules or projects. Unlike a Harmony Ability Package (HAP) file, a HAR file cannot be independently installed on a device. Instead, it can only be referenced as the dependency of an application module.
A HAR file is the build product of a [module](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3) of the Library type in a DevEco Studio project.
The HAR file reuses the standard [npm package](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-development-npm-package-0000001222578434) release mode and is packed into a .tar package with the file name extension .tgz. The packed HAR file contains the source code, resource files, and the **module.json** file (in stage model) or **config.json** file (in FA model).
此差异已折叠。
# Multi-HAP Build View
DevEco Studio allows you to develop and build multiple HAP files in one application project, as shown below.
**Figure 1** Multi-HAP build view
![hap-multi-view](figures/hap-multi-view.png)
1. Development view in DevEco Studio
- AppScope folder
- [app.json5](app-configuration-file.md): application-wide configuration, such as the application bundle name, version number, application icon, application name, and dependent SDK version number.
- **resources** folder: stores application icon resources and application name string resources.
**NOTE**
- The folder is automatically generated by DevEco Studio and its name cannot be changed.
- The file names in the **AppScope** folder cannot be the same as those in the entry- or feature-type module directories. Otherwise, DevEco Studio reports an error.
- Entry- or feature-type module directories (the names are customizable)
- You implement service logic of your application in these module directories. In this example, the module folders are **entry.hap** and **feature.hap**.
- **resources** directory: stores the resources used by the module.
- **ets** folder: stores the service logic.
- [module.json5](module-configuration-file.md): module configuration, such as the module name, entry code path of the module, and component information.
2. View after build and packaging
- After a module is built, a HAP file for deployment is generated. Each module corresponds to a HAP file.
- The **module.json** file in the HAP file is composed of the **app.json5** and **module.json5** files in the development view.
- All HAP files are finally built into an Application Package (App Pack) in .app format for release to the application market.
# Multi-HAP Design Objectives
- Modular management: A well-designed application is generally managed in a modular manner, where modules are loosely coupled. In light of this, the multi-HAP mechanism is designed, allowing you to divide services into multiple modules and store each module in an independent HAP file. For example, If you are developing a payment application and its home screen consists of multiple modules, such as the scan, pay, messaging, and finance modules, you can implement the logic of the home screen for managing other modules in the entry-type HAP file, and implement specific modules in feature-type HAP files. The feature-type HAP files are independent. You can develop and test each of them separately, and then integrate them with the entry-type HAP file.
- Flexible deployment: You can combine multiple HAP files and deploy them on different devices. Assume that an application contains one entry-type HAP file (**Entry.hap**) and two feature-type HAP files (**Feature1.hap** and **Feature2.hap**). The **Entry.hap** file can be deployed on device A and device B, the **Feature1.hap** file can be deployed only on device A, and the **Feature2.hap** can be deployed only on device B. In this way, you can easily combine the **Entry.hap** and **Feature1.hap** files and deploy them on device A, and combine the **Entry.hap** and **Feature2.hap** files and deploy them on device B.
- On-demand loading: You can load modules only when they are needed, reducing the package size. Specifically, you can configure some HAP files of an application to be loaded on demand. For example, if some features are not used during application startup, you can configure them to be loaded only when they are needed, rather than being loaded at startup. This can reduce the size of the application package to some extent.
- Easier resource sharing: The resources (including public resource files and public pages) and shared objects (.so library files) required by multiple HAP files can be stored in an independent HAP file. In this way, other HAP files can obtain the resources and files by accessing the HAP, which reduces the size of the application package to some extent.
# Multi-HAP Operation Mechanism and Data Communication Modes
The multi-HAP mechanism is used to facilitate modular management for developers. There is no one-to-one mapping between the HAP and the running process of the application. The detailed running mechanism is as follows:
- By default, all UIAbility, ServiceExtensionAbility, and DataShareExtensionAbility components of an application (with the same bundle name) run in the same independent process, and other ExtensionAbility components of the same type run in separate processes.
- The HAP file supports the process configuration through the **process** tag in the **module.json5** (stage model) or **config.json** (FA model) file. This feature is supported only by system applications. If **process** is configured for an HAP file, all components of the HAP file run in an independent process. Multiple HAP files can be configured with the same process, in which case the HAP files run in the same process. For details about the process configuration, see [module.json5 Configuration File](module-configuration-file.md).
- When an application is running, the resources and code of the corresponding HAP file are loaded only when the UIAbility component in the same process is started.
Based on the preceding mechanism, the multi-HAP data communication modes are as follows:
- For details about data communication in the same process, see [Thread Model (Stage Model)](../application-models/thread-model-stage.md).
- For details about cross-process data communication, see [Process Model (Stage Model)](../application-models/process-model-stage.md).
- If multiple HAPs run in the same process, the communication mode between the components of multiple HAP files is the same as that between the components of the same HAP file.
# Multi-HAP Development, Debugging, Release, and Deployment Process
Below is the process of developing, debugging, releasing, and deploying multiple HAP files.
**Figure 1** Process of developing, debugging, releasing, and deploying multiple HAP files
![hap-release](figures/hap-release.png)
## Development
You can use [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio) to create multiple modules based on service requirements and develop services in independent modules.
## Debugging
You can use DevEco Studio to build code into one or more HAP files. Then, you can debug the HAP files.
* Using DevEco Studio for debugging
Follow the instructions in [Debugging Configuration](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-debugging-and-running-0000001263040487#section10491183521520).
* Using [hdc_std](../../device-dev/subsystems/subsys-toolchain-hdc-guide.md) for debugging
You can obtain the hdc_std tool from the **toolchains** directory of the SDK. When using this tool to install an HAP file, the HAP file path is the one on the operating platform. In this example, the Windows operating platform is used. The command reference is as follows:
```
// Installation and update: Multiple file paths can be specified.
hdc_std install C:\entry.hap C:\feature.hap
// The execution result is as follows:
install bundle successfully.
// Uninstall
hdc_std uninstall com.example.myapplication
// The execution result is as follows:
uninstall bundle successfully.
```
* Using Bundle Manager (bm) for debugging
When using bm to install or update an HAP file, the HAP file path is the one on the real device. The command reference is as follows:
```
// Installation and update: Multiple file paths can be specified.
bm install -p /data/app/entry.hap /data/app/ feature.hap
// The execution result is as follows:
install bundle successfully.
// Uninstall
bm uninstall -n com.example.myapplication
// The execution result is as follows:
uninstall bundle successfully.
```
## Release
When your application package meets the release requirements, you can package and build it into an App Pack and release it to the application market on the cloud. The application market verifies the signature of the App Pack. If the signature verification is successful, the application market obtains the HAP files from the App Pack, signs them, and distributes the signed HAP files.
## Deployment
The application market on the cloud distributes the applications to application market clients. These applications can contain one or more HAP files. After the user selects an application to download, the application market downloads all the HAP files contained in this application.
## Installation on a Device
After the download is complete, the application market client calls the installation API of the bundle manager service in the system to install the downloaded HAP files. The bundle manager service deploys HAP files by application in the specified directory to complete the application installation.
# Multi-HAP Usage Rules
- The App Pack cannot be directly installed on the device. It is only a unit that is released to AppGallery.
- All HAP files in the App Pack must share the same **bundleName** value in the configuration files.
- All HAP files in the App Pack must share the same **versionCode** value in the configuration files.
- In an application, each type of device supports only one HAP of the entry type. Each application can contain zero, one, or more HAP files of the feature type.
- Each HAP file in the App Pack must have **moduleName** configured. The **moduleName** value corresponding to all HAP files of the same device type must be unique.
- The signing certificates of all HAP files in the same application must be the same. Applications are released to the application market in the form of App Pack after being signed. Before distribution, the application market splits an App Pack into HAP files and resigns them to ensure the consistency of all HAP file signing certificates. Before installing HAP files on a device through the CLI or DevEco Studio for debugging, you must ensure that their signing certificates are the same. Otherwise, the installation will fail.
...@@ -83,7 +83,7 @@ You can create resource group subdirectories (including element, media, and prof ...@@ -83,7 +83,7 @@ You can create resource group subdirectories (including element, media, and prof
| ------- | ---------------------------------------- | ---------------------------------------- | | ------- | ---------------------------------------- | ---------------------------------------- |
| element | Indicates element resources. Each type of data is represented by a JSON file. The options are as follows:<br>- **boolean**: boolean data<br>- **color**: color data<br>- **float**: floating-point data<br>- **intarray**: array of integers<br>- **integer**: integer data<br>- **pattern**: pattern data<br>- **plural**: plural form data<br>- **strarray**: array of strings<br>- **string**: string data| It is recommended that files in the **element** subdirectory be named the same as the following files, each of which can contain only data of the same type:<br>- boolean.json<br>- color.json<br>- float.json<br>- intarray.json<br>- integer.json<br>- pattern.json<br>- plural.json<br>- strarray.json<br>- string.json | | element | Indicates element resources. Each type of data is represented by a JSON file. The options are as follows:<br>- **boolean**: boolean data<br>- **color**: color data<br>- **float**: floating-point data<br>- **intarray**: array of integers<br>- **integer**: integer data<br>- **pattern**: pattern data<br>- **plural**: plural form data<br>- **strarray**: array of strings<br>- **string**: string data| It is recommended that files in the **element** subdirectory be named the same as the following files, each of which can contain only data of the same type:<br>- boolean.json<br>- color.json<br>- float.json<br>- intarray.json<br>- integer.json<br>- pattern.json<br>- plural.json<br>- strarray.json<br>- string.json |
| media | Indicates media resources, including non-text files such as images, audios, and videos. | The file name can be customized, for example, **icon.png**. | | media | Indicates media resources, including non-text files such as images, audios, and videos. | The file name can be customized, for example, **icon.png**. |
| profile | Indicates a user-defined configuration file. You can obtain the file content by using the [getProfileByAbility](../reference/apis/js-apis-bundleManager.md#bundlemanagergetprofilebyability) API. | The file name can be customized, for example, **test_profile.json**.| | profile | Indicates a user-defined configuration file. You can obtain the file content by using the [getProfileByAbility](../reference/apis/js-apis-bundleManager.md#bundlemanagergetprofilebyability) API. | The file name can be customized, for example, **test_profile.json**. |
| rawfile | Indicates other types of files, which are stored in their raw formats after the application is built as an HAP file. They will not be integrated into the **resources.index** file.| The file name can be customized. | | rawfile | Indicates other types of files, which are stored in their raw formats after the application is built as an HAP file. They will not be integrated into the **resources.index** file.| The file name can be customized. |
**Media Resource Types** **Media Resource Types**
...@@ -231,25 +231,25 @@ When referencing resources in the **rawfile** subdirectory, use the **"$rawfile( ...@@ -231,25 +231,25 @@ When referencing resources in the **rawfile** subdirectory, use the **"$rawfile(
> >
> The return value of **$r** is a **Resource** object. You can obtain the corresponding string by using the [getStringValue](../reference/apis/js-apis-resource-manager.md) API. > The return value of **$r** is a **Resource** object. You can obtain the corresponding string by using the [getStringValue](../reference/apis/js-apis-resource-manager.md) API.
In the **.ets** file, you can use the resources defined in the **resources** directory. In the **.ets** file, you can use the resources defined in the **resources** directory. The following is a resource usage example based on the resource file examples in [Resource Group Sub-directories](#resource-group-subdirectories):
```ts ```ts
Text($r('app.string.string_hello')) Text($r('app.string.string_hello'))
.fontColor($r('app.color.color_hello')) .fontColor($r('app.color.color_hello'))
.fontSize($r('app.float.font_hello')) .fontSize($r('app.float.font_hello'))
}
Text($r('app.string.string_world')) Text($r('app.string.string_world'))
.fontColor($r('app.color.color_world')) .fontColor($r('app.color.color_world'))
.fontSize($r('app.float.font_world')) .fontSize($r('app.float.font_world'))
}
Text($r('app.string.message_arrive', "five of the clock")) // Reference string resources. The second parameter of $r is used to replace %s. // Reference string resources. The second parameter of $r is used to replace %s, and value is "We will arrive at five'o clock".
Text($r('app.string.message_arrive', "five'o clock"))
.fontColor($r('app.color.color_hello')) .fontColor($r('app.color.color_hello'))
.fontSize($r('app.float.font_hello')) .fontSize($r('app.float.font_hello'))
}
Text($r('app.plural.eat_apple', 5, 5)) // Reference plural resources. The first parameter indicates the plural resource, the second parameter indicates the number of plural resources, and the third parameter indicates the substitute of %d. // Reference plural resources. The first parameter indicates the plural resource, the second parameter indicates the number of plural resources, and the third parameter indicates the substitute of %d.
// The value is "5 apple" in singular form and "5 apples" in plural form.
Text($r('app.plural.eat_apple', 5, 5))
.fontColor($r('app.color.color_world')) .fontColor($r('app.color.color_world'))
.fontSize($r('app.float.font_world')) .fontSize($r('app.float.font_world'))
} }
...@@ -279,9 +279,16 @@ Text('Hello') ...@@ -279,9 +279,16 @@ Text('Hello')
.fontSize($r('sys.float.ohos_id_text_size_headline1')) .fontSize($r('sys.float.ohos_id_text_size_headline1'))
.fontFamily($r('sys.string.ohos_id_text_font_family_medium')) .fontFamily($r('sys.string.ohos_id_text_font_family_medium'))
.backgroundColor($r('sys.color.ohos_id_color_palette_aux1')) .backgroundColor($r('sys.color.ohos_id_color_palette_aux1'))
Image($r('sys.media.ohos_app_icon')) Image($r('sys.media.ohos_app_icon'))
.border({color: $r('sys.color.ohos_id_color_palette_aux1'), radius: $r('sys.float.ohos_id_corner_radius_button'), width: 2}) .border({
.margin({top: $r('sys.float.ohos_id_elements_margin_horizontal_m'), bottom: $r('sys.float.ohos_id_elements_margin_horizontal_l')}) color: $r('sys.color.ohos_id_color_palette_aux1'),
radius: $r('sys.float.ohos_id_corner_radius_button'), width: 2
})
.margin({
top: $r('sys.float.ohos_id_elements_margin_horizontal_m'),
bottom: $r('sys.float.ohos_id_elements_margin_horizontal_l')
})
.height(200) .height(200)
.width(300) .width(300)
``` ```
...@@ -4,7 +4,7 @@ This document is intended for novices at developing OpenHarmony applications. It ...@@ -4,7 +4,7 @@ This document is intended for novices at developing OpenHarmony applications. It
![en-us_image_0000001364254729](figures/en-us_image_0000001364254729.png) ![en-us_image_0000001364254729](figures/en-us_image_0000001364254729.png)
Before you begin, there are two basic concepts that will help you better understand OpenHarmony: UI framework and ability. Before you begin, there are two basic concepts that will help you better understand OpenHarmony: UI framework and application model.
## Basic Concepts ## Basic Concepts
...@@ -16,29 +16,25 @@ OpenHarmony provides a UI development framework, known as ArkUI. ArkUI provides ...@@ -16,29 +16,25 @@ OpenHarmony provides a UI development framework, known as ArkUI. ArkUI provides
ArkUI comes with two development paradigms: ArkTS-based declarative development paradigm (declarative development paradigm for short) and JavaScript-compatible web-like development paradigm (web-like development paradigm for short). You can choose whichever development paradigm that aligns with your practice. ArkUI comes with two development paradigms: ArkTS-based declarative development paradigm (declarative development paradigm for short) and JavaScript-compatible web-like development paradigm (web-like development paradigm for short). You can choose whichever development paradigm that aligns with your practice.
| **Development Paradigm**| **Programming Language**| **UI Update Mode**| **Applicable To**| **Intended Audience**| | **Development Paradigm**| **Programming Language**| **UI Update Mode**| **Applicable To** | **Intended Audience** |
| -------- | -------- | -------- | -------- | -------- | | ---------------- | ------------ | -------------- | -------------------------------- | -------------------------------------- |
| Declarative development paradigm| ArkTS| Data-driven| Applications involving technological sophistication and teamwork| Mobile application and system application developers| | Declarative development paradigm | ArkTS | Data-driven | Applications involving technological sophistication and teamwork| Mobile application and system application developers|
| Web-like development paradigm| JavaScript| Data-driven| Applications and service widgets with simple UIs| Frontend web developers| | Web-like development paradigm | JavaScript | Data-driven | Applications and service widgets with simple UIs | Frontend web developers |
For more details, see [UI Development](../ui/arkui-overview.md). For more details, see [UI Development](../ui/arkui-overview.md).
### Application Model
### Ability The application model is the abstraction of capabilities required by OpenHarmony applications. It provides necessary components and running mechanisms for applications. With application models, you can develop applications based on a unified set of models, making application development simpler and more efficient. For details, see [Elements of the Application Model](../application-models/application-model-composition.md).
An ability is the abstraction of a functionality that an application can provide. An application may provide various capabilities, and so it can have multiple abilities. These abilities can be deployed together or independently from each other. Along its evolution, OpenHarmony has provided two application models:
The ability framework model has two forms: - Feature Ability (FA) model. This model is supported by OpenHarmony API version 7 and 8. It is no longer recommended. For details about development based on the FA model, see [FA Model Development Overview](../application-models/fa-model-development-overview.md).
- Stage model. This model is supported since OpenHarmony API version 9. It is recommended and will evolve for a long time. In this model, classes such as **AbilityStage** and **WindowStage** are provided as the stage of application components and windows. That's why it is named stage model. For details about development based on the stage model, see [Stage Model Development Overview](../application-models/fa-model-development-overview.md).
- **FA model**: applies to application development using API version 8 and earlier versions. For details, see [FA Model Overview](../ability/fa-brief.md). For details about the differences between the FA model and stage model, see [Interpretation of the Application Model](../application-models/application-model-description.md).
- **Stage model**: introduced since API version 9. For details, see [Stage Model Overview](../ability/stage-brief.md). To help you better understand the preceding basic concepts and application development process, **Getting Started** provides a development example that contains two pages in different programming languages and application models.
The project directory structure of the FA model is different from that of the stage model. The stage model only works with the ArkTS programming language.
For details about the differences between the FA model and stage model, see [Ability Framework Overview](../ability/ability-brief.md).
This document provides an ability with two pages. For more information about ability development, see [Ability Development](../ability/ability-brief.md).
## Tool Preparation ## Tool Preparation
......
...@@ -40,7 +40,7 @@ ...@@ -40,7 +40,7 @@
- **src > main > ets > MainAbility > pages > index.ets**: the first page in the **pages** list, also referred to as the entry to the application. - **src > main > ets > MainAbility > pages > index.ets**: the first page in the **pages** list, also referred to as the entry to the application.
- **src > main > ets > MainAbility > app.ets**: ability lifecycle file. - **src > main > ets > MainAbility > app.ets**: ability lifecycle file.
- **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Categories and Access](resource-categories-and-access.md#resource-categories). - **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Categories and Access](resource-categories-and-access.md#resource-categories).
- **src > main > config.json**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details about the configuration file, see [Application Package Structure Configuration File (FA Model)](package-structure.md). - **src > main > config.json**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details, see [Application Configuration File Overview (FA Model)](application-configuration-file-overview-fa.md).
- **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**. - **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**.
- **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation. - **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation.
...@@ -129,7 +129,7 @@ ...@@ -129,7 +129,7 @@
> **NOTE** > **NOTE**
> >
> You can also right-click the **pages** folder and choose **New** > **Page** from the shortcut menu. In this scenario, you do not need to manually configure page routes. > You can also right-click the **pages** folder and choose **New** > **Page** from the shortcut menu. In this scenario, you do not need to manually configure page routes.
- Configure the route for the second page, by setting **pages/second** under **module - js - pages** in the **config.json** The sample code is as follows: The sample code is as follows: - Configure the route for the second page, by setting **pages/second** under **module - js - pages** in the **config.json** file. The sample code is as follows:
```json ```json
{ {
...@@ -223,7 +223,7 @@ You can implement page redirection through the [page router](../reference/apis/j ...@@ -223,7 +223,7 @@ You can implement page redirection through the [page router](../reference/apis/j
.height('5%') .height('5%')
// Bind the onClick event to the Next button so that clicking the button redirects the user to the second page. // Bind the onClick event to the Next button so that clicking the button redirects the user to the second page.
.onClick(() => { .onClick(() => {
router.push({ url: 'pages/second' }) router.pushUrl({ url: 'pages/second' })
}) })
} }
.width('100%') .width('100%')
......
...@@ -38,7 +38,7 @@ ...@@ -38,7 +38,7 @@
- **src > main > ets > entryability**: entry to your application/service. - **src > main > ets > entryability**: entry to your application/service.
- **src > main > ets > pages**: pages included in your application/service. - **src > main > ets > pages**: pages included in your application/service.
- **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Categories and Access](resource-categories-and-access.md#resource-categories). - **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Categories and Access](resource-categories-and-access.md#resource-categories).
- **src > main > module.json5**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details about the configuration file, see [Application Package Structure Configuration File (Stage Model)](stage-structure.md). - **src > main > module.json5**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details, see [module.json5 Configuration File](module-configuration-file.md).
- **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**. - **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**.
- **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation. - **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation.
...@@ -216,7 +216,7 @@ You can implement page redirection through the [page router](../reference/apis/j ...@@ -216,7 +216,7 @@ You can implement page redirection through the [page router](../reference/apis/j
.height('5%') .height('5%')
// Bind the onClick event to the Next button so that clicking the button redirects the user to the second page. // Bind the onClick event to the Next button so that clicking the button redirects the user to the second page.
.onClick(() => { .onClick(() => {
router.push({ url: 'pages/Second' }) router.pushUrl({ url: 'pages/Second' })
}) })
} }
.width('100%') .width('100%')
......
...@@ -39,7 +39,7 @@ ...@@ -39,7 +39,7 @@
- **src > main > js > MainAbility > app.js**: ability lifecycle file. - **src > main > js > MainAbility > app.js**: ability lifecycle file.
- **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Limitations and Access](../ui/js-framework-resource-restriction.md). - **src > main > resources**: a collection of resource files used by your application/service, such as graphics, multimedia, character strings, and layout files. For details about resource files, see [Resource Limitations and Access](../ui/js-framework-resource-restriction.md).
- **src > main > config.json**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details about the configuration file, see [Application Package Structure Configuration File (FA Model)](package-structure.md). - **src > main > config.json**: module configuration file. This file describes the global configuration information of the application/service, the device-specific configuration information, and the configuration information of the HAP file. For details, see [Application Configuration File Overview (FA Model)](application-configuration-file-overview-fa.md).
- **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**. - **build-profile.json5**: current module information and build configuration options, including **buildOption** and **targets**.
- **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation. - **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation.
......
# SysCap List # SystemCapability List
SysCap, short for System Capability, refers to a standalone feature in the operating system. SystemCapability (SysCap in short) refers to a standalone feature in the operating system.
Before using an API for development, you are advised to familiarize yourself with [SysCap](../quick-start/syscap.md), and then consult the following tables to see whether the SysCap set required for the API is supported by the target device type. Before using an API for development, you are advised to familiarize yourself with [SysCap](syscap.md), and then consult the following tables to see whether the SysCap set required for the API is supported by the target device type.
## SystemCapability.ArkUI.ArkUI.Full ## SystemCapability.ArkUI.ArkUI.Full
......
# SysCap # SystemCapability
## Overview ## Overview
### System Capabilities and APIs ### System Capabilities and APIs
SysCap is short for System Capability. It refers to a standalone feature in the operating system, for example, Bluetooth, Wi-Fi, NFC, or camera. Each SysCap corresponds to a set of bound APIs, whose availability depends on the support of the target device. Such a set of APIs can be provided in DevEco Studio for association. SysCap is short for SystemCapability. It refers to a standalone feature in the operating system, for example, Bluetooth, Wi-Fi, NFC, or camera. Each SysCap corresponds to a set of APIs, whose availability depends on the support of the target device. Such a set of APIs can be provided in DevEco Studio for association.
![image-20220326064841782](figures/image-20220326064841782.png) ![image-20220326064841782](figures/image-20220326064841782.png)
For details about the SysCap sets in OpenHarmony, see [SysCap List](../reference/syscap-list.md). For details about the SysCap sets in OpenHarmony, see [SysCap List](../reference/syscap-list.md).
### Supported SysCap Set, Associated SysCap Set, and Required SysCap Set ### Supported SysCap Set, Associated SysCap Set, and Required SysCap Set
The supported SysCap set, associated SysCap set, and required SysCap set are collections of SysCaps. The supported SysCap set, associated SysCap set, and required SysCap set are collections of SysCaps.
...@@ -20,8 +18,6 @@ The associated SysCap set covers the system capabilities of associated APIs that ...@@ -20,8 +18,6 @@ The associated SysCap set covers the system capabilities of associated APIs that
![image-20220326064913834](figures/image-20220326064913834.png) ![image-20220326064913834](figures/image-20220326064913834.png)
### Devices and Supported SysCap Sets ### Devices and Supported SysCap Sets
Each device provides a SysCap set that matches its hardware capability. Each device provides a SysCap set that matches its hardware capability.
...@@ -29,24 +25,18 @@ The SDK classifies devices into general devices and custom devices. The general ...@@ -29,24 +25,18 @@ The SDK classifies devices into general devices and custom devices. The general
![image-20220326064955505](figures/image-20220326064955505.png) ![image-20220326064955505](figures/image-20220326064955505.png)
### Mapping Between Devices and SDK Capabilities ### Mapping Between Devices and SDK Capabilities
The SDK provides a full set of APIs for DevEco Studio. DevEco Studio identifies the supported SysCap set based on the devices supported by the project, filters the APIs contained in the SysCap set, and provides the supported APIs for association (to autocomplete input). The SDK provides a full set of APIs for DevEco Studio. DevEco Studio identifies the supported SysCap set based on the devices selected for the project, filters the APIs contained in the SysCap set, and provides the supported APIs for association (to autocomplete input).
![image-20220326065043006](figures/image-20220326065043006.png) ![image-20220326065043006](figures/image-20220326065043006.png)
## How to Develop ## How to Develop
### Obtaining the PCID ### Obtaining the PCID
The Product Compatibility ID (PCID) contains the SysCap information supported by the current device. For the moment, you can obtain the PCID of a device from the device vendor. In the future, you'll be able to obtain the PCIDs of all devices from the authentication center, which is in development. The Product Compatibility ID (PCID) contains the SysCap information supported by the current device. For the moment, you can obtain the PCID of a device from the device vendor. In the future, you'll be able to obtain the PCIDs of all devices from the authentication center, which is in development.
### Importing the PCID ### Importing the PCID
DevEco Studio allows Product Compatibility ID (PCID) imports for projects. After the imported PCID file is decoded, the SysCap is output and written into the **syscap.json** file. DevEco Studio allows Product Compatibility ID (PCID) imports for projects. After the imported PCID file is decoded, the SysCap is output and written into the **syscap.json** file.
...@@ -55,8 +45,6 @@ Right-click the project directory and choose **Import Product Compatibility ID** ...@@ -55,8 +45,6 @@ Right-click the project directory and choose **Import Product Compatibility ID**
![20220329-103626](figures/20220329-103626.gif) ![20220329-103626](figures/20220329-103626.gif)
### Configuring the Associated SysCap Set and Required SysCap Set ### Configuring the Associated SysCap Set and Required SysCap Set
DevEco Studio automatically configures the associated SysCap set and required SysCap set based on the settings supported by the created project. You can modify these SysCap sets when necessary. DevEco Studio automatically configures the associated SysCap set and required SysCap set based on the settings supported by the created project. You can modify these SysCap sets when necessary.
...@@ -91,51 +79,44 @@ Exercise caution when modifying the required SysCap set. Incorrect modifications ...@@ -91,51 +79,44 @@ Exercise caution when modifying the required SysCap set. Incorrect modifications
} }
``` ```
### Single-Device Application Development ### Single-Device Application Development
By default, the associated SysCap set and required SysCap set of the application are the same as the supported SysCap set of the device. Exercise caution when modifying the required SysCap set. By default, the associated SysCap set and required SysCap set of the application are the same as the supported SysCap set of the device. Exercise caution when modifying the required SysCap set.
![image-20220326065124911](figures/image-20220326065124911.png) ![image-20220326065124911](figures/image-20220326065124911.png)
### Cross-Device Application Development ### Cross-Device Application Development
By default, the associated SysCap set of an application is the union of multiple devices' supported SysCap sets, while the required SysCap set is the intersection of the devices' supported SysCap sets. By default, the associated SysCap set of an application is the union of multiple devices' supported SysCap sets, while the required SysCap set is the intersection of the devices' supported SysCap sets.
![image-20220326065201867](figures/image-20220326065201867.png) ![image-20220326065201867](figures/image-20220326065201867.png)
### Checking Whether an API Is Available ### Checking Whether an API Is Available
Use **canIUse** if you want to check whether a project supports a specific SysCap. - Method 1: Use the **canIUse** API predefined in OpenHarmony.
``` ```
if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) {
console.log("This application supports SystemCapability.ArkUI.ArkUI.Full."); console.log("This application supports SystemCapability.ArkUI.ArkUI.Full.");
} else { } else {
console.log("This application does not support SystemCapability.ArkUI.ArkUI.Full".); console.log("This application does not support SystemCapability.ArkUI.ArkUI.Full".);
} }
``` ```
You can import a module using the **import** API. If the current device does not support the module, the import result is **undefined**. Before using an API, you must make sure the API is available. - Method 2: Import a module using the **import** API. If the current device does not support the module, the import result is **undefined**. Before using an API, you must make sure the API is available.
``` ```
import geolocation from '@ohos.geolocation'; import geolocation from '@ohos.geolocation';
if (geolocation) { if (geolocation) {
geolocation.getCurrentLocation((location) => { geolocation.getCurrentLocation((location) => {
console.log(location.latitude, location.longitude); console.log(location.latitude, location.longitude);
}); });
} else { } else {
console.log('This device does not support location information.'); console.log('This device does not support location information.');
} }
``` ```
You can also find out the SysCap to which an API belongs by referring to the API reference document.
### Checking the Differences Between Devices with a Specific SysCap ### Checking the Differences Between Devices with a Specific SysCap
...@@ -159,7 +140,6 @@ authenticator.execute('FACE_ONLY', 'S1', (err, result) => { ...@@ -159,7 +140,6 @@ authenticator.execute('FACE_ONLY', 'S1', (err, result) => {
}) })
``` ```
### How Do SysCap Differences Arise Between Devices ### How Do SysCap Differences Arise Between Devices
The device SysCaps in product solutions vary according to the component combination defined by the product solution vendor. The following figure shows the overall process. The device SysCaps in product solutions vary according to the component combination defined by the product solution vendor. The following figure shows the overall process.
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册