資源分類與訪問

資源分類

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

資源目錄示例：

resources
|---base
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---en_US  // 默認(rèn)存在的目錄，設(shè)備語言環(huán)境是美式英文時(shí)，優(yōu)先匹配此目錄下資源
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|   |---profile
|   |   |---test_profile.json
|---zh_CN  // 默認(rèn)存在的目錄，設(shè)備語言環(huán)境是簡體中文時(shí)，優(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 // 其他類型文件，原始文件形式保存，不會(huì)被集成到resources.index文件中。文件名可自定義。

資源目錄

資源組目錄

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

表3 資源組目錄說明

媒體資源類型說明

表4 圖片資源類型說明

表5 音視頻資源類型說明

資源文件示例

color.json文件的內(nèi)容如下：

{
    "color": [
        {
            "name": "color_hello",
            "value": "#ffff0000"
        },
        {
            "name": "color_world",
            "value": "#ff0000ff"
        }
    ]
}

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

{
    "float":[
        {
            "name":"font_hello",
            "value":"28.0fp"
        },
    {
            "name":"font_world",
            "value":"20.0fp"
        }
    ]
}

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

{
    "string":[
        {
            "name":"string_hello",
            "value":"Hello"
        },
    {
            "name":"string_world",
            "value":"World"
        },
    {
            "name":"message_arrive",
            "value":"We will arrive at %s."
        }
    ]
}

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

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

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

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

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

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

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

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

創(chuàng)建資源目錄

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

創(chuàng)建資源文件

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

資源訪問

應(yīng)用資源

• 對于應(yīng)用資源，在工程中，通過"$r('app.type.name')"形式引用。其中，app為應(yīng)用內(nèi)resources目錄中定義的資源；type為資源類型或資源的存放位置，取值包含“color”、“float”、“string”、“plural”、“media”；name為資源命名，由開發(fā)者定義資源時(shí)確定。

• 對于rawfile目錄資源，通過"$rawfile('filename')"形式引用。其中，filename為rawfile目錄下文件的相對路徑，文件名需要包含后綴，路徑開頭不可以以"/"開頭。

• 對于rawfile目錄的descriptor，可通過資源管理的getRawFd接口引用，其返回值descriptor.fd為hap包的fd。此時(shí)，訪問rawfile文件需要結(jié)合{fd, offset, length}一起使用。

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

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

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

除了自定義資源，開發(fā)者也可以使用系統(tǒng)中預(yù)定義的資源，統(tǒng)一應(yīng)用的視覺風(fēng)格。可以查看應(yīng)用UX設(shè)計(jì)中關(guān)于資源的介紹，獲取支持的系統(tǒng)資源ID及其在不同配置下的取值。

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

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)

資源匹配

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

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

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

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

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