微信小程序 DarkMode適配指南

DarkMode 適配指南

微信從iOS客戶端 7.0.12、Android客戶端 7.0.13 開始正式支持 DarkMode，小程序也從基礎(chǔ)庫 v2.11.0、開發(fā)者工具 1.03.2004271 開始，為開發(fā)者提供小程序內(nèi)的 DarkMode 適配能力。

開啟 DarkMode

在app.json中配置darkmode為true，即表示當(dāng)前小程序已適配 DarkMode，所有基礎(chǔ)組件均會(huì)根據(jù)系統(tǒng)主題展示不同的默認(rèn)樣式，navigation bar 和 tab bar 也會(huì)根據(jù)下面的配置自動(dòng)切換。

相關(guān)配置

當(dāng)app.json中配置darkmode為true時(shí)，小程序部分配置項(xiàng)可通過變量的形式配置，在變量配置文件中定義不同主題下的顏色或圖標(biāo)，方法如下：

1. 在app.json中配置themeLocation，指定變量配置文件theme.json路徑，例如：在根目錄下新增theme.json，需要配置"themeLocation":"theme.json"
2. 在theme.json中定義相關(guān)變量；
3. 在app.json中以@開頭引用變量。

支持通過變量配置的屬性：

• 全局配置的 window 屬性與頁面配置下的屬性navigationBarBackgroundColornavigationBarTextStylebackgroundColorbackgroundTextStylebackgroundColorTopbackgroundColorBottom
• 全局配置 window.tabBar 的屬性colorselectedColorbackgroundColorborderStylelisticonPathselectedIconPath

變量配置文件 theme.json

theme.json用于顏色主題相關(guān)的變量定義，需要先在themeLocation中配置theme.json的路徑，否則無法讀取變量配置。

配置文件須包含以下屬性：

light和dark下均可以key: value的方式定義變量名和值，例如：

{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white"
  }
}

完成定義后，可在全局配置或頁面配置的相關(guān)屬性中以@開頭引用，例如：

// 全局配置
{
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle"
  }
}
// 頁面配置
{
  "navigationBarBackgroundColor": "@navBgColor",
  "navigationBarTextStyle": "@navTxtStyle"
}

配置完成后，小程序框架會(huì)自動(dòng)根據(jù)系統(tǒng)主題，為小程序展示對(duì)應(yīng)主題下的顏色。

配置示例

app.json（示例省略了主題相關(guān)以外的配置項(xiàng)）

{
    "window": {
        "navigationBarBackgroundColor": "@navBgColor",
        "navigationBarTextStyle": "@navTxtStyle",
        "backgroundColor": "@bgColor",
        "backgroundTextStyle": "@bgTxtStyle",
        "backgroundColorTop": "@bgColorTop",
        "backgroundColorBottom": "@bgColorBottom"
    },
    "tabBar": {
        "color": "@tabFontColor",
        "selectedColor": "@tabSelectedColor",
        "backgroundColor": "@tabBgColor",
        "borderStyle": "@tabBorderStyle",
        "list": [{
            "iconPath": "@iconPath1",
            "selectedIconPath": "@selectedIconPath1"
        }, {
            "iconPath": "@iconPath2",
            "selectedIconPath": "@selectedIconPath2"
        }]
    }
}

theme.json

{
    "light": {
        "navBgColor": "#f6f6f6",
        "navTxtStyle": "black",
        "bgColor": "#ffffff",
        "bgTxtStyle": "light",
        "bgColorTop": "#eeeeee",
        "bgColorBottom": "#efefef",
        "tabFontColor": "#000000",
        "tabSelectedColor": "#3cc51f",
        "tabBgColor": "#ffffff",
        "tabBorderStyle": "black",
        "iconPath1": "image/icon1_light.png",
        "selectedIconPath1": "image/selected_icon1_light.png",
        "iconPath2": "image/icon2_light.png",
        "selectedIconPath2": "image/selected_icon2_light.png",
    },
    "dark": {
        "navBgColor": "#191919",
        "navTxtStyle": "white",
        "bgColor": "#1f1f1f",
        "bgTxtStyle": "dark",
        "bgColorTop": "#191919",
        "bgColorBottom": "#1f1f1f",
        "tabFontColor": "#ffffff",
        "tabSelectedColor": "#51a937",
        "tabBgColor": "#191919",
        "tabBorderStyle": "white",
        "iconPath1": "image/icon1_dark.png",
        "selectedIconPath1": "image/selected_icon1_dark.png",
        "iconPath2": "image/icon2_dark.png",
        "selectedIconPath2": "image/selected_icon2_dark.png",
    }
}

獲取當(dāng)前系統(tǒng)主題

如果app.json中聲明了"darkmode": true，wx.getSystemInfo或wx.getSystemInfoSync的返回結(jié)果中會(huì)包含theme屬性，值為light或dark。

如果app.json未聲明"darkmode": true，則無法獲取到theme屬性（即theme為undefined）。

監(jiān)聽主題切換事件

支持2種方式：

1. 在App()中傳入onThemeChange回調(diào)方法，主題切換時(shí)會(huì)觸發(fā)此回調(diào)
2. 通過wx.onThemeChange監(jiān)聽主題變化，wx.offThemeChange取消監(jiān)聽

WXSS 適配

WXSS中，支持通過媒體查詢 prefers-color-scheme 適配不同主題，與 Web 中適配方式一致，例如：

/* 一般情況下的樣式 begin */
.some-background {
    background: white;
}
.some-text {
    color: black;
}
/* 一般情況下的樣式 end */

@media (prefers-color-scheme: dark) {
    /* DarkMode 下的樣式 start */
    .some-background {
        background: #1b1b1b;
    }
    .some-text {
        color: #ffffff;
    }
    /* DarkMode 下的樣式 end */
}

開發(fā)者工具調(diào)試

微信開發(fā)者工具 1.03.2004271 版本開始已支持 DarkMode 調(diào)試，在模擬器頂部可以切換 深色/淺色 模式進(jìn)行，如圖：

Bug & Tip

1. tip: 需要注意的是，WXSS 中的媒體查詢不受app.json中的darkmode開關(guān)配置影響，只要微信客戶端（iOS 7.0.12、Android 7.0.13）支持 DarkMode，無論是否配置"darkmode": true，在系統(tǒng)切換到 DarkMode 時(shí)，媒體查詢都將生效。
2. tip: 主題切換事件需要在配置"darkmode": true時(shí)，才會(huì)觸發(fā)。
3. bug: iOS 7.0.12 在 light 模式中配置 tabBar 的borderStyle為white時(shí)可能會(huì)出現(xiàn)黑色背景的 bug，后續(xù)版本將會(huì)修復(fù)。