資源分類與訪問

應用開發(fā)過程中，經常需要用到顏色、字體、間距、圖片等資源，在不同的設備或配置中，這些資源的值可能不同。

• 應用資源：借助資源文件能力，開發(fā)者在應用中自定義資源，自行管理這些資源在不同的設備或配置中的表現(xiàn)。
• 系統(tǒng)資源：開發(fā)者直接使用系統(tǒng)預置的資源定義（即分層參數(shù)，同一資源ID在設備類型、深淺色等不同配置下有不同的取值）。

資源分類

resources目錄

應用開發(fā)中使用的各類資源文件，需要放入特定子目錄中存儲管理。resources目錄包括三大類目錄，一類為base目錄，一類為限定詞目錄，還有一類為rawfile目錄。stage模型多工程情況下共有的資源文件放到AppScope下的resources目錄。

base目錄默認存在，而限定詞目錄需要開發(fā)者自行創(chuàng)建。應用使用某資源時，系統(tǒng)會根據當前設備狀態(tài)優(yōu)先從相匹配的限定詞目錄中尋找該資源。只有當resources目錄中沒有與設備狀態(tài)匹配的限定詞目錄，或者在限定詞目錄中找不到該資源時，才會去base目錄中查找。rawfile是原始文件目錄，不會根據設備狀態(tài)去匹配不同的資源。

資源目錄示例：

resources 
|---base 
|   |---element 
|   |   |---string.json 
|   |---media 
|   |   |---icon.png 
|   |---profile 
|   |   |---test_profile.json 
|---en_US  // 默認存在的目錄，設備語言環(huán)境是美式英文時，優(yōu)先匹配此目錄下資源 
|   |---element 
|   |   |---string.json 
|   |---media 
|   |   |---icon.png 
|   |---profile 
|   |   |---test_profile.json 
|---zh_CN  // 默認存在的目錄，設備語言環(huán)境是簡體中文時，優(yōu)先匹配此目錄下資源 
|   |---element 
|   |   |---string.json 
|   |---media 
|   |   |---icon.png 
|   |---profile 
|   |   |---test_profile.json 
|---en_GB-vertical-car-mdpi // 自定義多限定詞目錄示例，由開發(fā)者創(chuàng)建 
|   |---element 
|   |   |---string.json 
|   |---media 
|   |   |---icon.png 
|   |---profile 
|   |   |---test_profile.json 
|---rawfile // 其他類型文件，原始文件形式保存，不會被集成到resources.index文件中。文件名可自定義。

表1 resources目錄分類

分類	base目錄	限定詞目錄	rawfile目錄
組織形式	base目錄是默認存在的目錄。當應用的resources目錄中沒有與設備狀態(tài)匹配的限定詞目錄時，會自動引用該目錄中的資源文件。base目錄的二級子目錄為資源組目錄，用于存放字符串、顏色、布爾值等基礎元素，以及媒體、動畫、布局等資源文件，具體要求參見資源組目錄。	en_US和zh_CN是默認存在的兩個限定詞目錄，其余限定詞目錄需要開發(fā)者自行創(chuàng)建。目錄名稱由一個或多個表征應用場景或設備特征的限定詞組合而成，具體要求參見限定詞目錄。限定詞目錄的二級子目錄為資源組目錄，用于存放字符串、顏色、布爾值等基礎元素，以及媒體、動畫、布局等資源文件，具體要求參見資源組目錄。	支持創(chuàng)建多層子目錄，目錄名稱可以自定義，文件夾內可以自由放置各類資源文件。rawfile目錄的文件不會根據設備狀態(tài)去匹配不同的資源。
編譯方式	目錄中的資源文件會被編譯成二進制文件，并賦予資源文件ID。	目錄中的資源文件會被編譯成二進制文件，并賦予資源文件ID。	目錄中的資源文件會被直接打包進應用，不經過編譯，也不會被賦予資源文件ID。
引用方式	通過指定資源類型（type）和資源名稱（name）來引用。	通過指定資源類型（type）和資源名稱（name）來引用。	通過指定文件路徑和文件名來引用。

限定詞目錄

限定詞目錄可以由一個或多個表征應用場景或設備特征的限定詞組合而成，包括移動國家碼和移動網絡碼、語言、文字、國家或地區(qū)、橫豎屏、設備類型、顏色模式和屏幕密度等維度，限定詞之間通過下劃線（_）或者中劃線（-）連接。開發(fā)者在創(chuàng)建限定詞目錄時，需要掌握限定詞目錄的命名要求，以及限定詞目錄與設備狀態(tài)的匹配規(guī)則。

