微信小程序内嵌H5的技术实现与注意事项（二）

小前端大牛马

已于 2025-03-31 13:37:56 修改

阅读量2.1k

点赞数 11

CC 4.0 BY-SA版权

文章标签：微信小程序小程序

于 2025-03-28 17:36:30 首次发布

本文链接：https://blog.youkuaiyun.com/m0_51429350/article/details/146603079

微信的<web-view>（本文的web-view,均以uni-app为准）组件允许你在微信内置浏览器中嵌入网页内容。这使得你可以将现有的网页应用集成到微信小程序中，提供更好的用户体验。以下是关于微信<web-view>组件的详细说明和使用指南：

1. 基本概念4

<web-view>组件：用于在小程序中嵌入网页，会自动铺满整个小程序页面。它可以在小程序页面中显示一个网页，用户可以在其中浏览和交互。个人类型与海外类型的小程序暂不支持使用。
域名配置：使用<web-view>组件前，需要在微信公众平台配置业务域名。确保域名已备案且可以正常访问。

2. 配置域名(各小程序平台，web-view 加载的 url 需要在后台配置域名白名单，包括内部再次 iframe 内嵌的其他 url )

登录微信公众平台：进入微信公众平台，选择对应的小程序。
开发设置：在左侧菜单中选择“开发” -> “开发设置”。
服务器域名：在“服务器域名”部分，添加你的业务域名。确保域名已备案且可以正常访问。
业务域名：在“业务域名”列表中添加你的网页域名。

3. 使用`<web-view>`组件

引入组件：在小程序页面的WXML文件中引入<web-view>组件。
设置src属性：自动铺满整个页面，支持通过src属性指定网页链接‌ 。

4. 注意事项

小程序仅支持加载网络网页，不支持本地html
小程序端 web-view 组件一定有原生导航栏，下面一定是全屏的 web-view 组件，navigationStyle: custom 对 web-view 组件无效。

一、uni-app中`<web-view>`与小程序通信的实现方式

引用依赖的文件

在 web-view 加载的 HTML 中调用 uni 的 API，需要在 HTML 中引用必要的 JS-SDK。

<!-- 微信 JS-SDK 如果不需要兼容小程序，则无需引用此 JS 文件。微信 JS-SDK 是由微信官方提供的 JavaScript 库，用于在微信客户端中调用微信提供的各种功能，如分享、支付、地理位置等。 -->  
<script type="text/javascript" src="//res.wx.qq.com/open/js/jweixin-1.4.0.js"></script>  
<!-- uni 的 SDK，必须引用。 -->  
<script type="text/javascript" src="//js.cdn.aliyun.dcloud.net.cn/dev/uni-app/uni.webview.0.1.52.js"></script>

Tips

这些 JS 文件是在 web-view 加载的那个 HTML 文件中引用的，而不是 uni-app 项目中的文件。
如果不考虑微信小程序，则无需引入微信的 JS-SDK。
两个文件同时引入时，注意引入的顺序，微信的需要在前。

一、H5向小程序发送消息

‌消息事件机制（推荐）‌
- ‌H5端‌：引入uni.webview.js（仅仅是以uni-app中的<web-view>组件可以使用）库，调用uni.postMessage({ data: ... })发送数据‌。
- ‌小程序端‌：通过<web-view>组件的@message事件监听，并在回调函数中获取e.detail.data接收数据‌。
- ‌限制‌：在微信环境下，消息仅在页面后退、组件销毁或分享时触发‌。
‌URL参数传递‌
- 小程序加载H5时，通过src属性拼接参数（如src="https://domain?key=value"），H5通过解析URL获取初始数据‌。
- 适用于单向、低频数据传输，但无法实现实时更新‌。

二、小程序向H5发送消息

‌evalJS主动调用（仅限uni-app方案）‌
- ‌小程序端‌：通过this.$refs.webview.evalJS("全局函数名('参数')")调用H5页面的全局函数，实现实时通信‌。
- ‌H5端‌：需提前在全局作用域定义函数（如window.uniCallback = (data) => { ... }）用于接收数据‌。
‌URL初始化传参‌
- 小程序通过src属性传递初始参数（如src="https://domain?key=value"），H5通过window.location.search解析参数‌。
- 仅支持一次性数据传递，无法动态更新‌。

