All Products
Search
Document Center

Mobile Platform as a Service:App

Last Updated:Jul 14, 2023

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:

{
  "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 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:

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:

    image.png
  • 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:

    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
Note

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);