限定詞目錄的命名要求

• 限定詞的組合順序：移動國家碼_移動網絡碼-語言_文字_國家或地區(qū)-橫豎屏-設備類型-顏色模式-屏幕密度。開發(fā)者可以根據應用的使用場景和設備特征，選擇其中的一類或幾類限定詞組成目錄名稱。
• 限定詞的連接方式：語言、文字、國家或地區(qū)之間采用下劃線（）連接，移動國家碼和移動網絡碼之間也采用下劃線（）連接，除此之外的其他限定詞之間均采用中劃線（-）連接。例如：zh_Hant_CN、zh_CN-car-ldpi。
• 限定詞的取值范圍：每類限定詞的取值必須符合限定詞取值要求表中的條件，否則，將無法匹配目錄中的資源文件。

表2 限定詞取值要求

限定詞類型	含義與取值說明
移動國家碼和移動網絡碼	移動國家碼（MCC）和移動網絡碼（MNC）的值取自設備注冊的網絡。MCC后面可以跟隨MNC，使用下劃線（_）連接，也可以單獨使用。例如：mcc460表示中國，mcc460_mnc00表示中國_中國移動。詳細取值范圍，請查閱ITU-T E.212（國際電聯(lián)相關標準）。
語言	表示設備使用的語言類型，由2~3個小寫字母組成。例如：zh表示中文，en表示英語，mai表示邁蒂利語。詳細取值范圍，請查閱ISO 639（ISO制定的語言編碼標準）。
文字	表示設備使用的文字類型，由1個大寫字母（首字母）和3個小寫字母組成。例如：Hans表示簡體中文，Hant表示繁體中文。詳細取值范圍，請查閱ISO 15924（ISO制定的文字編碼標準）。
國家或地區(qū)	表示用戶所在的國家或地區(qū)，由2~3個大寫字母或者3個數(shù)字組成。例如：CN表示中國，GB表示英國。詳細取值范圍，請查閱ISO 3166-1（ISO制定的國家和地區(qū)編碼標準）。
橫豎屏	表示設備的屏幕方向，取值如下：- vertical：豎屏- horizontal：橫屏
設備類型	表示設備的類型，取值如下：- car：車機- tv：智慧屏- wearable：智能穿戴
顏色模式	表示設備的顏色模式，取值如下：- dark：深色模式- light：淺色模式
屏幕密度	表示設備的屏幕密度（單位為dpi），取值如下：- sdpi：表示小規(guī)模的屏幕密度（Small-scale Dots Per Inch），適用于dpi取值為(0, 120]的設備。- mdpi：表示中規(guī)模的屏幕密度（Medium-scale Dots Per Inch），適用于dpi取值為(120, 160]的設備。- ldpi：表示大規(guī)模的屏幕密度（Large-scale Dots Per Inch），適用于dpi取值為(160, 240]的設備。- xldpi：表示特大規(guī)模的屏幕密度（Extra Large-scale Dots Per Inch），適用于dpi取值為(240, 320]的設備。- xxldpi：表示超大規(guī)模的屏幕密度（Extra Extra Large-scale Dots Per Inch），適用于dpi取值為(320, 480]的設備。- xxxldpi：表示超特大規(guī)模的屏幕密度（Extra Extra Extra Large-scale Dots Per Inch），適用于dpi取值為(480, 640]的設備。

限定詞目錄與設備狀態(tài)的匹配規(guī)則

• 在為設備匹配對應的資源文件時，限定詞目錄匹配的優(yōu)先級從高到低依次為：移動國家碼和移動網絡碼 > 區(qū)域（可選組合：語言、語言_文字、語言_國家或地區(qū)、語言_文字_國家或地區(qū)）> 橫豎屏 > 設備類型 > 顏色模式 > 屏幕密度。
• 如果限定詞目錄中包含移動國家碼和移動網絡碼、語言、文字、橫豎屏、設備類型、顏色模式限定詞，則對應限定詞的取值必須與當前的設備狀態(tài)完全一致，該目錄才能夠參與設備的資源匹配。例如，限定詞目錄“zh_CN-car-ldpi”不能參與“en_US”設備的資源匹配。

資源組目錄

base目錄與限定詞目錄下面可以創(chuàng)建資源組目錄（包括element、media、profile），用于存放特定類型的資源文件，詳見資源組目錄說明。

表3 資源組目錄說明

