資源分類與訪問

2024-01-25 11:59 更新

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

  • 應用資源:借助資源文件能力,開發(fā)者在應用中自定義資源,自行管理這些資源在不同的設備或配置中的表現(xiàn)。

  • 系統(tǒng)資源:開發(fā)者直接使用系統(tǒng)預置的資源定義(即分層參數(shù),同一資源ID在設備類型、深淺色等不同配置下有不同的取值)。

資源分類

應用開發(fā)中使用的各類資源文件,需要放入特定子目錄中存儲管理。資源目錄的示例如下所示,base目錄、限定詞目錄、rawfile目錄稱為資源目錄,element、media、profile稱為資源組目錄。

說明

stage模型多工程情況下,共有的資源文件放到AppScope下的resources目錄。

資源目錄示例:

  1. resources
  2. |---base
  3. | |---element
  4. | | |---string.json
  5. | |---media
  6. | | |---icon.png
  7. | |---profile
  8. | | |---test_profile.json
  9. |---en_US // 默認存在的目錄,設備語言環(huán)境是美式英文時,優(yōu)先匹配此目錄下資源
  10. | |---element
  11. | | |---string.json
  12. | |---media
  13. | | |---icon.png
  14. | |---profile
  15. | | |---test_profile.json
  16. |---zh_CN // 默認存在的目錄,設備語言環(huán)境是簡體中文時,優(yōu)先匹配此目錄下資源
  17. | |---element
  18. | | |---string.json
  19. | |---media
  20. | | |---icon.png
  21. | |---profile
  22. | | |---test_profile.json
  23. |---en_GB-vertical-car-mdpi // 自定義限定詞目錄示例,由開發(fā)者創(chuàng)建
  24. | |---element
  25. | | |---string.json
  26. | |---media
  27. | | |---icon.png
  28. | |---profile
  29. | | |---test_profile.json
  30. |---rawfile // 其他類型文件,原始文件形式保存,不會被集成到resources.index文件中。文件名可自定義。

資源目錄

base目錄

base目錄是默認存在的目錄,二級子目錄element用于存放字符串、顏色、布爾值等基礎元素,media、profile存放媒體、動畫、布局等資源文件。

目錄中的資源文件會被編譯成二進制文件,并賦予資源文件ID。通過指定資源類型(type)和資源名稱(name)引用。

限定詞目錄

en_US和zh_CN是默認存在的兩個限定詞目錄,其余限定詞目錄需要開發(fā)者根據(jù)開發(fā)需要自行創(chuàng)建。二級子目錄element、media、profile用于存放字符串、顏色、布爾值等基礎元素,以及媒體、動畫、布局等資源文件。

同樣,目錄中的資源文件會被編譯成二進制文件,并賦予資源文件ID。通過指定資源類型(type)和資源名稱(name)來引用。

限定詞目錄的命名要求

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

  • 限定詞的組合順序:_移動國家碼_移動網(wǎng)絡碼-語言_文字_國家或地區(qū)-橫豎屏-設備類型-顏色模式-屏幕密度_。開發(fā)者可以根據(jù)應用的使用場景和設備特征,選擇其中的一類或幾類限定詞組成目錄名稱。

  • 限定詞的連接方式:語言、文字、國家或地區(qū)之間采用下劃線(_)連接,移動國家碼和移動網(wǎng)絡碼之間也采用下劃線(_)連接,除此之外的其他限定詞之間均采用中劃線(-)連接。例如:zh_Hant_CN、zh_CN-car-ldpi

  • 限定詞的取值范圍:每類限定詞的取值必須符合限定詞取值要求表中的條件,如表2。否則,將無法匹配目錄中的資源文件。

表2 限定詞取值要求

限定詞類型

含義與取值說明

移動國家碼和移動網(wǎng)絡碼

移動國家碼(MCC)和移動網(wǎng)絡碼(MNC)的值取自設備注冊的網(wǎng)絡。

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:車機

- tablet:平板

- 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]的設備。

rawfile目錄

支持創(chuàng)建多層子目錄,目錄名稱可以自定義,文件夾內(nèi)可以自由放置各類資源文件。

目錄中的資源文件會被直接打包進應用,不經(jīng)過編譯,也不會被賦予資源文件ID。通過指定文件路徑和文件名引用。

資源組目錄

資源組目類型包括element、media、profile,用于存放特定類型的資源文件。

表3 資源組目錄說明

目錄類型

說明

資源文件

element

