Host environment for mini programs offers various APIs from WeChat Native. Such as `wx.navigateTo()` in previous example, it stores current page and redirects page to a new one. `wx` here is the global Object from host environment, nearly all APIs are on this object (except special constructors like `Page`, `App`). So "API" in the chapter mainly means methods under `wx`.

APIs can be categorized to Network, Media, File, Cache, Location, Device, UI, Element and other ones. Here is the common rule of API calling:

1. `wx.on*` is some event listeners, accept a callback as parameter. When the event is triggered, the callback is run

2. Unless annotated, most APIs are async, accepting an Object as parameter

3. The parameter Object usually supports three callbacks: `success`, `fail`, `complete`, as shown in code snippet 3-17

4. `wx.get*` are APIs to get data from host environment.

5. `wx.set*` are APIs to write data to host environment.

*code snippet 3-17 network request through `wx.request`

wx.request({

url: 'test.php',

data: {},

header: { 'content-type': 'application/json' },

success: function(res) {

// when http request suceeds

console.log(res.data)

},

fail: function() {

// when error happens in request

},

complete: function() {

// when request completes, either succeeds or fails

}

})

*table 3-9 API callbacks*

parameter name | type | mandatory | description

success | Function | no | callbak when API suceeds

fail | Function | no | callback when API fails

complete | Function | no | callback when API complets

Attention most APIs are async, and some API will call out native views, which leads to `onHide()` in `Page` being called .

There are many many APIs, as the host environment envolves new APIs are added. Here we don't explain the details of all APIs, but the common skills. More details could be found in https://mp.weixin.qq.com/debug/wxadoc/dev/api/. In Chapter 4 we will show more use cases.

User interace need to be interacted by users, for example, users may click some buttons or long press some areas, these actions should be notified to developers, and the new state should be reflected.

Sometimes the feedback is not triggered by users, such as the progress bar when video is being played, these changes should also be notified.

In mini programs, these components' updates triggered by users' interactions are defined as "events" passed from rendering layer to logic layer, as the following image shows:


*Figure 3-7 redering layer generates and passes events to logic layer*

Here is a simple mini program.

*code snippet 3-18 exmaple of event handling*

<view id="tapTest" data-hi="WeChat" bindtap="tapName"> Click me! </view>

// page.js

Page({

tapName: function(event) {

console.log(event)

}

})

Event listener `tapName()` are attached to components through `bindtap` and it is declared in Page constructors. When users tap the view area, tap events are riggered, and `tapName()` will be called with the event as paremter.

Because different components have different state, here component-related events are not discussed, those events can be found at: https://mp.weixin.qq.com/debug/wxadoc/dev/component/.

Common event types are listed here:

*Table 3-10 common event types*

type | condition

-----|--------

touchstart | finger touchs screen

touchmove | finger moves after touching

touchcancel | finger move is disrupted by income call, native modal, .etc

touchend | finger move ends

tap | finger leaves right after first touch

longpress | finger touches, and leaves after 350ms. If this event is triggered, tap events will not occur

longtap | finger touches, and leaves after 350ms. (`longpress` is recommended to use)

transitionend | triggered after WXSS transition or `wx.createAnimation`

animationstart | triggered before the first paint of WXSS animation

animationiteration | triggered after one frame of animation is rendered

animationend | triggered after one WXSS animation is done

The event passed to event handler has following properties.

*Table 3-11 event object properties*

property | type | description

---------|-------|--------

type | String | event type

timeStamp | Integer | time passed from page opened to event triggered(in miliseconds)

target | Object | property set of the component where event is triggered

currentTarget | Object | property set of current component

detail | Object | extra information

touches | Array | touch events, current active touch points

changedTouches | Array | touch events, currently changed touch points

Attention to the difference between `target` and `currentTarget`. `currentTarget` is the component where event listener is attached, and `target` the source component where event is triggered.

*code snippet 3-19 event object example*

<view id="outer" catchtap="handleTap">

<view id="inner">click me</view>

