Resource Categories and Access

Function Description

In application development, it is common to use resources such as strings, colors, fonts, spacing, and icons. To ensure the application delivers an optimal experience across different devices (e.g., mobile phones, tablets, vehicle head units) and configurations (e.g., languages, screen densities, color modes), the system supports an automatic resource dynamic matching mechanism that selects the most appropriate resources for various scenarios. This section describes resource types and organization methods, and provides guidance for resource development.

Based on source differences, resources are categorized into system resources and application resources. System resources are provided by the system. You can retrieve system symbol icons, colors, spacing, characters, and other resource information from global_system_resources. Among these system resources, symbol icons can be further customized via SymbolGlyph. Application resources are custom-defined within the application, and resource files can be used to manage how resources behave across different devices or configurations.

Resource Categories

Resource files used during application development must be stored in specified directories for management. There are two types of resource directories, namely, resource directories and resource group directories. The resource directories are the base, qualifiers, rawfile, and resfile directories. The resource group directories are the element, media, and profile directories.

resources
|---base  // Default directory.
|   |---element
|   |   |---string.json // String resource file.
|   |---media
|   |   |---icon.png // Media resource file, which can be an image or a video.
|   |---profile
|   |   |---test_profile.json // User-defined profile.
|---en_GB-vertical-car-mdpi // Example of a qualifiers subdirectory, which needs to be created on your own.
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---rawfile // Other types of files are saved as raw files and will not be integrated into the resources.index file. You can customize the file name as needed.
|---resfile // Other types of files are saved as raw files and will not be integrated into the resources.index file. You can customize the file name as needed.

NOTE

• Files in resource directories and resource group directories are considered as resource files and will not be obfuscated during application packaging.

• The common resource files used across projects in the stage model are stored in the resources directory under AppScope.

• The resource files in the AppScope directory are merged into the resources directory. If files with the same name exist in these two directories, the ones in the AppScope directory are retained after build and packaging.

• For details about the resource packaging policies in directories other than resources, see copyCodeResource.

Resource Directories

Table 1 Description of resource directories

Resource Group Directories

Table 2 Resource group directories

Media Resource Types

Table 3 Image resource types

Table 4 Audio and video resource types

Qualifiers Directory

The name of a qualifiers directory consists of one or more qualifiers that represent the application scenarios or device characteristics. Qualifiers include the mobile country code (MCC), mobile network code (MNC), language, script, country or region, screen orientation, device type, night mode, and screen density. Underscores (_) or hyphens (-) are used to separate qualifiers. Before creating a qualifiers directory, familiarize yourself with the following directory naming conventions:

• Qualifiers are ordered in the following sequence: MCC_MNC-language_script_country/region-screen orientation-device type-night mode-screen density. You can select one or multiple qualifiers to name your subdirectory based on your application scenarios and device characteristics.

• Separation between qualifiers: the MCC and MNC qualifiers are separated by underscores (_); the language, script, and country/region qualifiers are separated by underscores (_); other qualifiers are separated by hyphens (-). For example, mcc460_mnc00-zh_Hant_CN and zh_CN-car-ldpi.

• Value range of qualifiers: The value of each qualifier must meet the requirements specified in the following table. Otherwise, the resource files in the resources directory cannot be matched.

Table 5 Requirements for qualifier values

Resource File Examples

The content of the color.json file is as follows.

The standard hexadecimal color value consists of eight hexadecimal digits. The first two digits indicate the opacity and the last six digits indicate the color value.

{
  "color": [
    {
      "name": "color_hello",
      "value": "#ffff0000"
    },
    {
      "name": "color_world",
      "value": "#ff0000ff"
    }
  ]
}

The content of the float.json file is as follows.

{
  "float": [
    {
      "name": "font_hello",
      "value": "28.0fp"
    },
    {
      "name": "font_world",
      "value": "20.0fp"
    }
  ]
}

The content of the string.json file is as follows.

{
  "string": [
    {
      "name": "string_hello",
      "value": "Hello"
    },
    {
      "name": "string_world",
      "value": "World"
    },
    {
      "name": "message_arrive",
      "value": "We will arrive at %1$s."
    },
    {
      "name": "message_notification",
      "value": "Hello, %1$s!,You have %2$d new messages."
    }
  ]
}

The content of the plural.json file is as follows.

{
  "plural": [
    {
      "name": "eat_apple",
      "value": [
        {
          "quantity": "one",
          "value": "%d apple"
        },
        {
          "quantity": "other",
          "value": "%d apples"
        }
      ]
    }
  ]
}

