Desarrollo de aplicaciones HarmonyOS: clasificación y acceso a recursos

Durante el proceso de desarrollo de la aplicación se suelen utilizar recursos como colores, fuentes, espacios e imágenes, cuyos valores pueden ser diferentes en diferentes dispositivos o configuraciones.

• Recursos de aplicaciones: con la capacidad de archivos de recursos, los desarrolladores pueden personalizar los recursos en sus aplicaciones y administrar el rendimiento de estos recursos en diferentes dispositivos o configuraciones.
• Recursos del sistema: los desarrolladores utilizan directamente definiciones de recursos preestablecidas del sistema (es decir, parámetros jerárquicos, el mismo ID de recurso tiene diferentes valores en diferentes configuraciones, como tipo de dispositivo, color oscuro y claro, etc.).

Clasificación de recursos

directorio de recursos

Varios archivos de recursos utilizados en el desarrollo de aplicaciones deben colocarse en subdirectorios específicos para su almacenamiento y administración. El directorio de recursos incluye tres categorías principales de directorios: uno es el directorio base, otro es el directorio calificador y el otro es el directorio de archivos sin formato. Los archivos de recursos comunes a varios proyectos en el modelo de etapa se colocan en el directorio de recursos en AppScope.

El directorio base existe de forma predeterminada, mientras que el desarrollador debe crear el directorio calificador. Cuando una aplicación utiliza un recurso, el sistema primero buscará el recurso en el directorio calificador coincidente según el estado actual del dispositivo. Solo cuando no haya ningún directorio calificador que coincida con el estado del dispositivo en el directorio de recursos, o el recurso no se encuentre en el directorio calificador, se buscará en el directorio base. rawfile es el directorio de archivos original y no coincidirá con diferentes recursos según el estado del dispositivo.

Ejemplo de directorio de recursos:

resources 
|---base 
|   |---element 
|   |   |---string.json 
|   |---media 
|   |   |---icon.png 
|   |---profile 
|   |   |---test_profile.json 
|---en_US  // 默认存在的目录，设备语言环境是美式英文时，优先匹配此目录下资源 
|   |---element 
|   |   |---string.json 
|   |---media 
|   |   |---icon.png 
|   |---profile 
|   |   |---test_profile.json 
|---zh_CN  // 默认存在的目录，设备语言环境是简体中文时，优先匹配此目录下资源 
|   |---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文件中。文件名可自定义。

Tabla 1  Clasificación del directorio de recursos

Clasificación	directorio base	directorio calificador	directorio de archivos sin formato
forma organizativa	El directorio base es el directorio que existe de forma predeterminada. Cuando no hay ningún directorio calificador que coincida con el estado del dispositivo en el directorio de recursos de la aplicación, se hará referencia automáticamente a los archivos de recursos en el directorio. El subdirectorio de segundo nivel del directorio base es el directorio del grupo de recursos , que se utiliza para almacenar elementos básicos como cadenas, colores y valores booleanos, así como archivos de recursos como medios, animaciones y diseños. Para requisitos específicos, consulte el directorio del grupo de recursos .	en_US y zh_CN son los dos directorios calificadores que existen de forma predeterminada. Los desarrolladores deben crear los otros directorios calificadores. El nombre del directorio se compone de uno o más calificadores que caracterizan escenarios de aplicación o características del dispositivo. Para requisitos específicos, consulte el directorio de calificadores . El subdirectorio de segundo nivel del directorio calificador es el directorio del grupo de recursos, que se utiliza para almacenar elementos básicos como cadenas, colores y valores booleanos, así como archivos de recursos como medios, animaciones y diseños. Para requisitos específicos, consulte el directorio del grupo de recursos .	Admite la creación de subdirectorios de varias capas, el nombre del directorio se puede personalizar y se pueden colocar libremente varios archivos de recursos en la carpeta. Los archivos en el directorio rawfile no coincidirán con diferentes recursos según el estado del dispositivo.
Método de compilación	Los archivos de recursos en el directorio se compilarán en archivos binarios y se les asignarán ID de archivos de recursos.	Los archivos de recursos en el directorio se compilarán en archivos binarios y se les asignarán ID de archivos de recursos.	Los archivos de recursos en el directorio se empaquetarán directamente en la aplicación sin compilación y no se les asignará una ID de archivo de recursos.
Método de referencia	Se hace referencia especificando el tipo de recurso (tipo) y el nombre del recurso (nombre).	Se hace referencia especificando el tipo de recurso (tipo) y el nombre del recurso (nombre).	Se hace referencia especificando la ruta del archivo y el nombre del archivo.

directorio calificador

