HarmonyOS NEXT應用開發之深色模式適配

介紹

本示例介紹在開發應用以適應深色模式時，對於深色和淺色模式的適配方案，採取了多種策略如下：

1. 固定屬性適配：對於部分組件的顏色屬性，如背景色或字體顏色，若保持不變，可直接設定固定色值或引用固定的資源文件。
2. 雙資源目錄適配：在resources目錄下新增dark子目錄，用於存放深色模式下的特定顏色配置（color.json文件）和圖片資源（media文件）。在深色模式下，系統會自動載入此目錄中的顏色及圖片資源，確保與淺色模式下的UI元素色彩差異性。
3. 利用系統分層參數：對於支持深淺模式切換的系統層級顏色資源，我們可以直接引用這些具有分層特性的參數，使得當切換設備主題時，相關組件的顏色能根據系統當前顏色模式自動更新。
4. 監聽當前顏色模式變化：通過註冊AbilityStage.onConfigurationUpdate事件監聽器，實時捕捉到設備深淺顏色模式的變化，並據此動態調整UI佈局結構或邏輯處理，以適應不同模式下的最佳視覺體驗。

效果圖預覽

使用說明

1. 在應用主頁點擊“深色模式”案例，將應用切至後臺，系統顏色模式發生改變（如在系統設置中切換深淺色模式），當應用重新被激活至前臺時，能夠立即檢測到系統顏色模式的變化，並自動更新為對應顏色主題的視圖界面。

實現思路

1. 當UI組件的顏色屬性被設置為固定顏色值時，其在深色模式和淺色模式下的顯示顏色將保持不變。

// 將Text直接設置成'#000000'固定色值
Text("精品好禮")
 .opacity(0.6)
 .fontColor($r('app.color.black_font_color'))
 .margin({ left: $r('app.integer.text_margin_left') })

2. 為了實現深色模式下的顏色適配，可以在resources目錄下新建'dark/element'的子目錄，併在此目錄中創建color.json文件。為深色模式下的各個UI組件指定相應的顏色值，務必確保與淺色模式下同名顏色資源名稱一致，以確保系統能夠正確識別並切換。

// 用資源ID方式設置Column背景色。（淺色模式色值為'#FA5A3C'、深色模式色值為'#000000'）
.backgroundColor($r('app.color.column_bg_color'))

3. 若UI組件的顏色屬性引用的是系統提供的具有層級參數的顏色資源，則當設備在深色模式和淺色模式間切換時，這些顏色會自動調整至對應模式下的預設色值。

// 用系統提供的分層參數顏色資源方式設置色值 
Text(item.price)
 .fontSize($r('app.integer.goods_font'))
 .offset({ x: -3 })// 因為￥是中文字元，上面的是中文字元，占的寬度不一樣，所以需要對齊，添加offset
 .fontColor($r('sys.color.ohos_id_color_foreground'))

4. 對於PNG、WEBP或JPEG格式的圖片資源，若需支持深色模式，應在resources目錄下新增一個'dark/media'子目錄，將深色模式下對應的圖片放入此目錄，並確保圖片文件名與淺色模式下的圖片相同，以便系統根據當前模式載入合適的圖片資源。

// SVG格式圖片fillColor顏色資源ID方式設置（淺色模式色值為'#000000'、深色模式色值為'#FFFFFF'）
Image($r('app.media.view'))
 .fillColor($r('app.color.view_fill_color'))
 .width($r('app.integer.view_image_width'))
 .aspectRatio(1)
 .objectFit(ImageFit.Contain)

5. 在存在深淺兩種模式下佈局結構或邏輯處理有所差異的情況時，開發者應當利用AbilityStage.onConfigurationUpdate監聽介面來實時感知系統主題的變化，並據此做出相應的佈局調整或邏輯處理，從而確保應用能夠在不同模式下呈現出理想的界面效果及功能體驗。

• 第一步保存全局參數，並通過onConfigurationUpdate刷新狀態欄

// 獲取當前的顏色模式並保存併在onConfigurationUpdate
AppStorage.setOrCreate('currentColorMode', this.context.config.colorMode);
// 保存windowStage供fitfordarkmode的har包中FitForDarkPage.ets中setStatusBar方法修改狀態欄顏色。
AppStorage.setOrCreate('windowStage', windowStage);

// 檢測當前的深淺模式是否發生變化，刷新狀態欄
onConfigurationUpdate(config: Configuration) {
 // 獲取最新的變更顏色並更新到AppStorage
 AppStorage.setOrCreate('currentColorMode', config.colorMode);
 logger.info(`onConfigurationUpdate, config: ${JSON.stringify(config)}`);
}

• 第二步在FitForDarKMode.ets中獲取並監聽當前顏色模式

// @StorageProp + @Watch 獲取並監聽當前顏色模式
@StorageProp('currentColorMode') @Watch('onColorModeChange') currentMode: number = 0;
// @Watch回調函數，監聽顏色模式刷新狀態變數
onColorModeChange(): void {
  if (this.currentMode === ConfigurationConstant.ColorMode.COLOR_MODE_DARK) {
    this.banner = $r("app.media.dark_mode_banner");
  } else {
    this.banner = $r("app.media.light_mode_banner");
  }
}

• 第三步在FitForDarKMode.ets生命周期aboutToAppear中根據當前顏色模式刷新banner狀態變數，切換不同的圖片。

// 在自定義組件生命周期aboutToAppear中，根據當前顏色模式刷新banner狀態變數，切換不同的圖片。
aboutToAppear(): void {
  if (this.currentMode === ConfigurationConstant.ColorMode.COLOR_MODE_DARK) {
    this.banner = $r("app.media.dark_mode_banner");
} else {
    this.banner = $r("app.media.light_mode_banner");
    // 在當前為淺色模式中，確保界面美觀且顏色統一，設置導航欄的背景色。
    setStatusBar(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
  }
}

• 第四步在FitForDarKMode.ets生命周期aboutToDisappear中，重置導航欄的背景色避免影響其它頁面的導航欄為紅色。

// 在自定義組件生命周期aboutToDisappear中，重置導航欄的背景色避免影響其它頁面的導航欄為紅色。
aboutToDisappear(): void {
  setStatusBar(this.currentMode)
}

• 第五步在FitForDarKMode.ets生命周期aboutToDisappear中，重置導航欄的背景色避免影響其它頁面的導航欄為紅色。

// 調用setWindowSystemBarProperties()設置狀態欄及導航欄的顏色
windowClass.setWindowSystemBarProperties(sysBarProps, (err) => {
  if (err.code) {
    logger.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err));
    return;
  }
  logger.info('Succeeded in setting the system bar properties.');
});

高性能知識點

不涉及

工程結構&模塊類型

fitfordarkmode                                   // har類型
|---mock
|   |---GoodsMock.ets                            // 商品列表數據 
|---mode
|   |---GoodsModel.ets                           // 商品數據類型定義 
|---view
|   |---FitForDarkMode.ets                       // 深色模式適配主頁面 
|   |---GoodsList.ets                            // 商品列表自定義組件 

模塊依賴

本實例依賴common模塊來實現資源的調用以及公共組件FunctionDescription的引用。 還需要依賴EntryAbility.ets模塊。

參考資料

設置深色模式

@ohos.app.ability.ConfigurationConstant (ConfigurationConstant)