Creating a Resource Directory and Resource File

You can create a directory and its files under the resources directory based on the naming rules of the qualifiers directory and file types supported by resource group directories. DevEco Studio provides a wizard for you to create resource directories and resource files.

Creating a Resource Directory and Resource File

Right-click the resources directory and choose New > Resource File. By default, the file is created in a resource group directory under base. If one or more qualifiers are selected, the system automatically generates a subdirectory and creates the file in this subdirectory.

Qualifiers of different types can be combined. For example, if Locale is set to zh_CN and ColorMode is set to Dark, the qualifiers directory name will be zh_CN-dark. For details about the combination rules, see Qualifiers Directory.

In File name, enter the name of the resource file to create. In Resource type, select the type of the resource group, which is element by default. In Root Element, select a resource type. To select a qualifier, highlight it under Available qualifiers and click the right arrow. To deselect a qualifier, highlight it under Selected qualifiers and click the left arrow.
The created directory is automatically named in the format of Qualifiers.Resource group type. For example, if you create a directory by setting Color Mode to Dark and Resource type to Element, the system automatically generates a directory named dark/element.

Creating a Resource Directory

Right-click the resources directory and choose New > Resource Directory to create a directory only. By default, the base directory is created. If one or more qualifiers are selected, the system automatically generates the qualifiers directories and resource group directories. After specifying the qualifier, select a resource group type. Currently, the supported resource group types are Element, Media, and Profile. A resource directory will be generated upon creation.

Creating a Resource File

Right-click a resource group directory (element, media, or profile) and choose New > XXX Resource File. A resource file under this directory is then created. For example, you can create an element resource file in the element subdirectory.

Example

The following takes the Chinese and English string resource files as examples to describe how to create resources with different qualifiers.

1. Right-click the resources directory and choose New > Resource File from the shortcut menu. Set File name to string_sample, Resource type to Element, Root Element to string, and Available qualifiers to Locale. Select zh from the language list and CN from the country/region list. After all is set, the zh_CN/element/string_sample.json file is created in the resources directory.

   

2. Similarly, select en for language and US for country/region to create the en_US/element/string_sample.json file.

   The following figure shows the created resource files. For details about how to access the created resource files, see Accessing Resources.

   

Using the attr Attribute for Resource Translation

Function Description

If the string resource referenced by an application needs to support multi-language adaptation, the attr attribute can be used to mark the translation scope and status of the string. The attr attribute is not involved in resource compilation.

If the attr attribute is not configured, a string is translated by default.

Parameters of attr

Constraints

The attr attribute applies to the string, strarray, and plural resources in the base directory.

resources
|---base
|   |---element
|   |   |---string.json
|   |   |---strarray.json
|   |   |---plural.json

Example

The following shows the attr attribute configured in string. The string1 string is marked as not to be translated, and the string2 string is marked as to be translated and the translation has been verified.

{
  "string": [
    {
      "name": "string1",
      "value": "1",
      "attr": {
        "translatable": false
      }
    },
    {
      "name": "string2",
      "value": "Hello world!",
      "attr": {
        "translatable": true,
        "priority": "LT"
      }
    }
  ]
}

Accessing Resources

HAP Resources

• Access resources through $r or $rawfile.
  Resources of the color, float, string, plural, media and profile types are accessed through $r('app.type.name'), in which app indicates the resource defined in the resources directory, type indicates the resource type, and name indicates the resource name.
  To access strings with multiple placeholders in the string.json file, for example, %1$s and %2$d in a value, use the $r('app.string.label', 'aaa', 444) format, where label indicates the resource name, and 'aaa' and 444 are used to replace placeholders.
  To access resources in the rawfile subdirectory, use the $rawfile('filename') format. filename indicates the relative path of a file in the rawfile subdirectory, which must contain the file name extension and cannot start with a slash (/).

  NOTE

  For details about how to use native APIs to access raw files, see Raw File Development.

Resource file examples show different .json files, including color.json, string.json, and plural.json. Before accessing application resources, you need to learn the usage specifications of the .json files.
The usage is as follows.

// Access the resource through $r('app.type.name').
// The resource name is an example. Replace it with the actual resource.
Text($r('app.string.string_hello'))
  .id('app_resource')
  .fontColor($r('app.color.color_emphasize'))
  .fontSize($r('app.float.text_size_headline1'))
  .fontFamily($r('app.string.font_family_medium'))
  .backgroundColor($r('app.color.color_palette_aux1'))

