FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

# DarkMode 适配指南

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

# SDK 开启暗黑模式

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

    # 小程序开启 DarkMode

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

    # 相关配置

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

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

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

    • 全局配置的 window 属性与页面配置下的属性
      • navigationBarBackgroundColor
      • navigationBarTextStyle
      • backgroundColor
      • backgroundTextStyle
      • backgroundColorTop
      • backgroundColorBottom
    • 全局配置 window.tabBar 的属性
      • color
      • selectedColor
      • backgroundColor
      • borderStyle
      • list
        • iconPath
        • selectedIconPath

    # 变量配置文件 theme.json

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

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

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

    lightdark下均可以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": trueft.getSystemInfoft.getSystemInfoSync的返回结果中会包含theme属性,值为lightdark。 如果app.json未声明"darkmode": true,则无法获取到theme属性(即themeundefined)。

    # 监听主题切换事件

    支持2种方式:

    1. App()中传入onThemeChange回调方法,主题切换时会触发此回调
    2. 通过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 调试,在模拟器顶部可以切换 深色/浅色 模式进行,如图:

    © FinClip with ❤ , Since 2017