资源分类与访问

应用开发过程中，需要使用字符串、颜色、字体、间距和图标等资源。不同设备或配置下，这些资源的值会有所不同。本文档对资源类型进行介绍，并提供资源开发指导。 根据来源差异，可以将资源分为：

• 应用资源：开发者在应用中自定义的资源，可以利用资源文件管理资源在不同的设备或配置中的表现。

• 系统资源：系统提供的资源，开发者可以通过主题图标库获取系统图标资源信息、通过系统资源分层设计表获取系统字体等资源信息。

资源分类

应用开发中使用的各类资源文件，需要放入特定子目录中存储管理。目录结构如下所示，base目录、限定词目录、rawfile目录、resfile目录称为资源目录，element、media、profile称为资源组目录。

说明

stage模型多工程情况下，共有的资源文件放到AppScope下的resources目录。

资源目录和资源组目录示例：

resources
|---base  // 默认存在的目录
||---element
|||---string.json
||---media
|||---icon.png
||---profile
|||---test_profile.json
|---en_GB-vertical-car-mdpi // 自定义限定词目录示例，由开发者创建
||---element
|||---string.json
||---media
|||---icon.png
||---profile
|||---test_profile.json
|---rawfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。
|---resfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。

资源目录

base目录

base目录默认存在。二级子目录element用于存放字符串、颜色、布尔值等基础元素，media和profile子目录存放媒体、动画、布局等资源文件。
目录中的资源文件会被编译成二进制文件，并分配资源ID。通过指定资源类型（type）和资源名称（name）来访问。

限定词目录

限定词目录需要开发者根据开发需要自行创建，二级子目录element用于存放字符串、颜色、布尔值等基础元素，media和profile子目录存放媒体、动画、布局等资源文件。
同样，目录中的资源文件会被编译成二进制文件，并分配资源ID。通过指定资源类型（type）和资源名称（name）来访问。

限定词目录的命名要求

限定词目录由一个或多个表征应用场景或设备特征的限定词组合而成，限定词包括移动国家码和移动网络码、语言、文字、国家或地区、横竖屏、设备类型、颜色模式和屏幕密度，限定词之间通过下划线（_）或者中划线（-）连接。开发者在创建限定词目录时，需要遵守如下限定词目录命名规则。

• 限定词的组合顺序：移动国家码_移动网络码-语言_文字_国家或地区-横竖屏-设备类型-颜色模式-屏幕密度。开发者可以根据应用的使用场景和设备特征，选择其中的一类或几类限定词组成目录名称。

• 限定词的连接方式：移动国家码和移动网络码之间采用下划线（_）连接，语言、文字、国家或地区之间也采用下划线（_）连接，除此之外的其他限定词之间均采用中划线（-）连接。例如：mcc460_mnc00-zh_Hant_CN、zh_CN-car-ldpi。

• 限定词的取值范围：每类限定词的取值必须符合限定词取值要求表中的条件，如表1。否则，将无法匹配目录中的资源文件。

表1 限定词取值要求

rawfile目录

支持创建多层子目录，子目录名称可以自定义，文件夹内可以自由放置各类资源文件。
目录中的资源文件会被直接打包进应用，不经过编译，也不会分配资源ID。通过指定文件路径和文件名访问。

resfile目录

支持创建多层子目录，子目录名称可以自定义，文件夹内可以自由放置各类资源文件。
目录中的资源文件会被直接打包进应用，不经过编译，也不会分配资源ID。应用安装后，resfile资源会被解压到应用沙箱路径，通过Context属性resourceDir获取到resfile资源目录后，可通过文件路径访问，且该路径仅能以只读方式访问。

资源组目录

资源组目录包括element、media、profile三种类型的资源文件，用于存放特定类型资源。

表2 资源组目录说明

媒体资源类型说明

表3 图片资源类型说明

表4 音视频资源类型说明

资源文件示例

color.json文件的内容如下：

标准的十六进制颜色值由八位十六进制数字组成，前两位表示透明度，后六位表示颜色值。

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

float.json文件的内容如下：

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

string.json文件的内容如下：

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

plural.json文件的内容如下：

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

创建资源目录和资源文件

在resources目录下，可按照限定词目录命名规则和资源组目录支持的文件类型，创建资源目录和资源组目录，添加特定类型资源。DevEco Studio支持同时创建资源目录和资源文件，也支持单独创建资源目录或资源文件。

创建资源目录和资源文件

在resources目录右键菜单选择“New > Resource File”，可同时创建资源目录和资源文件，文件默认创建在base目录的对应资源组中。如果选择了限定词，则会按照命名规范自动生成限定词和资源组目录，并将文件创建在限定词目录中。