// The resource name is an example. Replace it with the actual resource.
Image($r('app.media.app_icon'))
  .border({
    color: $r('app.color.color_palette_aux1'),
    radius: $r('app.float.corner_radius_button'), width: 2
  })
  .margin({
    top: $r('app.float.elements_margin_horizontal_m'),
    bottom: $r('app.float.elements_margin_horizontal_l')
  })
  .height(100)
  .width(100)

// For a string in string.json whose name is "message_notification", its value is "Hello, %1$s!,You have %2$d new messages."
// Replace the placeholders %1$s and %2$d with 'LiHua' and 2, respectively. Access the resource as follows.
// The resource name is an example. Replace it with the actual resource.
Text($r('app.string.message_notification', 'LiHua', 2)).id('app_string_resource')

// For a string in plural.json whose name is "eat_apple", its value of the singular form is "%d apple" and that of the plural form is "%d apples".
// You can access the plural.json resources. The first parameter determines whether a string is displayed in the singular or plural form. The value 1 indicates the singular form, and a value greater than 1 indicates the plural form.
// The resource has one placeholder %d, which should be replaced with 2. You can access the resource in the following way:
// The resource name is an example. Replace it with the actual resource.
Text($r('app.plural.eat_apple', 2, 2)).id('app_plural_resource')

• After obtaining a ResourceManager object through the application context, call APIs of resource management to access different resources. For example, you can call getContext().resourceManager.getStringByNameSync('test') to obtain string resources, and call getContext().resourceManager.getRawFd('rawfilepath') to obtain the descriptor information of the HAP where the rawfile is located, and then use {fd, offset, length} to access the rawfile.
  For API version 22 and earlier, when intermediate code HAR and bytecode HAR access resources through resource ID-related APIs, an exception is thrown due to invalid IDs.Starting from API version 23, if compatibleSdkVersion is configured to 23 or higher, intermediate code HAR and bytecode HAR can access resources normally through resource ID-related APIs after the onCreate() callback of the AbilityStage in the current module is executed.

Cross-HAP/HSP Resources

Cross-Bundle Access (for System Applications Only)

• Create the context of the corresponding HAP or HSP file through the createBundleContext(context, bundleName) API. After obtaining the resourceManager object, call different APIs of resource management to access various resources by resource ID or resource name.

Inter-Bundle, Cross-Module Access

• Create the context of the corresponding module through the createModuleContext(context, moduleName) API. After obtaining the resourceManager object, call different APIs of resource management to access various resources by resource ID or resource name.

• Access resources through $r or $rawfile. Specifically, perform either of the following:

  1. Add dependencies to the oh-package.json5 file in the entry directory. For example, "dependencies": {"library": "file:../library"}.

  

  2. Obtain resources using variables or the literal [Module name].type.name, where module name indicates the name of the HSP module, type indicates the resource type, and name indicates the resource name. The following is an example:

  @Entry
  @Component
  struct Second {
    // [library] is an example module name. Replace it with the actual module name.
    // The resource name is an example. Replace it with the actual resource.
    text: string = '[library].string.test_string';
    fontSize: string = '[library].float.font_size';
    fontColor: string = '[library].color.font_color';
    image: string = '[library].media.image';
    rawfile: string = '[library].icon.png';
  
    build() {
      Column() {
        // Use the literal [module name].type.name to obtain resources.
        // The resource name is an example. Replace it with the actual resource.
        Text($r('[library].string.test_string'))
          .id('hsp_resource_one')
          .fontSize($r('[library].float.font_size'))
          .fontColor($r('[library].color.font_color'))
        Image($rawfile('[library].icon.png'))
          .height(100)
          .width(100)
  
        // Use variables to obtain resources.
        Text($r(this.text))
          .id('hsp_resource_two')
          .fontSize($r(this.fontSize))
          .fontColor($r(this.fontColor))
  
        Image($r(this.image))
          .height(100)
          .width(100)
  
        Image($rawfile(this.rawfile))
          .height(100)
          .width(100)
      }
      .height('100%')
      .width('100%')
    }
  }
  

  Second.ets

  NOTE

  The HSP module name must be placed in the brackets ([]). If the rawfile directory contains multiple levels of folders, the path must start from the first level, for example, $rawfile{(}^{\prime }[hsp].firstDir/secondDir/icon.pn{g}^{\prime }).When\ast \ast$r** or $rawfile is used for cross-HSP resource access, resource verification is not available at compile time, and you need to manually check that the target resources exist in the corresponding location.