表示元素資源,以下每一類數(shù)據(jù)都采用相應的JSON文件來表征(目錄下僅支持文件類型)。

- boolean,布爾型

- color,顏色

- float,浮點型

- intarray,整型數(shù)組

- integer,整型

- pattern,樣式

- plural,復數(shù)形式

- strarray,字符串數(shù)組

- string,字符串

element目錄中的文件名稱建議與下面的文件名保持一致。每個文件中只能包含同一類型的數(shù)據(jù)。

- boolean.json

- color.json

- float.json

- intarray.json

- integer.json

- pattern.json

- plural.json

- strarray.json

- string.json

media

表示媒體資源,包括圖片、音頻、視頻等非文本格式的文件(目錄下只支持文件類型)。

圖片和音視頻的類型說明間表4和表5。

文件名可自定義,例如:icon.png。

profile

表示自定義配置文件,其文件內(nèi)容可通過包管理接口獲取(目錄下只支持文件類型)。

文件名可自定義,例如: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文件的內(nèi)容如下:

  1. {
  2. "color": [
  3. {
  4. "name": "color_hello",
  5. "value": "#ffff0000"
  6. },
  7. {
  8. "name": "color_world",
  9. "value": "#ff0000ff"
  10. }
  11. ]
  12. }

float.json文件的內(nèi)容如下:

  1. {
  2. "float":[
  3. {
  4. "name":"font_hello",
  5. "value":"28.0fp"
  6. },
  7. {
  8. "name":"font_world",
  9. "value":"20.0fp"
  10. }
  11. ]
  12. }

string.json文件的內(nèi)容如下:

  1. {
  2. "string":[
  3. {
  4. "name":"string_hello",
  5. "value":"Hello"
  6. },
  7. {
  8. "name":"string_world",
  9. "value":"World"
  10. },
  11. {
  12. "name":"message_arrive",
  13. "value":"We will arrive at %s."
  14. }
  15. ]
  16. }

plural.json文件的內(nèi)容如下:

  1. {
  2. "plural":[
  3. {
  4. "name":"eat_apple",
  5. "value":[
  6. {
  7. "quantity":"one",
  8. "value":"%d apple"
  9. },
  10. {
  11. "quantity":"other",
  12. "value":"%d apples"
  13. }
  14. ]
  15. }
  16. ]
  17. }

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

在resources目錄下,可按照限定詞目錄命名規(guī)則,以及資源組目錄支持的文件類型和說明,創(chuàng)建資源目錄和資源組目錄,添加特定類型資源。DevEco Studio支持同時創(chuàng)建資源目錄和資源文件,也支持單獨創(chuàng)建資源目錄或資源文件。

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

在resources目錄右鍵菜單選擇“New > Resource File”,可同時創(chuàng)建資源目錄和資源文件,文件默認創(chuàng)建在base目錄的對應資源組。如果選擇了限定詞,則會按照命名規(guī)范自動生成限定詞和資源組目錄,并將文件創(chuàng)建在限定詞目錄中。

圖中File name為需要創(chuàng)建的文件名。Resource type為資源組類型,默認是element。Root Element為資源類型。Avaliable qualifiers為供選擇的限定詞目錄,通過右邊的小箭頭可添加或者刪除。

創(chuàng)建的目錄名自動生成,格式固定為“限定詞.資源組”,例如:創(chuàng)建一個限定詞為dark的element目錄,自動生成的目錄名稱為“dark.element”。

創(chuàng)建資源目錄

在resources目錄右鍵菜單選擇“New > Resource Directory”,可創(chuàng)建資源目錄,默認創(chuàng)建的是base目錄。如果選擇了限定詞,則會按照命名規(guī)范自動生成限定詞和資源組目錄。確定限定詞后,選擇資源組類型,當前資源組類型支持Element、Media、Profile三種,創(chuàng)建后生成資源目錄。

創(chuàng)建資源文件

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

資源訪問

應用資源

  • 對于應用資源,在工程中,通過"$r('app.type.name')"形式引用。其中,app為應用內(nèi)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 方法獲取對應的字符串。

資源組目錄下的“資源文件示例”顯示了.json文件內(nèi)容,包含color.json文件、string.json文件和plural.json文件,訪問應用資源時需先了解.json文件的使用規(guī)范。

