Cross-Device Resource Files

Application Resources

Resource Files

All custom resource files used during app development are stored in the resources directory of different modules for easy use and maintenance. The resources directory consists of two types of directories: base and qualifier directories, and rawfile directories. The following uses the entry module as an example to describe the base directory structure:

└──entry/src/main/resources                                  // Resources
   ├──base                                                   // Default directory
   │  ├──element        
   │  │  ├──color.json                                       // Color resources
   │  │  ├──float.json                                       // Numeric resources
   │  │  └──string.json                                      // String resources
   │  ├──media                                               // Media resources
   │  └──profile                                             // Routing resources
   ├──en_US                                                  // Example of the qualifiers directory, created by developers
   ├──zh_CN                                                  // Example of the qualifiers directory, created by developers
   └──rawfile                                                // Raw file directory

The base directory exists by default, and the qualifiers directory needs to be created on your own. The name of a qualifiers directory may be a combination of one or more qualifiers that represent an application scenario or a device feature. When your app needs to use a resource, the system preferentially searches the qualifiers directories that match the current device state. The system searches the base directories for the target resource only when the resources directory does not contain any qualifiers directories that match the current device state or the target resource is not found in the qualifiers directories. The rawfile directory does not require device-state-based resource matching, so it is not covered in this section.

You can create resource group directories (including element and media) under the base and qualifiers directories to store resource files of specific types.

In each resource file in the element directory, resources are defined in the name-value format, as shown below. In the media directory, the file name is used as the directory name. Therefore, you only need to place the file in the media directory without naming it.

// color.json 
{
    "color": [
        {
            "name": "color_red",
            "value": "#FFFF0000"
        },
        {
            "name": "color_blue",
            "value": "#FF0000FF"
        }
    ]
}

Accessing Application Resources

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

Example

In the resources directory of the app module, create a qualifiers subdirectory named tablet, and add corresponding resources to the base and tablet subdirectories. Resources are listed in the below table.

Use app resources in the form of "$r('app.type.name')" in the code, and check the running effect on the default device and tablet. You can find that the values of the same resource on different devices are different.

@Entry
@Component
struct ResourceQualifier {
  build() {
    Column() {
      Text($r('app.string.my_string'))
        .fontSize(60)
        .fontColor($r('app.color.my_color'))
      Image($r('app.media.my_image'))
        .width(100)
        .height(100)
    }
    .height('100%')
    .width('100%')
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
  }
}

System Resources

In addition to custom resources, preset system resources are also known as layered parameters, where each resource ID has different values under different configurations such as the device type and dark and light modes.

During development, the usage of layered parameters is basically the same as that of qualifiers. Reference a system resource using the "$r('sys.type.resource_id')" format. sys indicates a system resource. type indicates the resource type, which can be color, float, string, or media. resource_id indicates the resource ID.