All Products
Search
Document Center

App

Last Updated: Feb 05, 2021

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 logic
  • app.json: Application configuration

Here’s a simple app.json:

 
  1. {
  2. "pages": [
  3. "pages/index/index",
  4. "pages/logs/index"
  5. ],
  6. "window": {
  7. "defaultTitle": "Demo"
  8. }
  9. }

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 starts
  • onShow: MINI program switches to the foreground
  • onHide: MINI program switches to the background
  • onError: MINI program error

app.js code sample is as follows:

 
  1. App({
  2. onLaunch(options) {
  3. // MINI program initializes
  4. },
  5. onShow(options) {
  6. // MINI program displays
  7. },
  8. onHide() {
  9. // MINI program hides
  10. },
  11. onError(msg) {
  12. console.log(msg)
  13. },
  14. globalData: {
  15. foo: true,
  16. }
  17. })

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:
    parameter passing

  • The parameter passing method for URL startup is: query is parsed from the query field of startup parameter, while path is parsed from the page field of startup parameter. For example, in the following URL:

       
    1. alipays://platformapi/startapp?appId=1999&query=number%3D1&page=x%2Fy%2Fz
    • The query parameter is parsed as follows:
           
      1. number%3D1 === encodeURIComponent('number=1')
    • The path parameter is parsed as follows:
           
      1. 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.

 
  1. App({
  2. onLaunch(options) {
  3. // Opened for the first time
  4. // options.query == {number:1}
  5. },
  6. onShow(options) {
  7. // Reopened from the background by scheme
  8. // options.query == {number:1}
  9. },
  10. })

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.

 
  1. var app = getApp()
  2. 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:

 
  1. // app.js
  2. App({
  3. globalData: 1
  4. })
 
  1. // a.js
  2. // localValue is only valid in a.js
  3. var localValue = 'a'
  4. // Generate the app instance
  5. var app = getApp()
  6. // Get global data and change it
  7. app.globalData++
 
  1. // b.js
  2. // localValue is only valid in b.js
  3. var localValue = 'b'
  4. // If a.js runs first, globalData will return 2
  5. 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.

 
  1. {
  2. "pages": [
  3. "pages/index/index",
  4. "pages/logs/index"
  5. ],
  6. "window": {
  7. "defaultTitle": "Demo"
  8. }
  9. }

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:

 
  1. pages/
  2. pages/index/index.axml
  3. pages/index/index.js
  4. pages/index/index.acss
  5. pages/logs/logs.axml
  6. pages/logs/logs.js
  7. app.js
  8. app.json
  9. app.acss

app.json must be coded as follows:

 
  1. {
  2. "pages":[
  3. "pages/index/index",
  4. "pages/logs/logs"
  5. ]
  6. }

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.

 
  1. {
  2. "window":{
  3. "defaultTitle": "Alipay interface feature demo"
  4. }
  5. }

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:

 
  1. {
  2. "tabBar": {
  3. "textColor": "#dddddd",
  4. "selectedColor": "#49a9ee",
  5. "backgroundColor": "#ffffff",
  6. "items": [
  7. {
  8. "pagePath": "pages/index/index",
  9. "name": "Home Page"
  10. },
  11. {
  12. "pagePath": "pages/logs/logs",
  13. "name": "Log"
  14. }
  15. ]
  16. }
  17. }

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
       
    1. NSDictionary *param = @{@"page":@"pages/card/index", @"query":@"own=1&sign=1&code=2452473"};
    2. MPNebulaAdapterInterface startTinyAppWithId:@"1234567891234568" params:param];
  • Android code sample
       
    1. Bundle param = new Bundle();
    2. param.putString("page", "pages/card/index");
    3. param.putString("query", "own=1&sign=1&code=2452473");
    4. MPNebula.startApp("1234567891234568",param);