El directorio de calificadores puede estar compuesto por uno o más calificadores que caracterizan escenarios de aplicación o características del dispositivo, incluido el código de país móvil y el código de red móvil, idioma, texto, país o región, pantalla horizontal y vertical, tipo de dispositivo, modo de color y densidad de pantalla. Dimensiones iguales, los calificadores están conectados mediante guiones bajos (_) o guiones (-). Al crear un directorio de calificadores, los desarrolladores deben comprender los requisitos de nomenclatura del directorio de calificadores y las reglas de coincidencia entre el directorio de calificadores y el estado del dispositivo.

Requisitos de denominación para directorios calificadores

• El orden de combinación de calificadores:_Código de país móvil_Código de red móvil-Idioma_Texto_País o región-Pantalla horizontal y vertical-Tipo de dispositivo-Modo de color-Densidad de pantalla_. Los desarrolladores pueden elegir uno o varios tipos de calificadores para formar un nombre de directorio según los escenarios de uso de la aplicación y las características del dispositivo.
• Cómo conectar calificadores: los idiomas, caracteres, países o regiones están conectados mediante guiones bajos (_). Los códigos de países móviles y los códigos de redes móviles también están conectados mediante guiones bajos (_). Otros calificadores también están conectados mediante guiones bajos (_). Utilice un guión. (-) para conectar. Por ejemplo: zh_Hant_CN , zh_CN-car-ldpi .
• Rango de valores del calificador: el valor de cada tipo de calificador debe cumplir con las condiciones de la tabla de requisitos de valores del calificador; de lo contrario, los archivos de recursos en el directorio no coincidirán.

Tabla 2  Requisitos de valor del calificador

Tipo de calificador	Descripción del significado y valor.
Código de país móvil y código de red móvil	Los valores del Código de país móvil (MCC) y del Código de red móvil (MNC) se toman de la red en la que está registrado el dispositivo. MCC puede ir seguido de MNC, conectado con un guión bajo (_) o usarse solo. Por ejemplo: mcc460 significa China, mcc460_mnc00 significa China_China Mobile. Para conocer el rango de valores detallado, consulte ITU-T E.212 (estándares relacionados con la UIT).
idioma	Indica el tipo de idioma utilizado por el dispositivo, compuesto por 2 a 3 letras minúsculas. Por ejemplo: zh significa chino, en significa inglés, mai significa maithili. Para conocer el rango de valores detallado, consulte ISO 639 (el estándar de codificación de idioma establecido por ISO).
carta	Indica el tipo de texto utilizado por el dispositivo, compuesto por 1 letra mayúscula (letra inicial) y 3 letras minúsculas. Por ejemplo: Hans representa chino simplificado, Hant representa chino tradicional. Para conocer el rango de valores detallado, consulte ISO 15924 (estándar de codificación de texto establecido por ISO).
País o Región	Indica el país o región donde se encuentra el usuario, compuesto por 2 a 3 letras mayúsculas o 3 números. Por ejemplo: CN significa China, GB significa Reino Unido. Para conocer el rango de valores detallado, consulte ISO 3166-1 (el estándar de codificación nacional y regional establecido por ISO).
Pantalla horizontal y vertical	Indica la orientación de la pantalla del dispositivo, los valores son los siguientes: - vertical: pantalla vertical -horizontal: pantalla horizontal
Tipo de equipo	Indica el tipo de dispositivo, los valores son los siguientes: - coche: máquina de coche - televisión: pantalla inteligente - usable: usable inteligente
Modo de color	Indica el modo de color del dispositivo, los valores son los siguientes: - oscuro: modo oscuro - luz: modo de luz
densidad de pantalla	Indica la densidad de pantalla del dispositivo (la unidad es ppp), el valor es el siguiente: - sdpi: representa la densidad de pantalla a pequeña escala (Small-scale Dots Per Inch), aplicable a dispositivos con un valor de ppp de (0, 120). - mdpi: representa la densidad de pantalla de escala media (Puntos por pulgada de escala media), adecuada para dispositivos con un valor de ppp de (120, 160). - ldpi：表示大规模的屏幕密度（Large-scale Dots Per Inch），适用于dpi取值为(160, 240]的设备。 - xldpi：表示特大规模的屏幕密度（Extra Large-scale Dots Per Inch），适用于dpi取值为(240, 320]的设备。 - xxldpi：表示超大规模的屏幕密度（Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(320, 480]的设备。 - xxxldpi：表示超特大规模的屏幕密度（Extra Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(480, 640]的设备。

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

• 在为设备匹配对应的资源文件时，限定词目录匹配的优先级从高到低依次为：移动国家码和移动网络码 > 区域（可选组合：语言、语言_文字、语言_国家或地区、语言_文字_国家或地区）> 横竖屏 > 设备类型 > 颜色模式 > 屏幕密度。
• 如果限定词目录中包含移动国家码和移动网络码、语言、文字、横竖屏、设备类型、颜色模式限定词，则对应限定词的取值必须与当前的设备状态完全一致，该目录才能够参与设备的资源匹配。例如，限定词目录“zh_CN-car-ldpi”不能参与“en_US”设备的资源匹配。

