tencent cloud

DarkMode Adaptation Guide
Download PDF
Last updated: 2024-11-21 18:34:18
DarkMode Adaptation Guide
Last updated: 2024-11-21 18:34:18
Download PDF

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.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback