目录
二、第一步：让H5“住”进来——使用 web-view 组件
朋友们，我是小杨，一个在前端世界里乐于“搭桥修路”的工程师。不知道你们有没有遇到过这种让人头疼的情况：运营急着上一个大型活动页，要求能随时修改，但小程序发版审核至少要等一天；或者，公司有一段成熟复杂的业务H5，老板说：“把它搬进小程序，但人力有限，最好别重写！”
这时候，把 H5 页面无缝嵌入小程序，就成了我们的“王牌解决方案”。但这事儿，就像让两个说不同方言的人合作，光是见面（嵌入）还不够，关键得让他们能顺畅交流（通信）。
今天，我就把自己在项目中总结的“嵌入与通信”实战经验分享给大家，让我们一起来实现小程序与H5的完美握手。
一、基础准备：给H5发一张“小程序入场券”
在开始写代码之前，有一个必须完成的配置步骤，很多新手都会在这里栽跟头。
配置业务域名：
你的H5不是想来就来的。你需要登录小程序后台，在 「开发」->「开发管理」->「开发设置」->「业务域名」 中，将你的H5页面所在域名添加进去。
-
关键点：
-
域名必须支持
HTTPS。 -
不能带端口号（如
https://mydomain.***:8080是不允许的）。 -
需要下载校验文件并放在你域名的根目录下，完成验证。
-
这一步如果没做，后面的一切都是空中楼阁。
二、第一步：让H5“住”进来——使用 web-view 组件
这步最简单，小程序提供了 web-view 组件作为H5的“容器”。
假设我们有一个活动页地址是：https://static.yourdomain.***/activity/index.html
在小程序页面中：
<!-- pages/webview/webview.wxml -->
<!-- 这个组件会铺满整个页面 -->
<web-view src="{{h5PageUrl}}"></web-view>// pages/webview/webview.js
Page({
data: {
h5PageUrl: '' // 初始化一个空地址
},
onLoad(options) {
// 场景1：直接加载一个完整的H5活动页
// const url = 'https://static.yourdomain.***/activity/index.html';
// 场景2：H5页面需要一些小程序的参数，比如用户标识
// 假设我们从全局App中获取了一个token
const token = getApp().globalData.userToken;
// 将参数拼接到URL上，这是小程序向H5传数据最直接的方式
const fullUrl = `https://static.yourdomain.***/activity/index.html?token=${token}&source=miniprogram`;
this.setData({
h5PageUrl: fullUrl
});
}
})到这里，你的H5页面已经能在小程序里正常展示了！但它们俩现在还处于“同居但无言”的状态。接下来，才是让它们产生化学反应的精彩部分。
三、第二步：让它们“对话”——实现双向通信
场景A：H5 主动给小程序“发消息”
这是最常见的需求。比如，H5页面里有个“关闭”按钮，点击后需要关掉当前的小程序页面；或者H5领取优惠券成功后，需要通知小程序更新用户资产。
1. 小程序端：设置消息监听器
在 web-view 所在的页面中，定义一个 onMessage 函数来接收消息。
// pages/webview/webview.js
Page({
// ... 其他代码同上
// 关键！监听来自H5的postMessage
onMessage(event) {
console.log('[小程序] 收到H5消息:', event.detail);
const data = event.detail.data; // H5传递过来的数据对象
const action = data.action; // 我们约定一个action字段来区分指令
switch(action) {
case 'closePage':
// H5通知关闭页面
wx.navigateBack();
break;
case 'showToast':
// H5希望小程序显示提示
wx.showToast({
title: data.message,
icon: 'none'
});
break;
case 'updateUserInfo':
// H5完成了一项操作，需要小程序更新本地数据
this.updateUserAsset();
break;
default:
console.warn('未知的指令:', action);
}
},
updateUserAsset() {
// ... 调用小程序的API更新用户数据
}
})2. H5端：调用方法发送消息
首先，确保你的H5页面引入了微信的JS-SDK（通常由小程序环境自动注入，但也可手动引入以保证兼容性）。
然后，在适当的时机（如按钮点击、请求回调）发送消息。
<!-- H5页面 index.html -->
<button onclick="notifyMiniProgram()点击关闭</button>
<button onclick="requestShare()">请求分享</button>
<script src="https://res.wx.qq.***/open/js/jweixin-1.6.0.js"></script>
<script>
// 判断是否在小程序环境中
function isInMiniProgram() {
return typeof wx !== 'undefined' && wx.miniProgram;
}
function notifyMiniProgram() {
if (isInMiniProgram()) {
// 核心代码：向小程序发送消息
wx.miniProgram.postMessage({
data: {
action: 'closePage' // 与小程序端约定的指令
}
});
} else {
// 非小程序环境下的降级处理
console.log('在普通浏览器中');
window.history.back();
}
}
function requestShare() {
if (isInMiniProgram()) {
wx.miniProgram.postMessage({
data: {
action: 'showToast',
message: '分享功能已调用'
// 可以传递更复杂的数据，如分享标题、图片等
}
});
}
}
// 或者，在某个异步操作成功后通知小程序
function onCouponReceived() {
if (isInMiniProgram()) {
wx.miniProgram.postMessage({
data: {
action: 'updateUserInfo'
}
});
}
}
</script>场景B：小程序向H5“传递数据”
除了在初始化时通过URL参数传递，如果需要在H5加载后动态传递数据，一个常见的“黑科技”是利用 web-view 组件的 eval 方法（但需注意官方文档的可用性）或更稳健的方式：通过URL参数触发H5的特定函数。
一个更实用的模式是 “小程序发起，H5监听”：
-
小程序通过修改
web-view的src（例如添加一个时间戳或特定hash参数）。 -
H5 端监听
hashchange或url change事件，解析出新参数，然后执行相应逻辑。
这种方式稍显复杂，但对于需要动态下发数据的场景非常有效。
四、我踩过的“坑”与填坑指南
-
白屏问题：
-
坑：
web-view一片空白。 -
查：第一反应就是去检查业务域名配置是否正确！这是最高频的错误。其次是检查网络和H5页面本身是否能正常访问。
-
-
通信失败：
-
坑：H5发了消息，小程序没反应。
-
查：确保小程序端的
onMessage函数已正确定义；确保H5端的环境判断正确，且wx.miniProgram.postMessage被成功调用。
-
-
样式问题：
-
坑：H5在小程序里显示错乱。
-
解：H5页面需要自己做好的移动端适配（ viewport, rem/vw 等），
web-view只是一个容器，不负责样式。
-
-
路由层级：
-
坑：
web-view页面层级太高，盖住了自定义的TabBar。 -
解：
web-view会覆盖其他原生组件，包括TabBar。设计导航时需考虑此点，通常需要在H5内部实现导航栏。
-
结语
通过 web-view 的嵌入和 postMessage 的通信，我们成功地让小程序和 H5 这两个强大的平台从简单的“嵌入”走向了深度的“融合”。小程序负责稳定、核心的功能和用户体验，H5则承担起需要快速迭代、灵活变动的业务部分。
⭐ 写在最后
请大家不吝赐教,在下方评论或者私信我,十分感谢🙏🙏🙏.✅ 认为我某个部分的设计过于繁琐,有更加简单或者更高逼格的封装方式
✅ 认为我部分代码过于老旧,可以提供新的API或最新语法
✅ 对于文章中部分内容不理解
✅ 解答我文章中一些疑问
✅ 认为某些交互,功能需要优化,发现BUG
✅ 想要添加新功能,对于整体的设计,外观有更好的建议
✅ 一起探讨技术加qq交流群：
906392632最后感谢各位的耐心观看，既然都到这了，点个 👍赞再走吧！
