目录

Configuring an Application Icon and Label

This page provides guidance on configuring the app icon and name. App icons are classified into single-layer icons and layered icons. A single-layer icon contains one image, while a layered icon contains a foreground image and a background image. For details about icon specifications, see icon resource specifications. Application information is restricted during application release review.. For details about icon and name configuration constraints, see Configuring the Application Icon and Label.

Use Scenarios

The display effects are as follows.

Configuration Priority and Build Policy

During compilation and building, the resource files under the AppScope directory are merged into the resource directory with the same path in the module. If files with the same name exist in both directories, the resource files under the AppScope directory overwrite the resources in the module after compilation and packaging.

For example, if the layered icon resource files configured in app.json5 and module.json5 have the same name but different icons, the resource files under the AppScope directory overwrite the files in the module, and the icon configured in app.json5 takes effect.

If no entry UIAbility is configured in the application, tapping the home screen icon directly opens the app details page (under Settings > Apps & services, tap any app to open its app details page). In other cases, tapping the home screen icon directly opens the app page. The scenario where no entry UIAbility is configured includes two cases:

  1. The application does not configure any UIAbility.
  2. In all UIAbilities, the entities under the skills tag are not configured or do not contain "entity.system.home", and the actions are not configured or do not contain "ohos.want.action.home".

Configuring a Single-Layer Icon and Label

Configuring a Layered Icon and Label

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 (_).

Configuring Alternate Icons

Starting from API version 26.0.0, you can configure alternate icons to dynamically switch them at application runtime, which applies to scenarios such as user preferences, festival themes, and brand campaigns. You can preconfigure multiple alternate icons in the alternateIcons tag of the app.json5 configuration file, up to 1024, and dynamically switch them by following the steps below.

Alternate icons support both single-layer icons and layered icons. For details about how to prepare and configure resource files, see Configuring a Single-Layer Icon and Label and Configuring a Layered Icon and Label, respectively.

  • The alternateIcons tag takes effect only when bundleType is app.

  • An application can enable only one alternate icon at a time.

  • Clone apps do not support setting and querying alternate icons.

  1. Add the alternateIcons tag to the app.json5 configuration file to declare the alternate icon list.

    {
  "app": {
    // ...
    "alternateIcons": [
      {
        "name": "summer_theme",
        "icon": "$media:layered_image"
      },
      {
        "name": "winter_theme",
        "icon": "$media:winter_icon"
      }
    ]
  }
}

  2. Use the bundleManager.setAlternateIcon API to set an alternate icon. Pass the value of the name field configured in the alternateIcons tag to enable the corresponding alternate icon.

    import { bundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {

  build() {
    Scroll() {
      Column() {
        Text("SetAlternateIcon")
          .fontSize($r('app.float.page_text_font_size'))
          .fontWeight(FontWeight.Bold)
          .alignRules({
            center: { anchor: '__container__', align: VerticalAlign.Center },
            middle: { anchor: '__container__', align: HorizontalAlign.Center }
          })
          .onClick(() => {
            // Replace alternateIconName with the name field value configured under the alternateIcons tag in app.json5.
            let alternateIconName: string = 'summer_theme';
            try {
              bundleManager.setAlternateIcon(alternateIconName).then(() => {
                hilog.info(0x0000, 'testTag', 'setAlternateIcon successfully');
              }).catch((err: BusinessError) => {
                hilog.error(0x0000, 'testTag', 'setAlternateIcon failed. Cause: %{public}s', err.message);
              });
            } catch (err) {
              let message = (err as BusinessError).message;
              hilog.error(0x0000, 'testTag', 'setAlternateIcon failed. Cause: %{public}s', message);
            }
          })
        // ...
        // ...
      }
      .width('100%')
    }
    .height('100%')
  }
}

  3. Call the bundleManager.setAlternateIcon API and pass an empty string to restore the default icon.

    import { bundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {

  build() {
    Scroll() {
      Column() {
        // ...
        Text("RestoreDefaultIcon")
          .fontSize($r('app.float.page_text_font_size'))
          .fontWeight(FontWeight.Bold)
          .alignRules({
            center: { anchor: '__container__', align: VerticalAlign.Center },
            middle: { anchor: '__container__', align: HorizontalAlign.Center }
          })
          .onClick(() => {
            try {
              bundleManager.setAlternateIcon('').then(() => {
                hilog.info(0x0000, 'testTag', 'restore default icon successfully');
              }).catch((err: BusinessError) => {
                hilog.error(0x0000, 'testTag', 'restore default icon failed. Cause: %{public}s', err.message);
              });
            } catch (err) {
              let message = (err as BusinessError).message;
              hilog.error(0x0000, 'testTag', 'restore default icon failed. Cause: %{public}s', message);
            }
          })
        // ...
      }
      .width('100%')
    }
    .height('100%')
  }
}

  4. Use the bundleManager.getAlternateIcons API to query alternate icon information. The returned AlternateIconInfo array contains the name (iconName), resource ID (iconId), and enabled status (enabled) of each alternate icon.

    import { bundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {

  build() {
    Scroll() {
      Column() {
        // ...
        Text("GetAlternateIcons")
          .fontSize($r('app.float.page_text_font_size'))
          .fontWeight(FontWeight.Bold)
          .alignRules({
            center: { anchor: '__container__', align: VerticalAlign.Center },
            middle: { anchor: '__container__', align: HorizontalAlign.Center }
          })
          .onClick(() => {
            try {
              bundleManager.getAlternateIcons().then((data) => {
                hilog.info(0x0000, 'testTag', 'getAlternateIcons successfully. Data: %{public}s', JSON.stringify(data));
              }).catch((err: BusinessError) => {
                hilog.error(0x0000, 'testTag', 'getAlternateIcons failed. Cause: %{public}s', err.message);
              });
            } catch (err) {
              let message = (err as BusinessError).message;
              hilog.error(0x0000, 'testTag', 'getAlternateIcons failed. Cause: %{public}s', message);
            }
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}