# Dark Mode Adaptation Guide

Supported in Base Library 2.12.2 and above. Use Developer Tools 1.8.11 or above for debugging, and SDK 2.35.1 or above.

# Enabling Dark Mode in the SDK

When initializing the Mini-Program SDK, set autoAdaptDarkMode = true (deprecated in version 2.44.5) to enable Dark Mode. Starting from version 2.44.5, you can set themeStyle (Light Mode, Dark Mode, Follow System) to specify the Mini-Program's theme mode.

    # Enabling Dark Mode in the Mini-Program

    Configure darkmode as true in app.json to indicate that the current Mini-Program has adapted to Dark Mode. All Basic Components will display different default styles according to the system theme, and the Navigation Bar and Tab Bar will also automatically switch based on the configurations below.

    When darkmode is set to true in app.json, some Mini-Program configuration items can be configured using variables. Define colors or icons under different themes in the variable configuration file as follows:

    1. Configure themeLocation in app.json to specify the path of the variable configuration file theme.json. For example, if you add theme.json in the root directory, configure "themeLocation":"theme.json".
    2. Define related variables in theme.json.
    3. Reference variables in app.json using @ as a prefix.

    Properties that support variable configuration:

    • Window properties under global configuration and properties under page configuration
      • navigationBarBackgroundColor
      • navigationBarTextStyle
      • backgroundColor
      • backgroundTextStyle
      • backgroundColorTop
      • backgroundColorBottom
    • Properties under global configuration window.tabBar
      • color
      • selectedColor
      • backgroundColor
      • borderStyle
      • list
        • iconPath
        • selectedIconPath

    # Variable Configuration File theme.json

    theme.json is used for defining variables related to color themes. You must first configure the path of theme.json in themeLocation; otherwise, the variable configuration cannot be read.

    The configuration file must include the following properties:

    Property Type Required Description
    light object Yes Variable definitions for Light Mode
    dark object Yes Variable definitions for Dark Mode

    Variables can be defined under light and dark in the format key: value, for example:

    {
      "light": {
        "navBgColor": "#f5f6f7",
        "navTxtStyle": "black"
      },
      "dark": {
        "navBgColor": "#1a1a1a",
        "navTxtStyle": "white"
      }
    }
    

    After definition, you can reference the variables in relevant properties of the global or page configuration using @ as a prefix, for example:

    // Global configuration
    {
      "window": {
        "navigationBarBackgroundColor": "@navBgColor",
        "navigationBarTextStyle": "@navTxtStyle"
      }
    }
    // Page configuration
    {
      "navigationBarBackgroundColor": "@navBgColor",
      "navigationBarTextStyle": "@navTxtStyle"
    }
    

    After configuration, the Mini-Program Framework will automatically display the colors corresponding to the system theme for the Mini-Program.

    # Configuration Example

    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",
        }
    }
    

    # Getting the Current System Theme

    If "darkmode": true is declared in app.json, the return result of ft.getSystemInfo or ft.getSystemInfoSync will include a theme property, with a value of light or dark. If "darkmode": true is not declared in app.json, the theme property cannot be obtained (i.e., theme is undefined).

    # Listening for Theme Change Events

    Two methods are supported:

    1. Pass the onThemeChange callback method in App(); this callback will be triggered when the theme changes.
    2. Use ft.onThemeChange to listen for theme changes and ft.offThemeChange to cancel listening.

    # WXSS Adaptation

    In WXSS, you can adapt to different themes using the media query prefers-color-scheme, consistent with the adaptation method on the Web, for example:

    /* Styles under normal conditions begin */
    .some-background {
        background: white;
    }
    .some-text {
        color: black;
    }
    /* Styles under normal conditions end */
    
    @media (prefers-color-scheme: dark) {
        /* Styles under Dark Mode start */
        .some-background {
            background: #1b1b1b;
        }
        .some-text {
            color: #ffffff;
        }
        /* Styles under Dark Mode end */
    }
    

    # Debugging in Developer Tools

    Developer Tools version 1.8.11 and above support Dark Mode debugging. You can switch between Dark/Light modes at the top of the simulator, as shown in the figure:

    © FinClip with ❤ , Since 2017