資源使用

在頁面開發過程中，經常需要用到顏色、字體、間距、圖片等資源，在不同的設備或配置中，這些資源的值可能不同。有兩種方式處理：

• [應用資源]：借助資源文件能力，開發者在應用中自定義資源，自行管理這些資源在不同的設備或配置中的表現。
• [系統資源]：開發者直接使用系統預置的資源定義（即分層參數）。
• 開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

應用資源

資源文件介紹

應用開發中使用的各類自定義資源文件，需要統一存放于應用的resources目錄下，便于使用和維護。resources目錄包括兩大類目錄，一類為base目錄與限定詞目錄，另一類為rawfile目錄，其基礎目錄結構如下所示。

resources
|---base  // 默認存在的目錄
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|---en_GB-vertical-car-mdpi // 限定詞目錄示例，需要開發者自行創建   
|   |---element
|   |   |---string.json
|   |---media
|   |   |---icon.png
|---rawfile  // rawfile目錄

base目錄默認存在，而限定詞目錄需要開發者自行創建，其名稱可以由一個或多個表征應用場景或設備特征的限定詞組合而成。應用使用某資源時，系統會根據當前設備狀態優先從相匹配的限定詞目錄中尋找該資源。只有當resources目錄中沒有與設備狀態匹配的限定詞目錄，或者在限定詞目錄中找不到該資源時，才會去base目錄中查找。rawfile是原始文件目錄，它不會根據設備狀態去匹配不同的資源，故不在本文的討論范文內。

說明：

• 請訪問[聲明式開發范式資源文件分類]，了解限定詞目錄的命名規則、創建流程、匹配規則等，本文不展開介紹。
• 沒有設備狀態匹配的限定詞目錄，或者在限定詞目錄中找不到目標資源時，會繼續在base目錄中查找。 強烈建議對于所有應用自定義資源都在base目錄中定義默認值 ，防止出現找不到資源值的異常場景。
• 類Web開發范式的資源文件路徑及資源限定詞的使用與聲明式范式不同，詳情請參考[類Web開發范式資源限定與訪問]及[類Web開發范式文件組織]。

base目錄與限定詞目錄下面可以創建資源組目錄（包括element、media等），用于存放特定類型的資源文件。

在element目錄的各個資源文件中，以“name-value”的形式定義資源，如下所示。而在media目錄中，直接以文件名作為name，故開發者將文件放入media目錄即可，無需再額外定義name。

// color.json 
{
    "color": [
        {
            "name": "color_red",
            "value": "#ffff0000"
        },
        {
            "name": "color_blue",
            "value": "#ff0000ff"
        }
    ]
}

訪問應用資源

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

說明： 可以查看[聲明式范式訪問應用資源]，了解資源訪問的更多細節。

示例

在應用的resources目錄下，創建名為tablet的限定詞子目錄，并按照下表所示，在base目錄和tablet限定詞目錄中添加相應的資源。

在代碼中通過 "$r('app.type.name')" 的形式使用應用資源，并分別在默認設備和平板上查看代碼的運行效果，可以發現同一資源在不同設備上的取值不同。

@Entry
@Component
struct Index {
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text($r("app.string.my_string"))
        .fontSize($r("app.float.my_float"))
        .fontColor($r("app.color.my_color"))
      Image($r("app.media.my_image"))
        .width(100)
        .height(100)
    }
    .width('100%')
    .height('100%')
  }
}

系統資源

除了自定義資源，開發者也可以使用系統中預定義的資源（即[分層參數]，同一資源ID在設備類型、深淺色等不同配置下有不同的取值）。

視覺基礎

虛擬像素單位：vp

虛擬像素(virtual pixel)是一臺設備針對應用而言所具有的虛擬尺寸（區別于屏幕硬件本身的像素單位）。它提供了一種靈活的方式來適應不同屏幕密度的顯示效果。

相同的vp，在不同像素密度的屏幕上，對應不同px，一般稱px/vp為像素密度比。像素密度比為當前設備屏幕的dpi/160。

在dpi為160的OpenHarmony設備上，像素密度比為1，則1vp等于1px。

以vp為尺寸標注單位，可使相同元素在不同密度的設備上具有一致的視覺體量，使用px則容易導致體量不一致的問題。

8vp網格系統

基于 8vp 為網格的基本單位可以對界面上元素的大小、位置、對齊方式進行更好的規劃，構建更有層次感、秩序感，以及多設備上一致的布局效果。一些更小的控件（例如圖標）大小也可以對齊 4vp 的網格大小。

字體像素單位：fp

字體像素(font pixel) 大小默認情況下與 vp 相同，即默認情況下 1 fp = 1vp。如果用戶在設置中選擇了更大的字體，字體的實際顯示大小就會在 vp 的基礎上乘以 scale 系數，即 1 fp = 1 vp * scale。

視覺屬性：分層參數

分層參數是根據使用場景定義的視覺屬性ID，通過在不同色彩主題、多種設備上配置不同的數值，實現多設備適配的效果。OpenHarmony的分層參數包含色彩、字體、圓角、間距、陰影、模糊、縮放，并提供了默認實現。設備、應用、服務均可在此基礎上管理并自定義不同場景的視覺屬性。

例如，對于不同場景的主色調定義了對應的ID與默認實現

在開發過程中，分層參數的用法與資源限定詞基本一致。開發者可以通過"$r('sys.type.resource_id')"的形式引用系統資源。sys代表是系統資源；type代表資源類型，值可以取color、float、string和media；resource_id代表資源id。

可以查看[應用UX設計中關于資源的介紹]，獲取系統支持的資源ID及其在不同配置下的取值。

說明：

• 僅聲明式開發范式支持使用分層參數，類Web開發范式不支持。
• 系統資源可以保證不同團隊開發出的應用有較為一致的視覺風格。對于系統預置應用，強烈建議使用系統資源；對于三方應用，可以根據需要選擇使用系統資源或自定義應用資源。
• 可以查看[resources代碼倉]了解系統預置資源的實現，這里的目錄結構與工程中的resources目錄類似，也是通過資源限定詞匹配不同的設備或設備狀態。

審核編輯 黃宇