HarmonyOS学习路之开发基础知识——资源文件

资源文件的分类

resources目录

应用的资源文件（字符串、图片、音频等）统一存放于resources目录下，便于开发者使用和维护。resources目录包括两大类目录，一类为base目录与限定词目录，另一类为rawfile目录
资源目录示例：

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

限定词目录

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

限定词目录的命名要求

• 限定词的组合顺序：移动国家码_移动网络码-语言_文字_国家或地区-横竖屏-设备类型-深色模式-屏幕密度。开发者可以根据应用的使用场景和设备特征，选择其中的一类或几类限定词组成目录名称。
• 限定词的连接方式：语言、文字、国家或地区之间采用下划线（）连接，移动国家码和移动网络码之间也采用下划线（）连接，除此之外的其他限定词之间均采用中划线（-）连接。例如：zh_Hant_CN、zh_CN-car-ldpi。
• 限定词的取值范围：每类限定词的取值必须符合表2中的条件，否则，将无法匹配目录中的资源文件。

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

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

资源组目录

base目录与限定词目录下面可以创建资源组目录（包括element、media、animation、layout、graphic、profile），用于存放特定类型的资源文件
element：表示元素资源，以下每一类数据都采用相应的JSON文件来表征。
media：表示媒体资源，包括图片、音频、视频等非文本格式的文件
animation：表示动画资源，采用XML文件格式。
layout：表示布局资源，采用XML文件格式。
graphic：表示可绘制资源，采用XML文件格式。
profile：表示其他类型文件，以原始文件形式保存。

创建资源文件

在resources目录下，可按照限定词目录和资源组目录的说明创建子目录和目录内的文件。
同时，DevEco Studio也提供了创建资源目录和资源文件的界面。

• 创建资源目录及资源文件
  在resources目录右键菜单选择“New > Harmony Resource File”，此时可同时创建目录和文件。
  文件默认创建在base目录的对应资源组下。如果选择了限定词，则会按照命名规范自动生成限定词+资源组目录，并将文件创建在目录中。
  目录名自动生成，格式固定为“限定词.资源组”，例如创建一个限定词为横竖屏类别下的竖屏，资源组为绘制资源的目录，自动生成的目录名称为“vertical.graphic”。
  
• 创建资源目录
  在resources目录右键菜单选择“New > Harmony Resource Directory”，此时可创建资源目录。
  选择资源组类型，设置限定词，创建后自动生成目录名称。目录名称格式固定为“限定词.资源组”，例如创建一个限定词为横竖屏类别下的竖屏，资源组为绘制资源的目录，自动生成的目录名称为“vertical.graphic”。
  
• 创建资源文件
  在资源目录的右键菜单选择“New > XXX Resource File”，即可创建对应资源组目录的资源文件。
  例如，在element目录下可新建Element Resource File。
  

资源文件的使用

资源文件的引用方法

base目录与限定词目录中的资源文件：通过指定资源类型（type）和资源名称（name）来引用。

• Java文件引用资源文件的格式：ResourceTable.type_name。特别地，如果引用的是系统资源，则采用：ohos.global.systemres.ResourceTable.type_name。
  • 示例一：在Java文件中，引用string.json文件中类型为“String”、名称为“app_name”的资源。

  
  ohos.global.resource.ResourceManager resManager = this.getResourceManager();
  String result = resManager.getElement(ResourceTable.String_app_name).getString();
  
  

  • 示例二：在Java文件中，引用color.json文件中类型为“Color”、名称为“red”的资源。

  
  ohos.global.resource.ResourceManager resManager = this.getResourceManager();
  int color = resManager.getElement(ResourceTable.Color_red).getColor();
  
  

• XML文件引用资源文件的格式：$type:name。特别地，如果引用的是系统资源，则采用： $ohos:type:name。
  在XML文件中，引用string.json文件中类型为“String”、名称为“app_name”的资源，示例如下：

<?xml version="1.0" encoding="utf-8"?>
<DirectionalLayout xmlns:ohos="http://schemas.huawei.com/res/ohos"
    ohos:width="match_parent"
    ohos:height="match_parent"
    ohos:orientation="vertical">
    <Text ohos:text="$string:app_name"/>
</DirectionalLayout>

rawfile目录中的资源文件：通过指定文件路径和文件名称来引用。
在Java文件中，引用一个路径为“resources/rawfile/”、名称为“example.js”的资源文件，示例如下：