資源組目錄	目錄說明	資源文件
element	表示元素資源，以下每一類數(shù)據都采用相應的JSON文件來表征（目錄下只支持文件類型）。- boolean，布爾型- color，顏色- float，浮點型- intarray，整型數(shù)組- integer，整型- pattern，樣式- plural，復數(shù)形式- strarray，字符串數(shù)組- string，字符串	element目錄中的文件名稱建議與下面的文件名保持一致。每個文件中只能包含同一類型的數(shù)據。- 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 AVCBaseline 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"}]}]
}

資源訪問

應用資源

創(chuàng)建資源文件

在resources目錄下，可按照限定詞目錄和資源組目錄的說明創(chuàng)建子目錄和目錄內的文件。

同時，DevEco Studio也提供了創(chuàng)建資源目錄和資源文件的界面。

• 創(chuàng)建資源目錄及資源文件

  在resources目錄右鍵菜單選擇“New > Resource File”，此時可同時創(chuàng)建目錄和文件。文件默認創(chuàng)建在base目錄的對應資源組下。如果選擇了限定詞，則會按照命名規(guī)范自動生成限定詞+資源組目錄，并將文件創(chuàng)建在目錄中。圖中Avaliable qualifiers為供選擇的限定詞目錄，通過右邊的小箭頭可添加或者刪除。File name為需要創(chuàng)建的文件名，Resource type為資源組類型，默認是element。Root Element為資源類型。創(chuàng)建的目錄名自動生成，格式固定為“限定詞.資源組”，例如：創(chuàng)建一個限定詞為dark的element目錄，自動生成的目錄名稱為“dark.element”。

  

• 創(chuàng)建資源目錄

  在resources目錄右鍵菜單選擇“New > Resource Directory”，此時可創(chuàng)建資源目錄。資源目錄創(chuàng)建的是base目錄，也可根據需求創(chuàng)建其它限定詞目錄。確定限定詞后，選擇資源組類型，當前資源組類型支持Element、Media、Profile三種，創(chuàng)建后自動生成目錄名稱。

  

• 創(chuàng)建資源文件

  在資源目錄的右鍵菜單選擇“New > XXX Resource File”，即可創(chuàng)建對應資源組目錄的資源文件。例如，在element目錄下可新建Element Resource File。

  

訪問應用資源

在工程中，通過"$r(‘app.type.name’)"的形式引用應用資源。app代表是應用內resources目錄中定義的資源；type代表資源類型（或資源的存放位置），可以取“color”、“float”、“string”、“plural”、“media”，name代表資源命名，由開發(fā)者定義資源時確定。

引用rawfile下資源時使用"$rawfile(‘filename’)“的形式，filename需要表示為rawfile目錄下的文件相對路徑，文件名需要包含后綴，路徑開頭不可以以”/"開頭。

訪問rawfile文件的descriptor時，可使用資源管理getRawFd接口，其返回值descriptor.fd為hap包的fd，訪問此rawfile文件需要結合{fd, offset, length}一起使用。

說明

資源描述符不能拼接使用，僅支持普通字符串如’app.type.name’。

$r返回值為Resource對象，可通過getStringValue 方法獲取對應的字符串。

在xxx.ets文件中，可以使用在resources目錄中定義的資源。資源分類中資源組目錄下的“資源文件示例”顯示了.json文件內容，包含color.json文件、float.json文件、string.json和plural.json文件。應用資源的具體使用方法如下：

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的第一個參數(shù)指定string資源，第二個參數(shù)用于替換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資源，第二個參數(shù)用于指定單復數(shù)（在中文，單復數(shù)均使用other。在英文，one：代表單數(shù)，取值為1；other：代表復數(shù)，取值為大于等于1的整數(shù)），第三個參數(shù)用于替換%d
// 如下示例代碼為復數(shù)，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目錄下圖片

系統(tǒng)資源

系統(tǒng)資源包含色彩、圓角、字體、間距、字符串及圖片等。通過使用系統(tǒng)資源，不同的開發(fā)者可以開發(fā)出具有相同視覺風格的應用。

開發(fā)者可以通過“$r(‘sys.type.resource_id’)”的形式引用系統(tǒng)資源。sys代表是系統(tǒng)資源；type代表資源類型，可以取“color”、“float”、“string”、“media”；resource_id代表資源id。

說明

• 僅聲明式開發(fā)范式支持使用系統(tǒng)資源，類Web開發(fā)范式不支持。

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)
er({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)