App
represents top-level applications, which manages all pages and global data, and provides lifecycle methods. It is also a constructor that generates an App
instance. A MINI program is an App
instance.
Introduction
The top level of each MINI program normally contains three files:
app.acss
: Application style (optional)app.js
: Application logicapp.json
: Application configuration
Here’s a simple app.json
:
{
"pages": [
"pages/index/index",
"pages/logs/index"
],
"window": {
"defaultTitle": "Demo"
}
}
In the above configuration, the MINI program contains two pages, and the default title of the application window is Demo
.
App
provides four events, allowing you to set the hook method:
onLaunch
: MINI program startsonShow
: MINI program switches to the foregroundonHide
: MINI program switches to the backgroundonError
: MINI program error
app.js
code sample is as follows:
App({
onLaunch(options) {
// MINI program initializes
},
onShow(options) {
// MINI program displays
},
onHide() {
// MINI program hides
},
onError(msg) {
console.log(msg)
},
globalData: {
foo: true,
}
})
App()
App()
Accept a object
as a parameter to configure the life cycle and other information of the MINI program.
Parameter Description:
Property | Type | Description | Trigger condition |
onLaunch | Function | Monitor the MINI program initialization | Triggered when the MINI program initialization is completed (only trigger once globally) |
onShow | Function | Monitor the MINI program display | Triggered when the MINI program starts or switches to foreground from background |
onHide | Function | Monitor the MINI program hiding | Triggered when the MINI program switches to background from foreground |
onError | Function | Monitor the MINI program error | Triggered when a JS error occurred in the MINI program |
Definition of foreground and background : When you tasp the close button in the upper left corner, or presses the Home button to leave the mPaaS client, the MINI program is not directly destroyed, but enters into the background. When you enters the mPaaS client again or opens the MINI program again, it will switch back to foreground from background.
Only when the MINI program enters into the background for a certain period of time, or the system resource usage is too high, will it be actually destroyed.
Parameters of onLaunch/onShow method
Property | Type | Description |
query | Object | Query of the current MINI program |
path | String | Page address of the current MINI program |
The parameter passing method for Native startup is:
The parameter passing method for URL startup is:
query
is parsed from thequery
field of startup parameter, whilepath
is parsed from thepage
field of startup parameter. For example, in the following URL:alipays://platformapi/startapp?appId=1999&query=number%3D1&page=x%2Fy%2Fz
The
query
parameter is parsed as follows:number%3D1 === encodeURIComponent('number=1')
The
path
parameter is parsed as follows:x%2Fy%2Fz === encodeURIComponent('x/y/z')
page
defaults to the home page when it is omitted
So, when you launches the MINI program for the first time, this parameter can be obtained from the onLaunch
method. Alternatively, when the MINI program is reopened from the background by using schema, this parameter can also be obtained from the onShow
method.
App({
onLaunch(options) {
// Opened for the first time
// options.query == {number:1}
},
onShow(options) {
// Reopened from the background by scheme
// options.query == {number:1}
},
})
getApp()
We provide a global getApp()
function to get the MINI program instance, which is typically used in each subpage to get the top-level application.
var app = getApp()
console.log(app.globalData) // Get globalData
Important: App() must be called in app.js, and cannot be called multiple times. Do not call getApp() in a function defined in App(). You can use this to get the app instance. Do not call getCurrentPages() in onLaunch as page has not been generated at this time. After getting the instance with getApp(), do not call the life-cycle function privately.
Global data can be set in App()
, and each subpage can get a global application instance through the global function getApp()
. For example:
// app.js
App({
globalData: 1
})
// a.js
// localValue is only valid in a.js
var localValue = 'a'
// Generate the app instance
var app = getApp()
// Get global data and change it
app.globalData++
// b.js
// localValue is only valid in b.js
var localValue = 'b'
// If a.js runs first, globalData will return 2
console.log(getApp().globalData)
In the above code, a.js
and b.js
both declare the variable localValue
, but they do not affect each other, because the variables and functions declared by each script are only valid in the file.
app.json
app.json
is used for global configuration, which determines the path of the page file and window presentation, sets up network timeout, multiple tabs, and so on.
The following is a simple app.json
that contains some configuration items.
{
"pages": [
"pages/index/index",
"pages/logs/index"
],
"window": {
"defaultTitle": "Demo"
}
}
The configuration of app.json
are as follows.
File | Type | Required | Description |
pages | String Array | Yes | Set page path |
window | Object | No | Set the window presentation of default page |
tabBar | Object | No | Set the presentation of bottom tabs |
pages
The property of pages
is an array, each item of which is a string that specifies the page of the MINI program. Each item represents the path information of the corresponding page. The first item of the array represents the home page of the MINI program. To add and reduce pages in the MINI program, you must modify the pages
array.
The page path does not need to have a js
suffix, and the framework will automatically load the .json
, .js
, .axml
, and .acss
files with the same name.
For example, if the development directory is:
pages/
pages/index/index.axml
pages/index/index.js
pages/index/index.acss
pages/logs/logs.axml
pages/logs/logs.js
app.js
app.json
app.acss
app.json
must be coded as follows:
{
"pages":[
"pages/index/index",
"pages/logs/logs"
]
}
window
window
is used to set the common status bar, navigation bar, title, and window background color of MINI programs.
Its sub-properties include titleBarColor
, defaultTitle
, pullRefresh
, and allowsBounceVertical
.
File | Type | Required | Description |
titleBarColor | Decimal | No | Navigation bar background color |
defaultTitle | String | No | Page title |
pullRefresh | Boolean | No | Whether to allow pull-to-refresh. It defaults to false. |
allowsBounceVertical | String(YES/NO) | No | Whether the page supports vertical drag and drop that exceeds the actual contents. It defaults to YES |
This is an example.
{
"window":{
"defaultTitle": "Alipay interface feature demo"
}
}
tabBar
If your MINI program is a multi-tab application (there are multiple tabs at the bottom of the window to switch pages), you can configure the presentation of the tab bar and the pages displayed when tapping the tabs through the tabBar
.
Note:
Any page reached by page jump (
my.navigateTo
) or page redirect (my.redirectTo
) will not display the bottom tab bar even if it is a page defined in the tabBar configuration.The first page of
tabBar
must be the home page.
tabBar configuration:
File | Type | Required | Description |
textColor | HexColor | No | Text color |
selectedColor | HexColor | No | Color of selected text |
backgroundColor | HexColor | No | Background color |
items | Array | Yes | Configuration of each tab |
Configuration of each item:
File | Type | Required | Description |
pagePath | String | Yes | Set page path |
name | String | Yes | Name |
icon | String | No | Path of normal icon |
activeIcon | String | No | Path of highlighted icon |
The recommended icon size is 60*60 px. A non-proportional stretch/scale is performed on any imported images.
For example:
{
"tabBar": {
"textColor": "#dddddd",
"selectedColor": "#49a9ee",
"backgroundColor": "#ffffff",
"items": [
{
"pagePath": "pages/index/index",
"name": "Home Page"
},
{
"pagePath": "pages/logs/logs",
"name": "Log"
}
]
}
}
Startup parameters
You can bring page
and query
parameters when opening a mini program from native code. Page
is used to specify the path to open a specific page, and query
is used to bring in parameters.
iOS code sample
NSDictionary *param = @{@"page":@"pages/card/index", @"query":@"own=1&sign=1&code=2452473"}; MPNebulaAdapterInterface startTinyAppWithId:@"1234567891234568" params:param];
Android code sample
Bundle param = new Bundle(); param.putString("page", "pages/card/index"); param.putString("query", "own=1&sign=1&code=2452473"); MPNebula.startApp("1234567891234568",param);