鸿蒙OS开发文档 鸿蒙OS 资源文件分类

2024-02-25 开发教程 鸿蒙OS开发文档 匿名 2

resources目录

应用的资源文件(字符串、图片、音频等)统一存放于resources目录下,便于开发者使用和维护。resources目录包括两大类目录,一类为base目录与限定词目录,另一类为 rawfile目录,详见表1。

资源目录示例:

resources
|---base // 默认存在的目录
| |---element
| | |---string.json
| |---media
| | |---icon.png
|---en_GB-vertical-car-mdpi // 限定词目录示例,需要开发者自行创建
| |---element
| | |---string.json
| |---media
| | |---icon.png
|---rawfile // 默认存在的目录

表1 resources目录分类

分类base目录与限定词目录rawfile目录
组织形式按照两级目录形式来组织,目录命名必须符合规范,以便根据设备状态去匹配相应目录下的资源文件。
一级子目录为 base目录和 限定词目录。base目录是默认存在的目录。当应用的resources资源目录中没有与设备状态匹配的限定词目录时,会自动引用该目录中的资源文件。限定词目录需要开发者自行创建。目录名称由一个或多个表征应用场景或设备特征的限定词组合而成,具体要求参见限定词目录。
二级子目录为资源目录,用于存放字符串、颜色、布尔值等基础元素,以及媒体、动画、布局等资源文件,具体要求参见资源组目录)。
支持创建多层子目录,目录名称可以自定义,文件夹内可以自由放置各类资源文件。
rawfile目录的文件不会根据设备状态去匹配不同的资源。
编译方式目录中的资源文件会被编译成二进制文件,并赋予资源文件ID。目录中的资源文件会被直接打包进应用,不经过编译,也不会被赋予资源文件 ID。
引用方式通过文件类型(type)和资源名称(name)的组合引用。
Java 文件采用:ResourceTable.*type*_****name。特别地,如果引用的是系统资源,则采用:ohos.global.systemres.ResourceTable.*type*_*name*。
XML 文件采用:$*type*:*name*。特别地,如果引用的是系统资源,则采用:$ohos:*type*:*name*。
通过指定文件路径和文件名来引用。
例如:“resources/rawfile/example.js”。

限定词目录

限定词目录可以由一个或多个表征应用场景或设备特征的限定词组合而成,包括语言、文字、国家或地区、横竖屏、设备类型和屏幕密度等六个维度,限定词之间通过下划线(_)或者中划线(-)连接。开发者在创建限定词目录时,需要掌握限定词目录的命名要求以及与限定词目录与设备状态的匹配规则。

限定词目录的命名**要求**

  • 限定词的组合顺序:语言_文字_国家或地区-横竖屏-设备类型-屏幕密度。开发者可以根据应用的使用场景和设备特征,选择其中的一类或几类限定词组成目录名称。
  • 限定词的连接方式:语言、文字、国家或地区之间采用下划线(_)连接,除此之外的其他限定词之间均采用中划线(-)连接。

例如:zh_Hant_CN、zh_CN-car-ldpi。

  • 限定词的取值范围:每类限定词的取值必须符合表2中的条件,否则,将无法匹配目录中的资源文件。

表2 限定词取值要求

限定词类型含义与取值说明
语言表示设备使用的语言类型,由 2个小写字母组成。
例如:zh表示中文,en表示英语。
详细取值范围,参见 ISO 639-1(ISO 制定的语言编码标准)。
文字表示设备使用的文字类型,由 1个大写字母(首字母)和 3个小写字母组成。
例如:Hans表示简体中文,Hant表示繁体中文。
详细取值范围,参见 ISO 15924(ISO 制定的文字编码标准)。
国家或地区表示用户所在的国家或地区,由 2~3个大写字母或者 3个数字组成。
例如:CN表示中国,GB表示英国。详细取值范围,参见 ISO 3166-1(ISO 制定的国家和地区编码标准)。
横竖屏表示设备的屏幕方向,取值如下:
vertical:竖屏
horizontal:横屏
设备类型表示设备的类型,取值如下:
car:车机
tv:智慧屏
wearable:智能穿戴
屏幕密度表示设备的屏幕密度(单位为dpi),取值如下:
sdpi:表示小规模的屏幕密度(Small-scale Dots Per Inch),适用于120dpi及以下的设备。
mdpi:表示中规模的屏幕密度(Medium-scale Dots Per Inch),适用于120dpi~160dpi的设备。
ldpi:表示大规模的屏幕密度(Large-scale Dots Per Inch),适用于160dpi~240dpi的设备。
xldpi:表示特大规模的屏幕密度(Extra Large-scale Dots Per Inch),适用于240dpi~320dpi的设备。
xxldpi:表示超大规模的屏幕密度(Extra Extra Large-scale Dots Per Inch),适用于320dpi~480dpi的设备。
xxxldpi:表示超特大规模的屏幕密度(Extra Extra Extra Large-scale Dots Per Inch),适用于480dpi~640dpi的设备。

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

  • 在为设备匹配对应的资源文件时,限定词目录匹配的优先级从高到低依次为:区域(语言_文字_国家或地区)> 横竖屏 > 设备类型 > 屏幕密度
  • 如果限定词目录中包含语言、文字、横竖屏、设备类型限定词,则对应限定词的取值必须与当前的设备状态完全一致,该目录才能够参与设备的资源匹配。例如,限定词目录“zh_CN-car-ldpi”不能参与“en_US”设备的资源匹配。

资源组目录

base目录与限定词目录下面可以创建资源组目录(包括elementmediaanimationlayoutgraphicprofile),用于存放特定类型的资源文件,详见表3。

表3 资源组目录 说明

资源组目录目录说明资源文件
element表示元素资源,以下每一类数据都采用相应的 JSON 文件来表征。
boolean,布尔型
color,颜色
float,浮点型
intarray,整型数组
integer,整型
pattern,样式
plural,复数形式
strarray,字符串数组
string,字符串
element目录中的文件名称建议与下面的文件名保持一致。
每个文件中只能包含同一类型的数据。
boolean.json
color.json
float.json
intarray.json
integer.json
pattern.json
plural.json
strarray.json
string.json
media表示媒体资源,包括图片、音频、视频等非文本格式的文件。文件名可自定义,例如:icon.png
animation表示动画资源,采用 XML 文件格式。文件名可自定义,例如:zoom_in.xml
layout表示布局资源,采用 XML 文件格式。文件名可自定义,例如:home_layout.xml
graphic表示可绘制资源,采用 XML 文件格式。文件名可自定义,例如:notifications_dark.xml
profile表示其他类型文件,以原始文件形式保存。文件名可自定义。

系统资源文件

目前支持的系统资源文件详见表4。

表4 系统资源文件说明

系统资源名称含义类型
ic_app表示 HarmonyOS 应用的默认图标。媒体
request_location_reminder_title表示“请求使用设备定位功能”的提示标题。字符串
request_location_reminder_content表示“请求使用设备定位功能”的提示内容,即:请在下拉快捷栏打开"位置信息"开关。字符串