@@ -33,6 +33,7 @@ As shown above, the **app.json5** file contains several tags.
| 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. | 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|
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",
"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**:
```json
{
"module":{
"name":"entry",
"type":"entry",
"srcEnty":"./ets/Application/MyAbilityStage.ts",
"description":"$string:entry_desc",
"mainElement":"MainAbility",
"deviceTypes":[
"default",
"tablet"
],
"deliveryWithInstall":true,
"installationFree":true,
"pages":"$profile:main_pages",
"atomicService":{
"preloads":[
{
"moduleName":"feature"
}
]
},
"abilities":[
{
"name":"MainAbility",
"srcEnty":"./ets/MainAbility/MainAbility.ts",
"description":"$string:MainAbility_desc",
"icon":"$media:icon",
"label":"$string:MainAbility_label",
"startWindowIcon":"$media:icon",
"startWindowBackground":"$color:white",
"exported":true,
"skills":[
{
"entities":[
"entity.system.home"
],
"actions":[
"action.system.home"
]
}
]
}
]
}
}
```
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:
@@ -87,6 +87,8 @@ As shown above, the **module.json5** file contains several tags.
| [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)|
| [atomicService](#atomicservice)| Atomic service configuration.| Object| Yes (initial value: left empty) |
| [dependencies](#dependencies)| List of shared libraries on which the current module depends during running.| Object array| Yes (initial value: left empty) |
## deviceTypes
...
...
@@ -206,10 +208,13 @@ UIAbility configuration of the module, which is valid only for the current UIAbi
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 uses the icon specified in the **app.json** file as the application icon and displays it on the home screen.
Touching this icon will direct the user to the application details screen in **Settings**.
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**:
...
...
@@ -231,37 +236,39 @@ Set **icon**, **label**, and **skills** under **abilities** in the **module.json
}]
}],
...
}
}
```
**Querying an application icon:**
* The HAP file contains ability configuration.
* The application icon is set under **abilities** in the **module.json5** file.
**Display rules of application icons and labels on the home screen:**
* The HAP file contains UIAbility configuration.
* The application icon on the home screen is set under **abilities** in the **module.json5** 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 UIAbility.
* The application label displayed on the home screen is the label configured for the UIAbility. If no label is configured, the bundle name is returned.
* The name of the UIAbility is displayed.
* When the user touches the home screen icon, the home screen of the UIAbility 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 **module.json5** file.
* The application icon on the home screen is not set under **abilities** in the **module.json5** 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 under **app**. (The **icon** parameter in the **app.json** file is mandatory.)
* The returned home screen label is the label configured under **app**. (The **label** parameter in the **app.json** file is mandatory.)
* 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 icon specified under **app**. (The **icon** field in the **app.json** file is mandatory.)
* The application label displayed on the home screen is the label specified under **app**. (The **label** field in the **app.json** file is mandatory.)
* 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 ability configuration.
* The HAP file does not contain UIAbility configuration.
* The application does not have the privilege to hide its icon from the home screen.
* The returned home screen icon is the icon configured under **app**. (The **icon** parameter in the **app.json** file is mandatory.)
* The returned home screen label is the label configured under **app**. (The **label** parameter in the **app.json** file is mandatory.)
* 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 icon specified under **app**. (The **icon** field in the **app.json** file is mandatory.)
* The application label displayed on the home screen is the label specified under **app**. (The **label** field in the **app.json** file is mandatory.)
* 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 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.<br><br>
@@ -396,38 +403,6 @@ Example of the **skills** 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:
@@ -475,7 +450,7 @@ Example of the **extensionAbilities** structure:
"metadata":[
{
"name":"ohos.extension.form",
"resource":"$profile:form_config",
"resource":"$profile:form_config",
}
]
}
...
...
@@ -534,7 +509,7 @@ The **shortcut** information is identified in **metadata**, where:
-**resource** indicates where the resources of the shortcut are stored.
| Attribute| Description| Data Type | Default Value|
| Name| 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)|
...
...
@@ -705,7 +680,7 @@ The **testRunner** tag represents the supported test runner.
| 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:
Example of the **testRunner** structure:
```json
...
...
@@ -719,3 +694,80 @@ Example of the / structure:
}
}
```
## atomicService
The **atomicService** tag represents the atomic service configuration. It is available only when **bundleType** is set to **atomicService** in the **app.json** file.
**Table 18** Internal structure of the atomicService tag
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| preloads | List of modules to pre-load.| Object array| Yes (initial value: left empty)|
Example of the **atomicService** structure:
```json
{
"module":{
"atomicService":{
"preloads":[
{
"moduleName":"feature"
}
]
}
}
}
```
## preloads
The **preloads** tag represents a list of modules to pre-load in an atomic service.
**Table 19** Internal structure of the preloads tag
| Name| Description| Data Type| Initial Value Allowed|
| -------- | -------- | -------- | -------- |
| moduleName | Name of the module to be preloaded when the current module is loaded in the atomic service.| String| No|
Example of the **preloads** structure:
```json
{
"module":{
"atomicService":{
"preloads":[
{
"moduleName":"feature"
}
]
}
}
}
```
## dependencies
The **dependencies** tag identifies the list of shared libraries that the module depends on when it is running.
**Table 20** Internal structure of the dependencies tag
| Name | Description | Data Type| Initial Value Allowed|
