目录

配置应用图标和名称

本页面提供应用图标和名称的配置指导。应用图标分为单层图标和分层图标。单层图标包含一个图片，分层图标包含前景图和背景图。图标规范详见图标资源规范，应用上架审核时对应用信息有限制，请参考应用审核指南的应用信息，确保应用信息符合相关限制规范，图标和名称配置约束详见图标和名称配置。

使用场景

效果图如下。

配置优先级和生成策略

在编译构建时，AppScope目录下的资源文件会合入到模块下相同路径的资源目录中，如果两个目录下存在重名文件，编译打包后AppScope目录下的资源文件会覆盖模块下的资源。

例如，app.json5和module.json5中配置的分层图标的资源文件名称一致、图标不一致，AppScope目录下的资源文件会覆盖模块中的文件，最后的效果是app.json5中的配置图标生效。

如果应用配置中未设置入口UIAbility，点击桌面图标将直接进入应用详情页（设置->应用和元服务下，点击任意应用即可进入该应用的应用详情页）。其他情况下，点击桌面图标将直接进入应用页面。应用未配置入口UIAbility包含2种场景：

  1. 应用没有配置任何UIAbility。
  2. 所有UIAbility中skills标签下的entities未配置或配置内容不包括 "entity.system.home"，并且actions未配置或配置内容不包括 "ohos.want.action.home"。

配置单层图标和应用名称

配置分层图标和应用名称

DevEco Studio NEXT Beta1(5.0.3.814) 及之后的版本，创建应用时默认模板中包含分层图标的资源文件，不同版本生成的资源文件名称可能不同，文件名称支持手动修改。如果分层图标资源文件不存在则需要手动创建，文件名称需要符合资源命名规范，由数字、字母、点和下划线组成。

配置备用图标

从API版本26.0.0开始，配置备用图标可在应用运行时动态切换，适用于用户偏好、节日主题、品牌活动等场景。开发者可以在app.json5配置文件的alternateIcons标签中预先配置多个备用图标，最多可以配置1024个，可参考下方步骤进行动态切换。

备用图标支持单层图标和分层图标，资源文件的准备和配置方式分别参考配置单层图标和应用名称和配置分层图标和应用名称。

  • alternateIcons标签仅在bundleType为app时生效。

  • 应用最多只能同时启用一个备用图标。

  • 分身应用不支持设置和查询备用图标。

  1. 在app.json5配置文件中添加alternateIcons标签，声明备用图标列表。

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

  2. 使用bundleManager.setAlternateIcon接口设置备用图标，传入alternateIcons标签中配置的name字段值即可启用对应备用图标。

    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(() => {
            // alternateIconName需要替换为app.json5中alternateIcons标签下配置的name字段值
            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. 调用bundleManager.setAlternateIcon接口传入空字符串可恢复默认图标。

    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. 使用bundleManager.getAlternateIcons接口查询备用图标信息。返回的AlternateIconInfo数组包含每个备用图标的名称（iconName）、资源ID（iconId）和启用状态（enabled）。

    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%')
  }
}