不同类型的限定词可以组合，如同时选择Locale为zh_CN，ColorMode为Dark，将创建zh_CN-dark目录，具体组合规则参考限定词目录。

图中File name为需要创建的文件名。Resource type为资源组类型，默认是element。Root Element为资源类型。Available qualifiers为供选择的限定词目录，通过右边的小箭头可添加或者删除。
创建的目录名自动生成，格式固定为“限定词.资源组”，例如：创建一个限定词为dark的element目录，自动生成的目录名称为“dark/element”。

创建资源目录

在resources目录右键菜单选择“New > Resource Directory”，可创建资源目录，默认创建的是base目录。如果选择了限定词，则会按照命名规范自动生成限定词和资源组目录。确定限定词后，选择资源组类型，当前资源组类型支持Element、Media、Profile三种，创建后生成资源目录。

创建资源文件

在资源组目录（element、media、profile）的右键菜单选择“New > XXX Resource File”，可创建对应资源组目录的资源文件。例如，在element目录下可新建Element Resource File。

示例

以创建中文和英文字符串资源文件为例，说明如何创建不同限定词的资源。

1. 在resources目录右键菜单选择“New > Resource File”，File name填写为string_sample，Resource type选择Element，Root Element选择string，Available qualifiers选中Locale，在右侧的语言列表中选择zh，地区列表中选择CN，将会在resources目录下创建zh_CN/element/string_sample.json文件。

2. 同理，语言选择en，地区选择US，创建en_US/element/string_sample.json文件。

最终创建的资源文件如下。资源文件创建完成后，如何访问资源文件请参见资源访问与相关实例。

资源可翻译特性

功能介绍

当应用引用的字符串资源需要支持国际化多语言翻译时，可使用attr属性标记字符串翻译范围和翻译状态。attr属性不参与资源编译，只标记字符串是否翻译。

未配置attr属性时，默认需要翻译。

attr支持属性

使用约束

可翻译特性使能范围：base目录下string、strarray、plural类型资源。

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

示例

string资源配置attr属性示例如下，其中string1字符串被标记为不需要翻译，string2字符串被标记为需要翻译且翻译已验证。

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

资源访问

单HAP包应用资源

• 通过$r或$rawfile访问资源。
  对于color、float、string、plural、media、profile等类型的资源，通过$r('app.type.name')形式访问。其中，app为resources目录中定义的资源，type为资源类型，name为资源名，由开发者定义资源时确定。
  对于string.json中使用多个占位符的情况，通过$r('app.string.label','aaa','bbb',444)形式访问。
  对于rawfile目录资源，通过$rawfile('filename')形式访问。其中，filename为rawfile目录下文件的相对路径，文件名需要包含后缀，路径开头不可以”/“开头。

说明：

rawfile的native的访问方式请参考Rawfile开发指导。

资源组目录下的“资源文件示例”显示了.json文件内容，包含color.json、string.json和plural.json，访问应用资源时需先了解.json文件的使用规范。
资源的具体使用方法如下：

    //通过$r('app.type.name')访问
    Text($r('app.string.string_hello'))
    .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'))

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

    //对占位符，通过$r('app.string.label','aaa','bbb',444)访问
    Text($r('app.string.message_notification','LiHua',2))

• 通过本应用上下文获取ResourceManager后，调用不同资源管理接口访问不同资源。例如：
  getContext().resourceManager.getStringByNameSync('test')可获取字符串资源。
  getContext().resourceManager.getRawFd('rawfilepath')可获取Rawfile所在hap包的descriptor信息，访问rawfile文件时需{fd, offset, length}一起使用。

跨HAP/HSP包应用资源

bundle不同，跨bundle访问（仅支持系统应用使用）

• 通过createBundleContext(context, bundleName)接口创建对应HAP/HSP包的上下文，获取resourceManager对象后，调用不同资源管理接口访问不同资源。

bundle相同，跨module访问

• 通过createModuleContext(context, moduleName)接口创建同应用中不同module的上下文，获取resourceManager对象后，调用不同资源管理接口访问不同资源。

• 通过$r或$rawfile访问资源。具体操作如下：

1.在entry的oh-package.json5文件中添加依赖。如"dependencies": {"library":"file":../library}。

2.使用字面量[hsp].type.name获取资源。其中，hsp为hsp模块名，type为资源类型，name为资源名称，示例如下：

```ts
  Text($r('[hsp].string.test_string'))
    .fontSize($r('[hsp].float.font_size'))
    .fontColor($r('[hsp].color.font_color'))  
  Image($rawfile('[hsp].icon.png'))
```

