小程序SDK DarkMode 适配指南

网友投稿 474 2024-07-02 11:22:22

DarkMode 适配指南

基础库 2.12.2 及以上版本支持，工具调试请使用 1.8.11 及以上版本，SDK 请使用 2.35.1 以上。

#SDK 开启暗黑模式

小程序 SDK 初始化时，需要设置 autoAdaptDarkMode = true(2.44.5版本废弃) 开启暗黑模式。2.44.5版本开始可以设置themeStyle(浅色模式、深色模式、跟随系统)来指定小程序的主题模式。

val uiConfig = UIConfig()uiConfig.autoAdaptDarkMode = true
        已复制代码

#基础组件开启 DarkMode

基础组件的样式可以通过theme属性进行配置，例如：

Kotlin

// 设置为深色模式Text(
    text = "DarkMode",
    modifier = Modifier.background(Color.White).padding(16.dp),
    textAlign = TextAlign.Center,
        已复制代码

#小程序开启 DarkMode

在app.json中配置darkmode为true，即表示当前小程序已适配 DarkMode，所有基础组件均会根据系统主题展示不同的默认样式，navigation bar 和 tab bar 也会根据下面的配置自动切换。

#相关配置

当app.json中配置darkmode为true时，小程序部分配置项可通过变量的形式配置，在变量配置文件中定义不同主题下的颜色或图标，方法如下：

在app.json中配置themeLocation，指定变量配置文件theme.json路径，例如：在根目录下新增theme.json，需要配置"themeLocation":"theme.json"
在theme.json中定义相关变量；
在app.json中以@开头引用变量。

支持通过变量配置的属性：

全局配置的 window 属性与页面配置下的属性

navigationBarBackgroundColor
navigationBarTextStyle
backgroundColor
backgroundTextStyle
backgroundColorTop
backgroundColorBottom

全局配置 window.tabBar 的属性

iconPath
selectedIconPath
color
selectedColor
backgroundColor
borderStyle
list

#变量配置文件 theme.json

theme.json用于颜色主题相关的变量定义，需要先在themeLocation中配置theme.json的路径，否则无法读取变量配置。

配置文件须包含以下属性：

属性	类型	必填	描述
light	object	是	浅色模式下的变量定义
dark	object	是	深色模式下的变量定义

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

{
  "light": {
    "navBgColor": "#f5f6f7",
    "navTxtStyle": "black"
  },
  "dark": {
    "navBgColor": "#1a1a1a",
    "navTxtStyle": "white"
  }
}
        已复制代码

完成定义后，可在全局配置或页面配置的相关属性中以@开头引用，例如：

// 全局配置
{
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle"
  }
}
// 页面配置
{
  "navigationBarBackgroundColor": "@navBgColor",
  "navigationBarTextStyle": "@navTxtStyle"
}
        已复制代码

配置完成后，小程序框架会自动根据系统主题，为小程序展示对应主题下的颜色。

#配置示例

app.json

{
    "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": "#f5f6f7",
        "navTxtStyle": "black",
        "bgColor": "#ffffff",
        "bgTxtStyle": "light",
        "bgColorTop": "#eeeeee",
        "bgColorBottom": "#efefef",
        "tabFontColor": "#000000",
        "tabSelectedColor": "#30c8121",
        "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": "#1a1a1a",
        "navTxtStyle": "white",
        "bgColor": "#1e1e1e",
        "bgTxtStyle": "dark",
        "bgColorTop": "#1a1a1a",
        "bgColorBottom": "#1e1e1e",
        "tabFontColor": "#ffffff",
        "tabSelectedColor": "#51a937",
        "tabBgColor": "#1a1a1a",
        "tabBorderStyle": "white",
        "iconPath1": "image/icon1_dark.png",
        "selectedIconPath1": "image/selected_icon1_dark.png",
        "iconPath2": "image/icon2_dark.png",
        "selectedIconPath2": "image/selected_icon2_dark.png",
    }
}
        已复制代码

#获取当前系统主题

如果app.json中声明了"darkmode": true，ft.getSystemInfo或ft.getSystemInfoSync的返回结果中会包含theme属性，值为light或dark。如果app.json未声明"darkmode": true，则无法获取到theme属性（即theme为undefined）。

#监听主题切换事件

支持2种方式：

在App()中传入onThemeChange回调方法，主题切换时会触发此回调
通过ft.onThemeChange监听主题变化，ft.offThemeChange取消监听

#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 */
}
        已复制代码

#开发者工具调试

开发者工具 1.8.11 版本开始已支持 DarkMode 调试，在模拟器顶部可以切换深色/浅色模式进行，如图：

标签：小程序SDK 程序小程序属性模拟