快應(yīng)用 夜間模式適配

從 Android 10 開始，系統(tǒng)加入了夜間模式（也有被稱為深色模式、暗色模式）的原生支持?？鞈?yīng)用也同步引入了此特性，方便開發(fā)者更好地適配夜間模式。

在這一篇教程，我們將從簡單的主題模式配置入門，到控制自動反色開關(guān)與手動配置夜間模式的樣式，逐步掌握夜間模式的最佳實(shí)踐。

注意：

1. 夜間模式僅在?Android 10?以上版本的手機(jī)支持，如果要查看效果，請確保擁有合適版本的手機(jī)，且快應(yīng)用平臺版本號在?1070?以上。另外，快應(yīng)用打包工具 hap-toolkit 的版本號要在?0.6.15?版本以上。（可通過命令?hap -v?查看版本號)
2. vivo 手機(jī)暫不支持快應(yīng)用的夜間模式適配

通過本篇教程，我們將學(xué)會：

• 配置 app 的主題模式
• 獲取 app 的主題模式值
• 系統(tǒng)主題模式切換的回調(diào)
• ForceDark 開關(guān)
• 通過媒體查詢配置指定主題模式的樣式

效果展示

配置 app 的主題模式

快應(yīng)用的主題模式支持三種：

• 跟隨系統(tǒng)主題模式
• 固定日間模式
• 固定夜間模式

其中，?跟隨系統(tǒng)主題模式?這一項(xiàng)選中時(shí)，當(dāng)系統(tǒng)切換?日間?、?夜間?兩種主題模式，快應(yīng)用也會跟隨變換主題模式。

了解 3 種主題模式的區(qū)別后，現(xiàn)在我們可以嘗試在快應(yīng)用配置?主題模式?啦。

步驟：

在?manifest.json?的?display?屬性，添加?themeMode?值即可，默認(rèn)為?-1?（跟隨系統(tǒng)主題模式）,詳情請查看 manifest 文檔

示例代碼：

"display": {
  "themeMode": -1,
}

themeMode 可填入值：

獲取 app 的主題模式值

如果需要針對特定的主題模式做適配邏輯，我們就需要獲取當(dāng)前的主題模式值了

步驟：

通過調(diào)用@system.configuration的getThemeMode方法即可獲取，詳情可參考 configuration 文檔

返回值：

示例代碼：

import configuration from '@system.configuration'
export default {
  getTheme() {
    const themeMode = configuration.getThemeMode()
    console.log(`Theme mode is ${themeMode} now~`)
  }
}

系統(tǒng)主題模式切換的回調(diào)

想象一個(gè)用戶常見的場景，比如說在小說閱讀時(shí)，用戶切換系統(tǒng)主題到夜間模式，應(yīng)用需彈出提示“進(jìn)入夜間模式啦”。這個(gè)時(shí)候，就需要監(jiān)聽主題模式切換了。

步驟：

1. 在頁面代碼如index.ux里，實(shí)現(xiàn)快應(yīng)用頁面級別的onConfigurationChanged回調(diào)，監(jiān)聽配置切換事件。
2. 當(dāng) type 為themeMode時(shí)，此時(shí)回調(diào)即為主題模式切換的回調(diào)

詳情可參考 script文檔 的onConfigurationChanged一節(jié)

注意：

1. 因?yàn)樵?code>onConfigurationChanged只能拿到type值，所以開發(fā)者如果需要在回調(diào)時(shí)同時(shí)獲取主題模式值來判斷，可以參考上一節(jié)教程，手動獲取themeMode值
2. 即使在 manifest.json 配置了themeMode為 0（固定日間模式）或 1（固定夜間模式），用戶切換系統(tǒng)主題時(shí)快應(yīng)用不會有界面變化，但仍會觸發(fā)onConfigurationChanged回調(diào)

示例代碼：

// index.ux
import configuration from '@system.configuration'
export default {
  onConfigurationChanged(params) {
    const { type = '' } = params
    if (type === 'themeMode') {
      const themeMode = configuration.getThemeMode()
      console.log(`themeMode has changed! And now theme mode is ${themeMode}.`)
    } else {
      console.log(`other type of config has changed, type is : ${type}.`)
    }
  }
}

ForceDark 開關(guān)

看了我們上面的效果圖，也許你會好奇，只是設(shè)置了皮膚模式，為什么我的快應(yīng)用就自動在夜間模式可以反色呢？而且效果還這么好！

其實(shí)，這是 Android 10 以上系統(tǒng)提供的一個(gè)功能，叫Force Dark。開啟了Force Dark的安卓應(yīng)用，就會在夜間模式自動反色，達(dá)到十分簡單且效果不賴的 APP 夜間模式效果，詳情可查看 Android 的深色主題背景文檔的"Force Dark"一節(jié)

而快應(yīng)用也把Force Dark的特性在 1070 以上的版本開始加入支持。