System Resources

To access system resources, use the $r('sys.type.name') format, where sys indicates the system resource, type indicates the resource type, such as color, float, string, media, or symbol, and name indicates the resource name.

NOTE

• For preset applications, you are advised to use system resources. For third-party applications, you can choose to use system resources or custom application resources as required.

• The use of system resources is only supported in the declarative development paradigm.

• The default system font used on the UI is HarmonyOS Sans, and the supported character range follows the standards in Information technology—Chinese coded character set GB18030-2022. If the characters cannot be displayed in HarmonyOS Sans, the system uses another font with the highest priority to display the characters. For details about the priority of the system fonts, see the /system/etc/fontconfig.json configuration file on the device.

Text('Hello')
  .fontColor($r('sys.color.ohos_id_color_emphasize'))
  .fontSize($r('sys.float.ohos_id_text_size_headline1'))
  .fontFamily($r('sys.string.ohos_id_text_font_family_medium'))
  .backgroundColor($r('sys.color.ohos_id_color_palette_aux1'))

Image($r('sys.media.ohos_app_icon'))
  .border({
    color: $r('sys.color.ohos_id_color_palette_aux1'),
    radius: $r('sys.float.ohos_id_corner_radius_button'), width: 2
  })
  .margin({
    top: $r('sys.float.ohos_id_elements_margin_horizontal_m'),
    bottom: $r('sys.float.ohos_id_elements_margin_horizontal_l')
  })
  .height(100)
  .width(100)

Matching Resources

When your application needs to use a resource, the system preferentially searches the qualifiers subdirectories that match the current device state. The system searches the base subdirectory for the target resource only when the resources directory does not contain any qualifiers subdirectories that match the current device state or the target resource is not found in the qualifiers subdirectories. rawfile and resfile are raw file directories, which will not match resources based on the device status.

NOTE

• The resource files in the AppScope directory are merged into the resources directory. If files with the same name exist in these two directories, the ones in the AppScope directory are retained after build and packaging.

Rules for Matching Qualifiers Subdirectories and Device Resources

• Qualifiers are matched with the device resources in the following priorities: MCC&MNC > locale (options: language, language_script, language_country/region, and language_script_country/region) > screen orientation > device type > color mode > screen density

• If the qualifiers subdirectories contain the MCC, MNC, language, script, screen orientation, device type, and color mode qualifiers, their values must be consistent with the current device status so that the subdirectories can be used for matching the device resources. For example, the qualifiers directory zh_CN-car-ldpi cannot be used for matching the resource files labeled en_US.

• If there are multiple qualifiers subdirectories for the screen density, the closest qualifiers are matched upwards; otherwise, downwards. For example, if qualifiers directories xldpi and xxldpi exist and the device screen density is xxldpi, the qualifier directory xxldpi will be matched.

For details about the rules for loading resources on the application UI, see Overview of Internationalization and Localization.

Obtaining Resources for a Specific Configuration

Basic Concepts

You can add qualifiers to the project-level resources directory to meet different system settings such as multi-language support and dark and light color modes. However, some directory resources fail to be obtained due to matching rules of the qualifiers directories.

If this is the case, you can use the following APIs to obtain resources for a specific configuration.

Available APIs

Example

The following example demonstrates how to obtain the specified resources for languages other than the one in use. Assume that the following resource files with the same name are defined in the resources directories for Chinese, English, and Japanese:

• entry/src/main/resources/zh_CN/element/string.json

{
  "string": [
    {
      "name": "greetings",
      "value": "你好，世界"
    }
  ]
}

• entry/src/main/resources/en_US/element/string.json

{
  "string": [
    {
      "name": "greetings",
      "value": "Hello, world"
    }
  ]
}

• entry/src/main/resources/ja_JP/element/string.json

{
  "string": [
    {
      "name": "greetings",
      "value": "こんにちは、世界"
    }
  ]
}

