資源使用

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

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

應用資源

資源文件介紹

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

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

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

說明：

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

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

在element目錄的各個資源文件中，以“name-value”的形式定義資源，如下所示。而在media目錄中，直接以文件名作為name，故開發(fā)者將文件放入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代表資源命名，由開發(fā)者添加資源時確定。

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

示例

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

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

@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%')
  }
}

系統(tǒng)資源

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

視覺基礎

虛擬像素單位：vp

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

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

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

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

8vp網格系統(tǒng)

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

字體像素單位：fp

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

視覺屬性：分層參數

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

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

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

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

說明：

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

審核編輯 黃宇