</view>

Page({

handleTap: function(evt) {

// when click inner element

// evt.target is inner view component

// evt.currentTarget is outer view where handleTap is attached

// evt.type == “tap”

// evt.timeStamp == 1542

// evt.detail == {x: 270, y: 63}

// evt.touches == [{identifier: 0, pageX: 270, pageY: 63, clientX: 270, clientY: 63}]

// evt.changedTouches == [{identifier: 0, pageX: 270, pageY: 63, clientX: 270, clientY: 63}]

}

})

The detailed property paramters about `target` and `currentTarget` are listed here:

*Table 3-12 properties of target and currentTarget*

property | type | description

---------|------|----------

id | String | current component's id

tagName | String | current component's type

dataset | Object | data attributes of current component

*Table 3-3 peroperties of touch and changedTouches*

property | type | description

-------|------|----------

identifier | Number | id of touch point

pageX, pageY | Number | distance to top left corner. Top left corner is the origin point, horizontal direction as x-axis, vertical direction as Y-axis

clientX, clientY | Number | similar to above one, but distance is relative screen area (without the navigation bar)

Event binding is done in the same format as `key="value"`.

1. key should start with `bind` or `catch`, followed by event type, such as `bindtap`, `catchtouchstart`. From version 1.5.0, semicolon could be inserted , like `bind:tap`, `catch:touchstart`, they are the same. You can also `capture-` at the beginning to handle events as capuring phase. value is String, which is the method name defined in Page constructor, error occurs if method is not defined. `bind` means bubbling phase, and `capture-bind` means capturing phase, the order is :


*Figure 3-8 bubbling and capuring phase*

In the following example, tapping inner view will call `handleTap1`, `handleTap2`, `handleTap3` and `handleWTap4` in the right order.

*code snippet 3-20 use capture to set phase*

<view id="outer" bind:tap="handleTap4" capture-bind:tap="handleTap1">

outer view

<view id="inner" bind:tap="handleTap3" capture-bind:tap="handleTap2">

inner view

</view>

</view>

`bind` will not stop event bubbling, `catch` is used to do that. If change `capture-bind:tap="handleTap1"` to `capture-catch:tap="handleTap1"`, tapping inner view will only trigger `handleATap1`, becase `catch` stops the bubbling.

*code snippet 3-21 event capturing and bubbling*

<view id="outer" bind:tap="handleTap4" capture-catch:tap="handleTap1">

outer view

<view id="inner" bind:tap="handleTap3" capture-bind:tap="handleTap2">

inner view

</view>

</view>

Attention that all other events(except above ones) are default to non-bubbling ones, unless special notice is addressed, such as `submit` in `<form/>`, `input` in `<input/>`, `scroll` in `<scroll-view/>`.

Host environment for mini programs are always envolving, providing more and more possibilities to developers, thus your mini programs are run in different versions of host environments. In order to provide all environments the same service, we need to know how to handle compatibility problems.

To handle problems across differnt devices, we can use `wx.getSystemInfo` or `wx.getSystemInfoSync` to retrieve brand, OS version, WeChat Native Version or Mini Program SDK version .etc, and offer localized service.

*code snippet 3-22 get host info from `wx.getSystemInfoSync`*

wx.getSystemInfoSync()

You can check whether some methods exists to improve compatibility.

*code 3-23 check API's existence*

if (wx.openBluetoothAdapter) {

wx.openBluetoothAdapter()

} else {

// 如果希望用户在最新版本的客户端上体验您的小程序，可以这样子提示

wx.showModal({

title: 'Alert',

content: 'Please update WeChat to use this feature'

})

}

`wx.canIUse` is provided to check whether some API is available, its parameter should follow `${API}.${method}.${param}.${options}` or `${component}.${attribute}.${option}`

Segments of the parameters are:

* `${API}`, API name

* `${method}`, way of calling, `return`, `success`, `object` or `callback`

* `${param}`, parameter or return value

* `${options}`, optional paramters

* `${component}`, component name