DarkMode Adaptation Guide

Recent Pages

DarkMode Adaptation Guide

Last updated: 2024-11-21 18:34:18

1. Enable DarkMode
Configure darkmode as true in app.json, that means the current mini program has been adapted to DarkMode, all the basic components will display different default styles according to the system theme, and the navigation bar and tab bar will be automatically switched according to the following configuration.
2. Related Configuration
When app.json is configured with darkmode as true, some of the configuration items of mini program can be configured in the form of variables, defining the colour or icon under different themes in the variable configuration file, as follows:
1. Configure themeLocation in app.json to specify the path of variable configuration file theme.json, for example: add theme.json in the root directory, you need to configure "themeLocation": "theme.json";
2. Define the relevant variables in theme.json;
3. Referencing variables in app.json starting with @;
Properties configured via variables are supported.
Globally configured window properties and properties under page configuration
navigationBarBackgroundColor;
navigationBarTextStyle;
backgroundColor;
backgroundTextStyle;
backgroundColourTop;
backgroundColorBottom.
Global configuration of window.tabBar properties
colour;
selectedColor;
backgroundColor;
borderStyle;
list;
iconPath;
selectedIconPath.
2.1 Variable configuration file theme.json
theme.json is used to define the variables related to the colour theme, you need to configure the path of theme.json in themeLocation first, otherwise you can't read the variable configuration.
The configuration file must contain the following properties:
Attributes
Type
Required
Descripción
light
object
yes
Definition of the variable in light mode
dark
object
yes
Definition of the variable in dark mode
Both light and dark can define variable names and values as key: value, for example:
{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white"
  }
}
After completing the definition, it can be referenced in the global configuration or in the relevant properties of the page configuration starting with @, for example:
// Global Configuration
{
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle"
  }
}
﻿
// Page Configuration
{
  "navigationBarBackgroundColor": "@navBgColor",
  "navigationBarTextStyle": "@navTxtStyle"
}
After the configuration is completed, the mini program framework will automatically display the colour under the corresponding theme for the mini program according to the system theme.
2.2 Configuration Example
app.json (the example omits configuration items other than those related to the theme)
{
  "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",
  }
}
3. Get current system theme
If app.json declares "darkmode": true, wx.getSystemInfo or wx.getSystemInfoSync will return a theme attribute with a value of light or dark.
If app.json does not declare "darkmode": true, the theme property is not available (i.e. theme is undefined).
4. Listening for theme switching events
There are 2 ways to do this:
Pass onThemeChange callback method in App(), the callback will be triggered when the theme is switched;
Listen to theme change by wx.onThemeChange, wx.offThemeChange cancels the listening.
5. WXSS Adaptation
WXSS supports adapting different themes via prefers-color-scheme media query, which is the same as the web adapting method, for example:
/* General style begin */
.some-background {
  background: white;
}
.some-text {
  color: black;
}
/* General style end */


@media (prefers-color-scheme: dark) {
  /* Style start under DarkMode */
  .some-background {
      background: #1b1b1b;
  }
  .some-text {
      color: #ffffff;
  }
  /* Style end under DarkMode */
}
6. Tips
1. Note that the media query in WXSS is not affected by the darkmode switch in app.json. As long as the client supports DarkMode, the media query will take effect when the system is switched to DarkMode, no matter "darkmode": true is configured or not;
2. Theme switch event needs to be triggered when "darkmode": true is configured.

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support

tencent cloud

Recent Pages

DarkMode Adaptation Guide

1. Enable DarkMode

2. Related Configuration

2.1 Variable configuration file theme.json

2.2 Configuration Example

3. Get current system theme

4. Listening for theme switching events

5. WXSS Adaptation

6. Tips

Was this page helpful?

Was this page helpful?

Attributes	Type	Required	Descripción
light	object	yes	Definition of the variable in light mode
dark	object	yes	Definition of the variable in dark mode

tencent cloud

Sign Up

Log in

Recent Pages

DarkMode Adaptation Guide

1. Enable DarkMode

2. Related Configuration

2.1 Variable configuration file theme.json

2.2 Configuration Example

3. Get current system theme

4. Listening for theme switching events

5. WXSS Adaptation

6. Tips

Was this page helpful?

Was this page helpful?