三、完整代码示例

‌H5端（需引入uni.webview.js）

// 发送消息给小程序
uni.postMessage({ data: { action: "h5_click" } });

// 定义接收小程序消息的函数
window.uniCallback = (data) => {
  console.log("收到小程序数据：", data);
};

‌2.小程序端（uni-app）

<template>
  <web-view :src="webUrl" @message="handleMessage" ref="webview"></web-view>
</template>
<script>
export default {
  methods: {
    handleMessage(e) {
      console.log("收到H5数据：", e.detail.data); // 接收H5消息
      // 调用H5函数
      this.$refs.webview.evalJS("uniCallback('小程序返回数据')");
    }
  }
};
</script>

四、注意事项

‌环境判断‌：H5需通过uni.getEnv判断是否运行在小程序环境‌。

document.addEventListener('UniAppJSBridgeReady', function() {  
    uni.getEnv(function(res) {  
        console.log('当前环境：' + JSON.stringify(res));  
    });  
});

‌安全性‌：URL传参需避免明文传输敏感数据；evalJS需防范代码注入风险‌。
‌兼容性‌：evalJS为uni-app特有方法，微信原生小程序需通过全局变量或自定义事件模拟双向通信‌。

二、‌uni-app 与 `<web-view>` 的跳转实现方案

‌一、uni-app 跳转至 `<web-view>`‌

‌基础跳转方式‌
- ‌通过 <web-view> 组件加载目标页面‌
  在 .vue 文件中直接使用 <web-view> 组件并设置 src 属性：

<template>
  <web-view :src="externalUrl"></web-view>
</template>
<script>
export default {
  data() {
    return { externalUrl: 'https://h5-domain.com' };
  }
};
</script>

2. ‌通过路由跳转至承载 <web-view> 的页面‌
使用 uni.navigateTo 跳转至包含 <web-view> 的页面，并传递 URL 参数：

uni.navigateTo({
  url: '/pages/webview/webview?url=' + encodeURIComponent('https://h5-domain.com')
});

（目标页面通过 onLoad 接收参数并赋值给 <web-view> 的 src）‌

‌二、`<web-view>` 内跳转回 uni-app 页面‌

‌通过 URL Scheme 触发跳转
- ‌H5 端‌：在链接中拼接 uni-app 路由协议（如 uniwebview://）或自定义协议：

这是一个自定义函数，用于检测当前是否在微信浏览器中，当前h5页面在微信内置浏览器中运行，可以使用URL Scheme:

URL Scheme 是一种自定义的 URL 协议，用于在移动应用之间进行跳转和通信。它允许一个应用通过特定的 URL 打开另一个应用或执行特定的操作。URL Scheme 类似于网页中的 URL，但它们是为移动应用设计的。

function isWeChatBrowser() {
  return /MicroMessenger/i.test(navigator.userAgent);
}

<a href="uniwebview:///pages/home/index">返回首页</a>

2.uni-app 端‌：通过 App.vue 监听协议触发跳转逻辑：

// App.vue
onLaunch(options) {
  if (options.query.url === 'uniwebview:///pages/home/index') {
    uni.switchTab({ url: '/pages/home/index' });
  }
}

（需在原生工程中配置 URL Scheme）‌

2‌.通过 uni.navigateTo 直接调用‌

‌ 1.H5 端‌：引入 uni-webview.js SDK 后调用 uni API：

// H5 页面中
uni.navigateTo({ url: '/pages/detail/index?id=123' });

三、web-view 返回 uni-app 页面

‌JS-SDK 调用‌
- ‌依赖文件‌：在 web-view 加载的 HTML 中引入 uni.webview.js‌7。
- ‌安全调用时机‌：监听 UniAppJSBridgeReady 事件后，调用 uni-app 路由方法：

document.addEventListener('UniAppJSBridgeReady', function() {
  uni.navigateBack(); // 返回上一页
  // 或 uni.switchTab({ url: '/pages/home' }); // 跳转至指定页面‌:ml-citation{ref="5,7" data="citationList"}
});