3.使用变量获取资源。示例如下：

    @Entry
    @Component
    struct Index {
      text: string = '[hsp].string.test_string';
      fontSize: string = '[hsp].float.font_size';
      fontColor: string = '[hsp].color.font_color';
      image: string = '[hsp].media.string';
      rawfile: string = '[hsp].icon.png';
  
      build() {
        Row() {
          Text($r(this.text))
            .fontSize($r(this.fontSize))
            .fontColor($r(this.fontColor))
  
          Image($r(this.image))
  
          Image($rawfile(this.rawfile))
        }
      }
    }

说明

hsp包名必须写在[]内，rawfile下有多层目录，需要从rawfile下面第一个目录开始写，如$rawfile('[hsp].oneFile/twoFile/icon.png')，使用$r和$rawfile跨包访问HSP包资源无法提供编译时的资源校验，需要开发者自行保证使用资源存在于对应包中。

系统资源

开发者可以通过主题图标库获取系统图标资源信息、通过系统资源分层设计表获取系统字体等资源信息。获取的图标资源可通过SymbolGlyph对图标颜色等进一步设置。

对于系统资源，可以通过$r('sys.type.name')的形式访问。其中，sys表示系统资源，type为资源类型，取值包括“color”、“float”、“string”、“media”、“symbol”，name为资源名称。

说明：

• 仅声明式开发范式支持使用系统资源。

• 对于系统预置应用，建议使用系统资源；对于三方应用，可以根据需要选择使用系统资源或自定义应用资源。

• 当前，界面显示时默认使用的系统字体是鸿蒙黑体（HarmonyOS Sans），支持的字符范围是中文编码字符集GB18030-2022（级别一/级别二）。若要显示的字符不在鸿蒙黑体支持的字符范围内，系统会在其他支持该字符的字体中选择优先级最高的字体用来显示。关于系统字体的优先级顺序，可以查看设备上的配置文件system/etc/fontconfig.json。

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)

资源匹配

应用使用某资源时，系统会根据当前设备状态优先从相匹配的限定词目录中寻找该资源。只有当resources目录中没有与设备状态匹配的限定词目录，或者在限定词目录中找不到该资源时，才会去base目录中查找。rawfile和resfile是原始文件目录，不会根据设备状态去匹配资源。

限定词目录与设备状态的匹配规则

• 在为设备匹配对应的资源文件时，限定词目录匹配的优先级从高到低依次为：移动国家码和移动网络码 > 区域（可选组合：语言、语言_文字、语言_国家或地区、语言_文字_国家或地区）> 横竖屏 > 设备类型 > 颜色模式 > 屏幕密度。

• 如果限定词目录中包含移动国家码和移动网络码、语言、文字、横竖屏、设备类型、颜色模式限定词，则对应限定词的取值必须与当前的设备状态完全一致，该目录才能够参与设备的资源匹配。例如，限定词目录zh_CN-car-ldpi不能参与en_US设备的资源匹配。

• 如果存在多个屏幕密度限定词目录，则优先向上匹配最接近的屏幕密度限定词目录，否则向下匹配最为接近的屏幕密度限定词目录。例如，假设存在限定词目录xldpi和xxldpi，设备屏幕密度为xxldpi，则会匹配xxldpi限定词目录。

关于应用界面加载资源的更多规则，请参考国际化和本地化文档。

获取指定配置的资源

基本概念

开发者可以在工程的resources目录下添加限定词目录，满足多语言、深浅色模式等不同类型的系统设置。然而，在获取资源时，由于限定词目录匹配规则，只能筛选出最匹配的资源，无法获取其它目录资源。

应用如果有获取指定配置的资源的诉求，可以通过以下方法进行获取。

接口说明

示例

以获取非当前系统语言的资源为例，说明如何获取指定配置的资源。假设工程中定义了中文、英文、德文的同名资源如下：

• 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/de_DE/element/string.json

{
  "string": [
    {
      "name": "greetings",
      "value": "Hallo, Welt"
    }
  ]
}

在Index.ets中，分别获取三种语言的资源并显示在文本框中，运行设备当前系统语言为中文，entry/src/main/ets/pages/Index.ets的代码如下：

import { common } from '@kit.AbilityKit'

@Entry
@Component
struct Index {
  @State englishString: string = ""
  @State germanString: string = ""

