Resource Categories and Access

During application development, you may need to use different resources, such as colors, fonts, spacing, and images, based on the device or configuration. Depending on the resource type, you can achieve this using the following methods:

• Application resources: Configure device- or configuration-specific resources in the resource files.

• System resources: Use the preset resource definitions.

Resource Categories

Resource files used during application development must be stored in specified directories for management. The resources directory consists of three types of subdirectories: the base subdirectory, qualifiers subdirectories, and the rawfile subdirectory. The common resource files used across projects in the stage model are stored in the resources directory under AppScope.

The base subdirectory is provided by default, and the qualifiers subdirectories are created on your own. 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. The rawfile directory is not searched for resources.

Example of the resources directory:

resources
|---base
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---en_US  // Default directory. When the device language is en-us, resources in this directory are preferentially matched.
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---zh_CN  // Default directory. When the device language is zh-cn, resources in this directory are preferentially matched.
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---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.

Table 1 Classification of the resources directory

Qualifiers Subdirectory

The name of a qualifiers subdirectory consists of one or more qualifiers that represent the application scenarios or device characteristics, covering the mobile country code (MCC), mobile network code (MNC), language, script, country or region, screen orientation, device type, night mode, and screen density. The qualifiers are separated using underscores (_) or hyphens (-). When creating a qualifiers subdirectory, you need to understand the directory naming conventions and the rules for matching qualifiers subdirectories and the device status.

Naming Conventions for Qualifiers Subdirectories

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

• Separation between qualifiers: The language, script, and country/region qualifiers are separated using underscores (_); the MNC and MCC qualifiers are also separated using underscores (_); other qualifiers are separated using hyphens (-). For example, 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 2 Requirements for qualifier values

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 subdirectory zh_CN-car-ldpi cannot be used for matching the resource files labeled en_US.

Resource Group Subdirectory

You can create resource group subdirectories (including element, media, and profile) in the base and qualifiers subdirectories to store resource files of specific types.

Table 3 Resource group subdirectories

Media Resource Types

Table 4 Image resource types

Table 5 Audio and video resource types

Resource File Examples

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

{
    "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 %s."
        }
    ]
}

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"
                }
            ]
        }
    ]
}

Resource Access

Application Resources

Creating a Resource File

You can create a subdirectory and its files under the resources directory based on the above descriptions of the qualifiers subdirectories and resource group subdirectories.

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. This operation creates a subdirectory and a resource file simultaneously. If no qualifier is selected, the file is created in a resource type subdirectory under base. If one or more qualifiers are selected, the system automatically generates a subdirectory and creates the file in this subdirectory. 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. 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. The created subdirectory is automatically named in the format of Qualifiers.Resource group type. For example, if you create a subdirectory by setting Color Mode to Dark and Resource type to Element, the system automatically generates a subdirectory named dark.element.

  

• Creating a resource directory

  Right-click the resources directory and choose New > Resource Directory. This operation creates a subdirectory only. By default, the base subdirectory is created. You can create qualifiers subdirectories as required, by specifying the qualifier and resource group type. After determining the qualifier, select a resource group type. Currently, the resource group type can be Element, Media, or Profile. After a resource group is created, a directory name is automatically generated.

  

• Creating a resource file

  Right-click a subdirectory under resources and choose New > example Resource File. This operation creates a resource file under this subdirectory. For example, you can create an element resource file in the element subdirectory.

  

Accessing Application Resources

To reference an application resource in a project, use the "$r('app.type.name')" format. app indicates the resource defined in the resources directory of the application. type indicates the resource type (or the location where the resource is stored). The value can be color, float, string, plural, or media. name indicates the resource name, which you set when defining the resource.

When referencing resources in the rawfile subdirectory, use the "$rawfile('filename')" format. Wherein 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

Resource descriptors accept only strings, such as 'app.type.name', and cannot be combined.

The return value of $r is a Resource object. You can obtain the corresponding string by using the getStringValue method.

In the example.ets file, you can use the resources defined in the resources directory. The following is a resource usage example based on the resource file examples in Resource Group Subdirectory:

Text($r('app.string.string_hello'))
  .fontColor($r('app.color.color_hello'))
  .fontSize($r('app.float.font_hello'))

Text($r('app.string.string_world'))
  .fontColor($r('app.color.color_world'))
  .fontSize($r('app.float.font_world'))

// Reference string resources. The second parameter of $r is used to replace %s, and value is "We will arrive at five of the clock".
Text($r('app.string.message_arrive', "five of the clock"))
  .fontColor($r('app.color.color_hello'))
  .fontSize($r('app.float.font_hello'))

// Reference plural resources. The first parameter indicates the plural resource, the second parameter indicates the number of plural resources, and the third parameter indicates the substitute of %d.
// The value is "5 apple" in singular form and "5 apples" in plural form.
Text($r('app.plural.eat_apple', 5, 5))
  .fontColor($r('app.color.color_world'))
  .fontSize($r('app.float.font_world'))

Image($r('app.media.my_background_image'))  // Reference media resources.

Image($rawfile('test.png'))                 // Reference an image in the rawfile directory.

Image($rawfile('newDir/newTest.png'))       // Reference an image in the rawfile directory.

System Resources

System resources include colors, rounded corners, fonts, spacing, character strings, and images. By using system resources, you can develop different applications with the same visual style.

To reference a system resource, use the "$r('sys.type.resource_id')" format. Wherein: sys indicates a system resource; type indicates the resource type, which can be color, float, string, or media; resource_id indicates the resource ID.

NOTE

• Use of system resources is supported in the declarative development paradigm, but not in the web-like development paradigm.

• For details about the implementation of preconfigured resources, visit the OpenHarmony/resources repository. The directory structure there is similar to that of the resources directory in the project. Resource qualifiers are used to match resources with different devices and device status.

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(200)
  .width(300)