Overview of Communication Mechanisms

The <web-view> component serves as a bridge allowing WeChat Mini Programs to embed web pages directly. However, developers often encounter complexities regarding data exchange between the host Mini Program and the hosted H5 page. The component relies primarily on two attributes: src for specifying the URL and bindmessage for receiving messages from the web page.

Data Transfer from H5 to Mini Program

To facilitate communicatino from the web page back to the Mini Program, the WeChat JSSDK provides the wx.miniProgram.postMessage API. A criitcal implementation detail involves the structure of the argument passed to this method. The data object must be nested strictly within a property named data. If you pass the object directly, the Mini Program will fail to receive the payload.

Additionally, the message handler defined in bindmessage is not executed in real-time. According to official specifications, the callback is triggered only during specific component lifecycle events, such as when the Mini Program destroys the component, navigates back, or triggers a share action.

Example Implementation:

<!-- H5 Page Script -->
<script type="text/javascript" src="https://res.wx.qq.com/open/js/jweixin-1.3.2.js"></script>
<script>
  // Correct implementation requires the 'data' wrapper
  wx.miniProgram.postMessage({
    data: {
      event: 'user_action',
      details: { id: 42, timestamp: Date.now() }
    }
  });
</script>

<!-- Mini Program WXML -->
<web-view src="https://example.com/page" bindmessage="handleWebMessage"></web-view>

// Mini Program JS Logic
Page({
  handleWebMessage(event) {
    const receivedData = event.detail.data;
    console.log('Message received from web page:', receivedData);
  }
});

Handling Dynamic URL Parameters

A common pitfall involves dynamically binding the src attribute using double curly braces in WXML, particularly when passing parameters via query strings.

Incorrect Approach:

<web-view src="{{dynamicUrl}}/detail?identifier={{itemId}}"></web-view>

On Android devices, this method often fails because the src may render prematurely before the data binding is fully resolved, resulting in a malformed URL (e.g., .../detail?identifier=).

Robust Solution:

To ensure compatibility across all platforms, construct the complete URL string within the JavaScript logic using setData before rendering the view.

Page({
  data: {
    webViewSrc: ''
  },

  onLoad(queryParams) {
    const targetId = queryParams.id;
    const baseUrl = 'https://api.service.com';
    
    // Construct the full URL in JS
    const fullUrl = `${baseUrl}/render?uid=${targetId}&token=xyz`;

    this.setData({
      webViewSrc: fullUrl
    });
  }
});

<!-- WXML -->
<web-view src="{{webViewSrc}}"></web-view>

Preserving Query Strings in Navigation

When navigating to a web-view page where the target URL itself contains query parameters, the Mini Program's router may strip the inner query string if not handled correctly.

Scenario:

<!-- Attempting to pass a URL with params -->
<navigator url="/pages/container?target=https://site.com?ref= promo">
  Open Web View
</navigator>

In the example above, the ?ref=promo segment is likely to be lost during routing.

**Fix:**You must encode the target URL using encodeURIComponent before passing it, and then decode it within the container page logic.

// Sender Page
const targetUrl = 'https://site.com?ref=promo';
const encodedUrl = encodeURIComponent(targetUrl); 
// Result: "https%3A%2F%2Fsite.com%3Fref%3Dpromo"

// Container Page (Receiver)
Page({
  onLoad(options) {
    if (options.target) {
      const decodedUrl = decodeURIComponent(options.target);
      this.setData({ src: decodedUrl });
    }
  }
});

Navigational Controls

The JSSDK 1.3.2 exposes methods under the wx.miniProgram namespace that allow the embedded web page to control the Mini Program's navigation stack. Developers can invoke methods such as navigateTo, switchTab, or navigateBack to transition between Mini Program pages based on user interactions within the web view.

**Best Practices:**Minimize the frequency of communication between the web view and the Mini Program to ensure performance stability. Furthermore, avoid implementing Single Page Applications (SPAs) that rely heavily on server-side redirects (such as OAuth authorization flows) inside the web-view, as these redirects can disrupt the expected navigation behavior and user experience.