@@ -19,7 +19,9 @@ This document gives an overview of the **app.json5** configuration file. To star
"debug":false,
"car":{
"minAPIVersion":8,
}
},
"targetBundleName":"com.application.test",
"targetPriority":50
},
}
```
...
...
@@ -28,11 +30,12 @@ This document gives an overview of the **app.json5** configuration file. To star
As shown above, the **app.json5** file contains several tags.
**Table 1** Tags in the app.json5 file
**Table 1** Tags in the app.json5 file
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| bundleName | Bundle name, which uniquely identifies an application. The value must comply with the following rules:<br>- Consists of letters, digits, underscores (_), and periods (.).<br>- Starts with a letter.<br>- Contains 7 to 127 bytes.<br>You are advised to use the reverse domain name notation, for example, *com.example.demo*, where the first part is the domain suffix **com**, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels.<br>If an application is built with the system source code, you are advised to name it in *com.ohos.demo* notation, where **ohos** signifies that the application is an OpenHarmony system application.| String| No|
| bundleType| Bundle type, which is used to distinguish applications and atomic services.<br>- **app**: The bundle is a common application.<br>- **atomicService**: The bundle is an atomic service.<br>- **shared**: The bundle is a shared object application. | String| Yes (initial value: **"app"**)|
| debug | Whether the application can be debugged. This tag is generated during compilation and building in DevEco Studio.<br>- **true**: The application can be debugged.<br>- **false**: The application cannot be debugged.| Boolean| Yes (initial value: **false**)|
| icon | [Icon of the application](../application-models/application-component-configuration-stage.md). The value is an icon resource index.| String| No|
| label | [Name of the application](../application-models/application-component-configuration-stage.md). The value is a string resource index.| String| No|
...
...
@@ -51,3 +54,5 @@ As shown above, the **app.json5** file contains several tags.
| wearable | Wearable-specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on wearables, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
| car | Head unit–specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on head units, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
| default | Default device–specific configuration, which includes **minAPIVersion** and **distributedNotificationEnabled** attributes.<br>When running on default devices, the application applies the attribute settings under this tag and ignores the general counterparts.| Object| Yes (initial value: general settings in the **app.json5** file)|
|targetBundleName|Target application name of the bundle. The value rule and range are the same as those of **bundleName**.|String|Yes (if the initial value is used, the target application is not an application with the overlay feature)|
|targetPriority|Priority of the application. When **targetBundleName** is set, the application is an application with the overlay feature. The value ranges from 1 to 100.|Number|Yes (initial value: **1**)|
@@ -11,7 +11,7 @@ The difference between the application package structures in the FA model and st
- 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** folder stores resource files (such as strings and images) of the application. For details, see [Resource Categories and Access](resource-categories-and-access.md).
- The **resources.index** file provides a resource index table, which is generated by DevEco Studio invoking the specific SDK tool.
@@ -22,7 +22,7 @@ To develop an application based on the [stage model](application-configuration-f
- 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** folder stores resource files (such as strings and images) of the application. For details, see [Resource Categories and Access](resource-categories-and-access.md).
- 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.
To speed up the initial startup of an atomic service, you can configure it to load on demand with the use of HAP files. HAP files of an atomic service are classified as entry-type or feature-type. The entry-type HAP file contains the page code and related resources required for starting up the atomic service. The feature-type HAP files contain the rest of the code and resources. To start the atomic service, the user only needs to download and install the entry-type HAP file, which minimizes the time for downloading the atomic service.
#### How to Use
You create HAP files of an atomic service by creating an atomic service project in DevEco Studio. The basic project directory structure is as follows:
```
├── AppScope
| ├── resources
| └── app.json5
├── entry
| └── src/main
| ├── ets
| ├── resources
| └── module.json5
├── feature
| └── src/main
| ├── ets
| ├── resources
| └── module.json5
├── library
| └── src/main
| ├── ets
| ├── resources
| └── module.json5
├── node_modules
```
Note that you must set the **bundleType** field to **atomicService** in the [app.json5](app-configuration-file.md) file, which is located in the **AppScope** folder. The following is an example of the file content:
```json
{
"app":{
"bundleName":"com.example.hmservice",
"bundleType":"atomicService",
"vendor":"example",
"versionCode":1000000,
"versionName":"1.0.0",
"icon":"$media:app_icon",
"label":"$string:app_name",
"distributedNotificationEnabled":true,
"targetAPIVersion":9
}
}
```
For details about HAP files, see [Multi-HAP Design Objectives](multi-hap-objective.md).
#### Restrictions
1. The **installationFree** field must be set to **true** in each module-specific configuration file [module.json5](module-configuration-file.md) file.
2. When packaging an atomic service, comply with the following size rules:
- The total size of HAP files cannot exceed 10 MB.
- The size of a HAP file itself and all its dependent [HSP](in-app-hsp.md) cannot exceed 2 MB.
### Pre-loading Implementation
You can configure the system to automatically pre-download required modules when the atomic service enters a module, thereby speeding up module access.
Currently, pre-loading can be implemented only through configuration, not by invoking APIs.
#### How to Use
Pre-loading is triggered after the first frame of the newly accessed module is rendered. You can configure what to pre-load for a module, by setting the **preloads** field under **atomicService** in the [module.json5](module-configuration-file.md) file of the module. The following is an example of the **module.json5** file of the **entry** module, saved in **entry/src/main**:
In this example, the system automatically pre-loads the **feature** module after the first frame of the **entry** module is rendered.
#### Restrictions
[moduleType](../reference/apis/js-apis-bundleManager.md#moduletype) corresponding to moduleName in the **preloads** list cannot be entry.
## Using Dynamic Shared Packages in Atomic Services
A [Harmony Shared Package (HSP)](shared-guide.md) is a dynamic shared package for sharing code, C++ libraries, resources, and configuration files among modules.
For details about how to use the HSP within an atomic service, see [In-Application HSP Development](in-app-hsp.md).
#### How to Use
Assume that the project directory structure is as follows:
```
├── AppScope
| ├── resources
| └── app.json5
├── entry
| └── src/main
| ├── ets
| ├── entryAbility
| └── pages
| └── Index.ets
| ├── resources
| └── module.json5
├── feature
| └── src/main
| ├── ets
| ├── resources
| └── module.json5
├── library
| └── src/main
| ├── ets
| └── pages
| └── menu.ets
| ├── resources
| └── module.json5
├── node_modules
```
If you want to add a button in the **entry** module to jump to the menu page (**library/src/main/ets/pages/menu.ets**) in the **library** module, you can write the following code in the **entry/src/main/ets/MainAbility/Index.ets** file of the **entry** module:
@@ -192,12 +192,20 @@ Example of the metadata attribute:
**By default, application icons cannot be hidden from the home screen in OpenHarmony.**
The OpenHarmony system imposes a strict rule on the presence of application icons. If no icon is configured in the HAP file of an application, the system creates a default icon for the application and displays it on the home screen.<br>
Touching this icon will direct the user to the application details screen in **Settings**.
The OpenHarmony system imposes a strict rule on the presence of application icons. If no icon is configured in the HAP file of an application, the system creates a default icon for the application and displays it on the home screen.
Touching this icon will direct the user to the application details screen in **Settings**, as shown in Figure 1.
To hide an application icon from the home screen, you must configure the **AllowAppDesktopIconHide** privilege. For details, see [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md).
**Objectives**:
This requirement on application icons is intended to prevent malicious applications from deliberately configuring no icon to block uninstallation attempts.
**Setting the application icon to be displayed on the home screen**:
Set **icon**, **label**, and **skills** under **abilities** in the **config.json** file. In addition, make sure the **skills** configuration contains **ohos.want.action.home** and **entity.system.home**.
**Setting the application icon to be displayed on the home screen**:<br>Set **icon**, **label**, and **skills** under **abilities** in the **config.json** file. In addition, make sure the **skills** configuration contains **ohos.want.action.home** and **entity.system.home**.
```
{
"module":{
...
...
@@ -220,36 +228,37 @@ To hide an application icon from the home screen, you must configure the **Allow
}
```
**Querying an application icon:**
**Display rules of application icons and labels on the home screen:**
* The HAP file contains Page ability configuration.
* The application icon is set under **abilities** in the **config.json** file.
* The application icon on the home screen is set under **abilities** in the **config.json** file.
* The application does not have the privilege to hide its icon from the home screen.
* The returned home screen icon is the icon configured for the ability.
* The returned home screen label is the label configured for the ability. If no label is configured, the bundle name is returned.
* The returned component name is the component name of the ability.
* When the user touches the home screen icon, the home screen of the ability is displayed.
* The application icon displayed on the home screen is the icon configured for the Page ability.
* The application label displayed on the home screen is the label configured for the Page ability. If no label is configured, the bundle name is returned.
* The name of the Page ability is displayed.
* When the user touches the home screen icon, the home screen of the Page ability is displayed.
* The application has the privilege to hide its icon from the home screen.
* The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen.
* The application icon is not set under **abilities** in the **config.json** file.
* The application icon on the home screen is not set under **abilities** in the **config.json** file.
* The application does not have the privilege to hide its icon from the home screen.
* The returned home screen icon is the default icon.
*The returned home screen label is the bundle name of the application.
* The returned component name is the component name displayed on the application details screen (this component is built in the system).
* Touching the home screen icon will direct the user to the application details screen.
* The application icon displayed on the home screen is the default icon.
* The application label displayed on the home screen is the bundle name of the application.
* Touching the application icon on the home screen will direct the user to the application details screen shown in Figure 1.
* The application has the privilege to hide its icon from the home screen.
* The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen.
* The HAP file does not contain Page ability configuration.
* The application does not have the privilege to hide its icon from the home screen.
* The returned home screen icon is the default icon.
*The returned home screen label is the bundle name of the application.
* The returned component name is the component name displayed on the application details screen (this component is built in the system).
* Touching the home screen icon will direct the user to the application details screen.
* The application icon displayed on the home screen is the default icon.
* The application label displayed on the home screen is the bundle name of the application.
* Touching the application icon on the home screen will direct the user to the application details screen shown in Figure 1.
* The application has the privilege to hide its icon from the home screen.
* The information about the application is not returned during home screen information query, and the icon of the application is not displayed on the home screen.
> **NOTE**
>
> The icon and label displayed on the application details page may be different from those displayed on the home screen. For non-Page abilities, they are the entry icon and label set under **abilities**, if any.
Note: The label displayed on the application details screen may be different from that displayed on the home screen. For non-Page abilities, it is the entry label set (if any).<br><br>
**Table 8** Internal structure of the abilities attribute
...
...
@@ -412,39 +421,6 @@ Example of the **skills** attribute structure:
]
```
**Enhanced implicit query**
URI-level prefix matching is supported.
When only **scheme** or a combination of **scheme** and **host** or **scheme**, **host**, and **port** are configured in the configuration file, the configuration is successful if a URI prefixed with the configuration file is passed in.
* The query enhancement involves the following APIs:<br>
- 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.
- 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 whose home screen consists of multiple modules, such as the scan, pay, messaging, and finance modules, you can implement the HAP files as follows: (1) In the entry-type HAP file, implement the home screen logic for managing modules; (2) in feature-type HAP files, implement specific modules. The feature-type HAP files are independent of each other. 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.
- Flexible deployment: You can flexibly combine HAP files for device-specific deployment. 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. This means that you can 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.
- On-demand loading: You can load modules only when they are needed, reducing the package size. Specifically, you can configure some HAP files of your 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.
- 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 also reduces the size of the application package to some extent.