我們只需要按照配置 app 的主題模式教程，將 themeMode 設(shè)為 -1(跟隨系統(tǒng)主題模式）或 1（固定夜間模式），即可在夜間模式查看反色效果，非常方便。

然而，因?yàn)?code>Force Dark反色的樣式由 Android 底層自動計(jì)算，我們是無法手動修改的。因此，根據(jù)需求場景，我們可能需要手動關(guān)閉反色效果，或指定夜間模式的樣式。

在這一節(jié)，我們將學(xué)習(xí)如何關(guān)閉反色效果。

ForceDark 的開關(guān)有 3 個(gè)級別：

• 應(yīng)用級別
• 單頁面級別
• 組件級別

ForceDark 開關(guān)基本原則

在快應(yīng)用中，ForceDark開關(guān)，除了直接影響自己的反色表現(xiàn)，也同樣影響其所有子元素的反色表現(xiàn)。

父子元素的層級順序：APP 級別 > 頁面級別 > 組件級別 > 子組件級別

具體規(guī)則如下：

• 如果父元素設(shè)置為true，子元素設(shè)置為false，則子元素的表現(xiàn)是false；子元素設(shè)置為true，則子元素的表現(xiàn)為true
• 如果父元素設(shè)置為false，子元素?zé)o論設(shè)置為false或true ，表現(xiàn)都是false

應(yīng)用級別的 forceDark

應(yīng)用級別的forceDark開關(guān)，可配置此快應(yīng)用所有頁面的自動反色開關(guān)。

步驟：

在manifest.json的display屬性下可配置forceDark屬性（屬性為駝峰命名）

參數(shù)值：

默認(rèn)為true（開啟），可選值：true（開啟），false（關(guān)閉）

示例代碼：

"display": {
   "themeMode": -1,
   "forceDark": true
}

單頁面級別的 forceDark

頁面級別的forceDark開關(guān)，可配置特定頁面的自動反色開關(guān)。

步驟：

在manifest.json的display屬性下的pages數(shù)組的頁面節(jié)點(diǎn)，可配置forceDark屬性（屬性為駝峰命名）

參數(shù)值：

默認(rèn)為true（開啟），可選值：true（開啟），false（關(guān)閉）

示例代碼：

"router": {
  "pages": {
    "Demo": {
      "titleBarText": "示例頁",
      "forceDark": false
    },
  }
}

組件級別的 forcedark

組件級別的forcedark開關(guān)，可以配置該組件的自動反色開關(guān)

步驟：

在組件標(biāo)簽里配置forcedark屬性(屬性為全小寫命名)

參數(shù)值：

默認(rèn)為true（開啟），可選值：true（開啟），false（關(guān)閉）

示例代碼：

// force-dark-demo.ux
<template>
<div>
   <text forcedark="false">關(guān)閉了自動反色的文字</text>
   <text>默認(rèn)開啟了自動反色的文字</text>
<div>
</template>

注意點(diǎn)：

• 組件級別的forcedark屬性為全小寫！與manifest.json的配置項(xiàng)為駝峰的forceDark不一樣！請注意書寫！
• 子節(jié)點(diǎn)的forcedark遵守 ForceDark 開關(guān)基本原則 的簡介，需要注意父子元素的forcedark開關(guān)的影響
• span組件不支持forcedark開關(guān)，它只能依賴父元素的forcedark參數(shù)值控制開關(guān)，并且當(dāng)父元素為span的時(shí)候，繼續(xù)往上找，直至找到父元素為a或text元素截止
• video、camera、map、custommarker、canvas組件均不支持設(shè)置forcedark參數(shù)，也不會響應(yīng)父元素的forcedark設(shè)置

通過媒體查詢配置指定主題模式的樣式

當(dāng)我們對安卓夜間模式的反色處理不太滿意時(shí)，上一節(jié)我們學(xué)習(xí)了如何手動關(guān)閉反色效果。這一節(jié)，我們會使用媒體查詢（media query），去配置指定主題模式的樣式

媒體查詢，即media query，快應(yīng)用在1070版本開始提供支持，詳情可查看 樣式文檔 。

如果需要使用media query實(shí)現(xiàn)夜間模式的樣式配置，則查詢條件是prefers-color-scheme

注意： prefers-color-scheme的媒體查詢僅在 Android 10+手機(jī)支持

支持參數(shù)：

• light 系統(tǒng)主題模式為日間模式時(shí)查詢生效
• dark 系統(tǒng)主題模式為夜間模式時(shí)查詢生效

示例代碼：

<style>
.box {
  width:100px;
  height:100px;
  background-color:black;
}

@media (prefers-color-scheme: dark) {
  .box {
    background: white;
  }
}
</style>

總結(jié)

夜間模式作為新的軟件交互界面的探索，快應(yīng)用在 Android 10+手機(jī)上提供了支持與豐富的可配置項(xiàng)。開發(fā)者配合這篇教程，可以更好更快捷地，實(shí)現(xiàn)快應(yīng)用的夜間模式形態(tài)。