1# Configuring an Application Icon and Label 2<!--Kit: Ability Kit--> 3<!--Subsystem: BundleManager--> 4<!--Owner: @wanghang904--> 5<!--Designer: @hanfeng6--> 6<!--Tester: @kongjing2--> 7<!--Adviser: @Brilliantry_Rui--> 8 9This topic describes how to configure the application icon and label. Application icons are classified into single-layer icons and layered icons. A single-layer icon contains only one image, and a layered icon contains a foreground image and a background image. For details about the icon specifications and icon configuration rules, see <!--RP1-->[Icon Deliverables](https://gitcode.com/openharmony/docs/blob/master/en/design/ux-design/visual-app-icons.md#icon-deliverables)<!--RP1End--> and [Configuring Icons and Labels](../application-models/application-component-configuration-stage.md#configuring-the-application-icon-and-label), respectively. 10 11## Use Scenarios 12 13<!--RP2--> 14- Display an application on an application screen, for example, application list in the Settings app. 15- Display an application on the home screen, for example, applications displayed on the home screen or in the recent task list. 16<!--RP2End--> 17 18The display effects are as follows. 19<!--RP3--> 20 21<!--RP3End--> 22 23## Configuration Priority and Build Policy 24 25* For the HAP file containing UIAbility configuration, the following scenarios are possible: 26 27 * If the **icon** and **label** fields under **abilities** of the [module.json5](module-configuration-file.md) file are configured, and under **skills** of the corresponding ability, **entities** contains **entity.system.home** and **actions** contains **ohos.want.action.home**, the system returns the **icon** and **label** configured in **module.json5**. If there are multiple abilities that meet the requirements, the system returns the icon and label specified for the ability corresponding to **mainElement** in **module.json5**. 28 29 * If the **icon** and **label** fields under **abilities** of the **module.json5** file are not configured, the system returns the **icon** and **label** configured in [app.json5](app-configuration-file.md). 30 31* For the HAP file that does not contain UIAbility configuration, the system returns the **icon** and **label** configured in **app.json5**. 32 33> 34> **NOTE** 35> 36> During compilation and build, resource files in the **AppScope** directory where the **app.json5** file is located are incorporated into the resource directory of the module. If resource files with the same name exist in these two directories, only the ones in the **AppScope** directory are retained after compilation and packaging. 37> 38> For example, if the labels of the layered icon files configured in **app.json5** and **module.json5** are the same but the icons are different, the resource files in the **AppScope** directory overwrite those in the module. Finally, the icon configured in **app.json5** is used. 39> 40> If no entry UIAbility is set in the application configuration, the application details page is displayed after you tap the application icon on the home screen. Alternatively, go to **Settings** > **Apps & services**, and tap any application to access the application details page. In other cases, the application main page is displayed after you tap the application icon on the home screen. An application does not have an entry UIAbility in either of the following scenarios: 41> 42> 1. The application does not have any UIAbility. 43> 2. The **entities** under the **skills** tag in all UIAbility configurations are not set or do not contain **entity.system.home**, and the **actions** tag is not set or does not contain **ohos.want.action.home**. 44> 45 46## Configuring a Single-Layer Icon and Label 47 48- **Method 1: Configuring app.json5** 49 50 This configuration takes effect only when the **module.json5** configuration file does not contain any UIAbility or **icon** and **label** under the **abilities** tag of the UIAbility are not set. (You can manually delete the icon and label configurations). 51 52 ```json 53 { 54 "app": { 55 "icon": "$media:app_icon", 56 "label": "$string:app_name" // Configure the resource whose name is app_name in AppScope/resources/base/element/string.json. If the resource already exists, skip this step. 57 // ... 58 } 59 } 60 ``` 61 62- **Method 2: Configuring module.json5** 63 64 In addition to configuring the **icon** and **label** fields, you need to add **entity.system.home** under **entities** and **ohos.want.action.home** under **actions**. 65 66 ```json 67 { 68 "module": { 69 // ... 70 "abilities": [ 71 { 72 "icon": "$media:icon", 73 "label": "$string:EntryAbility_label", // Configure the resource whose name is EntryAbility_label in entry/src/main/resources/base/element/string.json. If the resource already exists, skip this step. 74 "skills": [ 75 { 76 "entities": [ 77 "entity.system.home" 78 ], 79 "actions": [ 80 "ohos.want.action.home" 81 ] 82 } 83 ], 84 } 85 ] 86 } 87 } 88 ``` 89 90## Configuring the Layered Icon and Label 91 92- **Method 1: Configuring app.json5** 93 94 This configuration takes effect only when the **module.json5** configuration file does not contain any UIAbility or **icon** and **label** under the **abilities** tag of the UIAbility are not set. (You can manually delete the icon and label configurations). 95 96 1. Place the foreground and background resource files in **AppScope\resources\base\media**. 97 98 In this example, the file names of the foreground and background resource files are **foreground.png** and **background.png**, respectively. 99 100 2. In the **app_layered_image.json** file under the **AppScope\resources\base\media** directory, configure the foreground and background resources of the layered icon. 101 102 ```json 103 { 104 "layered-image": 105 { 106 "background" : "$media:background", 107 "foreground" : "$media:foreground" 108 } 109 } 110 ``` 111 3. Reference the layered icon resource file in the [app.json5](app-configuration-file.md) file. Example: 112 ```json 113 { 114 "app": { 115 "icon": "$media:app_layered_image", 116 "label": "$string:app_name" // Configure the resource whose name is app_name in AppScope/resources/base/element/string.json. If the resource already exists, skip this step. 117 // ... 118 } 119 } 120 ``` 121 122- **Method 2: Configuring module.json5** 123 124 1. Place the foreground and background resource files in **entry\src\main\resources\base\media**. 125 126 In this example, the file names of the foreground and background resource files are **foreground.png** and **background.png**, respectively. 127 128 2. In the **layered_image.json** file under the **entry\src\main\resources\base\media** directory, configure the foreground and background resources of the layered icon. 129 130 ```json 131 { 132 "layered-image": 133 { 134 "background" : "$media:background", 135 "foreground" : "$media:foreground" 136 } 137 } 138 ``` 139 140 3. To display a UIAbility icon on the home screen, you must configure the **icon** and **label** fields, and under the **skills** tag, add **entity.system.home** to **entities** and **ohos.want.action.home** to **actions**. 141 142 ```json 143 { 144 "module": { 145 "abilities": [ 146 { 147 "name": "EntryAbility", 148 // ... 149 "icon": "$media:layered_image", // Set icon to the index of the layered icon resource file. 150 "label": "$string:EntryAbility_label", // Configure the resource whose name is EntryAbility_label in entry/src/main/resources/base/element/string.json. If the resource already exists, skip this step. 151 "skills": [ 152 { 153 "entities": [ 154 "entity.system.home" 155 ], 156 "actions": [ 157 "ohos.want.action.home" 158 ] 159 } 160 ], 161 // ... 162 } 163 ] 164 // ... 165 } 166 } 167 ``` 168 169> 170> **NOTE** 171> 172> Since DevEco Studio 5.0.3.814, the default template contains the layered icon resource file when an application is created. The name of the resource file generated in different versions may be different. The file name can be manually modified. If the layered icon resource file does not exist, you have to manually create it. The file name must comply with the resource naming rules and can contain only digits, letters, periods (.), and underscores (_). 173> 174 175<!--Del--> 176## Management Rules 177 178The system strictly controls applications without icons to prevent malicious applications from deliberately displaying no icon on the home screen to block uninstall attempts. Therefore, home screen icons cannot be hidden for applications except pre-installed ones. 179 180If the pre-installed application indeed needs to hide the home screen icon, the **AllowAppDesktopIconHide** [application privilege](../../device-dev/subsystems/subsys-app-privilege-config-guide.md#general-application-privileges) must be configured. For details about the configuration, see "Application Privilege Configuration." After this privilege is granted, the application icon will not be displayed on the home screen.<!--DelEnd--> 181
