HarmonyOS學(xué)習(xí)路之開發(fā)基礎(chǔ)知識——資源文件
1
資源文件的分類
resources目錄
應(yīng)用的資源文件（字符串、圖片、音頻等）統(tǒng)一存放于resources目錄下，便于開發(fā)者使用和維護(hù)。
resources目錄包括兩大類目錄，一類為base目錄與限定詞目錄，另一類為rawfile目錄 資源目錄示例：
resources
|---base // 默認(rèn)存在的目錄
| |---element
| | |---string.json
| |---media
| | |---icon.png
|---en_GB-vertical-car-mdpi // 限定詞目錄示例，需要開發(fā)者自行創(chuàng)建
| |---element
| | |---string.json
| |---media
| | |---icon.png
|---rawfile // 默認(rèn)存在的目錄
2
限定詞目錄
限定詞目錄可以由一個或多個表征應(yīng)用場景或設(shè)備特征的限定詞組合而成，包括移動國家碼和移動網(wǎng)絡(luò)碼、語言、文字、國家或地區(qū)、橫豎屏、設(shè)備類型、顏色模式和屏幕密度等維度，限定詞之間通過下劃線（_）或者中劃線（-）連接。開發(fā)者在創(chuàng)建限定詞目錄時，需要掌握限定詞目錄的命名要求以及與限定詞目錄與設(shè)備狀態(tài)的匹配規(guī)則。
限定詞目錄的命名要求
限定詞的組合順序：移動國家碼_移動網(wǎng)絡(luò)碼-語言_文字_國家或地區(qū)-橫豎屏-設(shè)備類型-深色模式-屏幕密度。開發(fā)者可以根據(jù)應(yīng)用的使用場景和設(shè)備特征，選擇其中的一類或幾類限定詞組成目錄名稱。 限定詞的連接方式：語言、文字、國家或地區(qū)之間采用下劃線（）連接，移動國家碼和移動網(wǎng)絡(luò)碼之間也采用下劃線（）連接，除此之外的其他限定詞之間均采用中劃線（-）連接。例如：zh_Hant_CN、zh_CN-car-ldpi。 限定詞的取值范圍：每類限定詞的取值必須符合表2中的條件，否則，將無法匹配目錄中的資源文件。
限定詞目錄與設(shè)備狀態(tài)的匹配規(guī)則
在為設(shè)備匹配對應(yīng)的資源文件時，限定詞目錄匹配的優(yōu)先級從高到低依次為：移動國家碼和移動網(wǎng)絡(luò)碼 > 區(qū)域（語言_文字_國家或地區(qū)）> 橫豎屏 > 設(shè)備類型 > 顏色模式 > 屏幕密度。 如果限定詞目錄中包含移動國家碼和移動網(wǎng)絡(luò)碼、語言、文字、橫豎屏、設(shè)備類型、顏色模式限定詞，則對應(yīng)限定詞的取值必須與當(dāng)前的設(shè)備狀態(tài)完全一致，該目錄才能夠參與設(shè)備的資源匹配。例如，限定詞目錄“zh_CN-car-ldpi”不能參與“en_US”設(shè)備的資源匹配。
3
資源組目錄
base目錄與限定詞目錄下面可以創(chuàng)建資源組目錄（包括element、media、animation、layout、graphic、profile），用于存放特定類型的資源文件。
element：表示元素資源，以下每一類數(shù)據(jù)都采用相應(yīng)的JSON文件來表征。
media：表示媒體資源，包括圖片、音頻、視頻等非文本格式的文件。
animation：表示動畫資源，采用XML文件格式。
layout：表示布局資源，采用XML文件格式。
graphic：表示可繪制資源，采用XML文件格式。profile：表示其他類型文件，以原始文件形式保存。
4
創(chuàng)建資源文件
在resources目錄下，可按照限定詞目錄和資源組目錄的說明創(chuàng)建子目錄和目錄內(nèi)的文件。同時，DevEco Studio也提供了創(chuàng)建資源目錄和資源文件的界面。
創(chuàng)建資源目錄及資源文件在resources目錄右鍵菜單選擇“New > Harmony Resource File”，此時可同時創(chuàng)建目錄和文件。文件默認(rèn)創(chuàng)建在base目錄的對應(yīng)資源組下。如果選擇了限定詞，則會按照命名規(guī)范自動生成限定詞+資源組目錄，并將文件創(chuàng)建在目錄中。目錄名自動生成，格式固定為“限定詞.資源組”，例如創(chuàng)建一個限定詞為橫豎屏類別下的豎屏，資源組為繪制資源的目錄，自動生成的目錄名稱為“vertical.graphic”。
創(chuàng)建資源目錄在resources目錄右鍵菜單選擇“New > Harmony Resource Directory”，此時可創(chuàng)建資源目錄。選擇資源組類型，設(shè)置限定詞，創(chuàng)建后自動生成目錄名稱。目錄名稱格式固定為“限定詞.資源組”，例如創(chuàng)建一個限定詞為橫豎屏類別下的豎屏，資源組為繪制資源的目錄，自動生成的目錄名稱為“vertical.graphic”。
創(chuàng)建資源文件在資源目錄的右鍵菜單選擇“New > XXX Resource File”，即可創(chuàng)建對應(yīng)資源組目錄的資源文件。例如，在element目錄下可新建Element Resource File。
5
資源文件的使用
資源文件的引用方法
base目錄與限定詞目錄中的資源文件：通過指定資源類型（type）和資源名稱（name）來引用。
Java文件引用資源文件的格式：ResourceTable.type_name。特別地，如果引用的是系統(tǒng)資源，則采用：ohos.global.systemres.ResourceTable.type_name。
ohos.global.resource.ResourceManager resManager = this.getResourceManager();
String result = resManager.getElement(ResourceTable.String_app_name).getString();
ohos.global.resource.ResourceManager resManager = this.getResourceManager();
int color = resManager.getElement(ResourceTable.Color_red).getColor();
示例二：在Java文件中，引用color.json文件中類型為“Color”、名稱為“red”的資源。 示例一：在Java文件中，引用string.json文件中類型為“String”、名稱為“app_name”的資源。 XML文件引用資源文件的格式：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"); 系統(tǒng)資源文件
ic_app:表示HarmonyOS應(yīng)用的默認(rèn)圖標(biāo)。request_location_reminder_title:表示“請求使用設(shè)備定位功能”的提示標(biāo)題。request_location_reminder_content:表示“請求使用設(shè)備定位功能”的提示內(nèi)容，即：請在下拉快捷欄打開"位置信息"開關(guān)。
顏色模式的定義
應(yīng)用可以在config.json的module字段下定義“colorMode”字段，“colorMode”字段用來定義應(yīng)用自身的顏色模式，值可以是“dark”，“l(fā)ight”，“auto”（默認(rèn)值）。示例：
"colorMode": "light"
當(dāng)應(yīng)用的顏色模式值是“dark”時，無論系統(tǒng)當(dāng)前顏色模式是什么，應(yīng)用始終會按照深色模式選取資源；同理，當(dāng)應(yīng)用的顏色模式值是“l(fā)ight”時，無論系統(tǒng)當(dāng)前顏色模式是什么，應(yīng)用始終會按照淺色模式選取資源；當(dāng)應(yīng)用的顏色模式值是“auto”時，應(yīng)用會跟隨系統(tǒng)的顏色模式值選取資源。應(yīng)用可以在代碼中通過如下方式獲取應(yīng)用當(dāng)前的顏色模式：
int colorMode = Configuration.colorMode;為Element資源文件添加注釋或特殊標(biāo)識
Element目錄下的不同種類元素的資源均采用JSON文件表示，資源的名稱“name”和取值“value”是每一條資源的必備字段。
如果需要為某一條資源備注信息，以便于資源的理解和使用，可以通過comment字段添加注釋。 如果value字段中的部分文本不需要被翻譯人員處理，也不會被顯示在應(yīng)用界面上，可以通過特殊結(jié)構(gòu)來標(biāo)識無需翻譯的內(nèi)容。
通過comment字段添加注釋
通過comment字段，可以為JSON文件的資源添加注釋。示例如下：
{
"string":[
{
"name":"message_arrive",
"value":"We will arrive at %s",
"comment":"Transfer Arrival Time. %s is time,like 5:00 am"
}
]
}通過特殊結(jié)構(gòu)來標(biāo)識無需翻譯的內(nèi)容
在string、strarray、plural這三類資源中，可以通過特殊標(biāo)識來處理無需被翻譯的內(nèi)容。例如，一個字符串資源的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>標(biāo)記對。示例如下：
{
"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"
}
]
}6
國際化能力的支持
時間日期國際化
不同的區(qū)域具有不同的時間日期顯示習(xí)慣。例如，英語（美國）區(qū)域short時間格式為“9:31 AM”；簡體中文（中國）區(qū)域short時間格式為“上午9:31”；芬蘭語（芬蘭）區(qū)域short時間格式為“9.31”。因此為開發(fā)者提供了獲取不同區(qū)域的時間日期規(guī)格的能力。
界面時間日期字串和時間類控件顯示，應(yīng)當(dāng)遵循當(dāng)?shù)亓?xí)慣的規(guī)則，當(dāng)需要展示時間或日期時，建議獲取當(dāng)前地區(qū)的時間日期規(guī)格，并對顯示的字串根據(jù)獲取到的規(guī)格進(jìn)行格式化后再使用。
示例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日星期四"電話號碼國際化
不同的區(qū)域的電話號碼有不同的格式化效果，當(dāng)需要展示本地電話號碼時，應(yīng)遵循當(dāng)?shù)仉娫捥柎a的格式化原則。因此為開發(fā)者提供了對不同地區(qū)電話號碼格式化的能力，以便于在顯示電話號碼時正確的格式化。并提供了獲取電話號碼歸屬地的能力，開發(fā)者可以使用相關(guān)接口獲取電話號碼的歸屬地信息。
示例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為任意數(shù)字，返回值為"北京市"文本識別
提供了對地址、時間日期與電話號碼的文本識別能力，可以調(diào)用相關(guān)接口識別一段文本中包含的地址、時間日期與電話號碼。示例：
// 當(dāng)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"
}度量衡格式化
提供了對度量衡國際化能力的支持，可支持度量衡體系和維度之間的轉(zhuǎn)換，與不同國家度量衡體系的自動轉(zhuǎn)換。在開發(fā)包含度量衡的功能時，可以調(diào)用此能力滿足多語言和不同國家用戶的需求。
示例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"敏感禁忌
提供對政治敏感地區(qū)、城市、及語言的獲取能力，以及對地區(qū)名稱更正的能力。示例：
Locale locale = Locale.getDefault();
ArrayList<String> result = LocaleHelperUtils.getBlockedRegions(context, locale);//返回值包含"EH"與"XK"(西撒哈拉與科索沃），這兩個地區(qū)為有政治爭議的地區(qū)需謹(jǐn)慎使用
往期推薦