HarmonyOS服務卡片如何換膚

作者：zhenyu，華為軟件開發工程師

關注HarmonyOS的小伙伴肯定對服務卡片已經很熟悉了。服務卡片(也簡稱為“卡片”)是FA(FeatureAbility，元服務)的一種界面展示形式，將FA的重要信息或操作前置到卡片，以達到服務直達，減少體驗層級的目的。類似手機上應用的換膚，服務卡片也支持換膚。本期，我們就來聊一聊卡片換膚。

一、“卡片換膚”換的是什么?

服務卡片的UI界面由一系列的資源組成，這些資源包括顏色、文本、圖標和圓角等等。不同資源有對應的資源ID，通過替換資源ID對應的資源就可以實現換膚。

為了讓大家更了解卡片換膚，下面來看兩個示例：

1.更改卡片的圓角大小。

2.更改卡片的背景顏色和文字顏色。

通過上面兩個示例，我們看到：通過修改卡片的圓角資源參數、背景顏色、文本顏色等就對卡片進行了簡單的換膚。實際場景中，我們還可以對圖標、多彩色板、切圖資源等各類卡片資源進行修改和替換，實現更復雜的換膚。

二、如何實現卡片換膚?

卡片換膚需要應用開發者、主題開發者和系統三者的配合?？ㄆ瑩Q膚的整體流程如圖3所示。

圖3 卡片換膚流程

卡片換膚流程說明如下：

步驟一：應用開發者在開發卡片時，可以自定義卡片的各項資源及其資源ID。

步驟二：主題開發者在開發主題包時會使用新的資源來替換資源ID對應的資源信息。

步驟三：用戶下載和安裝主題包后，在切換主題時，由系統自動完成卡片相應的資源替換，從而達到卡片換膚的目的。

下面我們以JS卡片為例分別從應用開發者、主題開發者、系統三者的角度來介紹卡片換膚的實現方案。

1. 應用開發者：開發卡片

JS卡片工程中，應用開發者可以使用的資源，包括三類：JS模塊資源、應用資源和系統資源。下面一一介紹如何引用這三類資源。

(1)JS模塊資源

JS模塊資源指的是src/main/js/Component下resources目錄中的資源，如圖4所示。

圖4 JS模塊資源

此類資源的主要特點是只能在該JS模塊范圍內引用。引用方法一般為在應用開發的hml和js文件中使用$r的語法，對JS模塊內resources目錄下的json資源進行格式化，獲取相應的資源內容。

下面我們通過一個示例來說明JS模塊資源的引用方法。

例如，resources/res-defaults.json中定義了以下資源：

{    "image": {"clockFace":"common/face.png"},    "colors": { "background":"#ffffff"}}

在hml文件中可以通過{{ $r('colors.background') }}和{{ $r('image.clockFace') }}分別引用上面定義的background和clockFace資源。代碼如下：

<div style="background-color: {{ $r('colors.background') }}">    <image src="{{ $r('image.clockFace') }}">image>div>

(2)應用資源

應用資源指的是與java、js目錄同級的resources目錄中的資源，如圖5所示。

圖5 應用資源

應用資源的特點是所有JS模塊共享，可認為是應用內共享。從API Version 6開始，可以在hml/css/json文件中引用應用資源，包括顏色、圓角和圖片類型的資源。

在css文件中，通過“@app.type.resource_id”的形式引用應用資源。

在hml文件中，通過“{{$r('app.type.resource_id')}}”的形式引用應用資源。

在json文件中，通過“this.$r('app.type.resource_id')”的形式引用應用資源。

其中，“app”是固定字符串，代表應用資源?！皌ype”表示引用的資源類型，可以取值為“color”(顏色)、“float”(圓角)和“media”(圖片)?！皉esource_id”表示應用資源ID，取值為color.json或float.json中的“name”字段值，或者media目錄中圖片文件的名稱(不包含圖片類型后綴)。

下面我們通過一個示例來說明應用資源的引用方法。

例如，color.json中定義了背景色和前景色兩個資源：

{    "color": [        {            "name": "my_background_color",            "value": "#ffff0000"        },        {            "name": "my_foreground_color",            "value": "#ff0000ff"        }            ]}

其中，背景色資源ID為my_background_color，前景色資源ID為my_foreground_color。

在css文件中可以通過@app.color.my_background_color引用背景色資源，代碼如下：

.divA {    background-color: "@app.color.my_background_color";    border-radius: "@app.float.my_radius";      }

在hml文件中可以通過{{$r('app.color.my_background_color')}}引用背景色資源，代碼如下：

{    "data":{        "myColor": "this.$r('app.color.my_background_color')",        "myRadius": "this.$r('app.float.my_radius')",        "myImage":"this.$r('app.media.my_background_image')"}}

(3)系統資源

系統資源指的是系統預置的資源。HarmonyOS為服務卡片提供了一系列統一的資源ID標識，這些標識在系統中對應了默認的資源信息。這些資源不在應用工程中，但應用可以通過特定的語法來訪問。(系統資源的詳細信息可參考文末鏈接。)