ohos.global.resource.ResourceManager resManager = this.getResourceManager();
ohos.global.resource.RawFileEntry rawFileEntry = resManager.getRawFileEntry("resources/rawfile/example.js"); 

系统资源文件

ic_app:表示HarmonyOS应用的默认图标。
request_location_reminder_title:表示“请求使用设备定位功能”的提示标题。
request_location_reminder_content:表示“请求使用设备定位功能”的提示内容，即：请在下拉快捷栏打开"位置信息"开关。

颜色模式的定义

应用可以在config.json的module字段下定义“colorMode”字段，“colorMode”字段用来定义应用自身的颜色模式，值可以是“dark”，“light”，“auto”（默认值）。示例：

"colorMode": "light"

当应用的颜色模式值是“dark”时，无论系统当前颜色模式是什么，应用始终会按照深色模式选取资源；同理，当应用的颜色模式值是“light”时，无论系统当前颜色模式是什么，应用始终会按照浅色模式选取资源；当应用的颜色模式值是“auto”时，应用会跟随系统的颜色模式值选取资源。应用可以在代码中通过如下方式获取应用当前的颜色模式：

int colorMode = Configuration.colorMode;

为Element资源文件添加注释或特殊标识

Element目录下的不同种类元素的资源均采用JSON文件表示，资源的名称“name”和取值“value”是每一条资源的必备字段。

• 如果需要为某一条资源备注信息，以便于资源的理解和使用，可以通过comment字段添加注释。
• 如果value字段中的部分文本不需要被翻译人员处理，也不会被显示在应用界面上，可以通过特殊结构来标识无需翻译的内容。

通过comment字段添加注释

通过comment字段，可以为JSON文件的资源添加注释。示例如下：

{
    "string":[
        {
            "name":"message_arrive",
            "value":"We will arrive at %s",
            "comment":"Transfer Arrival Time. %s is time,like 5:00 am"
        }
    ]
}

通过特殊结构来标识无需翻译的内容

在string、strarray、plural这三类资源中，可以通过特殊标识来处理无需被翻译的内容。例如，一个字符串资源的Value取值为“We will arrive at %s”，其中的变量“%s”在翻译过程中希望保持不变。有以下两种方式处理：

• 方式一：在value字段中添加{}。示例如下：

{
    "string":[
        {
            "name":"message_arrive",
            "value":["We will arrive at",{
                "id":"time",
                "example":"5:00 am",
                "value":"%s"
            }
            ]
        }
    ]
}

• 方式二：添加<xliff:g></xliff:g>标记对。示例如下：

{
    "string":[
        {
            "name":"message_arrive",
            "value":"We will arrive at <xliff:g id='time' example='5:00 am'>%s</xliff:g>"
        }
    ]
}

boolean.json示例

{
    "boolean":[
        {
            "name":"boolean_1",
            "value":true
        },
        {
            "name":"boolean_ref",
            "value":"$boolean:boolean_1"
        }
    ]
}

color.json示例

{
    "color":[
        {
            "name":"red",
            "value":"#ff0000"
        },
        {
            "name":"red_ref",
            "value":"$color:red"
        }
    ]
}

float.json示例

{
    "float":[
        {
            "name":"float_1",
            "value":"30.6"
        },
        {
            "name":"float_ref",
            "value":"$float:float_1"
        },
        {
            "name":"float_px",
            "value":"100px"
        }
    ]
}

intarray.json示例

{
    "intarray":[
        {
            "name":"intarray_1",
            "value":[
                100,
                200,
                "$integer:integer_1"
            ]
        }
    ]
}

integer.json示例

{
    "integer":[
        {
            "name":"integer_1",
            "value":100
        },
        {
            "name":"integer_ref",
            "value":"$integer:integer_1"
        }
    ]
}

pattern.json示例

{
    "pattern":[
        {
            "name":"base",
            "value":[
                {
                    "name":"width",
                    "value":"100vp"
                },
                {
                    "name":"height",
                    "value":"100vp"
                },
                {
                    "name":"size",
                    "value":"25px"
                }
            ]
        },
        {
           "name":"child",
           "parent":"base",
           "value":[
               {
                   "name":"noTitile",
                   "value":"Yes"
               }
           ]
        }
    ]
}

plural.json示例

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

strarray.json示例

{
    "strarray":[
       {
           "name":"size",
           "value":[
               {
                   "value":"small"
               },
               {
                   "value":"$string:hello"
               },
               {
                   "value":"large"
               },
               {
                   "value":"extra large"
               }
            ]
       }
    ]
}

