1# 资源分类与访问 2 3<!--Kit: Localization Kit--> 4<!--Subsystem: Global--> 5<!--Owner: @liule_123--> 6<!--Designer: @buda_wy--> 7<!--Tester: @lpw_work--> 8<!--Adviser: @Brilliantry_Rui--> 9 10应用开发过程中，需要使用字符串、颜色、字体、间距和图标等资源。不同设备或配置下，这些资源的值会有所不同。本文档对资源类型进行介绍，并提供资源开发指导。 11根据来源差异，可以将资源分为： 12 13- 应用资源：开发者在应用中自定义的资源，可以利用资源文件管理资源在不同的设备或配置中的表现。 14- 系统资源：系统提供的资源，开发者可以通过[主题图标库](https://developer.huawei.com/consumer/cn/design/harmonyos-symbol/)获取系统symbol图标资源信息、通过[系统资源分层设计表](https://gitcode.com/openharmony/docs/blob/master/zh-cn/design/ux-design/design-resources.md)获取系统颜色、间距、圆角等资源信息。此外，系统颜色资源还可以通过[系统色彩全量表](https://developer.huawei.com/consumer/cn/doc/design-guides/color-0000001776857164#section17672143841113)获取，系统色彩全量表与系统资源分层设计表内的资源不重合，均为推荐使用的系统颜色资源。<br>表格中未列出的其他系统资源均为系统组件和底层能力参数，推荐开发者优先使用上述表格中提供的系统资源。 15 16## 资源分类 17 18应用开发中使用的各类资源文件，需要放入特定子目录中存储管理。目录结构如下所示，base目录、限定词目录、rawfile目录、resfile目录称为资源目录，element、media、profile称为资源组目录。 19 20``` 21resources 22|---base // 默认存在的目录 23| |---element 24| | |---string.json // 字符串资源 25| |---media 26| | |---icon.png // 图片、视频等媒体资源文件 27| |---profile 28| | |---test_profile.json // 自定义profile文件，文件内容可自定义 29|---en_GB-vertical-car-mdpi // 自定义限定词目录示例，由开发者创建 30| |---element 31| | |---string.json 32| |---media 33| | |---icon.png 34| |---profile 35| | |---test_profile.json 36|---rawfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。 37|---resfile // 其他类型文件，原始文件形式保存，不会被集成到resources.index文件中。文件名可自定义。 38``` 39> **说明** 40> 41> - 资源目录和资源组目录下的文件均被视为资源文件，在应用打包时不会进行混淆。 42> 43> - stage模型多工程情况下，共有的资源文件放到AppScope下的resources目录。 44> 45> - 在编译构建时，AppScope目录下的资源文件会合入到模块下面的资源文件中，如果两个目录下的相同资源目录和资源组目录下存在重名资源，编译打包后只会保留AppScope目录下的资源。 46 47### 资源目录 48 49表1 资源目录说明 50 51| 目录类型 | 说明 | 52|--- | --- | 53| base目录 | base目录默认存在。二级子目录element用于存放字符串、颜色、布尔值等基础元素，media和profile子目录存放媒体、动画、布局等资源文件。<br/>目录中的资源文件会被编译成二进制文件，并分配资源ID。通过指定资源类型（type）和资源名称（name）来访问。 | 54| 限定词目录 | 限定词目录需要开发者根据开发需要自行创建，二级子目录element用于存放字符串、颜色、布尔值等基础元素，media和profile子目录存放媒体、动画、布局等资源文件。<br/>同样，目录中的资源文件会被编译成二进制文件，并分配资源ID。通过指定资源类型（type）和资源名称（name）来访问。限定词的含义和取值范围以及限定词目录的命名规则请参考下方[限定词目录](#限定词目录)中的说明。 | 55| rawfile目录 | 支持创建多层子目录，子目录名称可以自定义，文件夹内可以自由放置各类资源文件。<br/>目录中的资源文件会被直接打包进应用，不经过编译，也不会分配资源ID。通过指定文件路径和文件名访问。 | 56| resfile目录 | 支持创建多层子目录，子目录名称可以自定义，文件夹内可以自由放置各类资源文件。<br/>目录中的资源文件会被直接打包进应用，不经过编译，也不会分配资源ID。应用安装后，resfile资源会被解压到应用沙箱路径，通过Context属性[resourceDir](../reference/apis-ability-kit/js-apis-inner-application-context.md#属性)获取到resfile资源目录后，可通过文件路径访问，且该路径仅能以只读方式访问。 | 57 58### 资源组目录 59 60表2 资源组目录说明 61 62| 目录类型 | 说明 | 资源文件 | 63| --------- | ---------------------------------------- | ---------------------------------------- | 64| element | 表示元素资源，以下每一类数据都采用相应的JSON文件来表征（目录下仅支持文件类型）。<br/>- boolean，布尔型<br/>- color，颜色<br/>- float，浮点型，范围是`-2^128到2^128`<br/>- intarray，整型数组<br/>- integer，整型，范围是`-2^31到2^31-1`<br/>- plural，复数形式<br/>- strarray，字符串数组<br/>- string，字符串，[格式化字符串请参考API文档](../reference/apis-localization-kit/js-apis-resource-manager.md#getstringsync10)<!--Del--><br/>- pattern，样式（仅支持系统应用使用）<!--DelEnd--><!--Del--><br/>- theme，主题（仅支持系统应用使用）<!--DelEnd-->| element目录中的文件名称建议与下面的文件名保持一致。每个文件中只能包含同一类型的数据。<br/>- boolean.json<br/>- color.json<br/>- float.json<br/>- intarray.json<br/>- integer.json<br/>- plural.json<br/>- strarray.json<br/>- string.json<!--Del--><br/>- pattern.json<!--DelEnd--><!--Del--><br/>- theme.json<!--DelEnd--> | 65| media | 表示媒体资源，包括图片、音频、视频等非文本格式的文件（目录下只支持文件类型）。<br/>图片和音视频的类型说明见表3和表4。 | 文件名可自定义，例如：icon.png。 | 66| profile | 表示自定义配置文件，其文件内容可[通过包管理接口](../reference/apis-ability-kit/js-apis-bundleManager.md#bundlemanagergetprofilebyability)获取（目录下只支持json文件类型）。 | 文件名可自定义，例如：test_profile.json。 | 67 68**媒体资源类型说明** 69 70表3 图片资源类型说明 71 72| 格式 | 文件后缀名 | 73| ---- | ----- | 74| JPEG | .jpg | 75| PNG | .png | 76| GIF | .gif | 77| SVG | .svg | 78| WEBP | .webp | 79| BMP | .bmp | 80 81表4 音视频资源类型说明 82 83| 格式 | 支持的文件类型 | 84| ------------------------------------ | --------------- | 85| H.264 AVC |.3gp | 86| Baseline Profile (BP) | .mp4 | 87 88 89### 限定词目录 90 91限定词目录由一个或多个表征应用场景或设备特征的限定词组合而成，限定词包括移动国家码和移动网络码、语言、文字、国家或地区、横竖屏、设备类型、颜色模式和屏幕密度，限定词之间通过下划线（\_）或者中划线（\-）连接。开发者在创建限定词目录时，需要遵守如下限定词目录命名规则。 92 93- 限定词的组合顺序：移动国家码_移动网络码-语言_文字_国家或地区-横竖屏-设备类型-颜色模式-屏幕密度。开发者可以根据应用的使用场景和设备特征，选择其中的一类或几类限定词组成目录名称。 94 95- 限定词的连接方式：移动国家码和移动网络码之间采用下划线（\_）连接，语言、文字、国家或地区之间也采用下划线（\_）连接，除此之外的其他限定词之间均采用中划线（-）连接。例如：**mcc460_mnc00-zh_Hant_CN**、**zh_CN-car-ldpi**。 96 97- 限定词的取值范围：每类限定词的取值必须符合限定词取值要求表中的条件，如表5。否则，将无法匹配目录中的资源文件。 98 99表5 限定词取值要求 100 101| 限定词类型 | 含义与取值说明 | 102| ----------- | ---------------------------------------- | 103| 移动国家码和移动网络码 | 移动国家码（MCC）和移动网络码（MNC）的值取自设备注册的网络。<br/>MCC可与MNC合并使用，使用下划线（_）连接，也可以单独使用。例如：mcc460表示中国，mcc460_mnc00表示中国_中国移动。<br/>详细取值范围，请查阅[**ITU-T E.212**](https://www.itu.int/rec/T-REC-E.212)（国际电联相关标准）。 | 104| 语言 | 表示设备使用的语言类型，由2~3个小写字母组成。例如：zh表示中文，en表示英语，mai表示迈蒂利语。<br/>详细取值范围，请查阅[**ISO 639**](https://www.iso.org/iso-639-language-code)（ISO制定的语言编码标准）。 | 105| 文字 | 表示设备使用的文字类型，由1个大写字母（首字母）和3个小写字母组成。例如：Hans表示简体中文，Hant表示繁体中文。<br/>详细取值范围，请查阅[**ISO 15924**](https://www.iso.org/standard/81905.html)（ISO制定的文字编码标准）。 | 106| 国家或地区 | 表示用户所在的国家或地区，由2~3个大写字母或者3个数字组成。例如：CN表示中国，GB表示英国。<br/>详细取值范围，请查阅[**ISO 3166-1**](https://www.iso.org/iso-3166-country-codes.html)（ISO制定的国家和地区编码标准）。 | 107| 横竖屏 | 表示设备的屏幕方向，取值如下：<br/>- vertical：竖屏<br/>- horizontal：横屏 | 108| 设备类型 | <!--RP1-->表示设备的类型，取值如下：<br/>- car：车机<br/>- tablet：平板<br/>- tv：智慧屏<br/>- wearable：智能穿戴<!--RP1End--> | 109| 颜色模式 | 表示设备的颜色模式，取值如下：<br/>- dark：深色模式<br/>- light：浅色模式 | 110| 屏幕密度 | 表示设备的屏幕密度（单位为dpi），取值如下：<br/>- sdpi：表示小规模的屏幕密度（Small-scale Dots Per Inch），适用于dpi取值为(0, 120]的设备。<br/>- mdpi：表示中规模的屏幕密度（Medium-scale Dots Per Inch），适用于dpi取值为(120, 160]的设备。<br/>- ldpi：表示大规模的屏幕密度（Large-scale Dots Per Inch），适用于dpi取值为(160, 240]的设备。<br/>- xldpi：表示特大规模的屏幕密度（Extra Large-scale Dots Per Inch），适用于dpi取值为(240, 320]的设备。<br/>- xxldpi：表示超大规模的屏幕密度（Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(320, 480]的设备。<br/>- xxxldpi：表示超特大规模的屏幕密度（Extra Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(480, 640]的设备。 | 111 112### 资源文件示例 113 114color.json文件的内容如下： 115 116标准的十六进制颜色值由八位十六进制数字组成，前两位表示透明度，后六位表示颜色值。 117```json 118{ 119 "color": [ 120 { 121 "name": "color_hello", 122 "value": "#ffff0000" 123 }, 124 { 125 "name": "color_world", 126 "value": "#ff0000ff" 127 } 128 ] 129} 130``` 131 132float.json文件的内容如下： 133 134```json 135{ 136 "float": [ 137 { 138 "name": "font_hello", 139 "value": "28.0fp" 140 }, 141 { 142 "name": "font_world", 143 "value": "20.0fp" 144 } 145 ] 146} 147``` 148 149string.json文件的内容如下： 150 151```json 152{ 153 "string": [ 154 { 155 "name": "string_hello", 156 "value": "Hello" 157 }, 158 { 159 "name": "string_world", 160 "value": "World" 161 }, 162 { 163 "name": "message_arrive", 164 "value": "We will arrive at %1$s." 165 }, 166 { 167 "name": "message_notification", 168 "value": "Hello, %1$s!,You have %2$d new messages." 169 } 170 ] 171} 172``` 173 174plural.json文件的内容如下： 175 176```json 177{ 178 "plural": [ 179 { 180 "name": "eat_apple", 181 "value": [ 182 { 183 "quantity": "one", 184 "value": "%d apple" 185 }, 186 { 187 "quantity": "other", 188 "value": "%d apples" 189 } 190 ] 191 } 192 ] 193} 194``` 195 196## 创建资源目录和资源文件 197 198在resources目录下，可按照限定词目录命名规则和资源组目录支持的文件类型，创建资源目录和资源组目录，添加特定类型资源。DevEco Studio支持同时创建资源目录和资源文件，也支持单独创建资源目录或资源文件。 199 200### 创建资源目录和资源文件 201 202在resources目录右键菜单选择“New > Resource File”，可同时创建资源目录和资源文件，文件默认创建在base目录的对应资源组中。如果选择了限定词，则会按照命名规范自动生成限定词和资源组目录，并将文件创建在限定词目录中。 203 204不同类型的限定词可以组合，如同时选择Locale为zh_CN，ColorMode为Dark，将创建zh_CN-dark目录，具体组合规则参考[限定词目录](#限定词目录)。 205 206图中File name为需要创建的文件名。Resource type为资源组类型，默认是element。Root Element为资源类型。Available qualifiers为供选择的限定词目录，通过右边的小箭头可添加或者删除。<br/>创建的目录名自动生成，格式固定为“限定词.资源组”，例如：创建一个限定词为dark的element目录，自动生成的目录名称为“dark/element”。 207 208  209 210### 创建资源目录 211 212在resources目录右键菜单选择“New > Resource Directory”，可创建资源目录，默认创建的是base目录。如果选择了限定词，则会按照命名规范自动生成限定词和资源组目录。确定限定词后，选择资源组类型，当前资源组类型支持Element、Media、Profile三种，创建后生成资源目录。 213 214  215 216### 创建资源文件 217 218在资源组目录（element、media、profile）的右键菜单选择“New > XXX Resource File”，可创建对应资源组目录的资源文件。例如，在element目录下可新建Element Resource File。 219 220  221 222### 示例 223 224以创建中文和英文字符串资源文件为例，说明如何创建不同限定词的资源。 225 2261. 在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文件。 227  228 2292. 同理，语言选择en，地区选择US，创建en_US/element/string_sample.json文件。 230 231最终创建的资源文件如下。资源文件创建完成后，如何访问资源文件请参见[资源访问](#资源访问)<!--Del-->与[相关实例](#相关实例)<!--DelEnd-->。 232 233 234 235## 资源可翻译特性 236 237### 功能介绍 238 239当应用引用的字符串资源需要支持国际化多语言翻译时，可使用attr属性标记字符串翻译范围和翻译状态。attr属性不参与资源编译，只标记字符串是否翻译。 240 241未配置attr属性时，默认需要翻译。 242 243**attr支持属性** 244 245| 名称 | 类型 | 说明 | 246| --------- | ----------------------- | ---- | 247| translatable | boolean | 标记字符串是否需要翻译。 <br> true：需要翻译。 <br> false：不需要翻译。| 248| priority | string | 标记字符串翻译状态。<br>code：未翻译。<br>translate：翻译未验证。<br>LT：翻译已验证。<br>customer：用户定制字符串。 | 249 250### 使用约束 251可翻译特性使能范围：base目录下string、strarray、plural类型资源。 252``` 253resources 254|---base 255| |---element 256| | |---string.json 257| | |---strarray.json 258| | |---plural.json 259``` 260### 示例 261string资源配置attr属性示例如下，其中string1字符串被标记为不需要翻译，string2字符串被标记为需要翻译且翻译已验证。 262 263```json 264{ 265 "string": [ 266 { 267 "name": "string1", 268 "value": "1", 269 "attr": { 270 "translatable": false 271 } 272 }, 273 { 274 "name": "string2", 275 "value": "Hello world!", 276 "attr": { 277 "translatable": true, 278 "priority": "LT" 279 } 280 } 281 ] 282} 283``` 284 285## 资源访问 286 287### 单HAP包应用资源 288 289 - 通过`$r`或`$rawfile`访问资源。<br/>对于color、float、string、plural、media、profile等类型的资源，通过`$r('app.type.name')`形式访问。其中，app为resources目录中定义的资源，type为资源类型，name为资源名，由开发者定义资源时确定。<br/>对于string.json中使用多个占位符的情况，例如资源值value中存在`$s`和`$d`两个占位符，需要通过`$r('app.string.label', 'aaa', 444)`形式访问。其中label为资源名称name，'aaa'和444用来替代占位符。<br/>对于rawfile目录资源，通过`$rawfile('filename')`形式访问。其中，filename为rawfile目录下文件的相对路径，文件名需要包含后缀，路径开头不可以"/"开头。 290 291 > **说明：** 292 > 293 > rawfile的native的访问方式请参考[Rawfile开发指导](../napi/rawfile-guidelines.md)。 294 295 [资源文件示例](#资源文件示例)中显示了.json文件内容，包含color.json、string.json和plural.json，访问应用资源时需先了解.json文件的使用规范。<br/>资源的具体使用方法如下： 296 297 ```ts 298 //通过$r('app.type.name')访问 299 Text($r('app.string.string_hello')) 300 .fontColor($r('app.color.color_emphasize')) 301 .fontSize($r('app.float.text_size_headline1')) 302 .fontFamily($r('app.string.font_family_medium')) 303 .backgroundColor($r('app.color.color_palette_aux1')) 304 305 Image($r('app.media.app_icon')) 306 .border({ 307 color: $r('app.color.color_palette_aux1'), 308 radius: $r('app.float.corner_radius_button'), width: 2 309 }) 310 .margin({ 311 top: $r('app.float.elements_margin_horizontal_m'), 312 bottom: $r('app.float.elements_margin_horizontal_l') 313 }) 314 .height(200) 315 .width(300) 316 317 // 对于string.json中name为"message_notification"，value为"Hello, %1$s!,You have %2$d new messages." 318 // 该资源存在$s、$d两个占位符，需要替代为'LiHua'、2，则采用如下方式访问 319 Text($r('app.string.message_notification', 'LiHua', 2)) 320 ``` 321 322- 通过本应用上下文获取ResourceManager后，可调用不同[资源管理接口](../reference/apis-localization-kit/js-apis-resource-manager.md)通过资源ID值或资源名称访问各类资源。例如：<br/>`getContext().resourceManager.getStringByNameSync('test')`可获取字符串资源。<br/>`getContext().resourceManager.getRawFd('rawfilepath')`可获取Rawfile所在hap包的descriptor信息，访问rawfile文件时需{fd, offset, length}一起使用。 323 324### 跨HAP/HSP包应用资源 325 326<!--Del--> 327**bundle不同，跨bundle访问（仅支持系统应用使用）** 328 329- 通过[createBundleContext(context, bundleName)](../reference/apis-ability-kit/js-apis-app-ability-application-sys.md#applicationcreatebundlecontext12)接口创建对应HAP/HSP包的上下文，获取resourceManager对象后，调用不同[资源管理接口](../reference/apis-localization-kit/js-apis-resource-manager.md)通过资源ID值或资源名称访问各类资源。 330<!--DelEnd--> 331 332**bundle相同，跨module访问** 333 334- 通过[createModuleContext(context, moduleName)](../reference/apis-ability-kit/js-apis-app-ability-application.md#applicationcreatemodulecontext12)接口创建同应用中不同module的上下文，获取resourceManager对象后，调用不同[资源管理接口](../reference/apis-localization-kit/js-apis-resource-manager.md)通过资源ID值或资源名称访问各类资源。 335 336- 通过`$r`或`$rawfile`访问资源。具体操作如下： 337 338 1.在entry的oh-package.json5文件中添加依赖。如`"dependencies": {"library": "file:../library"}`。 339 340  341 342 2.使用字面量`[hsp].type.name`获取资源。其中，hsp为hsp模块名，type为资源类型，name为资源名称，示例如下： 343 344 ```ts 345 Text($r('[hsp].string.test_string')) 346 .fontSize($r('[hsp].float.font_size')) 347 .fontColor($r('[hsp].color.font_color')) 348 Image($rawfile('[hsp].icon.png')) 349 ``` 350 3.使用变量获取资源。示例如下： 351 352 ```ts 353 @Entry 354 @Component 355 struct Index { 356 text: string = '[hsp].string.test_string'; 357 fontSize: string = '[hsp].float.font_size'; 358 fontColor: string = '[hsp].color.font_color'; 359 image: string = '[hsp].media.string'; 360 rawfile: string = '[hsp].icon.png'; 361 362 build() { 363 Row() { 364 Text($r(this.text)) 365 .fontSize($r(this.fontSize)) 366 .fontColor($r(this.fontColor)) 367 368 Image($r(this.image)) 369 370 Image($rawfile(this.rawfile)) 371 } 372 } 373 } 374 ``` 375 > **说明** 376 > 377 > hsp包名必须写在[]内，rawfile下有多层目录，需要从rawfile下面第一个目录开始写，如`$rawfile('[hsp].oneFile/twoFile/icon.png')`，使用`$r`和`$rawfile`跨包访问HSP包资源无法提供编译时的资源校验，需要开发者自行保证使用资源存在于对应包中。 378 379 380### 系统资源 381 382开发者可以通过[主题图标库](https://developer.huawei.com/consumer/cn/design/harmonyos-symbol/)获取系统symbol图标资源信息、通过[系统资源分层设计表](https://gitcode.com/openharmony/docs/blob/master/zh-cn/design/ux-design/design-resources.md)获取系统颜色、间距、圆角等资源信息。此外，系统颜色资源还可以通过[系统色彩全量表](https://developer.huawei.com/consumer/cn/doc/design-guides/color-0000001776857164#section17672143841113)获取，系统色彩全量表与系统资源分层设计表内的资源不重合，均为推荐使用的系统颜色资源。 383获取的symbol图标资源可通过[SymbolGlyph](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md)对图标颜色等进一步设置。 384 385对于系统资源，可以通过`$r('sys.type.name')`的形式访问。其中，sys表示系统资源，type为资源类型，取值包括“color”、“float”、“string”、“media”、“symbol”，name为资源名称。 386 387> **说明：** 388> - 上述表格中未列出的其他系统资源均为系统组件和底层能力参数，推荐开发者优先使用上述表格中提供的系统资源。 389> 390> - 对于系统预置应用，建议使用系统资源；对于三方应用，可以根据需要选择使用系统资源或自定义应用资源。 391> 392> - 仅声明式开发范式支持使用系统资源。 393> 394> - 当前，界面显示时默认使用的系统字体是鸿蒙黑体（HarmonyOS Sans），支持的字符范围是[中文编码字符集GB18030-2022（级别一/级别二）](https://openstd.samr.gov.cn/bzgk/gb/newGbInfo?hcno=A1931A578FE14957104988029B0833D3)。若要显示的字符不在鸿蒙黑体支持的字符范围内，系统会在其他支持该字符的字体中选择优先级最高的字体用来显示。关于系统字体的优先级顺序，可以查看设备上的配置文件`system/etc/fontconfig.json`。 395 396```ts 397Text('Hello') 398 .fontColor($r('sys.color.ohos_id_color_emphasize')) 399 .fontSize($r('sys.float.ohos_id_text_size_headline1')) 400 .fontFamily($r('sys.string.ohos_id_text_font_family_medium')) 401 .backgroundColor($r('sys.color.ohos_id_color_palette_aux1')) 402 403Image($r('sys.media.ohos_app_icon')) 404 .border({ 405 color: $r('sys.color.ohos_id_color_palette_aux1'), 406 radius: $r('sys.float.ohos_id_corner_radius_button'), width: 2 407 }) 408 .margin({ 409 top: $r('sys.float.ohos_id_elements_margin_horizontal_m'), 410 bottom: $r('sys.float.ohos_id_elements_margin_horizontal_l') 411 }) 412 .height(200) 413 .width(300) 414``` 415 416## 资源匹配 417 418应用使用某资源时，系统会根据当前设备状态优先从相匹配的限定词目录中寻找该资源。只有当resources目录中没有与设备状态匹配的限定词目录，或者在限定词目录中找不到该资源时，才会去base目录中查找。rawfile和resfile是原始文件目录，不会根据设备状态去匹配资源。 419 420> **说明** 421> 422> - 在编译构建时，AppScope目录下的资源文件会合入到模块下面的资源文件中，如果两个目录下的相同资源目录和资源组目录下存在重名资源，编译打包后只会保留AppScope目录下的资源。 423 424### 限定词目录与设备状态的匹配规则 425 426- 在为设备匹配对应的资源文件时，限定词目录匹配的优先级从高到低依次为：移动国家码和移动网络码 > 区域（可选组合：语言、语言_文字、语言_国家或地区、语言_文字_国家或地区）> 横竖屏 > 设备类型 > 颜色模式 > 屏幕密度。 427 428- 如果限定词目录中包含移动国家码和移动网络码、语言、文字、横竖屏、设备类型、颜色模式限定词，则对应限定词的取值必须与当前的设备状态完全一致，该目录才能够参与设备的资源匹配。例如，限定词目录`zh_CN-car-ldpi`不能参与`en_US`设备的资源匹配。 429 430- 如果存在多个屏幕密度限定词目录，则优先向上匹配最接近的屏幕密度限定词目录，否则向下匹配最为接近的屏幕密度限定词目录。例如，假设存在限定词目录`xldpi`和`xxldpi`，设备屏幕密度为`xxldpi`，则会匹配`xxldpi`限定词目录。 431 432关于应用界面加载资源的更多规则，请参考[国际化和本地化](../internationalization/i18n-l10n.md)文档。 433 434### 获取指定配置的资源 435 436**基本概念** 437 438开发者可以在工程的resources目录下添加限定词目录，满足多语言、深浅色模式等不同类型的系统设置。然而，在获取资源时，由于限定词目录匹配规则，只能筛选出最匹配的资源，无法获取其它目录资源。 439 440应用如果有获取指定配置的资源的诉求，可以通过以下方法进行获取。 441 442**接口说明** 443 444| 接口名 | 描述 | 445| ------------------------------------------------------------ | ------------------------------------------------------------ | 446| [getOverrideResourceManager](../reference/apis-localization-kit/js-apis-resource-manager.md#getoverrideresourcemanager12)(configuration?: [Configuration](../reference/apis-localization-kit/js-apis-resource-manager.md#configuration)) : [ResourceManager](../reference/apis-localization-kit/js-apis-resource-manager.md#resourcemanager) | 获取可以加载指定配置的资源的资源管理对象，使用同步方式返回。 | 447| [getOverrideConfiguration](../reference/apis-localization-kit/js-apis-resource-manager.md#getoverrideconfiguration12)() : [Configuration](../reference/apis-localization-kit/js-apis-resource-manager.md#configuration) | 获取指定的配置，使用同步方式返回。 | 448| [updateOverrideConfiguration](../reference/apis-localization-kit/js-apis-resource-manager.md#updateoverrideconfiguration12)(configuration: [Configuration](../reference/apis-localization-kit/js-apis-resource-manager.md#configuration)) : void | 更新指定的配置。 | 449 450**示例** 451 452以获取非当前系统语言的资源为例，说明如何获取指定配置的资源。假设工程中定义了中文、英文、日文的同名资源如下： 453 454- entry/src/main/resources/zh_CN/element/string.json 455 456```json 457{ 458 "string": [ 459 { 460 "name": "greetings", 461 "value": "你好，世界" 462 } 463 ] 464} 465``` 466 467- entry/src/main/resources/en_US/element/string.json 468 469```json 470{ 471 "string": [ 472 { 473 "name": "greetings", 474 "value": "Hello, world" 475 } 476 ] 477} 478``` 479 480- entry/src/main/resources/ja_JP/element/string.json 481 482```json 483{ 484 "string": [ 485 { 486 "name": "greetings", 487 "value": "こんにちは、世界" 488 } 489 ] 490} 491``` 492 493在`Index.ets`中，分别获取三种语言的资源并显示在文本框中，运行设备当前系统语言为中文，`entry/src/main/ets/pages/Index.ets`的代码如下： 494 495```ts 496import { common } from '@kit.AbilityKit'; 497import { BusinessError } from '@kit.BasicServicesKit'; 498 499@Entry 500@Component 501struct Index { 502 @State englishString: string = ""; 503 @State germanString: string = ""; 504 505 getString(): string { 506 let resMgr = this.getUIContext().getHostContext()?.resourceManager; 507 if (!resMgr) { 508 return ""; 509 } 510 let currentLanguageString: string = ""; 511 try { 512 let resId = $r('app.string.greetings').id; 513 514 //获取符合当前系统语言地区、颜色模式、分辨率等配置的资源 515 currentLanguageString = resMgr.getStringSync(resId); 516 517 //获取符合当前系统颜色模式、分辨率等配置的英文资源 518 let overrideConfig = resMgr.getOverrideConfiguration(); 519 overrideConfig.locale = "en_US"; //指定资源的语言为英语，地区为美国 520 let overrideResMgr = resMgr.getOverrideResourceManager(overrideConfig); 521 this.englishString = overrideResMgr.getStringSync(resId); 522 523 //获取符合当前系统颜色模式、分辨率等配置的日文资源 524 overrideConfig.locale = "ja_JP"; //指定资源的语言为日文，地区为日本 525 overrideResMgr.updateOverrideConfiguration(overrideConfig); //等效于resMgr.updateOverrideConfiguration(overrideConfig) 526 this.germanString = overrideResMgr.getStringSync(resId); 527 } catch (err) { 528 const code = (err as BusinessError).code; 529 const message = (err as BusinessError).message; 530 console.error(`get override resource failed, error code: ${code}, error msg: ${message}`); 531 } 532 return currentLanguageString; 533 } 534 535 build() { 536 Row() { 537 Column() { 538 Text(this.getString()) 539 .fontSize(50) 540 .fontWeight(FontWeight.Bold) 541 Text(this.englishString) 542 .fontSize(50) 543 .fontWeight(FontWeight.Bold) 544 Text(this.germanString) 545 .fontSize(50) 546 .fontWeight(FontWeight.Bold) 547 } 548 .width('100%') 549 } 550 .height('100%') 551 } 552} 553``` 554 555## overlay机制 556 557overlay是一种资源替换机制，针对不同品牌、产品的显示风格，开发者可以在不重新打包HAP的情况下，通过配置和使用overlay资源包，实现应用界面风格变换。overlay资源包只包含资源文件、资源索引文件和配置文件。 558 559### 动态overlay使用方式 560 5611. 对应的overlay资源包需要放在对应应用安装路径下。如应用`com.example.overlay`的安装路径为`data/app/el1/bundle/public/com.example.overlay/`。 5622. 应用通过[addResource(path)](../reference/apis-localization-kit/js-apis-resource-manager.md#addresource10)，实现资源覆盖；通过[removeResource(path)](../reference/apis-localization-kit/js-apis-resource-manager.md#removeresource10)，实现overlay删除。overlay资源路径需经过元能力的getContext().bundleCodeDir获取此应用对应的沙箱根目录，由应用的沙箱根目录与overlay资源包名称拼接而成。如：`let path = getContext().bundleCodeDir + "overlay资源包名称"`，其对应沙箱路径为`/data/storage/el1/bundle/overlay资源包名称`。 563 564### 静态overlay配置方式 565 566该功能默认使能，使能及去使能请参考[包管理接口](../reference/apis-ability-kit/js-apis-overlay.md)。 567 568包内overlay资源包中的配置文件app.json5中支持的字段： 569```json 570{ 571 "app":{ 572 "bundleName": "com.example.myapplication.overlay", 573 "vendor" : "example", 574 "versionCode": "1000000", 575 "versionName": "1.0.0.1", 576 "icon": "$media:app_icon", 577 "label": "$string:app_name" 578 } 579} 580``` 581包内overlay资源包中的配置文件module.json5中支持的字段： 582```json 583{ 584 "module":{ 585 "name": "entry_overlay_module_name", 586 "type": "shared", 587 "description": "$string:entry_overlay_desc", 588 "deviceTypes": [ 589 "default", 590 "tablet" 591 ], 592 "deliverywithInstall": true, 593 "targetModuleName": "entry_module_name", 594 "targetPriority": 1 595 } 596} 597``` 598<!--Del--> 599包间overlay资源包中的配置文件app.json5中支持的字段，仅对系统应用开放： 600```json 601{ 602 "app":{ 603 "bundleName": "com.example.myapplication.overlay", 604 "vendor" : "example", 605 "versionCode": "1000000", 606 "versionName": "1.0.0.1", 607 "icon": "$media:app_icon", 608 "label": "$string:app_name", 609 "targetBundleName": "com.example.myapplication", 610 "targetPriority": 1 611 } 612} 613``` 614包间overlay资源包中的配置文件module.json5中支持的字段，仅对系统应用开放： 615```json 616{ 617 "module":{ 618 "name": "entry_overlay_module_name", 619 "type": "shared", 620 "description": "$string:entry_overlay_desc", 621 "deviceTypes": [ 622 "default", 623 "tablet" 624 ], 625 "deliverywithInstall": true, 626 "targetModuleName": "entry_module_name", 627 "targetPriority": 1 628 } 629} 630``` 631<!--DelEnd--> 632> **说明：** 633><!--Del--> 634> - targetBundleName: 字符串类型，指定要overlay的bundleName。 635><!--DelEnd--> 636> - targetModuleName: 字符串类型，指定要overlay的应用中的目标module。 637> 638> - targetPriority： 整数类型，指定overlay优先级。 639> 640> - 不支持Ability、ExtensionAbility、Permission等其他字段的配置。 641> 642> - overlay不支持json类型的图片配置。 643 644在DevEco Studio中创建应用工程时，module的配置文件module.json5中包含targetModuleName和targetPriority字段时，该module将会在安装阶段被识别为overlay特征的module。overlay特征的module一般是为设备上存在的非overlay特征的module提供覆盖的资源文件，以便于targetModuleName指向的module在运行阶段可以使用overlay资源文件展示不同的颜色，标签，主题等等。 645 646<!--Del--> 647## 相关实例 648 649针对访问应用资源，有以下相关实例可供参考： 650 651- [资源管理（ArkTS）（API10）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Resource/ResourceManager) 652<!--DelEnd-->
