Configuration

The app.json file in the Mini Program root directory is used to apply global configurations to Mini Programs. The file content is a JSON object with the following properties:

Configuration Items#

Property	Type	Default Value	Required	Description
entryPagePath	`string`	-	✓	index page name
pages	`string[]`	-	✓	Page Path List
window	`Object`	-	-	Global default window behavior
tabBar	`Object`	-	-	Behavior of the `tab` bar at the bottom of the page.
subPackages	`Object[]`	-	-	subPackage structure configuration.
darkmode	`boolean`	-	-	whether app is in darkmode
theme	`{light?:Object,dark?:Object}`	-	-	theme configuration, basically replaced by themeLocation
themeLocation	`string`	-	-	Indicate the location of theme.json,it's required when darkmode is true

window#

Property	Type	Default Value	Required	Description
navigationBarBackgroundColor	`HexColor`	#000000	-	The navigation bar background color
navigationBarButtonColor	`HexColor`	#707A8A	-	The button color in the navigation.
navigationBarTitleText	`string`	-	✓	Title text of the navigation bar
navigationBarTextStyle	`string`	white	-	The title color of the navigation bar, only supports black or white
navigationStyle	`string`	default	-	The navigation bar style. Only the following values are supported. `default`: the default style. `custom`: custom navigation bar, only retains the Mini Program control button in the upper-right corner, click here for details.
backgroundTextStyle	`string`	dark	-	The pull-down loading style, only dark and light are supported.
backgroundColor	`HexColor`	#ffffff	-	The background color of the window.

tabBar#

If the Mini Program is a multi-tab app (which uses a tab bar at the bottom or top of the app window to switch between tabs), you can use the tabBar configuration item to specify the behavior of the tab bar and the pages displayed when the user switches between tabs.

Property	Type	Default Value	Required	Description
color	`HexColor`		✓	The default color of the tab bar text, only supports hex color codes.
selectedColor	`HexColor`		✓	The color of the tab bar text when being selected, only supports hex color codes.
backgroundColor	`HexColor`		✓	The color of the tab bar background, only supports hex color codes.
borderStyle	`string`	black		The border color of the tab bar, only supports `black` and `white`.
list	`array`		✓	The tab list (see the `list` property description), supports 2 to 5 tabs.
position	`string`	bottom		The tabBar position, only supports `bottom` and `top`.
custom	`boolean`	false		A custom tabBar, click here for details.

The list property accepts an array, which can only configure 2 to 5 tabs. The tabs are listed in the order of the array. Each item is an object with the following properties:

Property	Type	Required	Description
pagePath	`string`	✓	The page path, which must be defined first in pages.
text	`string`	✓	The text of tab buttons.
iconPath	`string`		The image path. The size of the icon is limited to 40 KB, suggested dimensions: 81px by 81px, online images are not supported. When `position` is set to `top`, the icon is not displayed.
selectedIconPath	`string`		The image path for the selected icon. The size of the icon is limited to 40 KB, suggested dimensions: 81px by 81px, online images are not supported. When `position` is set to `top`, the icon is not displayed.

subPackages#

In some cases, the developer needs to divide a Mini Program into different child packages, and package these child packages into different subpackages while building, so that users can load them as needed.

When building a subpackage project, one or more subpackages will be output. Each subpackaged Mini Program must contain a main package that includes the default startup/TabBar page and some common resources and JS scripts required by all subpackages. The sub-packages are divided according to the developer's configuration.

When the Mini Program starts, the main package is downloaded and the pages in the main package are started by default. When a user enters a page in a subpackage, the client downloads the corresponding subpackage and displays it after the download is completed.

Supported from SDK ^3.2.0, IDE ^2.9.0 and Native ^2.40.0

Property	Type	Required	Description
root	`string`	✓	root of subPackage
name	`string`		alias name
pages	`string[]`	✓	page list related to root
independent	`boolean`	✓	If it is an independent subPackage

useExtendedLib#

Specifies the extension library to be referenced. The following projects are currently supported:

react

When specified, is equivalent to introducing the latest version of the corresponding extension library npm Package, but also does not occupy the Mini Programs package volume. The rc tool version supports sub-packageing references. Usage is as follows:

use true to use the latestVersion.

{  "useExtendedLib": {    "react": true  }}

You can also specify the exact version you want to use.

{  "useExtendedLib": {    "react": "17.0.2"  }}

prefetchRules#

Data prefetching can initiate a request in advance when the Mini Program is cold started, and cache the response of the request, and use the cached data in the actual request to reduce the time for network requests. The specific process is as follows:

Configure prefetch rules#

Data prefetching rules need to be configured in app.json, examples are as follows:

{  "prefetchRules": {    // launch path that need to be configured with prefetch requests    "pages/index/index": {      // request url      "https://developer.binance.com/${pageid}": {        // request method        "method": "POST",        // request header        "header": {          "token": "${token}"        },        // request body        "data": {          "pageSize": "${pageSize}",          "pageNum": 1        },        // request response type        "responseType": "text"      }    },    // match all launch paths    "*": {      // local file path, language is the variable      "file://nezha-i18n-data_${language}.json": {        // whether to wait for the file download to complete when starting the mini program        "mandatory": true      }    }  }}

Configure variables#

In order to make configuration requests dynamic, we introduce configuration variables. Configuration variables have the format ${variable}. The process of assigning the variable is string replacement, replacing ${variable} in the prefetchRules configuration string with the variable's value.

Variable data source#

There are three data sources for configuration variables, sorted by priority:

The query parameter of the Mini Program page route
Data stored in storage by developers
The data returned by the getSystemInfo interface, such as language

The client starts to search for variables from the high-priority data source. If the corresponding variable is found, it does not continue to search, otherwise it continues to search for the next data source. If none of the data sources can find the corresponding variable, then no request will be made.

Request url#

The most basic thing that constitutes a request is the url. As long as there is a complete url, we can initiate a request. Currently we support variable in path and query of url, but host does not currently support.

When the prefetch configuration is as follows, assuming that the page route is pages/index/index?pageid=1000, and the developer’s storage stores the pageSize variable with a value of 10, then the final prefetch request will be https://developer.binance.com/1000?pagesize=10&pagenum=1

{  "prefetchRules": {    "pages/index/index": {      "https://developer.binance.com/${pageid}?pagesize=${pageSize}&pagenum=1": {}    }  }}

Request parameters#

The value of the request address is the request parameter, which includes method, header, data and responseType, corresponding to the parameters of the bn.request API, and these parameters also support configuration variables. The specific rules for the default values of method, header, data and responseType are shown in the table below:

Property	Type	Default Value	Description
header	`object`	{'content-type': 'application/json'}	Request header
method	`string`	GET	Request method, support GET, POST
data	`string or object`	null	Request data, needs to be consistent to hit the cache
responseType	`string`	text	Response data type, optional value: text

For example, suppose the request parameters are configured as follows:

{  "https://developer.binance.com/${pageid}": {    "method": "POST",    "header": {      "token": "${token}"    },    "data": {      "pageSize": "${pageSize}",      "pageNum": 1    }  }}

If the page route is pages/index/index?pageid=1000, the developer’s storage stores the pageSize variable with a value of 10, and also stores the token variable with a value of test_token, then the parameters of the final prefetch request will be as follows show:

{  "https://developer.binance.com/1000": {    "method": "POST",    "header": {      "token": "test_token"    },    "data": {      "pageSize": "10",      "pageNum": 1    }  }}

Use prefetch cache#

bn.request has added the usePrefetchCache parameter, and the return data has added isPrefetch to distinguish whether the data is prefetched or not. The example is as follows:

{  "prefetchRules": {    "pages/index/index": {      "https://developer1.binance.com/${sid}?testid=${testid}&testdata=${sData}": {        "method": "POST",        "header": {          "testCookie": "${sCookie}",          "token": "xxxs1823730"        },        "data": {          "mData": "${mData}"        },        "responseType": ""      }    }  }}

//storageconst testCookie = bn.getStorageSync('sData')const sCookie = bn.getStorageSync('sCookie')const mData = bn.getStorageSync('mData')
//requestconst token = 'xxxs1823730'const { sid, testid } = option.queryconst url = `https://developer1.binance.com/${sid}?testid=${testid}&testdata=${sData}`const header = { testCookie, token }const data = { mData }
bn.request({  url,  header,  data,  method: 'POST',  dataType: 'json',  responseType: 'text',  usePrefetchCache: true,  success: res => {    console.log('Whether the returned data is from prefetching:', res.isPrefetch)    console.log('Response data:', res.data)  },})

File Prefetch#

In addition to prefetching network requests, we also support prefetching files. The file prefetch configuration is similar to the network request configuration, but the value of the request address is the local file path. The file path supports configuration variables.

For example, suppose the file prefetch rule are configured as follows:

{  "prefetchRules": {    "pages/index/index": {      "file://nezha-i18n-data_${language}.json": {        "mandatory": true      }    }  }}

If the page route is pages/index/index, and the client language is zh_CN, the variable language will be replaced with zh_CN (which is got from getSystemInfo API), then the final prefetch request will be file://nezha-i18n-data_zh_CN.json.

When the mini program launches, the client will start downloading file://nezha-i18n-data_zh_CN.json immediately with parallel download. If the value of mandatory is true, the mini program will not start until the file is downloaded successfully, otherwise the mini program will start immediately (no blocking).

Developers can use the bn.getFileSystemManager API to read the file content. The example is as follows:

const fs = bn.getFileSystemManager()const filePath = 'file://nezha-i18n-data_zh_CN.json'const res = fs.readFileSync(filePath, 'utf8')console.log('File content:', res)

Page Configuration#

For each Mini Program page, the .json file named after the Mini Program can also be used to configure the window behaviors of this page. The configuration items in the current page overwrite the corresponding window configuration items in app.json. The file content is a JSON object, example:

{  "navigationBarBackgroundColor": "#ffffff",  "navigationBarTextStyle": "black",  "navigationBarTitleText": "Binance API feature demo",  "backgroundColor": "#eeeeee",  "backgroundTextStyle": "light",  "initialRenderingCache": "static"}

Property	Type	Default Value	Required	Description
initialRenderingCache	String		-	Add `static` value to enable static rendering cache.

DarkMode#

Provide developers with the ability to adapt DarkMode within applets.

Enable DarkMode#

Setting { darkmode : true } in app.json means that the current applet is adapted to DarkMode, and all basic components will display different default styles according to the system theme, and the navigation bar and tab bar will also automatically switch according to the following configuration.

Related Configuration#

When { darkmode: true } in app.json, some configuration items of the applet can be configured in the form of variables, and the colors or icons under different themes can be defined in the variable configuration file. The method is as follows:

Configure themeLocation in app.json, and specify the variable configuration file theme.json path, for example: add theme.json in the root directory, you need to configure {"themeLocation": "/path/to/theme.json"}
Define related variables in theme.json;
Reference variables starting with @ in app.json.

Properties that support configuration via variables:

The window attribute of the global configuration and the attribute under the page configuration
- navigationBarBackgroundColor
- navigationBarTextStyle
- backgroundColor
- backgroundTextStyle
- backgroundColorTop
- backgroundColorBottom
Globally configure the properties of window.tabBar
- color
- selectedColor
- backgroundColor
- borderStyle
- list
  - iconPath
  - selectedIconPath

Variable configuration file theme.json#

theme.json is used for variable definition related to the color theme. You need to configure the path of theme.json in themeLocation first, otherwise the variable configuration cannot be read.

The configuration file must contain the following properties:

Attribute	Type	Required	Description
light	object	Y	a variable definition in light mode
dark	object	Y	the variable definition in dark mode

Both light and dark can define variable names and values in the form of key: value, for example:

{  "light": {    "navBgColor": "#f6f6f6",    "navTxtStyle": "black"  },  "dark": {    "navBgColor": "#191919",    "navTxtStyle": "white"  }}

After the definition is completed, it can be referenced at the beginning of @ in the relevant properties of the global configuration or page configuration, for example:

// global configuration{  "window": {    "navigationBarBackgroundColor": "@navBgColor",    "navigationBarTextStyle": "@navTxtStyle"  }}// page configuration{  "navigationBarBackgroundColor": "@navBgColor",  "navigationBarTextStyle": "@navTxtStyle"}

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

Get the current system theme#

If "darkmode": true is declared in app.json, the return result of bn.getSystemInfo or bn.getSystemInfoSync will contain the theme attribute, whose value is light or dark.

If app.json does not declare "darkmode": true, the theme attribute cannot be obtained (that is, theme is undefined).`

Listen for theme switching events#

Support 2 ways:

Pass in the onThemeChange callback method in App(), this callback will be triggered when the theme is switched
Monitor theme changes through bn.onThemeChange, and cancel the monitoring with bn.offThemeChange

BXSS adaptation#

In BXSS, it is supported to adapt different themes through media query prefers-color-scheme, which is consistent with the adaptation method in the Web, for example:

/* normal css style begin */.case-background {    background: white;}.case-text {    color: black;}/* normal css style end */
@media (prefers-color-scheme: dark) {    /* style under DarkMode start */    .case-background {        background: #1b1b1b;    }    .case-text {        color: #ffffff;    }    /* style under DarkMode end */}