資源的具體使用方法如下:

  1. Text($r('app.string.string_hello'))
  2. .fontColor($r('app.color.color_hello'))
  3. .fontSize($r('app.float.font_hello'))
  4. Text($r('app.string.string_world'))
  5. .fontColor($r('app.color.color_world'))
  6. .fontSize($r('app.float.font_world'))
  7. // 引用string.json資源。Text中$r的第一個參數(shù)指定string資源,第二個參數(shù)用于替換string.json文件中的%s。
  8. // 如下示例代碼value為"We will arrive at five of the clock"。
  9. Text($r('app.string.message_arrive', "five of the clock"))
  10. .fontColor($r('app.color.color_hello'))
  11. .fontSize($r('app.float.font_hello'))
  12. // 引用plural$資源。Text中$r的第一個指定plural資源,第二個參數(shù)用于指定單復數(shù)(在中文,單復數(shù)均使用other。在英文,one:代表單數(shù),取值為1;other:代表復數(shù),取值為大于等于1的整數(shù)),第三個參數(shù)用于替換%d
  13. // 如下示例代碼為復數(shù),value為"5 apples"。
  14. Text($r('app.plural.eat_apple', 5, 5))
  15. .fontColor($r('app.color.color_world'))
  16. .fontSize($r('app.float.font_world'))
  17. Image($r('app.media.my_background_image')) // media資源的$r引用
  18. Image($rawfile('test.png')) // rawfile$r引用rawfile目錄下圖片
  19. Image($rawfile('newDir/newTest.png')) // rawfile$r引用rawfile目錄下圖片

系統(tǒng)資源

除了自定義資源,開發(fā)者也可以使用系統(tǒng)中預定義的資源,統(tǒng)一應用的視覺風格??梢圆榭?a rel="external nofollow" target="_blank" rel="external nofollow" target="_blank" target="_blank">應用UX設計中關于資源的介紹,獲取支持的系統(tǒng)資源ID及其在不同配置下的取值。

在開發(fā)過程中,分層參數(shù)的用法與資源限定詞基本一致。對于系統(tǒng)資源,可以通過“$r('sys.type.resource_id')”的形式引用。其中,sys為系統(tǒng)資源;type為資源類型,取值包括“color”、“float”、“string”、“media”;resource_id為資源id。

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

  • 對于系統(tǒng)預置應用,建議使用系統(tǒng)資源;對于三方應用,可以根據(jù)需要選擇使用系統(tǒng)資源或自定義應用資源。

  1. Text('Hello')
  2. .fontColor($r('sys.color.ohos_id_color_emphasize'))
  3. .fontSize($r('sys.float.ohos_id_text_size_headline1'))
  4. .fontFamily($r('sys.string.ohos_id_text_font_family_medium'))
  5. .backgroundColor($r('sys.color.ohos_id_color_palette_aux1'))
  6. Image($r('sys.media.ohos_app_icon'))
  7. .border({
  8. color: $r('sys.color.ohos_id_color_palette_aux1'),
  9. radius: $r('sys.float.ohos_id_corner_radius_button'), width: 2
  10. })
  11. .margin({
  12. top: $r('sys.float.ohos_id_elements_margin_horizontal_m'),
  13. bottom: $r('sys.float.ohos_id_elements_margin_horizontal_l')
  14. })
  15. .height(200)
  16. .width(300)

資源匹配

應用使用某資源時,系統(tǒng)會根據(jù)當前設備狀態(tài)優(yōu)先從相匹配的限定詞目錄中尋找該資源。只有當resources目錄中沒有與設備狀態(tài)匹配的限定詞目錄,或者在限定詞目錄中找不到該資源時,才會去base目錄中查找。rawfile是原始文件目錄,不會根據(jù)設備狀態(tài)去匹配不同的資源。

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

  • 在為設備匹配對應的資源文件時,限定詞目錄匹配的優(yōu)先級從高到低依次為:移動國家碼和移動網(wǎng)絡碼 > 區(qū)域(可選組合:語言、語言_文字、語言_國家或地區(qū)、語言_文字_國家或地區(qū))> 橫豎屏 > 設備類型 > 顏色模式 > 屏幕密度。

  • 如果限定詞目錄中包含移動國家碼和移動網(wǎng)絡碼、語言、文字、橫豎屏、設備類型、顏色模式限定詞,則對應限定詞的取值必須與當前的設備狀態(tài)完全一致,該目錄才能夠參與設備的資源匹配。例如,限定詞目錄“zh_CN-car-ldpi”不能參與“en_US”設備的資源匹配。

應用界面加載資源規(guī)則,更多請參考國際化和本地化文檔。

以上內(nèi)容是否對您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號