  getString(): string {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext
    let resMgr = context.resourceManager
    let resId = $r('app.string.greetings').id

    //获取符合当前系统语言地区、颜色模式、分辨率等配置的资源
    let currentLanguageString = resMgr.getStringSync(resId)

    //获取符合当前系统颜色模式、分辨率等配置的英文资源
    let overrideConfig = resMgr.getOverrideConfiguration()
    overrideConfig.locale = "en_US" //指定资源的语言为英语，地区为美国
    let overrideResMgr = resMgr.getOverrideResourceManager(overrideConfig)
    this.englishString = overrideResMgr.getStringSync(resId)

    //获取符合当前系统颜色模式、分辨率等配置的德文资源
    overrideConfig.locale = "de_DE" //指定资源的语言为德语，地区为德国
    overrideResMgr.updateOverrideConfiguration(overrideConfig) //等效于resMgr.updateOverrideConfiguration(overrideConfig)
    this.germanString = overrideResMgr.getStringSync(resId)

    return currentLanguageString
  }

  build() {
    Row() {
      Column() {
        Text(this.getString())
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        Text(this.englishString)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        Text(this.germanString)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

overlay机制

overlay是一种资源替换机制，针对不同品牌、产品的显示风格，开发者可以在不重新打包HAP的情况下，通过配置和使用overlay资源包，实现应用界面风格变换。overlay资源包只包含资源文件、资源索引文件和配置文件。

动态overlay使用方式

1、对应的overlay资源包需要放在对应应用安装路径下，通过hdc install的方式安装。如应用com.example.overlay的安装路径为data/app/el1/bundle/public/com.example.overlay/。

2、应用通过addResource(path)，实现资源覆盖；通过removeResource(path)，实现overlay删除。overlay资源路径需经过元能力的getContext().bundleCodeDir获取此应用对应的沙箱根目录，由应用的沙箱根目录与overlay资源包名称拼接而成。如：let path = getContext().bundleCodeDir + "overlay资源包名称"，其对应沙箱路径为/data/storage/el1/bundle/overlay资源包名称。

静态overlay配置方式

包内overlay资源包中的配置文件app.json5中支持的字段： “`{ “app”:{ “bundleName”: “com.example.myapplication.overlay”, “vendor” : “example”, “versionCode”: “1000000”, “versionName”: “1.0.0.1”, “icon”: “$media:app_icon”, “label”: “$string:app_name”, } }

包内overlay资源包中的配置文件module.json5中支持的字段：
```{
  "module":{
    "name": "entry_overlay_module_name",
    "type": "shared",
    "description": "$string:entry_overlay_desc",
    "deviceTypes": [
      "default",
      "tablet",
    ],
    "deliverywithInstall": true,

    "targetModuleName": "entry_module_name",
    "targetPriority": 1,
  }
}

包间overlay资源包中的配置文件app.json5中支持的字段，仅对系统应用开放： “`{ “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, } }

包间overlay资源包中的配置文件module.json5中支持的字段，仅对系统应用开放：
```{
  "module":{
    "name": "entry_overlay_module_name",
    "type": "shared",
    "description": "$string:entry_overlay_desc",
    "deviceTypes": [
      "default",
      "tablet",
    ],
    "deliverywithInstall": true,

    "targetModuleName": "entry_module_name",
    "targetPriority": 1,
  }
}

说明： > - targetBundleName: 字符串类型，指定要overlay的bundleName。 > - targetModuleName: 字符串类型，指定要overlay的应用中的目标module。

• targetPriority： 整数类型，指定overlay优先级。

• 不支持Ability、ExtensionAbility、Permission等其他字段的配置。

• overlay不支持json类型的图片配置。

在DevEco Studio中创建应用工程时，module的配置文件module.json5中包含targetModuleName和targetPriority字段时，该module将会在安装阶段被识别为overlay特征的module。overlay特征的module一般是为设备上存在的非overlay特征的module提供覆盖的资源文件，以便于targetModuleName指向的module在运行阶段可以使用overlay资源文件展示不同的颜色，标签，主题等等。

该功能默认使能，使能及去使能请参考包管理接口。

相关实例

针对访问应用资源，有以下相关实例可供参考：

• 资源管理（ArkTS）（API10）

你可能感兴趣的鸿蒙文章

harmony 鸿蒙入门

harmony 鸿蒙创建应用分身

harmony 鸿蒙app.json5配置文件

harmony 鸿蒙app对象内部结构

harmony 鸿蒙应用配置文件概述（FA模型）

harmony 鸿蒙应用配置文件概述（Stage模型）

harmony 鸿蒙应用程序包术语

harmony 鸿蒙应用安装卸载与更新开发指导

harmony 鸿蒙应用程序包概述

harmony 鸿蒙FA模型应用程序包结构