鸿蒙OS开发：典型页面场景【一次开发，多端部署】（资源使用）

资源使用

在页面开发过程中，经常需要用到颜色、字体、间距、图片等资源，在不同的设备或配置中，这些资源的值可能不同。有两种方式处理：

• [应用资源]：借助资源文件能力，开发者在应用中自定义资源，自行管理这些资源在不同的设备或配置中的表现。
• [系统资源]：开发者直接使用系统预置的资源定义（即分层参数）。
• 开发前请熟悉鸿蒙开发指导文档 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

应用资源

资源文件介绍

应用开发中使用的各类自定义资源文件，需要统一存放于应用的resources目录下，便于使用和维护。resources目录包括两大类目录，一类为base目录与限定词目录，另一类为rawfile目录，其基础目录结构如下所示。

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

base目录默认存在，而限定词目录需要开发者自行创建，其名称可以由一个或多个表征应用场景或设备特征的限定词组合而成。应用使用某资源时，系统会根据当前设备状态优先从相匹配的限定词目录中寻找该资源。只有当resources目录中没有与设备状态匹配的限定词目录，或者在限定词目录中找不到该资源时，才会去base目录中查找。rawfile是原始文件目录，它不会根据设备状态去匹配不同的资源，故不在本文的讨论范文内。

说明：

• 请访问[声明式开发范式资源文件分类]，了解限定词目录的命名规则、创建流程、匹配规则等，本文不展开介绍。
• 没有设备状态匹配的限定词目录，或者在限定词目录中找不到目标资源时，会继续在base目录中查找。 强烈建议对于所有应用自定义资源都在base目录中定义默认值 ，防止出现找不到资源值的异常场景。
• 类Web开发范式的资源文件路径及资源限定词的使用与声明式范式不同，详情请参考[类Web开发范式资源限定与访问]及[类Web开发范式文件组织]。

base目录与限定词目录下面可以创建资源组目录（包括element、media等），用于存放特定类型的资源文件。

资源组目录	目录说明	资源文件
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。

在element目录的各个资源文件中，以“name-value”的形式定义资源，如下所示。而在media目录中，直接以文件名作为name，故开发者将文件放入media目录即可，无需再额外定义name。

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

访问应用资源

在工程中，通过 "$r('app.type.name')" 的形式引用应用资源。app代表是应用内resources目录中定义的资源；type 代表资源类型（或资源的存放位置），可以取 color、float、string、plural和media，name代表资源命名，由开发者添加资源时确定。

说明： 可以查看[声明式范式访问应用资源]，了解资源访问的更多细节。

示例

在应用的resources目录下，创建名为tablet的限定词子目录，并按照下表所示，在base目录和tablet限定词目录中添加相应的资源。

资源名称	资源类型	base目录中资源值	限定词目录（tablet）中资源值
my_string	string	default	tablet
my_color	color	#ff0000	#0000ff
my_float	float	60vp	80vp
my_image	media	my_image.png（太阳图标）	my_image.png（月亮图标）

在代码中通过 "$r('app.type.name')" 的形式使用应用资源，并分别在默认设备和平板上查看代码的运行效果，可以发现同一资源在不同设备上的取值不同。

@Entry
@Component
struct Index {
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text($r("app.string.my_string"))
        .fontSize($r("app.float.my_float"))
        .fontColor($r("app.color.my_color"))
      Image($r("app.media.my_image"))
        .width(100)
        .height(100)
    }
    .width('100%')
    .height('100%')
  }
}

系统资源

除了自定义资源，开发者也可以使用系统中预定义的资源（即[分层参数]，同一资源ID在设备类型、深浅色等不同配置下有不同的取值）。

视觉基础

虚拟像素单位：vp

虚拟像素(virtual pixel)是一台设备针对应用而言所具有的虚拟尺寸（区别于屏幕硬件本身的像素单位）。它提供了一种灵活的方式来适应不同屏幕密度的显示效果。

相同的vp，在不同像素密度的屏幕上，对应不同px，一般称px/vp为像素密度比。像素密度比为当前设备屏幕的dpi/160。

在dpi为160的OpenHarmony设备上，像素密度比为1，则1vp等于1px。

以vp为尺寸标注单位，可使相同元素在不同密度的设备上具有一致的视觉体量，使用px则容易导致体量不一致的问题。

8vp网格系统

基于 8vp 为网格的基本单位可以对界面上元素的大小、位置、对齐方式进行更好的规划，构建更有层次感、秩序感，以及多设备上一致的布局效果。一些更小的控件（例如图标）大小也可以对齐 4vp 的网格大小。

字体像素单位：fp

字体像素(font pixel) 大小默认情况下与 vp 相同，即默认情况下 1 fp = 1vp。如果用户在设置中选择了更大的字体，字体的实际显示大小就会在 vp 的基础上乘以 scale 系数，即 1 fp = 1 vp * scale。

视觉属性：分层参数

分层参数是根据使用场景定义的视觉属性ID，通过在不同色彩主题、多种设备上配置不同的数值，实现多设备适配的效果。OpenHarmony的分层参数包含色彩、字体、圆角、间距、阴影、模糊、缩放，并提供了默认实现。设备、应用、服务均可在此基础上管理并自定义不同场景的视觉属性。

例如，对于不同场景的主色调定义了对应的ID与默认实现

主色调	色值	IDHarmonyOS与OpenHarmony鸿蒙文档籽料：mau123789是v直接拿
高亮色	#007DFF	ohos_id_color_emphasize
高亮色反色	#006CDE	ohos_id_color_emphasize_contrary
警告色	#FA2A2D	ohos_id_color_warning
警示色	#FF7500	ohos_id_color_alert
通讯色	#E84826	ohos_id_color_handup
通讯色	#00CB87	ohos_id_color_connected

在开发过程中，分层参数的用法与资源限定词基本一致。开发者可以通过"$r('sys.type.resource_id')"的形式引用系统资源。sys代表是系统资源；type代表资源类型，值可以取color、float、string和media；resource_id代表资源id。

可以查看[应用UX设计中关于资源的介绍]，获取系统支持的资源ID及其在不同配置下的取值。

说明：

• 仅声明式开发范式支持使用分层参数，类Web开发范式不支持。
• 系统资源可以保证不同团队开发出的应用有较为一致的视觉风格。对于系统预置应用，强烈建议使用系统资源；对于三方应用，可以根据需要选择使用系统资源或自定义应用资源。
• 可以查看[resources代码仓]了解系统预置资源的实现，这里的目录结构与工程中的resources目录类似，也是通过资源限定词匹配不同的设备或设备状态。

审核编辑 黄宇