App(object: Object)
App()
is used to register a Mini Program.App()
accepts an Object attribute to configure the lifecycle of the Mini Program.You can call App()
only in theapp.js
file and only for once.
Descriptions of object attributes
Attribute | Type | Description | Trigger condition |
---|---|---|---|
onLaunch | Function | Lifecycle callback: listens to the initialization of the Mini Program | Triggered when the initialization of the Mini Program completes. Triggered only for once during the lifecycle of the Mini Program. |
onShow | Function | Lifecycle callback: listens to the display of the Mini Program | Triggered when the Mini Program is launched or triggered when the display is switched to the foreground from the background. |
onHide | Function | Lifecycle callback: listens to hide operations of the Mini Program | Triggered when the Mini Program is switched to the background from the foreground. |
onError | Function | Listens to errors in the Mini Program | Triggered when a JavaScript error occurs in the Mini Program. |
onShareAppMessage | Function | Configures global sharing |
Definitions of the foreground and background of a Mini Program:
- When a user taps the close button in the upper-right corner to close a Mini Program or presses the Home button on the device to leave Alipay, the Mini Program is not terminated but runs in the background.
- When the user re-opens Alipay or the Mini Program, the Mini Program will run from the background to the foreground.
- A Mini Program is terminated only after it runs in the background for a specific period of time or it occupies excessive system resources.
onLaunch(object: Object) and onShow(object: Object)
The following table describes the object attributes.
Attribute | Type | Description |
---|---|---|
query | Object | The current query object of the Mini Program. This object is resolved from the “query” field for Mini Program startup. |
path | String | The current page address of the Mini Program. This page address is resolved from the “page” field for Mini Program startup. If the “page” field is not specified for Mini Program startup, the path corresponds to the homepage. |
referrerInfo | Object | The source information. |
For example, the schema URL for starting a Mini Program is shown as follows:
alipays://platformapi/startapp?appId=1999&query=number%3D1&page=x%2Fy%2Fz
The following code snippet shows the resolution results of the “query” and “path” attributes:
query = decodeURIComponent('number%3D1');
// number=1
path = decodeURIComponent('x%2Fy%2Fz');
// x/y/z
- When a Mini Program is started for the first time, you can use the
onLaunch
method to obtain the values of thequery
andpath
attributes. - When the Mini Program is opened by using a schema URL, you can use the
onShow
method to obtain the values of thequery
andpath
attributes.
App({
onLaunch(options) {
// Open for the first time.
console.log(options.query);
// {number:1}
console.log(options.path);
// x/y/z
},
onShow(options) {
// Re-opened by schema in the background.
console.log(options.query);
// {number:1}
console.log(options.path);
// x/y/z
},
});
The following table describes the sub attributes of the referrerInfo
attribute.
Attribute | Type | Description | Compatibility |
---|---|---|---|
appId | String | From the source Mini Program. | |
sourceServiceId | String | The source plug-in, which is visible in running mode. | 1.11.0 |
extraData | Object | The data that is transferred from the source Mini Program. |
- Do not call a method that manages pages, such as
redirectTo
ornavigateTo
, in theonShow
event. - Do not call the
getCurrentPages()
method in theonLaunch
event, because the Page objects have not been generated.
onHide()
The onHide()
event is triggered when the Mini Program is switched to the background from the foreground.
Code sample:
App({
onHide() {
// This event is triggered when the Mini Program is switched to the background.
console.log('app hide');
},
});
onError(error: String)
This event is triggered when a JavaScript error occurs or an API call fails in the Mini Program.
App({
onError(error) {
// This event is triggered when an execution error occurs in the Mini Program.
console.log(error);
},
});
onShareAppMessage(object: Object)
This event is triggered to configure global sharing. If page.onShareAppMessage
is not configured for a page, global sharing configurations apply when the page is being shared. For more information, see Sharing.
globalData
You can use globalData
to configure global data in App()
.
Code sample:
// app.js
App({
globalData: 1
});