diff --git a/en/application-dev/quick-start/Readme-EN.md b/en/application-dev/quick-start/Readme-EN.md index 9b89cfd83f8a3af29bda3fe76016d269561282cb..439bbdcb9d9455a36c75ceb8ba39e728d1aecebd 100644 --- a/en/application-dev/quick-start/Readme-EN.md +++ b/en/application-dev/quick-start/Readme-EN.md @@ -5,11 +5,30 @@ - [Getting Started with ArkTS in FA Model](start-with-ets-fa.md) - [Getting Started with JavaScript in FA Model](start-with-js-fa.md) - Development Fundamentals - - [Application Package Structure Configuration File (FA Model)](package-structure.md) - - [Application Package Structure Configuration File (Stage Model)](stage-structure.md) - - [SysCap](syscap.md) + - Application Package Fundamentals + - [Application Package Overview](application-package-overview.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) - - Learning ArkTS +- Learning ArkTS - [Getting Started with ArkTS](arkts-get-started.md) - ArkTS Syntax (Declarative UI) - [Basic UI Description](arkts-basic-ui-description.md) diff --git a/en/application-dev/quick-start/app-configuration-file.md b/en/application-dev/quick-start/app-configuration-file.md new file mode 100644 index 0000000000000000000000000000000000000000..3fff90e0682c4f79e63fa0ee8306a5f8aa7e9385 --- /dev/null +++ b/en/application-dev/quick-start/app-configuration-file.md @@ -0,0 +1,56 @@ +# 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:
- Consists of letters, digits, underscores (_), and periods (.).
- Starts with a letter.
- Contains 7 to 127 bytes.
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.
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.
- **true**: The application can be debugged.
- **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.
The value consists of only digits and dots. The four-part format *A.B.C.D* is recommended, wherein:
Part 1 (*A*): major version number, which ranges from 0 to 99. A major version consists of major new features or large changes.
Part 2 (*B*): minor version number, which ranges from 0 to 99. A minor version consists of some new features and large bug fixes.
Part 3 (*C*): feature version number, which ranges from 0 to 99. A feature version consists of scheduled new features.
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.
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.
- **Canary**: indicates a restricted release.
- **Beta**: indicates a publicly released beta version.
- **Release**: indicates a publicly released official version.
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.
- **true**: Distributed notification is enabled.
- **false**: Distributed notification is not enabled.| Boolean| Yes (initial value: **false**)| +| entityType | Type of the application. The options are as follows:
- game
- media
- communication
- news
- travel
- utility
- shopping
- education
- kids
- business
- photography
- unspecified| String| Yes (initial value: **"unspecified"**)| +| multiProjects | Whether the application supports joint development of multiple projects.
- **true**: The application supports joint development of multiple projects.
- **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.
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.
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.
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.
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.
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)| diff --git a/en/application-dev/quick-start/app-provision-structure.md b/en/application-dev/quick-start/app-provision-structure.md deleted file mode 100644 index df74f5fc03327cfa876d0bc329b16ec1f26dc8cb..0000000000000000000000000000000000000000 --- a/en/application-dev/quick-start/app-provision-structure.md +++ /dev/null @@ -1,99 +0,0 @@ -# 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 | diff --git a/en/application-dev/quick-start/app-structure.md b/en/application-dev/quick-start/app-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..62b23fad4d660b1d3e516a696b0f7ce95bbde053 --- /dev/null +++ b/en/application-dev/quick-start/app-structure.md @@ -0,0 +1,49 @@ +# 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:
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.
*A* indicates the major version number.
*B* indicates the minor version number.
*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.
*A* indicates the major version number.
*B* indicates the minor version number.
*C* indicates the feature version number.
*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:
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.
**canary**: preliminary release open only to specific developers. This release does not promise API stability and may require tolerance of instability.
**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.
**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" + } + } +``` diff --git a/en/application-dev/quick-start/application-configuration-file-overview-fa.md b/en/application-dev/quick-start/application-configuration-file-overview-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..73bc7ebb53a70742bf5d2f0e581ddcae1db673bc --- /dev/null +++ b/en/application-dev/quick-start/application-configuration-file-overview-fa.md @@ -0,0 +1,118 @@ +# 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 + } + } + ] + } +} +``` diff --git a/en/application-dev/quick-start/application-configuration-file-overview-stage.md b/en/application-dev/quick-start/application-configuration-file-overview-stage.md new file mode 100644 index 0000000000000000000000000000000000000000..ff66e3d405738a44f0c645593ffb0dbfb5beca97 --- /dev/null +++ b/en/application-dev/quick-start/application-configuration-file-overview-stage.md @@ -0,0 +1,25 @@ +# 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. diff --git a/en/application-dev/quick-start/application-package-install-uninstall.md b/en/application-dev/quick-start/application-package-install-uninstall.md new file mode 100644 index 0000000000000000000000000000000000000000..3ccafd9ad3da5f98b9fbd229ff7025863ca105d8 --- /dev/null +++ b/en/application-dev/quick-start/application-package-install-uninstall.md @@ -0,0 +1,8 @@ +# 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) diff --git a/en/application-dev/quick-start/application-package-overview.md b/en/application-dev/quick-start/application-package-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..c9c16ad5ec6a70b48180fc277d46c54664ca2182 --- /dev/null +++ b/en/application-dev/quick-start/application-package-overview.md @@ -0,0 +1,18 @@ +# 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. diff --git a/en/application-dev/quick-start/application-package-structure-fa.md b/en/application-dev/quick-start/application-package-structure-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..6909481445ecb1219c30ed3ae425d6b475662805 --- /dev/null +++ b/en/application-dev/quick-start/application-package-structure-fa.md @@ -0,0 +1,24 @@ +# 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 diff --git a/en/application-dev/quick-start/application-package-structure-stage.md b/en/application-dev/quick-start/application-package-structure-stage.md new file mode 100644 index 0000000000000000000000000000000000000000..305d44bc2b9b2736420d9de3618fdea2d0a16124 --- /dev/null +++ b/en/application-dev/quick-start/application-package-structure-stage.md @@ -0,0 +1,32 @@ +# 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) diff --git a/en/application-dev/quick-start/arkts-basic-ui-description.md b/en/application-dev/quick-start/arkts-basic-ui-description.md index f8afbe2d46922b9b2b9cf5a0713add7540c95325..4d4c16a57eea5cc11d8f29ccb4b1b1db3b51efdb 100644 --- a/en/application-dev/quick-start/arkts-basic-ui-description.md +++ b/en/application-dev/quick-start/arkts-basic-ui-description.md @@ -132,7 +132,7 @@ Events supported by components are configured using event methods, which each fo ```ts Button('add counter') .onClick(function () { - this.counter += 2 + this.counter += 2; }.bind(this)) ``` @@ -144,7 +144,7 @@ Events supported by components are configured using event methods, which each fo } ... - + Button('add counter') .onClick(this.myClickHandler.bind(this)) ``` diff --git a/en/application-dev/quick-start/arkts-state-mgmt-application-level.md b/en/application-dev/quick-start/arkts-state-mgmt-application-level.md index 145827cd820399e5078b7e395b3c23b3719e1a03..a13c2442497634e83cae3e8bdc992df0898af42e 100644 --- a/en/application-dev/quick-start/arkts-state-mgmt-application-level.md +++ b/en/application-dev/quick-start/arkts-state-mgmt-application-level.md @@ -60,26 +60,15 @@ struct ComponentA { this.label = (this.languageCode === 'en') ? 'Number' : 'Count' }) } - .margin({ bottom: 50 }) + .margin({ top: 50, bottom: 50 }) Row() { Button (`Change @StorageLink decorated variable: ${this.varA}`).height(40).fontSize(14) .onClick(() => { 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 > **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 diff --git a/en/application-dev/quick-start/arkts-state-mgmt-concepts.md b/en/application-dev/quick-start/arkts-state-mgmt-concepts.md index d3f1002dca22fe4522134d662d4c640742d86952..2eae06eca22030673ef35bcf756279444fcd9c60 100644 --- a/en/application-dev/quick-start/arkts-state-mgmt-concepts.md +++ b/en/application-dev/quick-start/arkts-state-mgmt-concepts.md @@ -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.| | @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.| -| @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.| +| @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 @@ -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. - **@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. +- **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. - **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. diff --git a/en/application-dev/quick-start/arkts-state-mgmt-page-level.md b/en/application-dev/quick-start/arkts-state-mgmt-page-level.md index accda367a04ab0c77bdce7557bf47cc73f48c8a3..504665688a8eada31cd51531c7cd8c485d795892 100644 --- a/en/application-dev/quick-start/arkts-state-mgmt-page-level.md +++ b/en/application-dev/quick-start/arkts-state-mgmt-page-level.md @@ -82,14 +82,18 @@ struct MyComponent { ## @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: - Support for simple types: The number, string, and boolean types are supported. - Private: Data is accessed only within the component. - 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** @@ -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. - 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. - 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** > -> **@Link** decorated variables cannot be initialized within the component. +> A **@Link** decorated variable cannot be initialized inside the component. **Simple Type Example** @@ -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. > **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 diff --git a/en/application-dev/quick-start/deviceconfig-structure.md b/en/application-dev/quick-start/deviceconfig-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..7386e27ea69a33efc2e7bca6dfcb2413e3479799 --- /dev/null +++ b/en/application-dev/quick-start/deviceconfig-structure.md @@ -0,0 +1,72 @@ +# 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.
**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" + } + ] + } + } + } + } +} +``` diff --git a/en/application-dev/quick-start/figures/ability-and-module.png b/en/application-dev/quick-start/figures/ability-and-module.png new file mode 100644 index 0000000000000000000000000000000000000000..8910b0f30e8fc6808498155263939dbcb1a21336 Binary files /dev/null and b/en/application-dev/quick-start/figures/ability-and-module.png differ diff --git a/en/application-dev/quick-start/figures/alarm.png b/en/application-dev/quick-start/figures/alarm.png new file mode 100644 index 0000000000000000000000000000000000000000..d8710f4cb2d41a8f9dde0be779909867aa237536 Binary files /dev/null and b/en/application-dev/quick-start/figures/alarm.png differ diff --git a/en/application-dev/quick-start/figures/alarmHand.png b/en/application-dev/quick-start/figures/alarmHand.png new file mode 100644 index 0000000000000000000000000000000000000000..020ae09b94904b6b89e4503b7139dcc2843daeb2 Binary files /dev/null and b/en/application-dev/quick-start/figures/alarmHand.png differ diff --git a/en/application-dev/quick-start/figures/app-pack-fa.png b/en/application-dev/quick-start/figures/app-pack-fa.png new file mode 100644 index 0000000000000000000000000000000000000000..51c78e2625228cfbce44d694a0eefae2b0f22782 Binary files /dev/null and b/en/application-dev/quick-start/figures/app-pack-fa.png differ diff --git a/en/application-dev/quick-start/figures/app-pack-stage.png b/en/application-dev/quick-start/figures/app-pack-stage.png new file mode 100644 index 0000000000000000000000000000000000000000..355681fd15a3d8365ab690002fdb9f88b35e2360 Binary files /dev/null and b/en/application-dev/quick-start/figures/app-pack-stage.png differ diff --git a/en/application-dev/quick-start/figures/hap-intall-uninstall.png b/en/application-dev/quick-start/figures/hap-intall-uninstall.png new file mode 100644 index 0000000000000000000000000000000000000000..de04aa18f5053de48dd0b595c8265c781e36fee5 Binary files /dev/null and b/en/application-dev/quick-start/figures/hap-intall-uninstall.png differ diff --git a/en/application-dev/quick-start/figures/hap-multi-view.png b/en/application-dev/quick-start/figures/hap-multi-view.png new file mode 100644 index 0000000000000000000000000000000000000000..be727ebd53ebffbd29e52b78a750462489008892 Binary files /dev/null and b/en/application-dev/quick-start/figures/hap-multi-view.png differ diff --git a/en/application-dev/quick-start/figures/hap-release.png b/en/application-dev/quick-start/figures/hap-release.png new file mode 100644 index 0000000000000000000000000000000000000000..527cefcf7e466e105f74065c3d8b59b18802d94b Binary files /dev/null and b/en/application-dev/quick-start/figures/hap-release.png differ diff --git a/en/application-dev/quick-start/full-sdk-switch-guide.md b/en/application-dev/quick-start/full-sdk-switch-guide.md index 818249975bfd00cd582414549237f955fec1fcb8..f9116ce7ead9c4dbcf15f9d7e6b88a1d8b274d6d 100644 --- a/en/application-dev/quick-start/full-sdk-switch-guide.md +++ b/en/application-dev/quick-start/full-sdk-switch-guide.md @@ -4,7 +4,7 @@ Both the public SDK and full SDK are toolkits for application development.
T 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** > @@ -16,7 +16,8 @@ Manually download the system-specific full SDK package from the mirror. For deta ## 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. @@ -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**). - 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. - 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) @@ -51,13 +56,13 @@ In DevEco Studio, choose **Tools** > **OpenHarmony SDK Manager** to check the lo ![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) - 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", "displayName": "Ets", @@ -71,24 +76,42 @@ 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 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. - 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) c. Check for system APIs. - + ![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. diff --git a/en/application-dev/quick-start/har-structure.md b/en/application-dev/quick-start/har-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..f3b1189d37b9292f4ff4e814726c2f9a8f58c493 --- /dev/null +++ b/en/application-dev/quick-start/har-structure.md @@ -0,0 +1,10 @@ +# 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). diff --git a/en/application-dev/quick-start/module-configuration-file.md b/en/application-dev/quick-start/module-configuration-file.md new file mode 100644 index 0000000000000000000000000000000000000000..f06e9f911b9d1cb949097e23d24163f7afaa09c2 --- /dev/null +++ b/en/application-dev/quick-start/module-configuration-file.md @@ -0,0 +1,637 @@ +# module.json5 Configuration File + + +This document gives an overview of the **module.json5** configuration file. To start with, let's go through an example of what this file contains. + +```json +{ + "module": { + "name": "entry", + "type": "entry", + "description": "$string:module_desc", + "mainElement": "EntryAbility", + "deviceTypes": [ + "default", + "tablet" + ], + "deliveryWithInstall": true, + "installationFree": false, + "pages": "$profile:main_pages", + "virtualMachine": "ark", + "metadata": [ + { + "name": "string", + "value": "string", + "resource": "$profile:distrofilter_config" + } + ], + "abilities": [ + { + "name": "EntryAbility", + "srcEntrance": "./ets/entryability/EntryAbility.ts", + "description": "$string:EntryAbility_desc", + "icon": "$media:icon", + "label": "$string:EntryAbility_label", + "startWindowIcon": "$media:icon", + "startWindowBackground": "$color:start_window_background", + "visible": true, + "skills": [ + { + "entities": [ + "entity.system.home" + ], + "actions": [ + "action.system.home" + ] + } + ] + } + ], + "requestPermissions": [ + { + "name": "ohos.abilitydemo.permission.PROVIDER", + "reason": "$string:reason", + "usedScene": { + "abilities": [ + "FormAbility" + ], + "when": "inuse" + } + } + ] + } +} +``` + + +As shown above, the **module.json5** file contains several tags. + + + **Table 1** Tags in the module.json5 file + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the module. The value is a string with a maximum of 31 bytes and must be unique in the entire application.| String| No| +| type | Type of the module. The value can be **entry** or **feature**.
- **entry**: main module of the application.
- **feature**: dynamic feature module of the application.| String| No| +| srcEntrance | Code path corresponding to the module. The value is a string with a maximum of 127 bytes.| String| Yes (initial value: left empty)| +| description | Description of the module. The value is a string with a maximum of 255 bytes or a string resource index. | String| Yes (initial value: left empty)| +| process | Process name of the current module. The value is a string with a maximum of 31 bytes. If **process** is configured under **HAP**, all UIAbility, DataShareExtensionAbility, and ServiceExtensionAbility components of the application run in the specified process.
**NOTE**
This tag applies only to system applications and does not take effect for third-party applications.| String| Yes (initial value: value of **bundleName** under **app** in the **app.json5** file)| +| mainElement | Name of the entry UIAbility or ExtensionAbility of the module. The value contains a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| [deviceTypes](#devicetypes) | Type of the device on which the module can run.| String array| No (can be left empty)| +| deliveryWithInstall | Whether the HAP file of the module will be installed when the user installs the application.
- **true**: The HAP file will be installed when the user installs the application.
- **false**: The HAP file will not be installed when the user installs the application.| Boolean| No| +| installationFree | Whether the module supports the installation-free feature.
- **true**: The module supports the installation-free feature and meets installation-free constraints.
- **false**: The module does not support the installation-free feature.
**NOTE**
- If this tag is set to **true** for an entry-type module, it must also be set to **true** for feature-type modules of the same application.
- If this tag is set to **false** for an entry-type module, it can be set to **true** or **false** for feature-type modules of the same application based on service requirements.| Boolean| No| +| virtualMachine | Type of the target virtual machine (VM) where the module runs. It is used for cloud distribution, such as distribution by the application market and distribution center.
If the target VM type is ArkTS engine, the value is **ark**+*version number*. | String| Yes (initial value: automatically inserted when DevEco Studio builds the HAP file)| +| uiSyntax (deprecated)| Syntax type of the JS component defined by the module syntax. This tag is deprecated since API version 9.
- **"hml"**: The JS component is developed using HML, CSS, or JS.
- **"ets"**: The JS component is developed using ArkTS. | String| Yes (initial value: **"hml"**)| +| [pages](#pages)| Profile that represents information about each page in the JS component. The value can contain a maximum of 255 bytes.| String| No in the UIAbility scenario| +| [metadata](#metadata)| Custom metadata of the module. The setting is valid only for the current module, UIAbility, or ExtensionAbility.| Object array| Yes (initial value: left empty)| +| [abilities](#abilities) | UIAbility configuration of the module, which is valid only for the current UIAbility component.| Object| Yes (initial value: left empty)| +| [extensionAbilities](#extensionabilities) | ExtensionAbility configuration of the module, which is valid only for the current ExtensionAbility component.| Object| Yes (initial value: left empty)| +| [requestPermissions](#requestpermissions) | A set of permissions that the application needs to request from the system for running correctly.| Object| Yes (initial value: left empty)| +| [testRunner](#testrunner) | Test runner configuration of the module.| Object| Yes (initial value: left empty)| + + +## deviceTypes + + **Table 2** deviceTypes + +| Device Type| Value| Description| +| -------- | -------- | -------- | +| Tablet| tablet | - | +| Smart TV| tv | - | +| Smart watch| wearable | Watch that provides call features.| +| Head unit| car | - | +| Default device| default | OpenHarmony device that provides full access to system capabilities.| + +Example of the **deviceTypes** structure: + + +```json +{ + "module": { + "name": "myHapName", + "type": "feature", + "deviceTypes" : [ + "tablet" + ] + } +} +``` + + +## pages + +The **pages** tag is a profile that represents information about specified pages. + + +```json +{ + "module": { + // ... + "pages": "$profile:main_pages", // Configured through the resource file in the profile + } +} +``` + +Define the **main_pages.json** file under **resources/base/profile** in the development view. The base name of the file (**main_pages** in this example) can be customized, but must be consistent with the information specified by the **pages** tag. The file lists the page information of the current application. + + +```json +{ + "src": [ + "pages/index/mainPage", + "pages/second/payment", + "pages/third/shopping_cart", + "pages/four/owner" + ] +} +``` + + +## metadata + +The **metadata** tag represents the custom metadata of the HAP file. The tag value is an array and contains three subtags: **name**, **value**, and **resource**. + + **Table 3** metadata + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the data item. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| value | Value of the data item. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| resource | Custom data format. The value is a resource index. It contains a maximum of 255 bytes. | String| Yes (initial value: left empty)| + + +```json +{ + "module": { + "metadata": [{ + "name": "module_metadata", + "value": "a test demo for module metadata", + "resource": "$profile:shortcuts_config", + }], + + "abilities": [{ + "metadata": [{ + "name": "ability_metadata", + "value": "a test demo for ability", + "resource": "$profile:config_file" + }, + { + "name": "ability_metadata_2", + "value": "a string test", + "resource": "$profile:config_file" + }], + }], + + "extensionAbilities": [{ + "metadata": [{ + "name": "extensionAbility_metadata", + "value": "a test for extensionAbility", + "resource": "$profile:config_file" + }, + { + "name": "extensionAbility_metadata_2", + "value": "a string test", + "resource": "$profile:config_file" + }], + }] + } +} +``` + + +## abilities + +The **abilities** tag describes the UIAbility configuration of the component, which is valid only for the current UIAbility component. The tag value is an array. + + **Table 4** abilities + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the UIAbility component, which must be unique in the entire application. The value is a string with a maximum of 127 bytes.| String| No| +| srcEntrance | Code path of the entry UIAbility component. The value is a string with a maximum of 127 bytes.| String| No| +| [launchType](../application-models/uiability-launch-type.md) | Launch type of the UIAbility component. The options are as follows:
- **standard**: A new UIAbility instance is created each time the UIAbility component is started.
- **singleton**: A new UIAbility instance is created only when the UIAbility component is started for the first time.
- **specified**: You can determine whether to create a new UIAbility instance when the application is running.| String| Yes (initial value: **"singleton"**)| +| description | Description of the UIAbility component. The value is a string with a maximum of 255 bytes or a resource index to the description in multiple languages. | String| Yes (initial value: left empty)| +| icon | Icon of the UIAbility component. The value is an icon resource index.
If **UIAbility** is set to **MainElement** of the current module, this attribute is mandatory. | String| Yes (initial value: left empty) | +| label | Name of the UIAbility component displayed to users. The value is a string resource index.
If **UIAbility** is set to **MainElement** of the current module, this attribute is mandatory and its value must be unique in the application. | String| No| +| permissions | Permissions required for another application to access the UIAbility component.
The value is an array of permission names predefined by the system, generally in the reverse domain name notation. It contains a maximum of 255 bytes.| String array| Yes (initial value: left empty)| +| [metadata](#metadata)| Metadata information of the UIAbility component.| Object array| Yes (initial value: left empty)| +| visible | Whether the UIAbility component can be called by other applications.
- **true**: The UIAbility component can be called by other applications.
- **false**: The UIAbility component cannot be called by other applications.| Boolean| Yes (initial value: **false**)| +| continuable | Whether the UIAbility component can be [migrated](../application-models/hop-cross-device-migration.md).
- **true**: The UIAbility component can be migrated.
- **false**: The UIAbility component cannot be migrated.| Boolean| Yes (initial value: **false**)| +| [skills](#skills) | Feature set of [wants](../application-models/want-overview.md) that can be received by the current UIAbility or ExtensionAbility component.
Configuring rule:
- For HAPs of the entry type, you can configure multiple **skills** attributes with the entry capability for an OpenHarmony application. (A **skills** attribute with the entry capability is the one that has **action.system.home** and **entity.system.home** configured.)
- For HAPs of the feature type, you can configure **skills** attributes with the entry capability for an OpenHarmony application, but not for an OpenHarmony service.| Object array| Yes (initial value: left empty)| +| backgroundModes | Continuous tasks of the UIAbility component.
Continuous tasks are classified into the following types:
- **dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices.
- **audioPlayback**: audio playback service.
- **audioRecording**: audio recording service.
- **location**: location and navigation services.
- **bluetoothInteraction**: Bluetooth scanning, connection, and transmission services (wearables).
- **multiDeviceConnection**: multi-device interconnection service.
- **wifiInteraction**: Wi-Fi scanning, connection, and transmission services (as used in the Multi-screen Collaboration and clone features)
- **voip**: voice/video call and VoIP services.
- **taskKeeping**: computing service.| String array| Yes (initial value: left empty)| +| startWindowIcon | Index to the icon file of the UIAbility component startup page. Example: **$media:icon**.
The value is a string with a maximum of 255 bytes.| String| No| +| startWindowBackground | Index to the background color resource file of the UIAbility component startup page. Example: **$color:red**.
The value is a string with a maximum of 255 bytes.| String| No| +| removeMissionAfterTerminate | Whether to remove the relevant task from the task list after the UIAbility component is destroyed.
- **true**: Remove the relevant task from the task list after the UIAbility component is destroyed.
- **false**: Do not remove the relevant task from the task list after the UIAbility component is destroyed.| Boolean| Yes (initial value: **false**)| +| orientation | Orientation of the UIAbility component when it is started. The options are as follows:
- **unspecified**: automatically determined by the system.
- **landscape**: landscape mode.
- **portrait**: portrait mode.
- **landscape_inverted**: inverted landscape mode.
- **portrait_inverted**: inverted portrait mode.
- **auto_rotation**: determined by the sensor.
- **auto_rotation_landscape**: determined by the sensor in the horizontal direction, including landscape and inverted landscape modes.
- **auto_rotation_portrait**: determined by the sensor in the vertical direction, including portrait and inverted portrait modes.
- **auto_rotation_restricted**: determined by the sensor when the sensor switch is enabled.
- **auto_rotation_landscape_restricted**: determined by the sensor in the horizontal direction, including landscape and inverted landscape modes, when the sensor switch is enabled.
- **auto_rotation_portrait_restricted**: determined by the sensor in the vertical direction, including portrait and inverted portrait modes, when the sensor switch is enabled.
- **locked**: auto rotation disabled.| String| Yes (initial value: **"unspecified"**)| +| supportWindowMode | Window mode supported by the UIAbility component. The options are as follows:
- **fullscreen**: full-screen mode.
- **split**: split-screen mode.
- **floating**: floating window mode.| String array| Yes (initial value:
["fullscreen", "split", "floating"])| +| priority | Priority of the UIAbility component. This attribute applies only to system applications and does not take effect for third-party applications. In the case of [implicit query](../application-models/explicit-implicit-want-mappings.md), UIAbility components with a higher priority are at the higher place of the returned list. The value is an integer ranging from 0 to 10. The greater the value, the higher the priority.| Number| Yes (initial value: **0**)| +| maxWindowRatio | Maximum aspect ratio supported by the UIAbility component. The minimum value is 0.| Number| Yes (initial value: maximum aspect ratio supported by the platform)| +| minWindowRatio | Minimum aspect ratio supported by the UIAbility component. The minimum value is 0.| Number| Yes (initial value: minimum aspect ratio supported by the platform)| +| maxWindowWidth | Maximum window width supported by the UIAbility component, in vp. The minimum value is 0.| Number| Yes (initial value: maximum window width supported by the platform)| +| minWindowWidth | Minimum window width supported by the UIAbility component, in vp. The minimum value is 0.| Number| Yes (initial value: minimum window width supported by the platform)| +| maxWindowHeight | Maximum window height supported by the UIAbility component, in vp. The minimum value is 0.| Number| Yes (initial value: maximum window height supported by the platform)| +| minWindowHeight | Minimum window height supported by the UIAbility component, in vp. The minimum value is 0.| Number| Yes (initial value: minimum window height supported by the platform)| +| excludeFromMissions | Whether the UIAbility component is displayed in the recent task list.
- **true**: displayed in the recent task list.
- **false**: not displayed in the recent task list.
**NOTE**
This tag applies only to system applications and does not take effect for third-party applications.| Boolean| Yes (initial value: **false**)| + +Example of the **abilities** structure: + + +```json +{ + "abilities": [{ + "name": "EntryAbility", + "srcEntrance": "./ets/entryability/EntryAbility.ts", + "launchType":"standard", + "description": "$string:description_main_ability", + "icon": "$media:icon", + "label": "Login", + "permissions": [], + "metadata": [], + "visible": true, + "continuable": true, + "skills": [{ + "actions": ["action.system.home"], + "entities": ["entity.system.home"], + "uris": [] + }], + "backgroundModes": [ + "dataTransfer", + "audioPlayback", + "audioRecording", + "location", + "bluetoothInteraction", + "multiDeviceConnection", + "wifiInteraction", + "voip", + "taskKeeping" + ], + "startWindowIcon": "$media:icon", + "startWindowBackground": "$color:red", + "removeMissionAfterTerminate": true, + "orientation": " ", + "supportWindowMode": ["fullscreen", "split", "floating"], + "maxWindowRatio": 3.5, + "minWindowRatio": 0.5, + "maxWindowWidth": 2560, + "minWindowWidth": 1400, + "maxWindowHeight": 300, + "minWindowHeight": 200, + "excludeFromMissions": false + }] +} +``` + + +## skills + +The **skills** tag represents the feature set of [wants](../application-models/want-overview.md) that can be received by the UIAbility or ExtensionAbility component. + + **Table 5** skills + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| actions | [Actions](../application-models/actions-entities.md) of wants that can be received, which can be predefined or customized.| String array| Yes (initial value: left empty)| +| entities | [Entities](../application-models/actions-entities.md) of wants that can be received.| String array| Yes (initial value: left empty)| +|uris | URIs that match the wants.| Object array| Yes (initial value: left empty)| + + **Table 6** uris + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| scheme | Scheme of the URI, such as HTTP, HTTPS, file, and FTP.| String| Yes when only **type** is set in **uris** (initial value: left empty) | +| host | Host address of the URI. This attribute is valid only when **schema** is set. Common methods:
- domain name, for example, **example.com**.
- IP address, for example, **10.10.10.1**.| String| Yes (initial value: left empty)| +| port | Port number of the URI. For example, the default HTTP port number is 80, the default HTTPS port number is 443, and the default FTP port number is 21. This attribute is valid only when both **scheme** and **host** are set.| String| Yes (initial value: left empty)| +| path \| pathStartWith \| pathRegex | Path of the URI. **path**, **pathStartWith**, and **pathRegex** represent different matching modes between the paths in the URI and the want. Set any one of them as needed. **path** indicates full matching, **pathStartWith** indicates prefix matching, and **pathRegex** indicates regular expression matching. This attribute is valid only when both **scheme** and **host** are set.| String| Yes (initial value: left empty)| +| type | Data type that matches the want. The value compiles with the [Multipurpose Internet Mail Extensions (MIME)](https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com %E3%80%82) type specification. This attribute can be configured together with **scheme** or be configured separately. | String| Yes (initial value: left empty)| + +Example of the **skills** structure: + + +```json +{ + "abilities": [ + { + "skills": [ + { + "actions": [ + "action.system.home" + ], + "entities": [ + "entity.system.home" + ], + "uris": [ + { + "scheme":"http", + "host":"example.com", + "port":"80", + "path":"path", + "type": "text/*" + } + ] + } + ] + } + ] +} +``` + + +## extensionAbilities + +The **extensionAbilities** tag represents the configuration of extensionAbilities, which is valid only for the current extensionAbility. + + **Table 7** extensionAbilities + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the ExtensionAbility component. The value is a string with a maximum of 127 bytes. The name must be unique in the entire application.| String| No| +| srcEntrance | Code path corresponding to the ExtensionAbility component. The value is a string with a maximum of 127 bytes.| String| No| +| description | Description of the ExtensionAbility component. The value is a string with a maximum of 255 bytes or a resource index to the description. | String| Yes (initial value: left empty)| +| icon | Icon of the ExtensionAbility component. The value is the index to an icon resource file. If **ExtensionAbility** is set to **MainElement** of the current module, this attribute is mandatory and its value must be unique in the application.| String| Yes (initial value: left empty)| +| label | Name of the ExtensionAbility component displayed to users. The value is the index to a string resource.
**NOTE**
If **ExtensionAbility** is set to **MainElement** of the current module, this attribute is mandatory and its value must be unique in the application.| String| No| +| type | Type of the ExtensionAbility component. The options are as follows:
- **form**: ExtensionAbility of a widget.
- **workScheduler**: ExtensionAbility of a Work Scheduler task.
- **inputMethod**: ExtensionAbility of an input method.
- **service**: service component running in the background.
- **accessibility**: ExtensionAbility of an accessibility feature.
- **dataShare**: ExtensionAbility for data sharing.
- **fileShare**: ExtensionAbility for file sharing.
- **staticSubscriber**: ExtensionAbility for static broadcast.
- **wallpaper**: ExtensionAbility of the wallpaper.
- **backup**: ExtensionAbility for data backup.
- **window**: ExtensionAbility of a window. This type of ExtensionAbility creates a window during startup for which you can develop the GUI. The window is then combined with other application windows through **abilityComponent**.
- **thumbnail**: ExtensionAbility for obtaining file thumbnails. You can provide thumbnails for files of customized file types.
- **preview**: ExtensionAbility for preview. This type of ExtensionAbility can parse the file and display it in a window. You can combine the window with other application windows.
**NOTE**
The **service** and **dataShare** types apply only to system applications and do not take effect for third-party applications. | String| No| +| permissions | Permissions required for another application to access the ExtensionAbility component.
The value is generally in the reverse domain name notation and contains a maximum of 255 bytes. It is an array of permission names predefined by the system or customized. The name of a customized permission must be the same as the **name** value of a permission defined in the **defPermissions** attribute.| String array| Yes (initial value: left empty)| +| uri | Data URI provided by the ExtensionAbility component. The value is a string with a maximum of 255 bytes, in the reverse domain name notation.
**NOTE**
This attribute is mandatory when **type** of the ExtensionAbility component is set to **dataShare**.| String| Yes (initial value: left empty)| +|skills | Feature set of [wants](../application-models/want-overview.md) that can be received by the ExtensionAbility component.
Configuration rule: In an entry package, you can configure multiple **skills** attributes with the entry capability. (A **skills** attribute with the entry capability is the one that has **action.system.home** and **entity.system.home** configured.) The **label** and **icon** in the first ExtensionAbility that has **skills** configured are used as the **label** and **icon** of the entire OpenHarmony service/application.
**NOTE**
The **skills** attribute with the entry capability can be configured for the feature-type package of an OpenHarmony application, but not for an OpenHarmony service. | Array| Yes (initial value: left empty)| +| [metadata](#metadata)| Metadata of the ExtensionAbility component.| Object| Yes (initial value: left empty)| +| visible | Whether the ExtensionAbility component can be called by other applications.
- **true**: The ExtensionAbility component can be called by other applications.
- **false**: The ExtensionAbility component cannot be called by other applications.| Boolean| Yes (initial value: **false**)| + +Example of the **extensionAbilities** structure: + + +```json +{ + "extensionAbilities": [ + { + "name": "FormName", + "srcEntrance": "./form/MyForm.ts", + "icon": "$media:icon", + "label" : "$string:extension_name", + "description": "$string:form_description", + "type": "form", + "permissions": ["ohos.abilitydemo.permission.PROVIDER"], + "readPermission": "", + "writePermission": "", + "visible": true, + "uri":"scheme://authority/path/query", + "skills": [{ + "actions": [], + "entities": [], + "uris": [] + }], + "metadata": [ + { + "name": "ohos.extension.form", + "resource": "$profile:form_config", + } + ] + } + ] +} +``` + + +## requestPermissions + +The **requestPermissions** tage represents a set of permissions that the application needs to request from the system for running correctly. + + **Table 8** requestPermissions + +| Name| Description| Data Type| Value Range| Default Value| +| -------- | -------- | -------- | -------- | -------- | +| name | Permission name. This attribute is mandatory.| String| Custom| –| +| reason | Reason for requesting the permission. This attribute is mandatory when the permission to request is **user_grant**.
**NOTE**
If the permission to request is **user_grant**, this attribute is required for the application to be released to the application market, and multi-language adaptation is required. | String| Resource reference of the string type in $string: \*\*\* format| A null value| +| usedScene | Scene under which the permission is used. It consists of the **abilities** and **when** sub-attributes. Multiple abilities can be configured.
**NOTE**
This attribute is optional by default. If the permission to request is **user_grant**, the **abilities** sub-attribute is mandatory and **when** is optional. | **abilities**: string array
**when**: string| **abilities**: array of names of UIAbility or ExtensionAbility components
**when**: **inuse** or **always**| **abilities**: null
**when**: null| + +Example of the **requestPermissions** structure: + + +```json +{ + "module" : { + "requestPermissions": [ + { + "name": "ohos.abilitydemo.permission.PROVIDER", + "reason": "$string:reason", + "usedScene": { + "abilities": [ + "EntryFormAbility" + ], + "when": "inuse" + } + } + ] + } +} +``` + + +## shortcuts + +The **shortcuts** tag provides the shortcut information of an application. The value is an array of up to four shortcuts. It consists of four sub-attributes: **shortcutId**, **label**, **icon**, and **wants**. + +The **shortcut** information is identified in **metadata**, where: + +- **name** indicates the name of the shortcut, identified by **ohos.ability.shortcuts**. + +- **resource** indicates where the resources of the shortcut are stored. + +| Attribute| Description| Data Type | Default Value| +| -------- | -------- | -------- | -------- | +| shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes.| String| No| +| label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the label, with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| icon | Icon of the shortcut. The value is an icon resource index. | String| Yes (initial value: left empty)| +| [wants](../application-models/want-overview.md) | Wants to which the shortcut points. Each want consists of the **bundleName** and **abilityName** sub-attributes.
**bundleName**: target bundle name of the shortcut. The value is a string.
**abilityName**: target component name of the shortcut. The value is a string.| Object| Yes (initial value: left empty)| + + +1. Configure the **shortcuts_config.json** file in **/resource/base/profile/**. + + ```json + { + "shortcuts": [ + { + "shortcutId": "id_test1", + "label": "$string:shortcut", + "icon": "$media:aa_icon", + "wants": [ + { + "bundleName": "com.ohos.hello", + "abilityName": "EntryAbility" + } + ] + } + ] + } + ``` + +2. In the **abilities** tag of the **module.json5** file, configure the **metadata** tag for the UIAbility component to which a shortcut needs to be added so that the shortcut configuration file takes effect for the UIAbility. + + ```json + { + "module": { + // ... + "abilities": [ + { + "name": "EntryAbility", + "srcEntrance": "./ets/entryability/EntryAbility.ts", + // ... + "skills": [ + { + "entities": [ + "entity.system.home" + ], + "actions": [ + "action.system.home" + ] + } + ], + "metadata": [ + { + "name": "ohos.ability.shortcuts", + "resource": "$profile:shortcuts_config" + } + ] + } + ] + } + } + ``` + + +## distroFilter + +The **distroFilter** tag defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when the application market distributes applications. Distribution rules cover five factors: API version, screen shape, screen size, screen resolution, and country code. During distribution, a unique HAP is determined based on the mapping between **deviceType** and these five factors. This tag must be configured in the **/resource/profile resource** directory. + + **Table 9** distroFilter + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| apiVersion | Supported API versions.| Object array| Yes (initial value: left empty)| +| screenShape | Supported screen shapes.| Object array| Yes (initial value: left empty)| +| screenWindow | Supported window resolutions for when the application is running. This attribute applies only to the lite wearables.| Object array| Yes (initial value: left empty)| +| screenDensity | Pixel density of the screen, in dots per inch (DPI). This attribute is optional. The options are as follows:
- **sdpi**: small-scale DPI. This value is applicable to devices with a DPI range of (0, 120].
- **mdpi**: medium-scale DPI. This value is applicable to devices with a DPI range of (120, 160].
- **ldpi**: large-scale DPI. This value is applicable to devices with a DPI range of (160, 240].
- **xldpi**: extra-large-scale DPI. This value is applicable to devices with a DPI range of (240, 320].
- **xxldpi**: extra-extra-large-scale DPI. This value is applicable to devices with a DPI range of (320, 480].
- **xxxldpi**: extra-extra-extra-large-scale DPI. This value is applicable to devices with a DPI range of (480, 640]. | Object array| Yes (initial value: left empty)| +| countryCode | Code of the country or region to which the application is to be distributed. The value is subject to the [ISO-3166-1](https://developer.harmonyos.com/en/docs/documentation/doc-guides/basic-resource-file-categories-0000001052066099) standard. Enumerated definitions of multiple countries and regions are supported.| Object array| Yes (initial value: left empty)| + + **Table 10** apiVersion + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | API versions, for example, 4, 5, or 6. Example: If an application comes with two versions developed using API version 5 and API version 6 for the same device model, two installation packages of the entry type can be released for the application.| Array| No| + + **Table 11** screenShape + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Screen shapes. The value can be **circle**, **rect**, or both. Example: Different HAP files can be provided for a smart watch with a circular face and that with a rectangular face.| String array| No| + + **Table 12** screenWindow + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Screen width and height, in pixels. The value an array of supported width and height pairs, each in the "width * height" format, for example, **"454 * 454"**.| String array| No| + + **Table 13** screenDensity + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Pixel density of the screen, in DPI.| String array| No| + + **Table 14** countryCode + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Code of the country or region to which the application is to be distributed.| String array| No| + +Configure the **distro_filter_config.json** file (this file name is customizable) in **resources/base/profile** under the development view. + + +```json +{ + "distroFilter": { + "apiVersion": { + "policy": "include", + "value": [ + 3, + 4 + ] + }, + "screenShape": { + "policy": "include", + "value": [ + "circle", + "rect" + ] + }, + "screenWindow": { + "policy": "include", + "value": [ + "454*454", + "466*466" + ] + }, + "screenDensity": { + "policy": "exclude", + "value": [ + "ldpi", + "xldpi" + ] + }, + "countryCode": {// Distribution to the Chinese mainland and Hong Kong, China is supported. + "policy": "include", + "value": [ + "CN", + "HK" + ] + } + } +} +``` + +Configure **metadata** in the **module** tag in the **module.json5** file. + + +```json +{ + "module": { + // ... + "metadata": [ + { + "name": "ohos.module.distro", + "resource": "$profile:distro_filter_config", + } + ] + } +} +``` + + +## testRunner + +The **testRunner** tag represents the supported test runner. + + **Table 15** testRunner + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the test runner object. The value is a string with a maximum of 255 bytes.| String| No| +| srcPath | Code path of the test runner. The value is a string with a maximum of 255 bytes. | String| No| + +Example of the / structure: + + +```json +{ + "module": { + // ... + "testRunner": { + "name": "myTestRunnerName", + "srcPath": "etc/test/TestRunner.ts" + } + } +} +``` diff --git a/en/application-dev/quick-start/module-structure.md b/en/application-dev/quick-start/module-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..a8df69c1846a1ff6f7647aff4490da5d4990d431 --- /dev/null +++ b/en/application-dev/quick-start/module-structure.md @@ -0,0 +1,640 @@ +# Internal Structure of the module Tag + + +The **module** tag contains the HAP configuration. + +### Table 1 Internal Structure of the module Tag + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| mainAbility | Ability whose icon is displayed in the Service Center. When the resident process is started, the **mainAbility** is started.| String| Yes (initial value: left empty)| +| package | Package name of the HAP file, which must be unique in the application. The value is a string with a maximum of 127 bytes, in the reverse domain name notation. It is recommended that the value be the same as the project directory of the HAP file. | String| No| +| name | Class name of the HAP file. The value is a string with a maximum of 255 bytes, in the reverse domain name notation. The prefix must be the same as the **package** value specified for this module. Alternatively, the value can start with a period (.) followed by the class name.| String| Yes (initial value: left empty)| +| description | Description of the HAP file. The value is a string with a maximum of 255 bytes. If the value exceeds the limit or needs to support multiple languages, you can use a resource index to the description.| String| Yes (initial value: left empty)| +| supportedModes | Modes supported by the application. Currently, only the **drive** mode is defined. This attribute applies only to head units.| String array| Yes (initial value: left empty)| +|deviceType | Type of device on which the ability can run. The device types predefined in the system include **tablet**, **tv**, **car**, and **wearable**.| String array| No| +|distro | Distribution description of the HAP file.| Object| No| +|metaData | Metadata of the HAP file.| Object| Yes (initial value: left empty)| +| abilities | All abilities in the current module. The value is an array of objects, each of which represents an ability.| Object array| Yes (initial value: left empty)| +| js | A set of JS modules developed using ArkUI. The value is an array of objects, each of which represents a JS module.| Object array| Yes (initial value: left empty)| +| shortcuts | Shortcuts of the application. The value is an array of objects, each of which represents a shortcut object.| Object array| Yes (initial value: left empty)| +| reqPermissions | Permissions that the application requests from the system when it is running.| Object array| Yes (initial value: left empty)| +| colorMode | Color mode of the application. The options are as follows:
- **dark**: Resources applicable for the dark mode are used.
- **light**: Resources applicable for the light mode are used.
- **auto**: Resources are used based on the color mode of the system.| String| Yes (initial value: **auto**)| +| distroFilter | Distribution rules of the application. This attribute defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when the application market distributes applications. Distribution rules cover three factors: API version, screen shape, and screen resolution. During distribution, a unique HAP is determined based on the mapping between **deviceType** and these three factors. | Object| Yes (initial value: left empty) Set this attribute when an application has multiple entry modules.| +|commonEvents | Information about the common event static subscriber, which must contain the subscriber name, required permissions, and list of the subscribed common events. When a subscribed event is sent, the static subscriber is started. Unlike the common dynamic subscriber, the static subscriber does not need to actively call the common event subscription API in the service code, and may not be started when the common event is released. In constrast, the dynamic subscriber actively calls the common event subscription API and therefore requires the application to stay active.| Object array| Yes (initial value: left empty)| +| entryTheme | Keyword of an OpenHarmony internal theme. Set it to the resource index of the name.| String| Yes (initial value: left empty)| +|testRunner | Test runner configuration.| Object| Yes (initial value: left empty)| + +Example of the **module** tag structure: + +```json +{ + "module": { + "mainAbility": ".MainAbility", + "deviceType": [ + "default", + "tablet" + ], + "abilities": [ + { + "skills": [ + { + "entities": [ + "entity.system.home" + ], + "actions": [ + "action.system.home" + ] + } + ], + "orientation": "unspecified", + "visible": true, + "srcPath": "MainAbility", + "name": ".MainAbility", + "srcLanguage": "ets", + "icon": "$media:icon", + "description": "$string:MainAbility_desc", + "formsEnabled": false, + "label": "$string:MainAbility_label", + "type": "page", + "launchType": "standard" + } + ], + "distro": { + "moduleType": "entry", + "installationFree": false, + "deliveryWithInstall": true, + "moduleName": "entry" + }, + "package": "com.example.entry", + "srcPath": "", + "name": ".entry", + "js": [ + { + "mode": { + "syntax": "ets", + "type": "pageAbility" + }, + "pages": [ + "pages/Index" + ], + "name": ".MainAbility", + "window": { + "designWidth": 720, + "autoDesignWidth": false + } + } + ] + } +} +``` + +#### Table 2 Internal structure of the distro attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| moduleName | Name of the HAP file. The maximum length is 31 bytes.| String| No| +| moduleType | Type of the HAP file, which can **entry**, **feature**, or **har**.| String| No| +| installationFree | Whether the HAP file supports the installation-free feature. **true**: The HAP file supports the installation-free feature and meets installation-free constraints. **false**: The HAP file does not support the installation-free feature. If this tag is set to **true** for an entry-type HAP file (**entry.hap**), it must also be set to **true** for feature-type HAP files (**feature.hap**) of the same application. If this tag is set to **false** for an entry-type HAP file, it can be set to **true** or **false** for feature-type modules of the same application based on service requirements.| Boolean| No| +| deliveryWithInstall | Whether the HAP file will be installed when the user installs the application. **true**: The HAP file will be installed when the user installs the application. **false**: The HAP file will not be installed when the user installs the application.| Boolean| No| + + +Example of the **distro** attribute structure: + +```json +"distro": { + "moduleName": "ohos_entry", + "moduleType": "entry", + "installationFree": true, + "deliveryWithInstall": true +} +``` + +#### Table 3 Internal structure of the metadata attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| parameters | Metadata of the parameters to be passed for calling the ability. The metadata of each parameter consists of the **description**, **name**, and **type** sub-attributes.| Object array| Yes (initial value: left empty)| +| results | Metadata of the ability return value. The metadata of each return value consists of the **description**, **name**, and **type** sub-attributes.| Object array| Yes (initial value: left empty)| +| customizeData | Custom metadata of the parent component. **parameters** and **results** cannot be configured in **application**.| Object array| Yes (initial value: left empty)| + +#### Table 4 Internal structure of the parameters attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| description | Description of the parameter. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String| Yes (initial value: left empty)| +| name | Name of the parameter passed for calling the ability. The value can contain a maximum of 255 bytes.| String| No| +| type | Type of the parameter passed for calling the ability, for example, **Integer**.| String| No| + +#### Table 5 Internal structure of the results attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| description | Description of the return value. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String| Yes (initial value: left empty)| +| name | Name of the return value. The value can contain a maximum of 255 characters.| String| Yes (initial value: left empty)| +| type | Type of the return value, for example, **Integer**.| String| No| + +#### Table 6 Internal structure of the customizeData attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Key of the data element. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| value | Value of the data element. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| extra | Custom format of the data element. The value is a resource index that identifies the data.| String| Yes (initial value: left empty)| + + +Example of the metadata attribute: + +```json +"metaData": { + "parameters" : [{ + "name" : "a test for metadata parameter", + "type" : "Float", + // "$string:parameters_description" is a file resource index. + "description" : "$string:parameters_description" + }], + "results" : [{ + "name" : "a test for metadata result", + "type" : "Float", + "description" : "$string:results_description" + }], + "customizeData" : [{ + "name" : "a customizeData", + "value" : "string", + "extra" : "$string:customizeData_description" + }] +} +``` + +#### Table 7 Values of the deviceType attribute + +| Device Type| Value| Description| +| -------- | -------- | -------- | +| Tablet| tablet | - | +| Smart TV| tv | - | +| Smart watch| wearable | Watch that provides call features.| +| Head unit| car | - | +| Default device| default | OpenHarmony device that provides full access to system capabilities.| + +#### Table 8 Internal structure of the abilities attribute + +| 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. If this attribute is set to the name of the process running other applications, all these applications can run in the same process, provided they have the same unified user ID and the same signature. The value can contain a maximum of 31 bytes.| String| Yes (initial value: left empty)| +| name | Ability name. The value can be a reverse domain name, in the format of "*Bundle name*.*Class name*", for example, **"com.example.myapplication.MainAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".MainAbility"**.
The ability name must be unique in an application. Note: If you use DevEco Studio to create the project, an ability named **MainAbility** will be created by default, and its configuration will be saved to the **config.json** file. The value of this attribute can be customized if you use other IDEs. The value can contain a maximum of 127 bytes.| String| No| +| description | Description of the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| icon | Index to the ability icon file. Example value: **$media:ability_icon**. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the icon of the ability is also used as the icon of the application. If multiple abilities address this condition, the icon of the first candidate ability is used as the application icon.
Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels.| String| Yes (initial value: left empty)| +| label | Ability name displayed to users. The value can be a name string or a resource index to names in multiple languages. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the label of the ability is also used as the label of the application. If multiple abilities address this condition, the label of the first candidate ability is used as the application label.
Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. The value can be a reference to a string defined in a resource file or a string enclosed in brackets ({}). The value can contain a maximum of 255 characters.| String| Yes (initial value: left empty)| +| uri | Uniform Resource Identifier (URI) of the ability. The value can contain a maximum of 255 bytes.| String| Yes (No for abilities using the Data template)| +| launchType | Launch type of the ability. The value can be **standard** or **singleton**.
**standard**: Multiple **Ability** instances can be created during startup. Most abilities can use this type.
**singleton**: Only a single **Ability** instance can be created across all task stacks during startup. For example, a globally unique incoming call screen uses the singleton launch type. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String| Yes (initial value: **"singleton"**)| +| visible | Whether the ability can be called by other applications.
**true**: The ability can be called by other applications.
**false**: The ability cannot be called by other applications.| Boolean| Yes (initial value: **false**)| +| permissions | Permissions required for abilities of another application to call the current ability. The value is an array of permission names predefined by the system, generally in the reverse domain name notation. It contains a maximum of 255 bytes.| String array| Yes (initial value: left empty)| +|skills | Types of the **want** that can be accepted by the ability.| Object array| Yes (initial value: left empty)| +| deviceCapability | Device capabilities required to run the ability. The value is an array of up to 512 elements, each of which contains a maximum of 64 bytes.| String array| Yes (initial value: left empty)| +| metaData | Metadata.| Object| Yes (initial value: left empty)| +| type | Ability type. The options are as follows:
**page**: FA developed using the Page template to provide the capability of interacting with users.
**service**: PA developed using the Service template to provide the capability of running tasks in the background.
**data**: PA developed using the Data template to provide unified data access for external systems.
**CA**: ability that can be started by other applications as a window.| String| No| +| orientation | Display orientations of the ability. This attribute applies only to the ability using the Page template. The options are as follows:
**unspecified**: indicates that the system automatically determines the display orientation of the ability.
**landscape**: indicates the landscape orientation.
**portrait**: indicates the portrait orientation.
**followRecent**: indicates that the orientation follows the most recent application in the stack.| String| Yes (initial value: **"unspecified"**)| +| backgroundModes | Background service type of the ability. You can assign multiple background service types to a specific ability. This field applies only to the ability using the Service template. The options are as follows:
**dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices.
**audioPlayback**: audio playback service.
**audioRecording**: audio recording service.
**pictureInPicture**: picture in picture (PiP) and small-window video playback services.
**voip**: voice/video call and VoIP services.
**location**: location and navigation services.
**bluetoothInteraction**: Bluetooth scanning, connection, and transmission services.
**wifiInteraction**: WLAN scanning, connection, and transmission services.
**screenFetch**: screen recording and screenshot services.
**multiDeviceConnection**: multi-device interconnection service.| String array| Yes (initial value: left empty)| +| grantPermission | Whether permissions can be granted for any data in the ability.| Boolean| Yes (initial value: left empty)| +| readPermission | Permission required for reading data in the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String| Yes (initial value: left empty)| +| writePermission | Permission required for writing data to the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| configChanges | System configurations that the ability concerns. Upon any changes on the concerned configurations, the **onConfigurationUpdated** callback will be invoked to notify the ability. The options are as follows:
**mcc**: indicates that the mobile country code (MCC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MCC is updated.
**mnc**: indicates that the mobile network code (MNC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MNC is updated.
**locale**: indicates that the locale is changed. Typical scenario: The user selectes a new language for the text display of the device.
**layout**: indicates that the screen layout is changed. Typical scenario: Currently, different display forms are all in the active state.
**fontSize**: indicates that font size is changed. Typical scenario: A new global font size is set.
**orientation**: indicates that the screen orientation is changed. Typical scenario: The user rotates the device.
**density**: indicates that the display density is changed. Typical scenario: The user may specify different display ratios, or different display forms are active at the same time.
**size**: indicates that the size of the display window is changed.
**smallestSize**: indicates that the length of the shorter side of the display window is changed.
**colorMode**: indicates that the color mode is changed.| String array| Yes (initial value: left empty)| +| mission | Task stack of the ability. This attribute applies only to the ability using the Page template. By default, all abilities in an application belong to the same task stack.| String| Yes (initial value: bundle name of the application)| +| targetAbility | Target ability that this ability alias points to. This attribute applies only to the ability using the Page template. If the **targetAbility** attribute is set, only **name**, **icon**, **label**, **visible**, **permissions**, and **skills** take effect in the current ability (ability alias). Other attributes use the values of the **targetAbility** attribute. The target ability must belong to the same application as the alias and must be declared in **config.json** ahead of the alias.| String| Yes (initial value: left empty, indicating that the current ability is not an alias)| +| formsEnabled | Whether the ability can provide widgets. This attribute applies only to the ability using the Page template.
**true**: This ability can provide widgets.
**false**: This ability cannot provide widgets.| Boolean| Yes (initial value: **false**)| +| forms | Information about the widgets used by the ability. This attribute is valid only when **formsEnabled** is set to **true**.| Object array| Yes (initial value: left empty)| +| srcLanguage | Programming language of the ability, which you can specify when creating the project.| String| Yes (initial value: **"js"**)| +| srcPath | JS code path corresponding to the ability. The value can contain maximum of 127 bytes.| String| No| +| uriPermission | Application data that the ability can access. This attribute consists of the **mode** and **path** sub-attributes. This attribute is valid only for the capability of the type provider.| Object| Yes (initial value: left empty)| +| startWindowIcon | Index to the icon file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$media:icon**.| String| Yes (initial value: left empty)| +| startWindowBackground | Index to the background color resource file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$color:red**.| String| Yes (initial value: left empty)| +| removeMissionAfterTerminate | Whether to remove the relevant task from the task list after the ability is destroyed. This attribute applies only to the ability using the Page template. The value **true** means to remove the relevant task from the task list after the ability is destroyed, and **false** means the opposite.| Boolean| Yes (initial value: **false**)| + +#### Table 9 Internal structure of the uriPermission attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| path | Path. The value can contain maximum of 255 bytes.| String| No| +| mode | Matching mode.| String| Yes (initial value: **default**)| + + +Example of the **abilities** attribute structure: + +```json +"abilities": [ + { + "name": ".MainAbility", + "description": "test main ability", + // $media:ic_launcher is a media resource. + "icon": "$media:ic_launcher", + // $string:example is a string resource. + "label": "$string:example", + "launchType": "standard", + "orientation": "unspecified", + "permissions": [], + "visible": true, + "skills": [ + { + "actions": [ + "action.system.home" + ], + "entities": [ + "entity.system.home" + ] + } + ], + "configChanges": [ + "locale", + "layout", + "fontSize", + "orientation" + ], + "type": "page", + "startWindowIcon": "$media:icon", + "startWindowBackground": "$color:red", + "removeMissionAfterTerminate": true + }, + { + "name": ".PlayService", + "description": "example play ability", + "icon": "$media:ic_launcher", + "label": "$string:example", + "launchType": "standard", + "orientation": "unspecified", + "visible": false, + "skills": [ + { + "actions": [ + "action.play.music", + "action.stop.music" + ], + "entities": [ + "entity.audio" + ] + } + ], + "type": "service", + "backgroundModes": [ + "audioPlayback" + ] + }, + { + "name": ".UserADataAbility", + "type": "data", + "uri": "dataability://com.example.world.test.UserADataAbility", + "visible": true + } +] +``` + +#### Table 10 Internal structure of the skills attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| actions | Actions of the **want** that can be accepted by the ability. Generally, the value is an **action** value predefined in the system.| String array| Yes (initial value: left empty)| +| entities | Entities of the **want** that can be accepted by the ability, such as video and home applications.| String array| Yes (initial value: left empty)| +| uris | Data specifications to be added to the want filter. The specification can be of data type only (**mimeType** attribute), URI only, or both.
The URI is specified by separate attributes of each part: <scheme>://<host>:<port>[<path>\|<pathStartWith>\|<pathRegex>].
**scheme** is mandatory when the specification is of the URI type and is optional when the specification is of data type only.| Object array| Yes (initial value: left empty)| + +#### Table 11 Internal structure of the uris attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| scheme | Scheme of the URI.| String| No| +| host | Host value of the URI.| String| Yes (initial value: left empty)| +| port | Port number of the URI.| String| Yes (initial value: left empty)| +| pathStartWith | **pathStartWith** value of the URI.| String| Yes (initial value: left empty)| +| path | **path** value of the URI.| String| Yes (initial value: left empty)| +| pathRegx | **pathRegx** value of the URI.| String| Yes (initial value: left empty)| +| type | **type** value of the URI. The value is a MIME type. Typical values include **"audio/aac"** and **"text/css"**.| String| Yes (initial value: left empty)| + + +Example of the **skills** attribute structure: + +```json +"skills": [ + { + "actions": [ + "action.system.home" + ], + "entities": [ + "entity.system.home" + ], + "uris": [ + { + "scheme": "http", + "host": "www.example.com", + "port": "8080", + "path": "query/student/name", + "type": "text/*" + } + ] + } +] +``` + +#### Table 12 reqPermissions attributes + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the permission to request.| String| No| +| reason | Reason for requesting the permission. Multi-language adaptation is required.| String| No if the permission to request is **user_grant**, yes in other cases (initial value: left empty)
If the permission to request is **user_grant** this attribute is required for the application to be released to the application market, and multi-language adaptation is required. | +| usedScene | Scene under which the permission is used. It consists of the **abilities** and **when** sub-attributes.
- **ability**: ability name. Multiple ability names can be configured.
- **when**: time for using the permission. The options are **inuse** and **always**.| Object| Yes (initial value: left empty)
**when**: initial value (**inuse**) allowed| + +#### Table 13 Internal structure of the usedScene attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| ability | Names of abilities that require the permission.| String array| Yes (initial value: all ability names)| +| when | Time when the permission is used.
**inuse**: The permission is required when the ability is in use.
**always**: The permission is required at all times.| Value| Yes (initial value: left empty)| + +#### Table 14 Internal structure of the js attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the JS component. The default value is **default**.| String| No| +| pages | Route information about all pages in the JavaScript component, including the page path and page name. The value is an array, in which each element represents a page. The first element in the array represents the home page of the JS FA.| String array| No| +| window | Window-related configurations.| Object| Yes (initial value: see Table 15)| +| type | Type of the JS component. The options are as follows:
**normal**: indicates an application instance.
**form**: indicates a widget instance.| String| Yes (initial value: **"normal"**)| +|mode | Development mode of the JS component.| Object| Yes (initial value: left empty)| + +#### Table 15 Internal structure of the window attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| designWidth | Baseline width for page design. The size of an element is scaled by the actual device width.| Number| Yes (initial value: 720px)| +| autoDesignWidth | Whether to automatically calculate the baseline width for page design. If it is set to **true**, the **designWidth** attribute becomes invalid. The baseline width is calculated based on the device width and screen density.| Boolean| Yes (initial value: **false**)| + +#### Table 16 Internal structure of the mode attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| type | Type of the JS component. The value can be **pageAbility** or **form**.| String| Yes (initial value: **pageAbility**)| +| syntax | Syntax type of the JS component. The value can be **"hml"** or **"ets"**.| String| Yes (initial value: **"hml"**)| + + +Example of the **js** attribute structure: + +```json +"js": [ + { + "name": "default", + "pages": [ + "pages/index/index", + "pages/detail/detail" + ], + "window": { + "designWidth": 720, + "autoDesignWidth": false + }, + "type": "form" + } +] +``` + +#### Table 17 Internal structure of the shortcuts attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes.| String| No| +| label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the label. The value is a string with a maximum of 63 bytes.| String| Yes (initial value: left empty)| +| icon | Icon of the shortcut. The value is a resource index to the description.| String| Yes (initial value: left empty)| +| intents | Wants to which the shortcut points. The attribute consists of the **targetClass** and **targetBundle** sub-attributes.| Object array| Yes (initial value: left empty)| + +#### Table 18 Internal structure of the intents attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| targetClass | Target class of the shortcut.| String| Yes (initial value: left empty)| +| targetBundle | Application bundle name for the target ability of the shortcut.| String| Yes (initial value: left empty)| + + +Example of the **shortcuts** attribute structure: + +```json +"shortcuts": [ + { + "shortcutId": "id", + // $string:shortcut is a string resource index. + "label": "$string:shortcut", + "intents": [ + { + "targetBundle": "com.example.world.test", + "targetClass": "com.example.world.test.entry.MainAbility" + } + ] + } +] +``` + +#### Table 19 Internal structure of the forms attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Class name of the widget. The value is a string with a maximum of 127 bytes.| String| No| +| description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| isDefault | Whether the widget is a default one. Each ability has only one default widget.
**true**: The widget is the default one.
**false**: The widget is not the default one.| Boolean| No| +| type | Type of the widget. The options are as follows:
**JS**: indicates a JavaScript-programmed widget.| String| No| +| colorMode | Color mode of the widget. The options are as follows:
**auto**: The widget adopts the auto-adaptive color mode.
**dark**: The widget adopts the dark color mode.
**light**: The widget adopts the light color mode.| String| Yes (initial value: **auto**)| +| supportDimensions | Grid styles supported by the widget. Available values are as follows:
**1 * 2**: indicates a grid with one row and two columns.
**2 * 1**: indicates a grid with two rows and one column.
**2 * 2**: indicates a grid with two rows and two columns.
**2 * 4**: indicates a grid with two rows and four columns.
**4 * 4**: indicates a grid with four rows and four columns.| String array| No| +| defaultDimension | Default grid style of the widget. The value must be from the **supportDimensions** array of the widget.| String| No| +| updateEnabled | Whether the widget can be updated periodically. Available values are as follows:
**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.
**false**: The widget cannot be updated periodically.| Boolean| No| +| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute.| String| Yes (initial value: **"0:0"**)| +| updateDuration | Interval to update the widget. The value is a natural number, in the unit of 30 minutes.
If the value is **0**, this attribute does not take effect.
If the value is a positive integer *N*, the interval is calculated by multiplying *N* and 30 minutes.| Number| Yes (initial value: **0**)| +| formConfigAbility | Name of the ability used to adjust the widget.| String| Yes (initial value: left empty)| +| jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes. This attribute is required only by JavaScript-programmed widgets.| String| No| +| metaData | Metadata of the widget. This attribute contains the array of the **customizeData** attribute.| Object| Yes (initial value: left empty)| +| customizeData | Custom information of the widget.| Object array| Yes (initial value: left empty)| + +#### Table 20 Internal structure of the customizeData attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Key name that identifies a data item. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| value | Value of the data item. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| extra | Format of the current custom data. The value is the resource value of **extra**.| String| Yes (initial value: left empty)| + + +Example of the **forms** attribute structure: + +```json +"forms": [ + { + "name": "Form_Js", + "description": "It's Js Form", + "type": "JS", + "jsComponentName": "card", + "colorMode": "auto", + "isDefault": true, + "updateEnabled": true, + "scheduledUpdateTime": "11:00", + "updateDuration": 1, + "defaultDimension": "2*2", + "supportDimensions": [ + "2*2", + "2*4", + "4*4" + ] + }, + { + "name": "Form_Js", + "description": "It's JS Form", + "type": "Js", + "colorMode": "auto", + "isDefault": false, + "updateEnabled": true, + "scheduledUpdateTime": "21:05", + "updateDuration": 1, + "defaultDimension": "1*2", + "supportDimensions": [ + "1*2" + ], + "landscapeLayouts": [ + "$layout:ability_form" + ], + "portraitLayouts": [ + "$layout:ability_form" + ], + "formConfigAbility": "ability://com.example.myapplication.fa/.MainAbility", + "metaData": { + "customizeData": [ + { + "name": "originWidgetName", + "value": "com.example.weather.testWidget" + } + ] + } + } +] +``` + +#### Table 21 Internal structure of the distroFilter attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| apiVersion | Supported API versions.| Object array| Yes (initial value: left empty)| +|screenShape | Supported screen shapes.| Object array| Yes (initial value: left empty)| +| screenWindow | Supported window resolutions for when the application is running. This attribute applies only to the lite wearables.| Object array| Yes (initial value: left empty)| +|screenDensity | Pixel density of the screen, in dots per inch (DPI).| Object array| Yes (initial value: left empty)| +| countryCode | Country code used for distributing the application. For details, see the ISO-3166-1 standard. Multiple enumerated values of countries and regions are supported.| Object array| Yes (initial value: left empty)| + +#### Table 22 Internal structure of the apiVersion attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | API versions, for example, 4, 5, or 6. Example: If an application comes with two versions developed using API version 5 and API version 6 for the same device model, two installation packages of the entry type can be released for the application.| Array| No| + +#### Table 23 Internal structure of the screenShape attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Screen shapes. The value can be **circle**, **rect**, or both. Example: Different HAP files can be provided for a smart watch with a circular face and that with a rectangular face. | Array| No| + +#### Table 24 Internal structure of the screenWindow attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Screen width and height, in pixels. The value an array of supported width and height pairs, each in the "width * height" format, for example, **"454 * 454"**. | Array| No| + +#### Table 25 Internal structure of the screenDensity attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Pixel density of the screen, in dots per inch (DPI). The options are as follows:
**sdpi**: small-scale DPI. This value is applicable to devices with a DPI range of (0, 120].
**mdpi**: medium-scale DPI. This value is applicable to devices with a DPI range of (120, 160].
**ldpi**: large-scale DPI. This value is applicable to devices with a DPI range of (160, 240].
**xldpi**: extra-large-scale DPI. This value is applicable to devices with a DPI range of (240, 320].
**xxldpi**: extra-extra-large-scale DPI. This value is applicable to devices with a DPI range of (320, 480].
**xxxldpi**: extra-extra-extra-large-scale DPI. This value is applicable to devices with a DPI range of (480, 640].| Array| No| + +#### Table 26 Internal structure of the countryCode attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| policy | Rule for the sub-attribute value. Set this attribute to **exclude** or **include**.
- **exclude**: Exclude the matches of the sub-attribute value.
- **include**: Include the matches of the sub-attribute value.| String| No| +| value | Country code of the area to which the application is to be distributed. The value is a string array, of which each substring indicates a country or region. The substring consists of two uppercase letters.| String array| No| + + +Example of the **distroFilter** attribute structure: + +```json +"distroFilter": { + "apiVersion": { + "policy": "include", + "value": [4,5] + }, + "screenShape": { + "policy": "include", + "value": ["circle","rect"] + }, + "screenWindow": { + "policy": "include", + "value": ["454*454","466*466"] + }, + "screenDensity":{ + "policy": "exclude", + "value": ["ldpi","xldpi"] + }, + "countryCode": { + "policy":"include", + "value":["CN","HK"] + } +} +``` + +#### Table 27 Internal structure of the commonEvents attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the static common event. The value can contain a maximum of 127 bytes.| String| No| +| permission | Permission required to implement static common events. The value can contain a maximum of 255 bytes.| String| Yes (initial value: left empty)| +| data | Additional data array to be carried by the current static common event.| String array| Yes (initial value: left empty)| +| type | Type array of the current static common event.| String array| Yes (initial value: left empty)| +| events | A set of events for the wants that can be received. The value can be system predefined or custom.| String array| No| + + +Example of the **commonEvents** attribute structure: + +```json +"commonEvents": [ + { + "name": ".MainAbility", + "permission": "ohos.permission.GET_BUNDLE_INFO", + "data": [ + "com.example.demo", + "100" + ], + "events": [ + "install", + "update" + ] + } +] +``` + +#### Table 28 Internal structure of the testRunner attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of the test runner object. The value can contain a maximum of 255 bytes.| String| No| +| srcPath | Code path of the test runner. The maximum length of this tag is 255 bytes.| String| No| + +```json +"testRunner": { + "name": "myTestRunnerName", + "srcPath": "etc/test/TestRunner.ts" +} +``` + + +**definePermission** applies only to system applications and does not take effect for third-party applications. + +#### Table 29 Internal structure of the definePermissions attribute + +| Name| Description| Data Type| Initial Value Allowed| +| -------- | -------- | -------- | -------- | +| name | Name of a permission. The value can contain a maximum of 255 bytes.| String| No| +| grantMode | Permission grant mode. The options are as follows:
- **system_grant**: The permission is automatically granted by the system after the application is installed.
- **user_grant**: The permission is dynamically requested when needed and must be granted by the user.| String| Yes (initial value: **"system_grant"**)| +| availableLevel | Permission type. The options are as follows:
- **system_core**: system core permission.
- **system_basic**: basic system permission.
- **normal**: normal permission, which can be requsted by all applications.| String| Yes (initial value: **"normal"**)| +| provisionEnable | Whether the permission can be requested in provision mode, including high-level permissions. The value **true** means that the permission can be requested in provision mode.| Boolean| Yes (initial value: **true**)| +| distributedSceneEnabled | Whether the permission can be used in distributed scenarios.| Boolean| Yes (initial value: **false**)| +| label | Brief description of the permission. The value is a resource index to the description.| String| Yes (initial value: left empty)| +| description | Detailed description of the permission. The value is a string with a maximum of 255 bytes or a string resource index.| String| Yes (initial value: left empty)| diff --git a/en/application-dev/quick-start/multi-hap-build-view.md b/en/application-dev/quick-start/multi-hap-build-view.md new file mode 100644 index 0000000000000000000000000000000000000000..3266828fdbda2b969668410a98ce4b64cce54411 --- /dev/null +++ b/en/application-dev/quick-start/multi-hap-build-view.md @@ -0,0 +1,28 @@ +# 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. diff --git a/en/application-dev/quick-start/multi-hap-objective.md b/en/application-dev/quick-start/multi-hap-objective.md new file mode 100644 index 0000000000000000000000000000000000000000..ad43c84fd7799be1e3277400c6c5dfb1926d5b7c --- /dev/null +++ b/en/application-dev/quick-start/multi-hap-objective.md @@ -0,0 +1,10 @@ +# 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. diff --git a/en/application-dev/quick-start/multi-hap-principles.md b/en/application-dev/quick-start/multi-hap-principles.md new file mode 100644 index 0000000000000000000000000000000000000000..9268c0ddafacf26962d8a3d46d9f2adf98e6aac4 --- /dev/null +++ b/en/application-dev/quick-start/multi-hap-principles.md @@ -0,0 +1,21 @@ +# 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. diff --git a/en/application-dev/quick-start/multi-hap-release-deployment.md b/en/application-dev/quick-start/multi-hap-release-deployment.md new file mode 100644 index 0000000000000000000000000000000000000000..785f476bf2fa508470d433477f4e1139e76589fd --- /dev/null +++ b/en/application-dev/quick-start/multi-hap-release-deployment.md @@ -0,0 +1,51 @@ +# 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. diff --git a/en/application-dev/quick-start/multi-hap-rules.md b/en/application-dev/quick-start/multi-hap-rules.md new file mode 100644 index 0000000000000000000000000000000000000000..34b7824cb62b7e1ca73232faa9f58685df2077ac --- /dev/null +++ b/en/application-dev/quick-start/multi-hap-rules.md @@ -0,0 +1,14 @@ +# 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. diff --git a/en/application-dev/quick-start/package-structure.md b/en/application-dev/quick-start/package-structure.md deleted file mode 100644 index 6c1ecfe7be836e8b17dcb7d6d1045354d5aa386d..0000000000000000000000000000000000000000 --- a/en/application-dev/quick-start/package-structure.md +++ /dev/null @@ -1,797 +0,0 @@ - - -# Application Package Structure Configuration File - -When developing an application in the Feature Ability (FA) model, you must declare the package structure of the application in the **config.json** file. - -## Internal Structure of the config.json File - -The **config.json** file consists of three mandatory tags, namely, **app**, **deviceConfig**, and **module**. For details, see Table 1. - -Table 1 Internal structure of the config.json file - -| Tag | Description | Data Type| Initial Value Allowed| -| ------------ | ------------------------------------------------------------ | -------- | ---------- | -| app | Global configuration of the application. Different HAP files of the same application must use the same **app** configuration. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No | -| deviceConfig | Application configuration applied to a specific type of device. For details, see [Internal Structure of the deviceconfig Tag](#internal-structure-of-the-deviceconfig-tag).| Object | No | -| module | Configuration of a HAP file. It is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No | - -Example of the **config.json** file: - -```json -{ - "app": { - "bundleName": "com.example.myapplication", - "vendor": "example", - "version": { - "code": 1, - "name": "1.0" - }, - "apiVersion": { - "compatible": 4, - "target": 5, - "releaseType": "Beta1" - } - }, - "deviceConfig": {}, - "module": { - "package": "com.example.myapplication.entrymodule", - "name": ".MyApplication", - "deviceType": [ - "default" - ], - "distro": { - "moduleName": "entry", - "moduleType": "entry" - }, - "abilities": [ - { - "skills": [ - { - "entities": [ - "entity.system.home" - ], - "actions": [ - "action.system.home" - ] - } - ], - "name": "com.example.myapplication.entrymodule.MainAbility", - "icon": "$media:icon", - "description": "$string:mainability_description", - "label": "$string:app_name", - "type": "page", - "launchType": "standard" - } - ], - "js": [ - { - "pages": [ - "pages/index/index" - ], - "name": "default", - "window": { - "designWidth": 720, - "autoDesignWidth": false - } - } - ] - } -} -``` - -### Internal Structure of the app Tag - -The **app** tag contains the global configuration information of the application. For details about the internal structure, see Table 2. - -Table 2 Internal structure of the app tag - -| Attribute | Description | Data Type| Initial Value Allowed | -| ----------------- | ------------------------------------------------------------ | -------- | --------------------------- | -| bundleName | Bundle name, which uniquely identifies an application. The bundle name can contain only letters, digits, underscores (_), and periods (.). It must start with a letter. The value 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 | Description of the application vendor. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty) | -| version | Version of the application. For details, see Table 3. | Object | No | -| apiVersion | OpenHarmony API version on which the application depends. For details, see Table 4. | Object | Yes (initial value: left empty) | -| singleton | Whether to enable singleton mode for the application. This attribute applies only to system applications and does not take effect for third-party applications. If this attribute is set to **true**, the application always runs in singleton mode, even in multi-user scenarios. This attribute is supported since API version 8.| Boolean | Yes (initial value: **false**)| -| removable | Whether the application can be uninstalled. This attribute applies only to system applications and does not take effect for third-party applications. It is supported since API version 8. | Boolean | Yes (initial value: **true**) | -| userDataClearable | Whether user data of the application can be cleared. This attribute applies only to system applications and does not take effect for third-party applications. It is supported since API version 8.| Boolean | Yes (initial value: **true**) | - -Table 3 Internal structure of version - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------------------ | ------------------------------------------------------------ | -------- | -------------------------- | -| name | Application version number visible to users. The value can be customized and cannot exceed 127 bytes. The customization rules are as follows:
API 5 and earlier versions: A three-segment version number is recommended, for example, A.B.C (also compatible with A.B). In the version number, A, B, and C are integers ranging from 0 to 999. Other formats are not supported.
A indicates the major version number.
B indicates the minor version number.
C indicates the patch version number.
API 6 and later versions: A four-segment version number is recommended, for example, A.B.C.D. In the version number, A, B, and C are integers ranging from 0 to 99, and D is an integer ranging from 0 to 999.
A indicates the major version number.
B indicates the minor version number.
C indicates the feature version number.
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 value rules are as follows:
API 5 and earlier versions: It is a non-negative integer less than 32 bits in binary mode, converted from the value of version.name as follows: The conversion rules are 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 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 ranging from 2 to 31. Note that the value must be updated each time the application version is updated. 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: **code** attribute value)| - -Table 4 Internal structure of apiVersion - -| Attribute | Description | Data Type| Initial Value Allowed| -| ----------- | ----------------------------------------------------------- | -------- | ---------- | -| compatible | Minimum API version required for running the application. The value ranges from 0 to 2147483647. | Integer | Yes | -| target | Target API version required for running the application. The value ranges from 0 to 2147483647.| Integer | Yes | -| releaseType | Type of the target API version required for running the application. | String | Yes | - -Example of the app tag structure: - -```json -"app": { - "bundleName": "com.example.myapplication", - "vendor": "example", - "version": { - "code": 1, - "name": "1.0" - }, - "apiVersion": { - "compatible": 4, - "target": 5, - "releaseType": "Beta1" - } -} -``` - -### Internal Structure of the deviceConfig Tag - -The **deviceConfig** tag contains the application configuration information on the device, 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. For details about the internal structure, see Table 5. - -Table 5 Internal structure of the deviceConfig tag - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ----------------------------------------- | -------- | ------------------ | -| default | Application configuration applied to all types of devices. For details, see Table 6.| Object | No | -| tablet | Application configuration specific to tablets. For details, see Table 6. | Object | Yes (initial value: left empty)| -| tv | Application configuration specific to smart TVs. For details, see Table 6. | Object | Yes (initial value: left empty)| -| car | Application configuration specific to head units. For details, see Table 6. | Object | Yes (initial value: left empty)| -| wearable | Application configuration specific to wearables. For details, see Table 6.| Object | Yes (initial value: left empty)| - -For details about the internal structures of device attributes, see Table 6. - -Table 6 Internal structure of device attributes - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------------ | ------------------------------------------------------------ | -------- | ----------------------- | -| process | 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. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. The value can contain a maximum of 31 characters.| String | Yes | -| keepAlive | Whether the application is always kept alive. This attribute applies only to system applications and does not take effect for third-party applications. The value **true** means that the application is always kept alive: The system automatically launches the application at startup and restarts it after it exits.| 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.
This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| 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.
This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean | Yes (initial value: **true**) | -| directLaunch | Whether the application can be started when the device is locked. The value **true** means that the application can be started when the device is locked. Devices running OpenHarmony do not support this attribute.| Boolean | Yes (initial value: **false**)| -| ark | Maple configuration. For details, see Table 7. | Object | Yes (initial value: left empty) | -| 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. For details, see Table 9.| Object | Yes (initial value: left empty) | - -Table 7 Internal structure of the ark attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ---------- | -------------------------------- | -------- | ------------------------------ | -| reqVersion | Maple version required for the application. For details, see Table 8.| Object | No | -| flag | Type of the Maple application. | String | No (available options: **m**, **mo**, **z**).| - -Table 8 Internal structure of the reqVersion attribute - -| Attribute | Description | Data Type| Initial Value Allowed| -| ---------- | --------------------------------------------------------- | -------- | ---------- | -| compatible | Minimum Maple version required for the application. The value is a 32-bit unsigned integer.| Integer | No | -| target | Type of the Maple application. The value is a 32-bit unsigned integer. | Integer | No | - -Table 9 Internal structure of the network attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ---------------- | ------------------------------------------------------------ | -------- | ----------------------- | -| cleartextTraffic | Whether to allow the application to use plaintext traffic, for example, plaintext HTTP traffic.
**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. For details, see Table 10. | Object | Yes (initial value: left empty) | - -Table 10 Internal structure of the securityConfig attribute - -| Attribute | Sub-attribute | 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)| -| | 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| No | -| | 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| No | - -Example of the deviceConfig tag structure: - -```json -"deviceConfig": { - "default": { - "process": "com.example.test.example", - "supportBackup": false, - "network": { - "cleartextTraffic": true, - "securityConfig": { - "domainSettings": { - "cleartextPermitted": true, - "domains": [ - { - "subdomains": true, - "name": "example.ohos.com" - } - ] - } - } - } - } -} -``` - -### Internal Structure of the module Tag - -The **module** tag contains the configuration information of the HAP file. For details about the internal structure, see Table 11. - -Table 11 Internal structure of the module tag - -| Attribute | Description | Data Type | Initial Value Allowed | -| ----------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | -| mainAbility | Ability displayed on the Service Center icon. When the resident process is started, the **mainAbility** is started.| String | No if any ability using the Page template exists | -| package | Package name of the HAP file, which must be unique in the application. The value is a string with a maximum of 127 bytes, in the reverse domain name notation. It is recommended that the value be the same as the project directory of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | No | -| name | Class name of the HAP file. The value is in the reverse domain name notation, with the prefix same as the package name specified by **package** at the same level. It can also start with a period (.). The value is a string with a maximum of 255 bytes.
This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | No | -| description | Description of the HAP file. The value is a string with a maximum of 255 bytes. If the value exceeds the limit or needs to support multiple languages, you can use a resource index to the description. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) | -| supportedModes | Mode supported by the application. Currently, only the **drive** mode is defined. This attribute applies only to head units.| String array| Yes (initial value: left empty) | -| deviceType | Type of device on which the ability can run. The device types predefined in the system include **tablet**, **tv**, **car**, and **wearable**.| String array| No | -| distro | Distribution description of the HAP file. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 12.| Object | No | -| metaData | Metadata of the HAP file. For details, see Table 13. | Object | Yes (initial value: left empty) | -| abilities | All abilities in the current module. The value is an array of objects, each of which represents a shortcut object. For details, see Table 17.| Object array | Yes (initial value: left empty) | -| js | A set of JS modules developed using ArkUI. Each element in the set represents the information about a JS module. For details, see Table 22.| Object array | Yes (initial value: left empty) | -| shortcuts | Shortcuts of the application. The value is an array of objects, each of which represents a shortcut object. For details, see Table 25.| Object array | Yes (initial value: left empty) | -| reqPermissions | Permissions that the application requests from the system when it is running. For details, see Table 21. | Object array | Yes (initial value: left empty) | -| colorMode | Color mode of the application. Available values are as follows:
**"dark"**: Resources applicable for the dark mode are selected.
**"light"**: Resources applicable for the light mode are selected.
**"auto"**: Resources are selected based on the color mode of the system.
This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | Yes (initial value: **auto**) | -| distroFilter | Distribution rules of the application.
AppGallery uses these rules to distribute HAP files to the matching devices. Distribution rules cover three factors: API version, screen shape, and screen resolution. AppGallery distributes a HAP file to the device whose on the mapping between **deviceType** and these three factors. For details, see Table 29.| Object | Yes (initial value: left empty) Set this attribute when an application has multiple entry modules.| -| reqCapabilities | Device capabilities required for running the application. | String array| Yes (initial value: left empty) | -| commonEvents | Static broadcast. For details, see Table 35. | Object array | Yes (initial value: left empty) | -| entryTheme | Keyword of an OpenHarmony internal theme. Set it to the resource index of the name.| String | Yes (initial value: left empty) | -| testRunner | Test runner configuration. For details, see Table 36. | Object | Yes (initial value: left empty) | -| definePermissions | Permissions defined for the HAP file. This attribute applies only to system applications and does not take effect for third-party applications. The caller of the application must have these permissions to properly call the app. For details, see Table 37.| Object | Yes (initial value: left empty) | - -Example of the **module** tag structure: - -```json -"module": { - "mainAbility": "MainAbility", - "package": "com.example.myapplication.entry", - "name": ".MyOHOSAbilityPackage", - "description": "$string:description_application", - "supportModes": [ - "drive" - ], - "deviceType": [ - "car" - ], - "distro": { - "moduleName": "ohos_entry", - "moduleType": "entry" - }, - "abilities": [ - ... - ], - "shortcuts": [ - ... - ], - "js": [ - ... - ], - "reqPermissions": [ - ... - ], - "colorMode": "light" -} -``` - -Table 12 Internal structure of the distro attribute - -| Attribute | Description | Data Type| Initial Value Allowed| -| ---------------- | ------------------------------------------------------------ | -------- | ---------- | -| moduleName | Name of the HAP file. The maximum length is 31 characters. | String | No | -| moduleType | Type of the HAP file. The value can be **entry** or **feature**. For the HAR type, set this attribute to **har**.| String | No | -| installationFree | Whether the HAP file supports the installation-free feature.
**true**: The HAP file supports the installation-free feature and meets installation-free constraints.
**false**: The HAP file does not support the installation-free feature.
Pay attention to the following:
- When **entry.hap** is set to **true**, all **feature.hap** fields related to **entry.hap **must be **true**.
- When **entry.hap** is set to **false**, **feature.hap** related to **entry.hap** can be set to **true** or **false** based on service requirements. | Boolean | No | -| deliveryWithInstall | Whether the HAP file is installed with application.
**true**: The HAP file is installed together with the application.
**false**: The HAP file is not installed together with the application.| Boolean| No| - -Example of the **distro** attribute structure: - -```json -"distro": { - "moduleName": "ohos_entry", - "moduleType": "entry", - "installationFree": true, - "deliveryWithInstall": true -} -``` - -Table 13 Internal structure of the metaData attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------- | ------------------------------------------------------------ | -------- | -------------------- | -| parameters | Metadata of the parameters to be passed for calling the ability. The metadata of each parameter consists of the **description**, **name**, and **type** sub-attributes. For details, see Table 14.| Object array| Yes (initial value: left empty) | -| results | Metadata of the ability return value. The metadata of each return value consists of the **description**, **name**, and **type** sub-attributes. For details, see Table 15.| Object array| Yes (initial value: left empty)| -| customizeData | Custom metadata of the parent component. **parameters** and **results** cannot be configured in **application**. For details, see Table 16.| Object array| Yes (initial value: left empty)| - -Table 14 Internal structure of the parameters attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ----------- | ------------------------------------------------------------ | -------- | ------------------ | -| description | Description of the parameter passed for calling the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)| -| name | Name of the parameter passed for calling the ability. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)| -| type | Type of the parameter passed for calling the ability, for example, **Integer**. | String | No | - -Table 15 Internal structure of the results attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ----------- | ------------------------------------------------------------ | -------- | -------------------- | -| description | Description of the return value. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty)| -| name | Name of the return value. The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty)| -| type | Type of the return value, for example, **Integer**. | String | No | - -Table 16 Internal structure of the customizeData attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ---------------------------------------------------------- | -------- | -------------------- | -| name | Key of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| -| value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| -| extra | Custom format of the data item. The value is an index to the resource that identifies the data.| String | Yes (initial value: left empty)| - -Example of the **metaData** attribute structure: - -```json -"metaData": { - "parameters" : [{ - "name" : "string", - "type" : "Float", - "description" : "$string:parameters_description" - }], - "results" : [{ - "name" : "string", - "type" : "Float", - "description" : "$string:results_description" - }], - "customizeData" : [{ - "name" : "string", - "value" : "string", - "extra" : "$string:customizeData_description" - }] -} -``` - -Table 17 Internal structure of the abilities attribute - -| Attribute | 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. If this attribute is set to the name of the process running other applications, all these applications can run in the same process, provided they have the same unified user ID and the same signature. Devices running OpenHarmony do not support this attribute.| String | Yes (initial value: left empty) | -| name | Ability name. The value can be a reverse domain name, in the format of "*Bundle name*.*Class name*", for example, **"com.example.myapplication.MainAbility"**. Alternatively, the value can start with a period (.) followed by the class name, for example, **".MainAbility"**.
The ability name must be unique in an application. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.
Note: If you use DevEco Studio to create the project, an ability named **MainAbility** will be created together with the default configuration in the **config.json** file. The value of this attribute can be customized if you use other IDEs. The value can contain a maximum of 127 characters. | String | No | -| description | Description of the ability. The value can be a string or a resource index to descriptions in multiple languages. The value can contain a maximum of 255 characters.| String | Yes (initial value: left empty) | -| icon | Index to the ability icon file. Example value: **$media:ability_icon**. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the icon of the ability is also used as the icon of the application. If multiple abilities address this condition, the icon of the first candidate ability is used as the application icon.
Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. | String | Yes (initial value: left empty) | -| label | Ability name visible to users. The value can be a name string or a resource index to names in multiple languages. In the **skills** attribute of the ability, if the **actions** value contains **action.system.home** and the **entities** value contains **entity.system.home**, the label of the ability is also used as the label of the application. If multiple abilities address this condition, the label of the first candidate ability is used as the application label.
Note: The **icon** and **label** values of an application are visible to users. Ensure that at least one of them is different from any existing icons or labels. The value can be a reference to a string defined in a resource file or a string enclosed in brackets ({}). The value can contain a maximum of 255 characters. | String | Yes (initial value: left empty) | -| uri | Uniform Resource Identifier (URI) of the ability. The value can contain a maximum of 255 characters. | String | Yes (No for abilities using the Data template) | -| launchType | Launch type of the ability. Available values are as follows:
**"standard"**: Multiple **Ability** instances can be created during startup. Most abilities can use this type.
**"singleton"**: Only a single **Ability** instance can be created across all task stacks during startup. For example, a globally unique incoming call screen uses the singleton startup type. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. | String | Yes (initial value: **"singleton"**) | -| visible | Whether the ability can be called by other applications.
**true**: The ability can be called by other applications.
**false**: The ability cannot be called by other applications.| Boolean | Yes (initial value: **false**) | -| permissions | Permissions required for abilities of another application to call the current ability. The value is an array of permission names predefined by the system, generally in the format of a reverse domain name the reverse domain name format (a maximum of 255 bytes).| String array| Yes (initial value: left empty) | -| skills | Types of the **want** that can be accepted by the ability. | Object array | Yes (initial value: left empty) | -| deviceCapability | Device capabilities required to run the ability.| String array| Yes (initial value: left empty) | -| metaData | Metadata. For details, see Table 13. | Object | Yes (initial value: left empty) | -| type | Ability type. Available values are as follows:
**"page"**: FA developed using the Page template to provide the capability of interacting with users.
**"service"**: PA developed using the Service template to provide the capability of running tasks in the background.
**"data"**: PA developed using the Data template to provide unified data access for external systems.
**"CA"**: ability that can be started by other applications as a window. | String | No | -| orientation | Display orientation of the ability. This attribute applies only to the ability using the Page template. Available values are as follows:
**"unspecified"**: indicates that the system automatically determines the display orientation of the ability.
**"landscape"**: indicates the landscape orientation.
**"portrait"**: indicates the portrait orientation.
**"followRecent"**: indicates that the orientation follows the most recent application in the stack. | String | Yes (initial value: **"unspecified"**) | -| backgroundModes | Background service type of the ability. You can assign multiple background service types to a specific ability. This attribute applies only to the ability using the Service template. Available values are as follows:
**dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices
**audioPlayback**: audio playback service
**audioRecording**: audio recording service
**pictureInPicture**: picture in picture (PiP) and small-window video playback services
**voip**: voice/video call and VoIP services
**location**: location and navigation services
**bluetoothInteraction**: Bluetooth scanning, connection, and transmission services
**wifiInteraction**: WLAN scanning, connection, and transmission services
**screenFetch**: screen recording and screenshot services
**multiDeviceConnection**: multi-device interconnection service| String array| Yes (initial value: left empty) | -| grantPermission | Whether permissions can be granted for any data in the ability. | Boolean | Yes (initial value: left empty) | -| readPermission | Permission required for reading data in the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) | -| writePermission | Permission required for writing data to the ability. This attribute applies only to the ability using the Data template. The value is a string with a maximum of 255 bytes. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty) | -| configChanges | System configurations that the ability concerns. Upon any changes on the concerned configurations, the **onConfigurationUpdated** callback will be invoked to notify the ability. Available values are as follows:
**mcc**: indicates that the mobile country code (MCC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MCC is updated.
**mnc**: indicates that the mobile network code (MNC) of the IMSI is changed. Typical scenario: A SIM card is detected, and the MNC is updated.
**locale**: indicates that the locale is changed. Typical scenario: The user has selected a new language for the text display of the device.
**layout**: indicates that the screen layout is changed. Typical scenario: Currently, different display forms are all in the active state.
**fontSize**: indicates that font size is changed. Typical scenario: A new global font size is set.
**orientation**: indicates that the screen orientation is changed. Typical scenario: The user rotates the device.
**density**: indicates that the display density is changed. Typical scenario: The user may specify different display ratios, or different display forms are active at the same time.
**size**: indicates that the size of the display window is changed.
**smallestSize**: indicates that the length of the shorter side of the display window is changed.
**colorMode**: indicates that the color mode is changed.| String array| Yes (initial value: left empty) | -| mission | Task stack of the ability. This attribute applies only to the ability using the Page template. By default, all abilities in an application belong to the same task stack. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: bundle name of the application) | -| targetAbility | Target ability that this ability alias points to. This attribute applies only to the ability using the Page template. If the **targetAbility** attribute is set, only **name**, **icon**, **label**, **visible**, **permissions**, and **skills** take effect in the current ability (ability alias). Other attributes use the values of the **targetAbility** attribute. The target ability must belong to the same application as the alias and must be declared in **config.json** ahead of the alias. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| String | Yes (initial value: left empty, indicating that the current ability is not an alias)| -| multiUserShared | Whether the ability supports data sharing among multiple users. This attribute applies only to the ability using the Data template. If this attribute is set to **true**, only one copy of data is stored for multiple users. Note that this attribute will invalidate the **visible** attribute. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean| Yes (initial value: **false**) | -| supportPipMode | Whether the ability allows the user to enter the Picture in Picture (PiP) mode. The PiP mode enables the user to watch a video in a small window that hovers on top of a full screen window (main window). This attribute applies only to the ability using the Page template. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types.| Boolean| Yes (initial value: **false**) | -| formsEnabled | Whether the ability can provide forms. This attribute applies only to the ability using the Page template.
**true**: This ability can provide forms.
**false**: This ability cannot provide forms.| Boolean| Yes (initial value: **false**) | -| forms | Information about the forms used by the ability. This attribute is valid only when **formsEnabled** is set to **true**. For details, see Table 27.| Object array | Yes (initial value: left empty) | -| srcLanguage | Programming language used to develop the ability. The value can be **"js"** or **"ets"**. | String | Yes | -| srcPath | Path of the JS component code corresponding to the ability. | String | Yes (initial value: left empty) | -| uriPermission | Application data that the ability can access. This attribute consists of the **mode** and **path** sub-attributes. This attribute is valid only for the capability of the type provider. Devices running OpenHarmony do not support this attribute. For details, see Table 18.| Object | Yes (initial value: left empty) | -| startWindowIcon | Index to the icon file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$media:icon**.| String | Yes (initial value: left empty)| -| startWindowBackground | Index to the background color resource file of the ability startup page. This attribute applies only to the ability using the Page template. Example: **$color:red**.| String | Yes (initial value: left empty)| -| removeMissionAfterTerminate | Whether to remove the relevant task from the task list after the ability is destroyed. This attribute applies only to the ability using the Page template. The value **true** means to remove the relevant task from the task list after the ability is destroyed, and **false** means the opposite.| Boolean | Yes (initial value: **false**)| - -Table 18 Internal structure of the uriPermission attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ----------------------- | -------- | ------------------------- | -| path | Path identified by **uriPermission**.| String | No | -| mode | Mode matching the **uriPermission**.| String | Yes (initial value: *default***)| - -Example of the **abilities** attribute structure: - -```json -"abilities": [ - { - "name": ".MainAbility", - "description": "test main ability", - "icon": "$media:ic_launcher", - "label": "$media:example", - "launchType": "standard", - "orientation": "unspecified", - "permissions": [], - "visible": true, - "skills": [ - { - "actions": [ - "action.system.home" - ], - "entities": [ - "entity.system.home" - ] - } - ], - "configChanges": [ - "locale", - "layout", - "fontSize", - "orientation" - ], - "type": "page", - "startWindowIcon": "$media:icon", - "startWindowBackground": "$color:red", - "removeMissionAfterTerminate": true - }, - { - "name": ".PlayService", - "description": "example play ability", - "icon": "$media:ic_launcher", - "label": "$media:example", - "launchType": "standard", - "orientation": "unspecified", - "visible": false, - "skills": [ - { - "actions": [ - "action.play.music", - "action.stop.music" - ], - "entities": [ - "entity.audio" - ] - } - ], - "type": "service", - "backgroundModes": [ - "audioPlayback" - ] - }, - { - "name": ".UserADataAbility", - "type": "data", - "uri": "dataability://com.example.world.test.UserADataAbility", - "visible": true - } -] -``` - -Table 19 Internal structure of the skills attribute - -| Attribute| Description | Data Type | Initial Value Allowed | -| -------- | ------------------------------------------------------------ | ---------- | -------------------- | -| actions | Actions of the **want** that can be accepted by the ability. Generally, the value is an **action** value predefined in the system.| String array| Yes (initial value: left empty)| -| entities | Entities of the **want** that can be accepted by the ability, such as video and home applications.| String array| Yes (initial value: left empty)| -| uris | URIs of the **want** that can be accepted by the ability. For details, see Table 20.| Object array | Yes (initial value: left empty)| - -Table 20 Internal structure of the uris attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------- | -------------------------- | -------- | -------------------- | -| scheme | Scheme of the URI. | String | No | -| host | Host value of the URI. | String | Yes (initial value: left empty)| -| port | Port number of the URI. | String | Yes (initial value: left empty)| -| pathStartWith | **pathStartWith** value of the URI.| String | Yes (initial value: left empty)| -| path | **path** value of the URI. | String | Yes (initial value: left empty)| -| pathRegx | **pathRegx** value of the URI. | String | Yes (initial value: left empty)| -| type | **type** value of the URI. | String | Yes (initial value: left empty)| - -Example of the **skills** attribute structure: - -```json -"skills": [ - { - "actions": [ - "action.system.home" - ], - "entities": [ - "entity.system.home" - ], - "uris": [ - { - "scheme": "http", - "host": "www.example.com", - "port": "8080", - "path": "query/student/name", - "type": "text/*" - } - ] - } -] -``` - -Table 21 reqPermissions - -| Attribute | Description | Data Type| Initial Value Allowed | -| ---------- | ------------------------------------------------------------ | -------- | ------------------ | -| name | Name of the permission to request.| String| No| -| reason | Reason for requesting the permission. The value cannot exceed 256 bytes. Multi-language adaptation is required.| String| No if the requested permission is **user_grant** (if it is left empty, application release will be rejected)| -| usedScene | Application scenario and timing for using the permission. This attribute consists of the **ability** and **when** sub-attributes. **ability**: ability name. Multiple ability names can be configured. **when**: time for using the permission. The options are **inuse** and **always**.| Object| **ability**: mandatory for the **user_grant** permission and can be left empty in other cases
**when**: initial value allowed (initial value: **inuse**)| -For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md#fa-model). - -Table 22 Internal structure of the js attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | ------------------------ | -| name | Name of the JS component. The default value is **default**. | String | No | -| pages | Route information about all pages in the JS component, including the page path and page name. The value is an array, in which each element represents a page. The first element in the array represents the home page of the JavaScript FA.| Array | No | -| window | Window-related configurations. This attribute applies only to the default, tablet, smart TV, head unit, and wearable device types. For details, see Table 23.| Object | Yes | -| type | Type of the JS component. Available values are as follows:
**"normal"**: indicates that the JavaScript component is an application instance.
**"form"**: indicates that the JavaScript component is a widget instance. | String | Yes (initial value: **"normal"**) | -| mode | Development mode of the JS component. For details, see Table 24. | Object | Yes (initial value: left empty) | - -Table 23 Internal structure of the window attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| --------------- | ------------------------------------------------------------ | -------- | ----------------------- | -| designWidth | Baseline width for page design. The size of an element is scaled by the actual device width.| Number | Yes (initial value: 720px) | -| autoDesignWidth | Whether to automatically calculate the baseline width for page design. If it is set to **true**, the **designWidth** attribute becomes invalid. The baseline width is calculated based on the device width and screen density.| Boolean | Yes (initial value: **false**)| - -Table 24 Internal structure of the mode attribute - -| Attribute| Description | Data Type | Initial Value Allowed | -| -------- | -------------------- | ----------------------------------- | --------------------------- | -| type | Type of the JS component. The value can be **"pageAbility"** or **"form"**. | String | Yes (initial value: **"pageAbility"**) | -| syntax | Syntax type of the JS component. The value can be **"hml"** or **"ets"**. | String | Yes (initial value: **"hml"**) | - -Example of the **js** attribute structure: - -```json -"js": [ - { - "name": "default", - "pages": [ - "pages/index/index", - "pages/detail/detail" - ], - "window": { - "designWidth": 720, - "autoDesignWidth": false - }, - "type": "form" - } -] -``` - -Table 25 Internal structure of the shortcuts attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ---------- | ------------------------------------------------------------ | -------- | ------------------ | -| shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes. | String | No | -| label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty)| -| icon | Icon of the shortcut. The value is a resource index to the description. | String | Yes (initial value: left empty)| -| intents | Intents to which the shortcut points. The attribute consists of the **targetClass** and **targetBundle** sub-attributes. For details, see Table 26.| Object array| Yes (initial value: left empty)| - -Table 26 Internal structure of the intents attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------ | --------------------------------------- | -------- | -------------------- | -| targetClass | Target class of the shortcut. | String | Yes (initial value: left empty)| -| targetBundle | Application bundle name for the target ability of the shortcut.| String | Yes (initial value: left empty)| - -Example of the **shortcuts** attribute structure: - -```json -"shortcuts": [ - { - "shortcutId": "id", - "label": "$string:shortcut", - "intents": [ - { - "targetBundle": "com.example.world.test", - "targetClass": "com.example.world.test.entry.MainAbility" - } - ] - } -] -``` - -Table 27 Internal structure of the forms attribute - -| Attribute | Description | Data Type | Initial Value Allowed | -| ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | -| name | Class name of the widget. The value is a string with a maximum of 127 bytes. | String | No | -| description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) | -| isDefault | Whether the widget is a default one. Each ability has only one default widget.
**true**: The widget is the default one.
**false**: The widget is not the default one.| Boolean | No | -| type | Type of the widget. Available values are as follows:
**JS**: indicates a JavaScript-programmed widget. | String | No | -| colorMode | Color mode of the widget. Available values are as follows:
**auto**: The widget adopts the auto-adaptive color mode.
**dark**: The widget adopts the dark color mode.
**light**: The widget adopts the light color mode.| String | Yes (initial value: **auto**)| -| supportDimensions | Grid styles supported by the widget. Available values are as follows:
1 * 2: indicates a grid with one row and two columns.
2 * 1: indicates a grid with two rows and one column.
2 * 2: indicates a grid with two rows and two columns.
2 * 4: indicates a grid with two rows and four columns.
4 * 4: indicates a grid with four rows and four columns.| String array| No | -| defaultDimension | Default grid style of the widget. The value must be from the **supportDimensions** array of the widget.| String | No | -| updateEnabled | Whether the widget can be updated periodically. Available values are as follows:
**true**: The widget can be updated periodically, depending on the update way you select, either at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** is preferentially recommended.
**false**: The widget cannot be updated periodically.| Boolean | No | -| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute. | String | Yes (initial value: **0:0**) | -| updateDuration | Interval to update the widget. The value is a natural number, in the unit of 30 minutes.
If the value is **0**, this field does not take effect.
If the value is a positive integer ***N***, the interval is calculated by multiplying ***N*** and 30 minutes.| Number | Yes (initial value: **0**) | -| formConfigAbility | Name of the facility or activity used to adjust the ability. | String | Yes (initial value: left empty) | -| formVisibleNotify | Whether the widget is allowed to use the widget visibility notification. | String | Yes (initial value: left empty) | -| jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes. This attribute is required only by JavaScript-programmed widgets.| String | No | -| metaData | Metadata of the widget. The value contains value of the **customizeData** attribute. For details, see Table 13. | Object | Yes (initial value: left empty) | -| customizeData | Custom information of the widget. For details, see Table 28. | Object array | Yes (initial value: left empty) | - -Table 28 Internal structure of the customizeData attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | --------------------------------------------------- | -------- | -------------------- | -| name | Key name that identifies a data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| -| value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| -| extra | Current format of the custom data. The value indicates the resource.| String | Yes (initial value: left empty)| - -Example of the **forms** attribute structure: - -```json -"forms": [ - { - "name": "Form_Js", - "description": "It's Js Form", - "type": "JS", - "jsComponentName": "card", - "colorMode": "auto", - "isDefault": true, - "updateEnabled": true, - "scheduledUpdateTime": "11:00", - "updateDuration": 1, - "defaultDimension": "2*2", - "supportDimensions": [ - "2*2", - "2*4", - "4*4" - ] - }, - { - "name": "Form_Js", - "description": "It's JS Form", - "type": "Js", - "colorMode": "auto", - "isDefault": false, - "updateEnabled": true, - "scheduledUpdateTime": "21:05", - "updateDuration": 1, - "defaultDimension": "1*2", - "supportDimensions": [ - "1*2" - ], - "landscapeLayouts": [ - "$layout:ability_form" - ], - "portraitLayouts": [ - "$layout:ability_form" - ], - "formConfigAbility": "ability://com.example.myapplication.fa/.MainAbility", - "metaData": { - "customizeData": [ - { - "name": "originWidgetName", - "value": "com.example.weather.testWidget" - } - ] - } - } -] -``` - -Table 29 Internal structure of the distroFilter attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------- | ------------------------------------------------------------ | -------- | -------------------- | -| apiVersion | Supported API versions. For details, see Table 30. | Object | Yes (initial value: left empty)| -| screenShape | Supported screen shapes. For details, see Table 31. | Object array| Yes (initial value: left empty)| -| screenWindow | Supported window resolutions for when the application is running. This attribute applies only to the lite wearables. For details, see Table 32.| Object array| Yes (initial value: left empty)| -| screenDensity | Pixel density of the screen, in dots per inch (dpi). For details, see Table 33. | Object array| Yes (initial value: left empty)| -| countryCode | Country code used for distributing the application. For details, see the ISO-3166-1 standard. Multiple enumerated values of countries and regions are supported. For details, see Table 34.| Object array| Yes (initial value: left empty)| - -Table 30 Internal structure of the apiVersion attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | An integer of the existing API version, for example, 4, 5, or 6. Example: If an application uses two software versions developed using API 5 and API 6 for the same device model, two installation packages of the entry type can be released.| Array | Yes (initial value: left empty)| - -Table 31 Internal structure of the screenShape attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | The value can be **circle** or **rect**. Example: Different HAPs can be provided for a smart watch with a circular face and that with a rectangular face.| Array | Yes (initial value: left empty)| - -Table 32 Internal structure of the screenWindow attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | Width and height of the screen. The value of a single string is in the format of Width x Height in pixels, for example, **454*454**.| Array | Yes (initial value: left empty)| - -Table 33 Internal structure of the screenDensity attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | Available values are as follows:
**sdpi**: screen density with small-scale dots per inch (SDPI). This value is applicable for devices with a DPI range of (0, 120].
**mdpi**: screen density with medium-scale dots per inch (MDPI). This value is applicable for devices with a DPI range of (120, 160].
**ldpi**: screen density with large-scale dots per inch (LDPI). This value is applicable for devices with a DPI range of (160, 240].
**xldpi**: screen density with extra-large-scale dots per inch (XLDPI). This value is applicable for devices with a DPI range of (240, 320].
**xxldpi**: screen density with extra-extra-large-scale dots per inch (XXLDPI). This value is applicable for devices with a DPI range of (320, 480].
**xxxldpi**: screen density with extra-extra-extra-large-scale dots per inch (XXXLDPI). This value is applicable for devices with a DPI range of (480, 640].| Array | Yes (initial value: left empty)| - -Table 34 Internal structure of the countryCode attribute - -| Attribute| Description | Data Type | Initial Value Allowed | -| -------- | ------------------------------------------------------------ | ---------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | Country code of the area to which the application is to be distributed. The value is a string array, of which each substring indicates a country or region. The substring consists of two uppercase letters.| String array| Yes (initial value: left empty)| - -Example of the **distroFilter** attribute structure: - -```json -"distroFilter": { - "apiVersion": { - "policy": "include", - "value": [4,5] - }, - "screenShape": { - "policy": "include", - "value": ["circle","rect"] - }, - "screenWindow": { - "policy": "include", - "value": ["454*454","466*466"] - }, - "screenDensity":{ - "policy": "exclude", - "value": ["ldpi","xldpi"] - }, - "countryCode": { - "policy":"include", - "value":["CN","HK"] - } -} -``` - -Table 35 Internal structure of the commonEvents attribute - -| Attribute | Description | Data Type | Initial Value Allowed | -| ---------- | ------------------------------------------------------------ | ---------- | ------------------ | -| name | Name of a static broadcast. | String | No | -| permission | Permission needed to implement the static common event. | String array| Yes (initial value: left empty)| -| data | Additional data array to be carried by the current static common event. | String array| Yes (initial value: left empty)| -| type | Type array of the current static common event. | String array| Yes (initial value: left empty)| -| events | A set of events for the wants that can be received. The value can be system predefined or custom.| String array| No | - -Example of the **commonEvents** attribute structure: - -```json -"commonEvents": [ - { - "name":"MainAbility", - "permission": "string", - "data":[ - "string", - "string" - ], - "events": [ - "string", - "string" - ] - } -] -``` - -Table 36 Internal structure of the testRunner attribute - -| Attribute| Description | Data Type| Initial Value Allowed| -| -------- | -------------------- | -------- | ---------- | -| name | Name of the test runner object.| String | No | -| srcPath | Path of the test runner code.| String | No | - -```json -"testRunner": { - "name": "myTestRUnnerName", - "srcPath": "etc/test/TestRunner.ts" -} -``` - -Table 37 Internal structure of the definePermissions attribute -**definePermission** applies only to system applications and does not take effect for third-party applications. - -| Attribute | Description | Data Type| Initial Value Allowed| -| ----------------------- | ------------------------------------------------------------ | -------- | ---------- | -| name | Permission name. | String | No | -| grantMode | Permission grant mode.
Available values are as follows:
**"system_grant"**: The permission is automatically granted by the system after the application is installed.
**"user_grant"**: The permission must be dynamically requested and can be used only after being granted by the user. | String | Yes (initial value: **"system_grant"**) | -| availableLevel | Permission level. Available values are as follows:
**"system_core"**: core system permission.
**"system_basic"**: basic system permission.
**"normal"**: normal permission, which is open to all applications. | String | Yes (initial value: **"normal"**) | -| provisionEnable | Whether the permission can be requested in provision mode. | Boolean | Yes (initial value: **true**) | -| distributedSceneEnabled | Whether the permission can be used in distributed scenarios. | Boolean | Yes (initial value: **false**) | -| label | Brief description of the permission. The value is a resource index. | String | Yes | -| description | Detailed description of the permission, which can be a string or a resource index.| String | Yes | diff --git a/en/application-dev/quick-start/resource-categories-and-access.md b/en/application-dev/quick-start/resource-categories-and-access.md index f19fb2936779dd1989a0b7cf080885050d94cf12..56e8209a5c19e353a21b80ff8b34dd51885db310 100644 --- a/en/application-dev/quick-start/resource-categories-and-access.md +++ b/en/application-dev/quick-start/resource-categories-and-access.md @@ -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:
- **boolean**: boolean data
- **color**: color data
- **float**: floating-point data
- **intarray**: array of integers
- **integer**: integer data
- **pattern**: pattern data
- **plural**: plural form data
- **strarray**: array of strings
- **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:
- boolean.json
- color.json
- float.json
- intarray.json
- integer.json
- pattern.json
- plural.json
- strarray.json
- 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**. | -| 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. | **Media Resource Types** @@ -231,27 +231,27 @@ 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. -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 Text($r('app.string.string_hello')) - .fontColor($r('app.color.color_hello')) - .fontSize($r('app.float.font_hello')) -} + .fontColor($r('app.color.color_hello')) + .fontSize($r('app.float.font_hello')) Text($r('app.string.string_world')) - .fontColor($r('app.color.color_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. - .fontColor($r('app.color.color_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. - .fontColor($r('app.color.color_world')) - .fontSize($r('app.float.font_world')) + .fontColor($r('app.color.color_world')) + .fontSize($r('app.float.font_world')) + +// 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')) + .fontSize($r('app.float.font_hello')) + +// 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')) + .fontSize($r('app.float.font_world')) } Image($r('app.media.my_background_image')) // Reference media resources. @@ -275,13 +275,20 @@ To reference a system resource, use the **"$r('sys.type.resource_id')"** format. ```ts Text('Hello') - .fontColor($r('sys.color.ohos_id_color_emphasize')) - .fontSize($r('sys.float.ohos_id_text_size_headline1')) - .fontFamily($r('sys.string.ohos_id_text_font_family_medium')) - .backgroundColor($r('sys.color.ohos_id_color_palette_aux1')) + .fontColor($r('sys.color.ohos_id_color_emphasize')) + .fontSize($r('sys.float.ohos_id_text_size_headline1')) + .fontFamily($r('sys.string.ohos_id_text_font_family_medium')) + .backgroundColor($r('sys.color.ohos_id_color_palette_aux1')) + 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}) - .margin({top: $r('sys.float.ohos_id_elements_margin_horizontal_m'), bottom: $r('sys.float.ohos_id_elements_margin_horizontal_l')}) - .height(200) - .width(300) + .border({ + 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) + .width(300) ``` diff --git a/en/application-dev/quick-start/stage-structure.md b/en/application-dev/quick-start/stage-structure.md deleted file mode 100644 index 03845296847a43338cca31673b76e46b8c496bbf..0000000000000000000000000000000000000000 --- a/en/application-dev/quick-start/stage-structure.md +++ /dev/null @@ -1,843 +0,0 @@ - - -# Application Package Structure Configuration File - -When developing an application in the Feature Ability (FA) model, you need to declare the package structure of the application in the **config.json** file. Similarly, when developing an application in the stage model, you need to declare the package structure of the application in the **module.json5** and **app.json** files. - -## Configuration File Internal Structure - -The configuration files each consist of two mandatory tags, namely, **app** and **module**. For details, see Table 1. - -Table 1 Configuration file internal structure - -| Tag| Description | Data Type| Initial Value Allowed| -| -------- | ------------------------------------------------------------ | -------- | ---------- | -| app | Global configuration of the application. For details, see [Internal Structure of the app Tag](#internal-structure-of-the-app-tag).| Object | No | -| module | Configuration of the HAP file. It is valid only for the current HAP file. For details, see [Internal Structure of the module Tag](#internal-structure-of-the-module-tag).| Object | No | - -### Internal Structure of the app Tag - -Code snippet in the **app.json** file: - -```json -{ - "app": { - "bundleName": "com.application.music", - "vendor": "application", - "versionCode": 1, - "versionName": "1.0", - "minCompatibleVersionCode": 1, - "minAPIVersion": 7, - "targetAPIVersion": 8, - "apiReleaseType": "Release", - "debug": false, - "icon": "$media:app_icon", - "label": "$string:app_name", - "description": "$string:description_application", - "distributedNotificationEnabled": true, - "entityType": "game", - "car": { - "apiCompatibleVersion": 8 - } - } -} -``` - -This tag is an application-level attribute that applies to all the HAP files and components in the application. For the internal structure of the tag, see Table 2. - -Table 2 Internal structure of the app tag - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------------------------ | ------------------------------------------------------------ | -------- | ------------------------------------------- | -| bundleName | Bundle name that uniquely identifies the application. The value must comply with the following rules:
(1) Consists of letters, digits, underscores (_), and periods (.).
(2) Starts with a letter.
(3) Contains 7 to 127 bytes.
You are advised to use the reverse domain name notion, for example, *com.example.xxx*, 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.
For an application compiled with the system source code, its bundle name must be in the format of **com.ohos.*xxx***, where **ohos** signifies OpenHarmony. | String | No | -| debug | Whether the application can be debugged. | Boolean | Yes (initial value: **false**) | -| icon | Icon of the application. The value is the index to the resource file. | String | No | -| label | Name of the application. The value is a resource index to descriptions in multiple languages.| String | No | -| description | Description of the application. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) | -| vendor | Application vendor. 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 and 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 | Text description of the version number, which is displayed to users.
The value consists of only digits and dots. The four-segment format *A.B.C.D* is recommended, wherein:
Segment 1: major version number, which ranges from 0 to 99. A major version consists of major new features or large changes.
Segment 2: minor version number, which ranges from 0 to 99. A minor version consists of some new features and large bug fixes.
Segment 3: feature version number, which ranges from 0 to 99. A feature version consists of scheduled new features.
Segment 4: 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.| String | No | -| minCompatibleVersionCode | Earliest version that the application is compatible with. It is used to determine cross-device compatibility. | Number | Yes (initial value: value of **versionCode**)| -| minAPIVersion | Minimum API version required for running the application. | Integer | Yes (initial value: value of **compatibleSdkVersion** in **bundle-profile.json5**)| -| targetAPIVersion | Target API version required for running the application. | Integer | 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.
**Canary**: indicates a restricted release.
**Beta**: indicates a publicly released beta version.
**Release**: indicates a publicly released official version.| String | Yes (initial value: **"Release"**) | -| distributedNotificationEnabled | Whether the distributed notification feature is enabled for the application. | Boolean | Yes (initial value: **true**) | -| entityType | Category of the application, which can be **game**, **media**, **communication**, **news**, **travel**, **utility**, **shopping**, **education**, **kids**, **business**, and **photography**.| String | Yes (initial value: **"unspecified"**) | -| singleton | Whether to enable singleton mode for the application. This attribute applies only to system applications and does not take effect for third-party applications. If this attribute is set to **true**, the application always runs in singleton mode, even in multi-user scenarios. This attribute is supported since API version 8. | Boolean | Yes (initial value: **false**) | -| removable | Whether the application can be uninstalled. This attribute applies only to system applications and does not take effect for third-party applications. It is supported since API version 8.| Boolean | Yes (initial value: **true**) | -| 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 is always kept alive: The system automatically launches the application at startup and restarts it after it exits.| Boolean | Yes (initial value: **false**) | -| userDataClearable | Whether user data of the application can be cleared. This attribute applies only to system applications and does not take effect for third-party applications. It is supported since API version 8.| Boolean | Yes (initial value: **true**) | -| accessible | Whether the installation directory of the application is accessible. This attribute applies only to system applications and does not take effect for third-party applications. The value **true** means that the installation directory can be accessed by third-party applications, and **false** means the opposite.| Boolean | Yes (initial value: **false**) | -| multiProjects | Whether multiple projects are supported.| Boolean| Yes (initial value: **false**)| -| deviceType | Supported device types, such as **tablet**, **tv**, **wearable**, and **car**. The following attributes may be included: **minAPIVersion**, **distributedNotificationEnabled**, **keepAlive**, and **removable**.| Object | Yes (initial value: settings under **"app"**)| - -### Internal Structure of the module Tag - -Code snippet in the **module.json5** file: - -```json -{ - "module": { - "name": "myHapName", - "type": "entry|feature|har", - "srcEntrance" : "./MyAbilityStage.js", - "description" : "$string:description_application", - "mainElement": "MainAbility", - "deviceTypes": [ - "tablet", - "tv", - "wearable", - "car", - "router" - ], - "deliveryWithInstall": true, - "installationFree": false, - "virtualMachine": "ark | default", - "metadata": [ - { - "name": "string", - "value": "string", - "resource": "$profile:config_file1" - }, - { - "name": "string", - "value": "string", - "resource": "$profile:config_file2" - } - ], - "abilities": [ - { - "name": "MainAbility", - "srcEntrance" : "./login/MyMainAbility.ts", - "description": "$string:description_main_ability", - "icon": "$media:icon", - "label": "HiMusic", - "visible": true, - "skills": [ - { - "actions": [ - "action.system.home" - ], - "entities": [ - "entity.system.home" - ], - "uris": [ ] - } - ], - "backgroundModes": [ - "dataTransfer", - "audioPlayback", - "audioRecording", - "location", - "bluetoothInteraction", - "multiDeviceConnection", - "wifiInteraction", - "voip", - "taskKeeping" - ], - "startWindowIcon": "$media:icon", - "startWindowBackground": "$color:red" - }, - { - "name": "sampleAbility", - "srcEntrance" : "./login/sampleAbility.ts", - "description": "$string:description_sample_ability", - "icon": "$media:icon", - "label": "HiMusic", - "visible": true, - "startWindowIcon": "$media:icon", - "startWindowBackground": "$color:red" - } - ], - "requestPermissions": [ - { - "name": "ohos.abilitydemo.permission.PROVIDER", - "reason": "$string:reason", - "usedScene": { - "abilities": [ - "FormAbility" - ], - "when": "inuse" - } - } - ] - } -} -``` - -This tag stores the HAP configuration, which only applies to the current HAP file. - -Table 3 Internal structure of the module tag - -| Attribute | Description | Data Type | Initial Value Allowed | -| -------------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | -| name | Name of the current module. After the module is packed into a HAP file, this attribute indicates the name of the HAP file. The value is a string with a maximum of 31 bytes and must be unique in the entire application.| String | No | -| type | Type of the HAP file. There are three types: **entry**, **feature**, and **har**.| String | No | -| srcEntrance | Path of the entry JS code corresponding to the HAP file. The value is a string with a maximum of 127 bytes.| String | Yes | -| description | Description of the HAP file. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) | -| process | Process of the HAP file. The value is a string with a maximum of 31 bytes. If a process is configured under **hap**, all abilities of the application run in this process. This attribute applies only to system applications.| String | Yes (initial value: value of **bundleName** under the **app** tag) | -| mainElement | Entrance ability name or extension name of the HAP file. Only the ability or extension whose value is **mainElement** can be displayed in the Service Center. This attribute cannot be left at the initial value for an OpenHarmony atomic service.| String | Yes for an OpenHarmony application | -| deviceTypes | Types of the devices on which the HAP file can run. Table 4 lists the device types predefined by the system.
Unlike **syscap**, which is based on the device capability (such as Bluetooth and Wi-Fi), **deviceTypes** is based on the device type.| String array| No (can be left empty) | -| deliveryWithInstall | Whether the current HAP file will be installed when the user installs the application. The value **true** means that the HAP file will be automatically installed when the user installs the application, and **false** means the opposite.| Boolean | No | -| installationFree | Whether the HAP file supports the installation-free feature.
**true**: The HAP file supports the installation-free feature and meets installation-free constraints.
**false**: The HAP file does not support the installation-free feature.

When **entry.hap** is set to **true**, all **feature.hap** fields related to **entry.hap** must be **true**.
When **entry.hap** is set to **false**, **feature.hap** fields related to **entry.hap** can be set to **true** or **false** based on service requirements. | Boolean | No | -| virtualMachine | Type of the target virtual machine (VM) where the current HAP file is running. It is used for cloud distribution, such as the application market and distribution center.
If the target VM type is Ark, the value is **ark**. Otherwise, the value is **default**. This attribute is automatically inserted when the IDE builds the HAP file. When the decompression tool parses the HAP file, if the HAP file does not contain this attribute, the value is set to **default**. | String | Yes (initial value: **default**) | -| uiSyntax(deprecated) | Syntax type of the JS component. This attribute is deprecated since API version 9.
**"hml"**: indicates that the JS component is developed using HML, CSS, or JS.
**"ets"**: indicates that the JS component is developed using the eTS declarative syntax.| String | Yes (initial value: **"hml"**) | -| pages | Profile resource used to list information about each page in the JS component. For details about how to use **pages**, see the **pages** example.| Object | No in the ability scenario | -| metadata | Custom metadata of the HAP file. The configuration is valid only for the current module, ability, or extensionAbility. For details, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Array | Yes (initial value: left empty) | -| abilities | Ability configuration, which is valid only for the current ability. For details, see [Internal Structure of the abilities Attribute](#internal-structure-of-the-abilities-attribute).| Object | Yes (initial value: left empty) | -| extensionAbilities | Extension ability configuration, which is valid only for the current Extension ability. For details, see [Internal structure of the extensionAbility attribute](#internal-structure-of-the-extensionability-attribute).| Object | Yes (initial value: left empty) | -| definePermissions | Permissions defined for the HAP file. This attribute applies only to system applications and does not take effect for third-party applications. The callers must acquire these permissions before calling the application. For details, see [Internal structure of the definePermissions attribute](#internal-structure-of-the-definepermissions-attribute).| Object | Yes (initial value: left empty)| -| requestPermissions | A set of permissions that the application needs to request from the system when the application is running. For details, see [Internal structure of the requestPermissions attribute](#internal-structure-of-the-requestpermissions-attribute). | Object | Yes (initial value: left empty) | -| testRunner | Test runner configuration. For details, see [Internal structure of the testRunner attribute](#internal-structure-of-the-testrunner-attribute).| Object | Yes (initial value: left empty) | - -Table 4 System-defined deviceTypes values - -| Value | Device Type | -| -------- | -------------------------------------------------------- | -| tablet | Tablet, speaker with a screen | -| tv | Smart TV | -| wearable | Smart watch, kids' watch, especially a watch that provides call features| -| car | Head unit | -| router | Router | - -Example of the **deviceTypes** attribute structure: - -```json -{ - "module": { - "name": "myHapName", - "type": "har", - "deviceTypes" : [ - "wearable" - ] - } -} -``` - -Example of the **pages** attribute structure: - -```json -{ - "module": { - "name": "myHapName", - "type": "har", - "deviceTypes" : [ - "wearable" - ], - "pages": "$profile:pages_config" - } -} -``` - -Example of the **pages_config** configuration file: - -```json -{ - "src": [ - "pages/index/index", - "pages/second/second", - "pages/third/third", - "pages/four/four" - ] -} -``` - - - -#### Internal Structure of the metadata Attribute - -The **metadata** attribute provides the configuration about the module, ability, and extensionAbility. The value is of the array type. The configuration is valid only for the current module, ability, or extensionAbility. - -Table 5 Internal structure of the metadata attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------------- | -| name | Name of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty)| -| value | Value of the data item. The value is a string with a maximum of 255 bytes. | String | Yes (initial value: left empty) | -| resource | Custom data format. The value is an index to the resource that identifies the data.| String | Yes (initial value: left empty) | - -Example of the **metadata** attribute structure: - -```json -{ - "module": { - "metadata": [ - { - "name": "string", - "value": "string", - "resource": "$profile:config_file" - }, - { - "name": "string", - "value": "string", - "resource": "$profile:config_file" - } - ] - } -} -``` - -#### Internal Structure of the abilities Attribute - -The **abilities** attribute describes the ability configuration information. The value is of the array type. - -Table 6 Internal structure of the abilities attribute - -| Attribute | Description | Data Type | Initial Value Allowed | -| --------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ | -| name | Logical name of the ability, which must be unique in the entire application. The value is a string with a maximum of 127 bytes.| String | No | -| srcEntrance | JS code path corresponding to the ability. The value is a string with a maximum of 127 bytes.| String | No | -| launchType | Ability startup mode. Available values are as follows:
**"standard"**: indicates common multi-instance.
**"singleton"**: indicates a singleton.
**"specified"**: indicates one or more specified instances, depending on the internal service of the ability. | String | Yes (initial value: **singleton**) | -| description | Ability description. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) | -| icon | Icon of the ability. The value is the index to the resource file. | String | Yes (initial value: left empty)
If **ability** is set to **MainElement**, this attribute is mandatory.| -| permissions | Permissions required for abilities of another application to call the current ability. The value is an array of permission names predefined by the system, generally in the format of a reverse domain name the reverse domain name format (a maximum of 255 bytes).| String array| Yes (initial value: left empty) | -| metadata | Metadata of the ability. For details, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Array | Yes (initial value: left empty) | -| visible | Whether the ability can be invoked by other applications. The value **true** means that the ability can be invoked by other applications, and **false** means the opposite.| Boolean | Yes (initial value: **false**) | -| continuable | Whether the ability can be migrated. The value **true** means that the ability can be migrated, and **false** means the opposite.| Boolean | Yes (initial value: **false**) | -| skills | Feature set of wants that can be received by the ability.
Configuration rule: In an entry package, you can configure multiple abilities with the **skills** attribute (where **action.system.home** and **entity.system.home** are configured) that has the entry capability. The **label** and **icon** in the first ability that has **skills** configured are used as the **label** and **icon** of the entire service/application.
The **skills** attribute with the entry capability can be configured for the feature package of an OpenHarmony application, but not for an OpenHarmony service.
For details, see [Internal Structure of the skills Attribute](#internal-structure-of-the-skills-attribute). | Array | Yes (initial value: left empty) | -| backgroundModes | Continuous task modes of the ability.
Continuous tasks are classified into the following types:
**dataTransfer**: service for downloading, backing up, sharing, or transferring data from the network or peer devices
**audioPlayback**: audio playback service
**audioRecording**: audio recording service
**location**: location and navigation services
**bluetoothInteraction**: Bluetooth scanning, connection, and transmission services (wearables)
**multiDeviceConnection**: multi-device interconnection service
**wifiInteraction**: Wi-Fi scanning, connection, and transmission services (multi-screen cloning)
**voip**: voice/video call and VoIP services
**taskKeeping**: computing service
| String | Yes (initial value: left empty) | -| startWindowIcon | Index to the icon file of the ability startup page. Example: **$media:icon**.| String | No| -| startWindowBackground | Index to the background color resource file of the ability startup page. Example: **$color:red**.| String | No| -| removeMissionAfterTerminate | Whether to remove the relevant task from the task list after the ability is destroyed. The value **true** means to remove the relevant task from the task list after the ability is destroyed, and **false** means the opposite.| Boolean | Yes (initial value: **false**)| -| orientation | Display orientation of the ability when it is started. Available values are as follows:
**"unspecified"**: The device orientation is auto-set by the system.
**"landscape"**: The device is in landscape orientation.
**"portrait"**: The device is in portrait orientation.
**"landscape_inverted"**: The device is in inverted landscape orientation.
**"portrait_inverted"**: The device is in inverted portrait orientation.
**"auto_rotation"**: The device orientation is determined by the sensor.
**auto_rotation_landscape**: The device orientation is determined by the sensor in the horizontal direction, including landscape and reverse landscape.
**auto_rotation_portrait**: The device orientation is determined by the sensor in the vertical direction, including portrait and reverse portrait.
**auto_rotation_restricted**: The device orientation is determined by the sensor when the sensor switch is enabled.
**auto_rotation_landscape_restricted**: The device orientation is determined by the sensor in the horizontal direction, including landscape and reverse landscape, when the sensor switch is enabled.
**auto_rotation_portrait_restricted**: The device orientation is determined by the sensor in the vertical direction, including portrait and reverse portrait, when the sensor switch is enabled.
**locked**: Auto rotate is disabled.| String | Yes (initial value: **"unspecified"**)| -|supportWindowMode|Window display mode of the ability. Available values are as follows:
**fullscreen**: full-screen mode.
**split**: split-screen mode.
**floating**: floating window mode.|Array | Yes (initial value:
["fullscreen", "split", "floating"])| -|priority|Priority of the ability. This attribute applies only to system applications and does not take effect for third-party applications. During implicit query, an ability with a higher the priority is closer to the top of the returned list. The value is an integer ranging from 0 to 10. A larger value indicates a higher priority.|Number| Yes (initial value: **0**)| -|maxWindowRatio|Maximum aspect ratio of the ability.| Number |Yes (initial value: maximum aspect ratio of the platform)| -|minWindowRatio|Minimum aspect ratio of the ability.| Number |Yes (initial value: minimum aspect ratio supported by the platform)| -|maxWindowWidth|Maximum window width of the ability, in vp.| Number |Yes (initial value: maximum window width supported by the platform)| -|minWindowWidth|Minimum window width of the ability, in vp.| Number |Yes (initial value: minimum window width supported by the platform)| -|maxWindowHeight|Maximum window height of the ability, in vp.| Number |Yes (initial value: maximum window height supported by the platform)| -|minWindowHeight|Minimum window height of the ability, in vp.| Number |Yes (initial value: minimum window height supported by the platform)| -| excludeFromMissions | Whether the ability is excluded from the recent tasks list. This attribute applies only to system applications and does not take effect for third-party applications. The value **true** indicates that the task is excluded from the recent tasks list, and **false** indicates that the task is displayed in the recent tasks list.| Boolean | Yes (initial value: **false**)| - -Example of the **abilities** attribute structure: - -```json -{ - "abilities": [{ - "name": "MainAbility", - "srcEntrance": "./ets/login/MyLoginAbility.ts", - "launchType":"standard", - "description": "$string:description_main_ability", - "icon": "$media:icon", - "label": "Login", - "permissions": [], - "metadata": [], - "visible": true, - "continuable": true, - "skills": [{ - "actions": ["action.system.home"], - "entities": ["entity.system.home"], - "uris": [] - }], - "backgroundModes": [ - "dataTransfer", - "audioPlayback", - "audioRecording", - "location", - "bluetoothInteraction", - "multiDeviceConnection", - "wifiInteraction", - "voip", - "taskKeeping" - ], - "startWindowIcon": "$media:icon", - "startWindowBackground": "$color:red", - "removeMissionAfterTerminate": true, - "orientation": " ", - "supportWindowMode": ["fullscreen", "split", "floating"], - "maxWindowRatio": 3.5, - "minWindowRatio": 0.5, - "maxWindowWidth": 2560, - "minWindowWidth": 1400, - "maxWindowHeight": 300, - "minWindowHeight": 200, - "excludeFromMissions": false - }] -} -``` - -#### Internal Structure of the skills Attribute - -This attribute identifies a want feature that can be received by the ability or extension. - -Table 7 Internal structure of the skills attribute - -| Attribute| Description | Data Type | Initial Value Allowed | -| -------- | ------------------------------------------------------------ | ---------- | -------------------- | -| actions | A set of want action values that can be received. The value can be a value predefined by the system or a custom value.| String array| Yes (initial value: left empty)| -| entities | Categories of abilities that can receive the want. The value can be a value predefined by the system or a custom value.| String array| Yes (initial value: left empty)| -| uris | Data specifications to be added to the want filter. The specification can be of data type only (**mimeType** attribute), URI only, or both. For details, see Table 8.| Object array | Yes (initial value: left empty)| - -Table 8 Internal structure of the uris attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------- | -------- | -------------------- | -| scheme | Scheme of the URI.| String | No | -| host | Host value of the URI. | String | Yes (initial value: left empty)| -| port | Port number of the URI. | String | Yes (initial value: left empty)| -| path | **path** value of the URI. | String | Yes (initial value: left empty)| -| type | **type** value of the URI. | String | Yes (initial value: left empty)| - -Example of the **skills** attribute structure: - -```json -{ - "abilities": [ - { - "skills": [ - { - "actions": [ - "action.system.home" - ], - "entities": [ - "entity.system.home" - ], - "uris": [ - { - "scheme":"uri2", - "host":"host2", - "port":"port2", - "pathStartWith":"path2", - "pathRegex":"/query/.*", - "path":"path", - "type": "text/*" - } - ] - } - ] - } - ], - "extensionAbilities": [ - { - "skills": [ - { - "actions": [ - ], - "entities": [ - ], - "uris": [ - { - "scheme":"uri2", - "host":"host2", - "port":"port2", - "pathStartWith":"path2", - "pathRegex":"/query/.*", - "path":"path", - "type": "text/*" - } - ] - } - ] - } - ] -} -``` - -#### Internal Structure of the extensionAbility Attribute - -The **extensionAbility** attribute describes the configuration information of the current Extension ability. - -Table 9 Internal structure of the extensionAbility attribute - -| Attribute | Description | Data Type | Initial Value Allowed | -| ----------- | ------------------------------------------------------------ | ---------- | ----------------------------- | -| name | Logical name of the current Extension ability. The value is a string with a maximum of 127 bytes. The name must be unique in the entire application.| String | No | -| srcEntrance | JS code path corresponding to the Extension ability. The value is a string with a maximum of 127 bytes.| String | No | -| description | Description of the Extension ability. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty) | -| icon | Icon of the Extension ability. The value is the index to the resource file. If **extensionAbility** is set to **MainElement**, this attribute is mandatory.| String | Yes (initial value: left empty) | -| label | Name of the Extension ability displayed to users. The value is a resource index to names in multiple languages.
If **extensionAbility** is set to **MainElement**, this attribute is mandatory and the value must be unique in the application.| String | No | -| type | Type of the Extension ability. The value can be **"form"**, **"workScheduler"**, **"inputMethod"**, **"service"**, **"accessibility"**, **"dataShare"**, **"fileShare"**, **"staticSubscriber"**, **"wallpaper"**, **"backup"**, **"window"**, **"enterpriseAdmin"**, **"thumbnail"**, or **"preview"**.| String | No | -| permissions | A set of permissions that need to be applied for when the capability of another application is invoked. The value is a string array. Each array element is a permission name, which is usually represented by a reverse domain name (a maximum of 255 bytes). The permission can be predefined by the system or customized by the application. For the latter, the value must be the same as the **name** value of a permission defined in the **defPermissions** attribute.| String array| Yes (initial value: left empty) | -| uri | Data URI provided by the ability. The value is an array containing a maximum of 255 characters and is in the format of a reverse domain name. This attribute is mandatory when **type** is set to **extensionAbility** of the dataShare type.| String | Yes (initial value: left empty) | -| skills | Feature set of wants that can be received by the ability.
Configuration rule: In an entry package, you can configure multiple abilities with the **skills** attribute (where **action.system.home** and **entity.system.home** are configured) that has the entry capability. The **label** and **icon** in the first ability that has **skills** configured are used as the **label** and **icon** of the entire service/application.
The **skills** attribute with the entry capability can be configured for the feature package of an OpenHarmony application, but not for an OpenHarmony service.
For details, see [Internal Structure of the skills Attribute](#internal-structure-of-the-skills-attribute). | Array | Yes (initial value: left empty) | -| metadata | Metadata of the Extension ability. For details, see [Internal Structure of the metadata Attribute](#internal-structure-of-the-metadata-attribute).| Object | Yes (initial value: left empty) | -| visible | Whether extensionAbility can be invoked by other applications. The value is of the Boolean type. The value **true** means that it can be invoked by other applications, and the value **false** means the opposite.| Boolean | Yes (initial value: **false**)| - -Example of the **extensionAbility** attribute structure: - -```json -{ - "extensionAbilities": [ - { - "name": "FormName", - "srcEntrance": "./form/MyForm.ts", - "icon": "$media:icon", - "label" : "$string:extension_name", - "description": "$string:form_description", - "type": "form", - "permissions": ["ohos.abilitydemo.permission.PROVIDER"], - "readPermission": "", - "writePermission": "", - "visible": true, - "uri":"scheme://authority/path/query" - "skills": [{ - "actions": [], - "entities": [], - "uris": [] - }], - "metadata": [ - { - "name": "ohos.extability.form", - "resource": "$profile:form_config", - } - ] - } - ] -} - -``` - -#### Internal Structure of the definePermissions Attribute - -The **definePermissions** attribute indicates the permissions defined for the HAP file. - -Table 10 Internal structure of the definePermissions attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ---------------------- | ------------------------------------------------------------ | -------- | ------------------------------ | -| name | Permission name. | String | No | -| grantMode | Permission grant mode. Available values are as follows:
**"system_grant"**: The permission is automatically granted by the system after the application is installed.
**"user_grant"**: The permission must be dynamically requested and can be used only after being granted by the user.| String | Yes (initial value: **"system_grant"**)| -| availableLevel | Permission level. Available values are as follows:
**"system_core"**: core system permission.
**"system_basic"**: basic system permission.
**"normal"**: normal permission, which is open to all applications. | String | Yes (initial value: **"normal"**) | -| provisionEnable | Whether to enable provision mode for requesting permissions, including higher-level permissions. The value **true** indicates that provision mode is enabled.| Boolean | Yes (initial value: **true**) | -| distributedSceneEnable | Whether the permission can be used in distributed scenarios. | Boolean | Yes (initial value: **false**) | -| label | Brief description of the permission. The value is a resource index. | String | Yes (initial value: left empty) | -| description | Detailed description of the permission, which can be a string or a resource index.| String | Yes (initial value: left empty) | - -#### Internal Structure of the requestPermissions Attribute - -This attribute identifies a set of permissions that the application needs to request from the system when the application is running. - -Table 11 Internal structure of the requestPermissions attribute - -| Attribute | Description | Type | Value Range | Default Value | Restrictions | -| --------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------ | -------------------- | ------------------------------------------------------------ | -| name | Permission name. This attribute is mandatory. | String | Custom | N/A | Parsing will fail if this attribute is not set. | -| reason | Reason for requesting the permission. This attribute is mandatory when the permission to request is **user_grant**. | String | Resource reference of the string type in `$string: ***` format | Empty | If the permission to request is **user_grant**, this attribute is required for the application to be released to AppGallery. Multi-language adaptation is required.| -| usedScene | Application scenario and timing for using the permission. This attribute is mandatory when the permission to request is **user_grant**. It consists of the **abilities** and **when** sub-attributes. Multiple abilities can be configured.| **abilities**: string array; **when**: string| **abilities**: array of ability names; **when**: **inuse** and **always**| **abilities**: left empty; **when**: left empty| If the permission to request is **user_grant**, the **abilities** sub-attribute is mandatory and **when** is optional. | - -Example of the **requestPermissions** attribute structure: - -```json -{ - "name": "ohos.abilitydemo.permission.PROVIDER", - "reason": "$string:reason", - "usedScene": { - "abilities": [ - "AudioAbility", - "VideoAbility", - ], - "when": "inuse" - } -} -``` -For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md#fa-model). - -#### Internal Structure of the form Attribute - -The **forms** attribute indicates the service widget configuration. The service widget is an application brief view that can be displayed on the home screen and periodically updated. You can include the **forms** attribute in any of the following modes: - -1. Set **type** to **form** in **extensions**. - -2. Specify the **form** information in **metadata**, where: - - **name** indicates the name of the service widget, for example, **ohos.extability.form**. - - **resource** indicates where the resources of the service widget are stored. - -Table 12 Internal structure of the forms attribute - -| Attribute | Description | Data Type | Initial Value Allowed | -| ------------------- | ------------------------------------------------------------ | ---------- | ----------------------------- | -| name | Class name of the widget. The value is a string with a maximum of 127 bytes. | String | No | -| description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) | -| src | UI code of a JS service widget. It is recommended that you use the adaptive layout to display a service widget of different specifications. If the layout of a service widget of different specifications differs greatly, you are advised to use different service widgets.| String | Yes (initial value: left empty) | -| window | Adaptive capability of a JS service widget. For details, see Table 12. | Object | Yes (initial value: left empty) | -| isDefault | Whether the widget is a default one. Each ability has only one default widget. **true**: The service widget is the default one. **false**: The service widget is not the default one.| Boolean | No | -| colorMode | Color mode of the widget. The value can be **auto**, **dark**, or **light**.| String | Yes (initial value: **auto**) | -| supportDimensions | Dimensions supported by the service widget. The value can be **1 * 2**, **2 * 1**, **2 * 2**, **2 * 4**, or **4 * 4**, where the number before the asterisk (*) indicates the number of rows, and the number after the asterisk (*) indicates the number of columns.| String array| No | -| defaultDimension | Default grid style of the widget. The value must be from the **supportDimensions** array of the widget.| String | No | -| updateEnabled | Whether the widget can be updated periodically. The value **true** indicates that the widget can be updated periodically, and **false** indicates that the widget cannot be updated periodically.| Boolean | No | -| scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute. | String | Yes | -| updateDuration | Update frequency of a widget. The unit is 30 minutes. The value is a multiple of 30. The highest frequency of refreshing a widget is once every 30 minutes. You can also use scheduled refresh to refresh a widget at a fixed time or once every 30 minutes. If both of them are configured, the scheduled refresh takes precedence.| Number | Yes (initial value: left empty) | -| metadata | Metadata of the widget. For details, see Table 5. | Object | Yes (initial value: left empty) | -| formConfigAbility | Ability name for widget adjustment. The value is a string of up to 127 characters. The value must be in the following format:
ability:// Name of an ability.
The name must be the same as that of the current application.| String | Yes (initial value: left empty) | -| formVisibleNotify | Whether the widget is allowed to use the visibility notification. The value is **true** or **false**.| Boolean | Yes (initial value: **false**)| - -Table 13 Internal structure of the window attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| --------------- | ------------------------------------------------------------ | -------- | -------------------- | -| designWidth | Baseline width of the page design, in pixels. The element size is scaled by the actual device width. The value is an integer.| Number | Yes (initial value: left empty)| -| autoDesignWidth | Whether to automatically calculate the baseline width of the page design. If this parameter is set to **true**, the **designWidth** attribute is invalid. The baseline width is calculated based on the device width and screen density.| Boolean | Yes (initial value: left empty)| - -Example of the **forms** attribute structure: - -Define the **form_config.json** file (this file name is customizable) in **resources/base/profile** of the development view. - -```json -{ - "forms": [ - { - "name": "Form_Js", - "description": "$string:form_description", - "src": "./js/pages/card/index", - "window": { - "designWidth": 720, - "autoDesignWidth": true - }, - "colorMode": "auto", - "formConfigAbility": "ability://xxxxx", - "formVisibleNotify": false, - "isDefault": true, - "updateEnabled": true, - "scheduledUpdateTime": "10:30", - "updateDuration": 1, - "defaultDimension": "2*2", - "updateEnabled": true, - "scheduledUpdateTime": "21:33", - "supportDimensions": [ - "2*2" - ], - "metadata": [ - { - "name": "string", - "value": "string", - "resource": "$profile:config_file" - } - ] - } - ] -} -``` - -Define metadata information in the **extension** component of the **module.json5** file. - -```json -{ - "extensionAbilities": [{ - "name": "MyForm", - "type": "form", - "metadata": [{ - "name": "ohos.extability.form", - "resource": "$profile:form_config" - }] - }] -} -``` - -#### Internal Structure of the shortcuts Attribute - -This attribute identifies the shortcut information of an application. The value is an array. A maximum of four shortcuts can be configured. It contains four sub-attributes: **shortcutId**, **label**, **icon**, and **wants**. - -Specify the **shortcut** information in **metadata**, where: - -- **name** indicates the name of the shortcut, for example, **ohos.ability.shortcuts**. - -- **resource** indicates where the resources of the shortcut are stored. - -Table 14 Internal structure of the shortcuts attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ---------- | ------------------------------------------------------------ | -------- | -------------------------- | -| shortcutId | ID of the shortcut. The value is a string with a maximum of 63 bytes. | String | No | -| label | Label of the shortcut, that is, the text description displayed for the shortcut. The value can be a string or a resource index to the description. The value is a string with a maximum of 63 bytes.| String | Yes (initial value: left empty) | -| icon | Icon of the shortcut. The value is the index to the resource file. | String | Yes (initial value: left empty)| -| wants | Wants to which the shortcut points. The attribute consists of the **bundleName** and **abilityName** sub-attributes.
**bundleName**: target bundle name of the shortcut; string type.
**abilityName**: target component name of the shortcut; string type.| Object | Yes (initial value: left empty) | - -Define the **shortcut_config.json** file (this file name is customizable) in **resources/base/profile** of the development view. - -```json -{ - "shortcuts": [{ - "shortcutId": "id_test1", - "label": "$string:shortcut", - "icon": "$media:aa_icon", - "wants": [{ - "bundleName": "com.ohos.hello", - "abilityName": "MainAbility" - }] - }] -} -``` - -Define the **metadata** information under **module** in the **module.json5** file as follows: - -```json -{ - "module": { - "name": "MyAbilityStage", - "abilities": [{ - "name": "MyAbility", - "srcEntrance": "./abilities/MyAbility.ts", - "skills": [{ - "actions": ["action.system.home"], - "entities": ["entity.system.home"], - "uris": [] - }], - "metadata": [{ - "name": "ohos.ability.shortcuts", - "resource": "$profile:shortcuts_config" - }] - }] - } -} -``` - -#### Internal Structure of the commonEvents Attribute - -The **commonEvents** attribute identifies the registered static common event information. The value is an array. - -Specify the **commonEvent** information in the **metadata**, where: - -- **name** indicates the name of the common event, for example, **ohos.extability.staticSubscriber**. - -- **resource** indicates where the resources of the common event are stored. - -Table 15 Internal structure of the commonEvents attribute - -| Attribute | Description | Data Type | Initial Value Allowed | -| ---------- | ------------------------------------------------------------ | ---------- | -------------------------- | -| name | Ability name corresponding to the current static common event. The class must be marked in the ability.| String | No | -| permission | Permission required for implementing the static common event. The value is a string with a maximum of 255 bytes, in the reverse domain name notation.| String | Yes (initial value: left empty) | -| types | Types of the current static common event. The value is an array of strings, each of which represents a type.| String array| Yes (initial value: left empty)| -| events | Events of the intents that can be accepted by the ability. The value can be customized or be the events predefined in the system.| String array| No | - -Define the **common_event_config.json** file in **resources/base/profile** in the development view. (The file name can be defined by developers.) - -```json -{ - "commonEvents": [{ - "name": "abilityName", - "permission": "string", - "types": [ - "string", - "string" - ], - "events": [ - "string", - "string" - ] - }] -} -``` - -Define the **metadata** information under **extension** in the **module.json5** file as follows: - -```json -"extensionAbilities": [ - { - "name": "mySubscriber", - "srcEntrance": "./extension/my_subscriber.js", - "type": "staticSubscriber", - "metadata": [{ - "name": "ohos.extability.staticSubscriber", - "resource": "$profile:common_event_config", - }], - } -] -``` - -#### Internal Structure of the distroFilter Attribute - -Distribution rules of the application. - -This attribute defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when AppGallery distributes applications. Distribution rules cover three factors: API version, screen shape, and screen resolution. During distribution, a unique HAP is determined based on the mapping between **deviceType** and these three factors. - -Table 16 Internal structure of the distroFilter attribute - -| Attribute | Description | Data Type| Initial Value Allowed | -| ------------- | ------------------------------------------------------------ | -------- | -------------------------- | -| apiVersion | Supported API versions. For details, see Table 16. | Object array| Yes (initial value: left empty)| -| screenShape | Supported screen shapes. | Object array| Yes (initial value: left empty)| -| screenWindow | Supported window resolutions for when the application is running. This attribute applies only to the lite wearables.| Object array| Yes (initial value: left empty)| -| screenDensity | Pixel density of the screen, in dots per inch (dpi). This attribute is optional. The value options are as follows:
**sdpi**: small-scale dots per inch. This value is applicable for devices with a DPI range of (0, 120].
**mdpi**: medium-scale dots per inch. This value is applicable for devices with a DPI range of (120, 160].
**ldpi**: large-scale dots per inch. This value is applicable for devices with a DPI in the (160, 240] range.
**xldpi**: extra-large-scale dots per inch. This value is applicable for devices with a DPI in the (240, 320] range.
**xxldpi**: extra-extra-large-scale dots per inch (XXLDPI). This value is applicable for devices with a DPI in the (320, 480] range.
**xxxldpi**: extra-extra-extra-large-scale dots per inch. This value is applicable for devices with a DPI in the (480, 640] range.| Object array| Yes (initial value: left empty)| -| countryCode | Code of the country or region to which the application is to be distributed. For details, see ISO-3166-1. Enumerated definitions of multiple countries and regions are supported. This attribute is optional. The substring of the value consists of two uppercase letters and indicates the supported countries or regions.| Object array| Yes (initial value: left empty)| - -Table 17 Internal structure of the apiVersion attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | An integer of the existing API version, for example, 4, 5, or 6. If an application uses two software versions developed using API 5 and API 6 for the same device model, two installation packages of the entry type can be released.| Array | Yes (initial value: left empty)| - -Table 18 Internal structure of the screenShape attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | The value can be **circle** or **rect**. Example: Different HAP files can be provided for a smart watch with a circular face and a smart watch with a rectangular face.| Array | Yes (initial value: left empty)| - -Table 19 Internal structure of the screenWindow attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | Width and height of the screen. The value is in the "width * height" format, in pixels, for example, **454*454**.| Array | Yes (initial value: left empty)| - -Table 20 Internal structure of the screenDensity attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | Pixel density of the screen, in dots per inch (dpi). | Array | Yes (initial value: left empty)| - -Table 21 Internal structure of the countryCode attribute - -| Attribute| Description | Data Type| Initial Value Allowed | -| -------- | ------------------------------------------------------------ | -------- | -------------------- | -| policy | Blocklist and trustlist rule of the sub-attribute value. Set this attribute to **exclude** or **include**. **include** indicates that the sub-attribute value is in the trustlist. If the value matches any of the **value** enums, it matches this attribute.| String | Yes (initial value: left empty)| -| value | Code of the country or region to which the application is to be distributed. | Array | Yes (initial value: left empty)| - -Example of the **distroFilter** attribute structure: - -Define the **distroFilter_config.json** file in **resources/base/profile** of the development view. (The file name can be defined by developers.) - -```json -"distroFilter": [ - { - "apiVersion": { - "policy": "include", - "value": [4, 5] - }, - "screenShape": { - "policy": "include", - "value": ["circle", "rect"] - }, - "screenWindow": { - "policy": "include", - "value": ["454*454", "466*466"] - } - } -] -``` - -Define the **metadata** information under **extensionAbilities** in the **module.json5** file as follows: - -```json -"extensionAbilities": [ - { - "name": "mySubscriber", - "srcEntrance": "./extension/my_subscriber.js", - "type": "staticSubscriber", - "metadata": [{ - "name": "ohos.extability.staticSubscriber", - "resource": "$profile:distroFilter_config", - }], - } -] -``` - -#### Internal Structure of the testRunner Attribute - -Table 22 Internal structure of the testRunner attribute - -| Attribute| Description | Data Type| Initial Value Allowed| -| -------- | ---------------------- | -------- | ---------- | -| name | Name of the test runner object.| String | No| -| srcPath | Path of the test runner code.| String | No| - -``` -"testRunner": { - "name": "myTestRUnnerName", - "srcPath": "etc/test/TestRunner.ts" -} -``` diff --git a/en/application-dev/quick-start/start-overview.md b/en/application-dev/quick-start/start-overview.md index 5548032d25184e05086648501f67d52b6caf6c65..fd04d4b1e0e2551d2b2885f0314b39204692fc40 100644 --- a/en/application-dev/quick-start/start-overview.md +++ b/en/application-dev/quick-start/start-overview.md @@ -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) -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 @@ -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. -| **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| -| Web-like development paradigm| JavaScript| Data-driven| Applications and service widgets with simple UIs| Frontend web developers| +| **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| +| 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). +### 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). - -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). +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. ## Tool Preparation diff --git a/en/application-dev/quick-start/start-with-ets-fa.md b/en/application-dev/quick-start/start-with-ets-fa.md index f1280c77658fd048619ec34bd5b6736713465ad0..66f2ead3d35e72950a81c5495db14254210c8c2b 100644 --- a/en/application-dev/quick-start/start-with-ets-fa.md +++ b/en/application-dev/quick-start/start-with-ets-fa.md @@ -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 > 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 > 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**. - **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation. @@ -129,7 +129,7 @@ > **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. - - 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 { @@ -223,7 +223,7 @@ You can implement page redirection through the [page router](../reference/apis/j .height('5%') // Bind the onClick event to the Next button so that clicking the button redirects the user to the second page. .onClick(() => { - router.push({ url: 'pages/second' }) + router.pushUrl({ url: 'pages/second' }) }) } .width('100%') diff --git a/en/application-dev/quick-start/start-with-ets-stage.md b/en/application-dev/quick-start/start-with-ets-stage.md index a37eb8d3da42490bfc4027ecadbf401f21982444..3bf9d124a666b0ad057310b21e1bf3b52cdf5505 100644 --- a/en/application-dev/quick-start/start-with-ets-stage.md +++ b/en/application-dev/quick-start/start-with-ets-stage.md @@ -38,7 +38,7 @@ - **src > main > ets > entryability**: entry to 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 > 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**. - **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 .height('5%') // Bind the onClick event to the Next button so that clicking the button redirects the user to the second page. .onClick(() => { - router.push({ url: 'pages/Second' }) + router.pushUrl({ url: 'pages/Second' }) }) } .width('100%') diff --git a/en/application-dev/quick-start/start-with-js-fa.md b/en/application-dev/quick-start/start-with-js-fa.md index e0b43711caa931013ca581c40f588fd6f6cfe070..ad648638defddada7565cc34b2172c67d3050765 100644 --- a/en/application-dev/quick-start/start-with-js-fa.md +++ b/en/application-dev/quick-start/start-with-js-fa.md @@ -39,7 +39,7 @@ - **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 > 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**. - **hvigorfile.ts**: module-level build script. You can customize related tasks and code implementation. diff --git a/en/application-dev/reference/syscap-list.md b/en/application-dev/reference/syscap-list.md index 51ada8f2b45879986ed8aa932336827cb5b546f1..adede69fe1d7cd8c400d056d6588c9faab441513 100644 --- a/en/application-dev/reference/syscap-list.md +++ b/en/application-dev/reference/syscap-list.md @@ -1,8 +1,8 @@ -# 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 diff --git a/en/application-dev/quick-start/syscap.md b/en/application-dev/reference/syscap.md similarity index 84% rename from en/application-dev/quick-start/syscap.md rename to en/application-dev/reference/syscap.md index 07570f1359d7a4ead492ea15e02624f35e4e12c1..295ec50046c660282964f41679bd7a3377ca846b 100644 --- a/en/application-dev/quick-start/syscap.md +++ b/en/application-dev/reference/syscap.md @@ -1,17 +1,15 @@ -# SysCap +# SystemCapability ## Overview ### 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) 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 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 ![image-20220326064913834](figures/image-20220326064913834.png) - - ### Devices and Supported SysCap Sets 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 ![image-20220326064955505](figures/image-20220326064955505.png) - - ### 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) - - ## How to Develop ### 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. - - ### 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. @@ -55,8 +45,6 @@ Right-click the project directory and choose **Import Product Compatibility ID** ![20220329-103626](figures/20220329-103626.gif) - - ### 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. @@ -91,51 +79,44 @@ Exercise caution when modifying the required SysCap set. Incorrect modifications } ``` - - ### 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. ![image-20220326065124911](figures/image-20220326065124911.png) - - ### 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. ![image-20220326065201867](figures/image-20220326065201867.png) - - ### 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")) { - console.log("This application supports SystemCapability.ArkUI.ArkUI.Full."); -} else { - 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. + ``` + if (canIUse("SystemCapability.ArkUI.ArkUI.Full")) { + console.log("This application supports SystemCapability.ArkUI.ArkUI.Full."); + } else { + console.log("This application does not support SystemCapability.ArkUI.ArkUI.Full".); + } + ``` -``` -import geolocation from '@ohos.geolocation'; - -if (geolocation) { - geolocation.getCurrentLocation((location) => { - console.log(location.latitude, location.longitude); - }); -} else { - console.log('This device does not support location information.'); -} -``` +- 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'; + if (geolocation) { + geolocation.getCurrentLocation((location) => { + console.log(location.latitude, location.longitude); + }); + } else { + 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 @@ -159,7 +140,6 @@ authenticator.execute('FACE_ONLY', 'S1', (err, result) => { }) ``` - ### 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.