资源组目录

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

表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。
profile	表示自定义配置文件，其文件内容可通过包管理接口获取（目录下只支持文件类型）。	文件名可自定义，例如：test_profile.json。

媒体资源类型说明

表4 图片资源类型说明

格式	文件后缀名
JPEG	.jpg
PNG	.png
GIF	.gif
SVG	.svg
WEBP	.webp
BMP	.bmp

表5 音视频资源类型说明

格式	支持的文件类型
H.263	.3gp .mp4
H.264 AVC Baseline Profile (BP)	.3gp .mp4
MPEG-4 SP	.3gp
VP8	.webm .mkv

资源文件示例

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

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目录的对应资源组下。如果选择了限定词，则会按照命名规范自动生成限定词+资源组目录，并将文件创建在目录中。图中Avaliable qualifiers为供选择的限定词目录，通过右边的小箭头可添加或者删除。File name为需要创建的文件名，Resource type为资源组类型，默认是element。Root Element为资源类型。创建的目录名自动生成，格式固定为“限定词.资源组”，例如：创建一个限定词为dark的element目录，自动生成的目录名称为“dark.element”。

• 创建资源目录

在resources目录右键菜单选择“New > Resource Directory”，此时可创建资源目录。资源目录创建的是base目录，也可根据需求创建其它限定词目录。确定限定词后，选择资源组类型，当前资源组类型支持Element、Media、Profile三种，创建后自动生成目录名称。

• 创建资源文件

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

访问应用资源

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

Al hacer referencia a recursos en un archivo sin formato, utilice el formato "$rawfile('nombre de archivo')". El nombre del archivo debe expresarse como una ruta relativa al archivo en el directorio del archivo sin formato. El nombre del archivo debe incluir un sufijo y la ruta no puede comenzar con "/".

Al acceder al descriptor de un archivo rawfile, puede usar la interfaz getRawFd de administración de recursos . Su valor de retorno descriptor.fd es el fd del paquete hap. Para acceder a este archivo rawfile, debe usar {fd, offset, length} juntos .

ilustrar

Los descriptores de recursos no se pueden concatenar y solo admiten cadenas ordinarias como 'app.type.name'.

El valor de retorno de $r es un objeto de recurso y  la cadena correspondiente se puede obtener mediante el método getStringValue .

En el archivo xxx.ets, puede utilizar los recursos definidos en el directorio de recursos. El "Ejemplo de archivo de recursos" en el directorio del grupo de recursos en la categoría de recursos muestra el contenido del archivo .json, incluidos los archivos color.json, float.json, string.json y plural.json. El uso específico de los recursos de la aplicación es el siguiente:

Text($r('app.string.string_hello'))
  .fontColor($r('app.color.color_hello'))
  .fontSize($r('app.float.font_hello'))

Text($r('app.string.string_world'))
  .fontColor($r('app.color.color_world'))
  .fontSize($r('app.float.font_world'))

// 引用string.json资源。Text中$r的第一个参数指定string资源，第二个参数用于替换string.json文件中的%s。
//如下示例代码value为"We will arrive at five of the clock"。
Text($r('app.string.message_arrive', "five of the clock"))
  .fontColor($r('app.color.color_hello'))
  .fontSize($r('app.float.font_hello'))

// 引用plural$资源。Text中$r的第一个指定plural资源，第二个参数用于指定单复数（在中文，单复数均使用other。在英文，one：代表单数，取值为1；other：代表复数，取值为大于等于1的整数），第三个参数用于替换%d
// 如下示例代码为复数，value为"5 apples"。
Text($r('app.plural.eat_apple', 5, 5))
  .fontColor($r('app.color.color_world'))
  .fontSize($r('app.float.font_world'))

Image($r('app.media.my_background_image'))  // media资源的$r引用

Image($rawfile('test.png'))                 // rawfile$r引用rawfile目录下图片

Image($rawfile('newDir/newTest.png'))       // rawfile$r引用rawfile目录下图片

recurso del sistema

Los recursos del sistema incluyen colores, esquinas redondeadas, fuentes, espacios, cadenas, imágenes, etc. Al utilizar los recursos del sistema, diferentes desarrolladores pueden desarrollar aplicaciones con el mismo estilo visual.

Los desarrolladores pueden hacer referencia a los recursos del sistema en forma de "$r('sys.type.resource_id')". sys representa los recursos del sistema; type representa el tipo de recurso, que puede ser "color", "flotante", "cadena" y "medios"; Resource_id representa la identificación del recurso.

ilustrar

• Sólo el paradigma de desarrollo declarativo admite el uso de recursos del sistema, y ​​el paradigma de desarrollo similar a la web no.

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)