string.json示例

{
    "string":[
        {
            "name":"hello",
            "value":"hello base"
        },
        {
            "name":"app_name",
            "value":"my application"
        },
        {
            "name":"app_name_ref",
            "value":"$string:app_name"
        },
        {
            "name":"app_sys_ref",
            "value":"$ohos:string:request_location_reminder_title"
        }
    ]
}

国际化能力的支持

时间日期国际化

不同的区域具有不同的时间日期显示习惯。例如，英语（美国）区域short时间格式为“9:31 AM”；简体中文（中国）区域short时间格式为“上午9:31”；芬兰语（芬兰）区域short时间格式为“9.31”。因此为开发者提供了获取不同区域的时间日期规格的能力。
界面时间日期字串和时间类控件显示，应当遵循当地习惯的规则，当需要展示时间或日期时，建议获取当前地区的时间日期规格，并对显示的字串根据获取到的规格进行格式化后再使用。

示例1：

Locale locale = new Locale("de", "CH");
String skeleton = "MMMMd";
String bestPattern = DateFormatUtil.getBestPattern(skeleton, locale); // 返回值为"d. MMMM"

示例2：

String languageTag = "zh";
String out = DateFormatUtil.format("EEEEdMMMMy", languageTag, "Asia/Shanghai", 0, 3600 * 1000); // 返回值为"1970年1月1日星期四"

电话号码国际化

不同的区域的电话号码有不同的格式化效果，当需要展示本地电话号码时，应遵循当地电话号码的格式化原则。因此为开发者提供了对不同地区电话号码格式化的能力，以便于在显示电话号码时正确的格式化。并提供了获取电话号码归属地的能力，开发者可以使用相关接口获取电话号码的归属地信息。

示例1：

InputFormatter formatter = InputFormatter.getInstance("CN");
formatter.inputNumberAndRememberPosition('1'); // 返回值为"1"
formatter.inputNumber('5'); // 返回值为"15"
formatter.inputNumber('6'); // 返回值为"156"
formatter.inputNumberAndRememberPosition('1');// 返回值为"156 1"

示例2：

Locale.Builder builder = new Locale.Builder();
builder.setLanguage("zh");
builder.setRegion("CN");
builder.setScript("Hant");
Locale locale = builder.build();
String displayName = PhoneNumberAttribution.getAttribute("+8615611xxxxxx", "CN", locale); // x为任意数字，返回值为"北京市"

文本识别

提供了对地址、时间日期与电话号码的文本识别能力，可以调用相关接口识别一段文本中包含的地址、时间日期与电话号码。
示例：

// 当Locale.getDefault().getLanguage()为"en"时
String source = "it is 123 test St";
int[] re = TextRecognitionUtils.getAddress(source);
if (re[0] == 1) {
    result = source.substring(re[1], re[2] + 1);// 返回值为"123 main St"
}

度量衡格式化

提供了对度量衡国际化能力的支持，可支持度量衡体系和维度之间的转换，与不同国家度量衡体系的自动转换。在开发包含度量衡的功能时，可以调用此能力满足多语言和不同国家用户的需求。

示例1：

Locale zhCN = Locale.CHINA;
MeasureFormatter mes = MeasureFormatter.getInstance(zhCN);
mes.format(MeasureOptions.Unit.AREA_UK_ACRE,
           10000,
           MeasureOptions.Usage.AREA_LAND_AGRICULT,
           MeasureOptions.FormatStyle.WIDE,
           MeasureOptions.Style.AUTO_STYLE_ON));// 返回值为"4,046.856公顷"

示例2：

Locale enUS = Locale.US;
MeasureFormatter mes = MeasureFormatter.getInstance(enUS);
mes.format(MeasureOptions.Unit.VOLUME_US_CUP,
           1000,
           MeasureOptions.Unit.VOLUME_SI_LITER,
           MeasureOptions.FormatStyle.WIDE));// 返回值为"236.588 liters"

敏感禁忌

提供对政治敏感地区、城市、及语言的获取能力，以及对地区名称更正的能力。
示例：

Locale locale = Locale.getDefault();
ArrayList<String> result = LocaleHelperUtils.getBlockedRegions(context, locale);//返回值包含"EH"与"XK"(西撒哈拉与科索沃），这两个地区为有政治争议的地区需谨慎使用