web-view

Start from base library version 1.6.4. Please remaining backward compatible.

Container that carries webpages. It automatically fills the entire Mini Program page. It is currently not supported on Mini Programs owned by personal entities (individual).

The navigationStyle: custom property does not take effect for the web-view component as of WeChat 6.7.2.

Property Type Default Value Required Description Minimum Version
src string No The link from the webview to a webpage. It allows you to open an article of a linked Official Account. For other webpages, log in to Mini Program admin console to configure the service domain name. 1.6.4
bindmessage eventhandler No Triggered at a specific occasion (for example, the Mini Program returns to a previous page, a component is terminated, or a page is shared) when postMessage is called from a webpage to the Mini Program. A message is received after the event is triggered. The e.detail is { data }, where data is an array consisting of parameter values obtained via multiple calls to postMessage. 1.6.4
bindload eventhandler No Triggered when a webpage is loaded. e.detail = { src } 1.6.4
binderror eventhandler No Triggered when a webpage failed to be loaded. e.detail = { src } 1.6.4

On the web-view webpage, you can call APIs provided in JSSDK 1.3.2 to return to a Mini Program page. Supported APIs are as follows:

API Description Minimum Version
wx.miniProgram.navigateTo Parameters of this API are the same as those of the corresponding API for Mini Programs. 1.6.4
wx.miniProgram.navigateBack Parameters of this API are the same as those of the corresponding API for Mini Programs. 1.6.4
wx.miniProgram.switchTab Parameters of this API are the same as those of the corresponding API for Mini Programs. 1.6.5
wx.miniProgram.reLaunch Parameters of this API are the same as those of the corresponding API for Mini Programs. 1.6.5
wx.miniProgram.redirectTo Parameters of this API are the same as those of the corresponding API for Mini Programs. 1.6.5
wx.miniProgram.postMessage Triggers the message event at a specific occasion (for example, the Mini Program returns to a previous page, a component is terminated, or an event is shared) when a message is sent to a Mini Program. 1.7.1
wx.miniProgram.getEnv Obtains the current environment 1.7.1

Sample Code

Preview with Developer Tool

// <script type="text/javascript" src="https://res.wx.qq.com/open/js/jweixin-1.3.2.js"></script>

// javascript
wx.miniProgram.navigateTo({url: '/path/to/page'})
wx.miniProgram.postMessage({ data: 'foo' })
wx.miniProgram.postMessage({ data: {foo: 'bar'} })
wx.miniProgram.getEnv(function(res) { console.log(res.miniprogram) })

On web-view webpages, only the following JSSDK APIs are supported:

API Module API Description API
Determines whether WeChat supports JS code checkJSApi
Image APIs Takes or uploads a photo chooseImage
Previews a photo previewImage
Uploads a photo uploadImage
Downloads a photo downloadImage
Obtains a local photo getLocalImgData
Audio APIs Starts recording startRecord
Stops recording stopRecord
Listens on when the recording automatically ends onVoiceRecordEnd
Plays the voice playVoice
Pauses the voice playback pauseVoice
Stops the voice playback stopVoice
Listens on whether the voice playback ends onVoicePlayEnd
Uploads the voice uploadVoice
Downloads the voice downloadVoice
Smart API Identifies an audio translateVoice
Device information Obtains the network status information getNetworkType
Geographic location Opens the location via the built-in map openLocation
Obtains the geographic location getLocation
Shake Nearby Enables ibeacon startSearchBeacons
Disables ibeacon stopSearchBeacons
Listens on ibeacon onSearchBeacons
Scan on WeChat Calls Scan scanQRCode
Cards & Offers on WeChat Draws the list of Cards & Offers chooseCard
Adds cards & offers in batch addCard
Views coupons in Cards & Offers on WeChat openCard
Tap and hold to recognize the QR code Displays the round Mini Program code None

The URL of the current web-view component can be obtained when the component is shared by the user. To be specific, the webViewUrl parameter is returned from the onShareAppMessage callback.

Sample Code

Sample code:

Page({
  onShareAppMessage(options) {
    console.log(options.webViewUrl)
  }
})

On a webpage, the Mini Program environment can be determined via the window.__wxjs_environment variable. We recommended that the API be used during the callback of WeixinJSBridgeReady. The getEnv API provided in JSSDK 1.3.2 can be used alternatively.

Sample Code

// On a page in the web-view.
function ready() {
  console.log(window.__wxjs_environment === 'miniprogram') // true
}
if (!window.WeixinJSBridge || !WeixinJSBridge.invoke) {
  document.addEventListener('WeixinJSBridgeReady', ready, false)
} else {
  ready()
}

// or
wx.miniProgram.getEnv(function(res) {
  console.log(res.miniprogram) // true
})

As of WeChat 7.0.0, the Mini Program web-view environment can be determined via miniProgram in userAgent.

As of WeChat 7.0.3, whether a Mini Programs is running in the foreground can be determined by the following way:

WeixinJSBridge.on('onPageStateChange', function(res) {
  console.log('res is active', res.active)
})

Bug & Tip

  1. tip: The domain name of an iframe on a webpage also needs to be added to the domain name whitelist.
  2. tip: On the WeChat DevTools, you can debug the web-view component by right-clicking the web-view component and selecting Debug.
  3. tip: Each page includes only one web-view component. The web-view component automatically fills the whole page and covers other components.
  4. tip: Only communication between web-view webpages and Mini Programs via APIs provided in JSSDK is supported.
  5. tip: On iOS, if any JSSDK API does not respond after called, append the src in web-view with #wechat_redirect.
  6. tip: Avoid Chinese characters in links. Tapping links containing Chinese characters on iOS will cause a white screen. encodeURIComponent should be added.