In Index.ets, add code to obtain the resources of the three languages and display them in the text box. The current system language is Chinese. The following is sample code in entry/src/main/ets/pages/Index.ets:

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State englishString: string = '';
  @State japaneseString: string = '';

  build() {
    Column() {
    // ...
      Text(this.getString())
        .id('config_resource_one')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
      Text(this.englishString)
        .id('config_resource_two')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
      Text(this.japaneseString)
        .id('config_resource_three')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
    // ...
    }
    .height('100%')
    .width('100%')
  }

  getString(): string {
    let resMgr = this.getUIContext().getHostContext()?.resourceManager;
    if (!resMgr) {
      return '';
    }
    let currentLanguageString: string = '';
    try {
      // The resource name is an example. Replace it with the actual resource.
      let resId = $r('app.string.greetings').id;

      // Obtain resources that match the current system configuration, including the color mode and resolution, for the current system language.
      currentLanguageString = resMgr.getStringSync(resId);

      // Obtain resources that match the current system configuration, including the color mode and resolution, for the English language.
      let overrideConfig = resMgr.getOverrideConfiguration();
      overrideConfig.locale = 'en_US'; // Set the language to English and locale to en_US.
      let overrideResMgr = resMgr.getOverrideResourceManager(overrideConfig);
      this.englishString = overrideResMgr.getStringSync(resId);

      // Obtain resources that match the current system configuration, including the color mode and resolution, for the Japanese language.
      overrideConfig.locale = 'ja_JP'; // Set the language to Japanese and locale to ja_JP.
      // Equivalent to resMgr.updateOverrideConfiguration(overrideConfig)
      overrideResMgr.updateOverrideConfiguration(overrideConfig);
      this.japaneseString = overrideResMgr.getStringSync(resId);
    } catch (err) {
      const code = (err as BusinessError).code;
      const message = (err as BusinessError).message;
      console.error(`get override resource failed, error code: ${code}, error msg: ${message}`);
    }
    return currentLanguageString;
  }
}

Overlay Mechanism

Overlay is a resource replacement mechanism. With overlay resource packages, you can enable your application UI to adapt to different styles of various brands and products, without having to repack your application HAPs. The overlay mechanism works in dynamic and static modes. Overlay resource packages contain only resource files, resource index files, and configuration files.

Using overlay in dynamic mode

1. Place the overlay resource package in the target application installation path. For example, for the com.example.overlay application, place the overlay resource package in data/app/el1/bundle/public/com.example.overlay/.
2. The application uses addResource(path) to load overlay resources and uses removeResource(path) to remove overlay resources. The path to an overlay resource consists of the application's sandbox root directory (obtained through getContext().bundleCodeDir) and the overlay resource bundle name. For example, let path = getContext().bundleCodeDir + "overlay resource bundle name", such as /data/storage/el1/bundle/overlayResourceBundleName.

Using overlay in static mode

This feature is enabled by default. For details about how to enable and disable this feature, see @ohos.bundle.overlay (overlay Module).

The app.json5 file in the inter-application overlay resource package supports the following fields:

{
  "app":{
    "bundleName": "com.example.myapplication.overlay",
    "vendor" : "example",
    "versionCode": "1000000",
    "versionName": "1.0.0.1",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

The module.json5 file in the inter-application overlay resource package supports the following fields:

{
  "module":{
    "name": "entry_overlay_module_name",
    "type": "shared",
    "description": "$string:entry_overlay_desc",
    "deviceTypes": [
      "default",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "targetModuleName": "entry_module_name",
    "targetPriority": 1
  }
}

The app.json5 file in the cross-application overlay resource package supports the following fields, which are available for system applications only:

{
  "app":{
    "bundleName": "com.example.myapplication.overlay",
    "vendor" : "example",
    "versionCode": "1000000",
    "versionName": "1.0.0.1",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "targetBundleName": "com.example.myapplication",
    "targetPriority": 1
  }
}

The module.json5 file in the cross-application overlay resource package supports the following fields, which are available for system applications only:

{
  "module":{
    "name": "entry_overlay_module_name",
    "type": "shared",
    "description": "$string:entry_overlay_desc",
    "deviceTypes": [
      "default",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "targetModuleName": "entry_module_name",
    "targetPriority": 1
  }
}

NOTE

• targetBundleName: name of the target application to apply the overlay feature. The value is a string.

• targetModuleName: name of the target module to apply the overlay feature. The value is a string.

• targetPriority: overlay priority. The value is an integer.

• Other fields such as Ability, ExtensionAbility, and Permission are not supported.

• The overlay feature does not support JSON images.

If the module.json5 file of a module contains the targetModuleName and targetPriority fields during project creation on DevEco Studio, the module is identified as a module with the overlay feature in the installation phase. Modules with the overlay feature generally provide an overlay resource file for other modules on the device, so that the module specified by targetModuleName can display different colors, labels, themes, and the like by using the overlay resource file in a running phase.