系統資源的特點是所有應用均可訪問，但具體的資源內容或資源值是根據應用的上下文獲取到的。從API Version 6開始，在hml/css/json文件中可以引用系統資源，包括顏色、圓角和圖片類型的資源。系統資源的引用方法與應用資源比較類似，只是資源前綴由“app”換成“sys”了，“sys”代表系統資源。

在css文件中，通過“@sys.type.resource_id”的形式引用系統資源。

.divA {    background-color: "@sys.color.fa_background";    border-radius: "@sys.float.fa_corner_radius_card";      }

在hml文件中，通過“{{$r('sys.type.resource_id')}}”的形式引用系統資源。

<div style="background-color:{{$r('sys.color.fa_background')}};">div><div style="border-radius:{{$r('sys.float.fa_corner_radius_card')}};">div><divstyle="background-image:{{$r('sys.media.fa_card_background')}};">div>

在json文件中，通過“this.$r('sys.type.resource_id')”的形式引用系統資源。

{    "data":{        "sysColor": "this.$r('sys.color.fa_background')",        "sysRadius": "this.$r('sys.float.fa_corner_radius_card')",        "sysImage":"this.$r('sys.media.fa_card_background')"}}

比較推薦卡片優先引用系統資源ID來適配UI界面。這樣，主題開發者做換膚適配時，可以極大減少對單個應用的資源ID適配的工作量，同時避免應用升級引用資源ID發生變化時引起的兼容性問題。

2. 主題開發者：開發主題包

“主題”由企業或個人開發者設計開發，主要是對系統皮膚界面進行個性化設計，這其中也包括對卡片皮膚界面的個性化設計。

主題開發者在開發主題包的時候，根據卡片引用的資源，開發新的資源進行替換。

下面我們通過一個示例主題包來進行介紹：

此示例中，應用開發者在開發卡片時同時引用了應用資源和系統資源。主題包的目錄結構與卡片工程的目錄結構一一對應。圖6展示了主題包與卡片工程之間的資源覆蓋關系。

圖6 主題包資源覆蓋

主題包的外層colors.json文件用于覆蓋應用中自定義的color資源定義。

主題包的外層的floats.json文件用于覆蓋應用中自定義的float類型資源定義，如自定義圓角大小等。

主題包的entry目錄用于替換卡片工程中entry目錄的資源，分別替換entry/src/resources/base/media目錄的淺色模式下的圖片，entry/src/resources/dark/media目錄的深色模式下的圖片。

主題包的ohos.global.systemres目錄中的colors.json文件用于覆蓋引用的系統顏色資源定義，floats.json文件用于覆蓋引用的系統圓角資源定義。

另外，我們為廣大主題開發者提供了一款智能、高效的主題開發工具——Theme Studio。工具的相關信息和主題的開發教程可參考文末鏈接。

3. 系統：切換主題

用戶在華為主題APP中下載主題包后，后續的主題切換由系統自動完成。系統切換主題的流程如圖7所示。

圖7 切換主題

用戶在點擊主題包后，主題APP對主題包進行解壓解析，然后通知系統進行資源切換。系統資源管理模塊根據應用包名對其引用的資源ID進行重定向映射，使用主題包中對應的資源完成解析替換，然后通知卡片應用重新加載刷新?？ㄆ瑧米x取到重映射后的資源，將其刷新顯示到界面上。

三、開發實例

了解了卡片換膚的整體實現方案之后，下面我們來看一個簡單的卡片換膚開發實例：

1.新建卡片工程，應用包名com.example.cardtest。

2.編寫卡片的界面布局hml，并設置卡片的圖標和文本顏色。

圖8 卡片界面布局代碼

3.查看卡片顯示效果，如圖9所示。

4.制作測試主題包，添加com.example.cardtest應用資源。

圖10 com.example.cardtest應用資源

　　圖11 資源內容

資源替換說明如下：

• entry esourcesasemedia目錄下的圖片資源替換應用圖標ic_icon.png。

• 外層colors.json替換第一行文本顏色為黑色。

{  "color": [    {      "name": "text_color",      "value": "#000000"    }           ]}

• ohos.global.systemres目錄下colors.json替換第二行文本顏色為藍色。

{    "color": [        {            "name": "fa_text_primary",            "value": "#ff0000ff"        }             ]}

5.進入主題APP，應用上面制作的測試主題包。顯示效果如圖12所示。

四、結束語

以上就是本期卡片換膚的全部內容了。通過本期的介紹，對于卡片換膚的概念和具體實現，您是否都已經了解了呢?最后，我們為還想深入學習和了解的同學匯總了一些鏈接，建議收藏!

想了解更多HarmonyOS技術?后臺留言，立刻安排!

原文標題：一文讀懂服務卡片怎么換膚

文章出處：【微信公眾號：HarmonyOS開發者】歡迎添加關注!文章轉載請注明出處。

審核編輯：湯梓紅