更新记录

1.4.0（2025-11-15） 下载此版本

• 文档优化：强调推荐手动指定宿主类型
• 更新所有使用示例，默认添加 env 参数
• 优化注意事项，增加环境选择指南
• 对自动检测方式添加警告说明
• 新增手动指定环境功能，通过env参数控制消息发送方式
• 优化错误处理，增强兼容性
• 更新使用文档，添加手动指定环境的示例
• 推荐使用手动指定环境以避免自动检测问题

1.1.0（2025-11-15） 下载此版本

1.1.0（功能增强）

• 新增微信小程序web-view环境支持
• 添加autoNavigateBack选项，解决微信小程序消息延迟问题
• 优化根目录index.js，正确导出lib模块
• 增强环境检测功能，支持更详细的环境信息
• 添加静态detectEnv方法，支持同步环境检测
• 更新文档和示例代码
• 优化错误处理和日志输出

1.0.0（2025-11-14） 下载此版本

1.0.0 (2025-11-14)

新增

• 首次发布
• 支持H5环境下的消息通信
• 提供postMessage方法用于向原生应用发送消息
• 支持Vue2和Vue3
• 添加完整的文档和使用示例

特性

• 经过实际项目测试验证
• 简单易用的API
• 完善的错误提示

平台兼容性

uni-app(4.86)

webview-postmessage

uniapp打包成H5后，用于向原生应用或***小程序发送消息的插件。

说明

经过实际项目测试验证，uniapp打包成H5后，向不同容器发送消息需要使用不同的方式：

1. App环境：使用 webUni.postMessage 方式
2. ***小程序web-view环境：使用 wx.miniProgram.postMessage 方式

其他常见方式（如 uni.postMessage、window.parent.postMessage）在H5环境下无法正常工作。

重要提示：在小程序的web-view中，如果只调用 postMessage，消息会在页面销毁后才被小程序接收。这是官方的已知问题。解决方案是在发送消息后立即调用 wx.miniProgram.navigateBack()，插件提供了 autoNavigateBack 选项来自动处理。

功能特性

• ✅ 支持H5环境下的消息通信（App、***小程序、普通H5）
• ✅ 自动检测运行环境并使用对应的API
• ✅ 支持***小程序消息延迟问题的自动处理
• ✅ 经过实际项目测试验证
• ✅ 支持Vue2和Vue3
• ✅ 简单易用的统一API

安装

方式：手动安装到uni_modules

1. 将 webview-postmessage 插件复制到你的 uniapp 项目的 uni_modules 目录下
2. 在需要使用的页面或组件中直接引入

使用方法

基础用法

import webviewPostMessage from '@/uni_modules/webview-postmessage/index.js'

// 发送消息（自动检测环境：App、***小程序、普通H5）
webviewPostMessage.postMessage({ 
  data: { 
    action: 'closeWebView' 
  } 
})

// 手动指定***小程序环境
webviewPostMessage.postMessage({ 
  data: { 
    action: 'closeWebView' 
  },
  env: '***',
  autoNavigateBack: true  // 自动调用 navigateBack，确保消息立即被接收
})

// 手动指定App环境
webviewPostMessage.postMessage({ 
  data: { 
    action: 'closeWebView' 
  },
  env: 'app'
})

在Vue组件中使用

<template>
  <view>
    <button @click="sendMessage">发送消息</button>
    <button @click="sendMessageAndBack">发送消息并返回</button>
  </view>
</template>

<script setup>
import webviewPostMessage from '@/uni_modules/webview-postmessage/index.js'

// 普通发送消息 - 推荐手动指定环境类型
const sendMessage = () => {
  webviewPostMessage.postMessage({
    data: {
      action: 'closeWebView',
      // 可以传递其他数据
      token: 'xxx',
      userId: 123
    },
    env: 'app' // 手动指定宿主类型：'app' 或 '***'
  })
}

// ***小程序环境：发送后自动返回（推荐手动指定环境类型）
const sendMessageAndBack = () => {
  webviewPostMessage.postMessage({
    data: {
      action: 'closeWebView',
      token: 'xxx',
      userId: 123
    },
    env: '***', // 手动指定宿主类型为***小程序
    autoNavigateBack: true  // 自动返回，确保消息立即被接收
  })
}
</script>

在页面中使用

import webviewPostMessage from '@/uni_modules/webview-postmessage/index.js'

// 在 onLoad 或 onShow 中发送消息 - 推荐手动指定环境类型
onLoad(() => {
  webviewPostMessage.postMessage({
    data: {
      action: 'init',
      pageId: 'home'
    },
    env: 'app' // 手动指定宿主类型：'app' 或 '***'
  })
})

// 关闭页面时发送消息 - 推荐手动指定环境类型
const closePage = () => {
  webviewPostMessage.postMessage({
    data: {
      action: 'closeWebView'
    },
    env: 'app' // 手动指定宿主类型：'app' 或 '***'
  })
}

API说明

postMessage(options)

向原生应用或***小程序发送消息（推荐手动指定环境类型）

参数：

示例：

// App环境或普通H5环境
webviewPostMessage.postMessage({
  data: {
    action: 'closeWebView',
    // 其他自定义数据
    type: 'userAction',
    value: 'someValue'
  }
})

// ***小程序环境，发送后自动返回
webviewPostMessage.postMessage({
  data: {
    action: 'closeWebView',
    token: 'xxx'
  },
  autoNavigateBack: true  // 自动调用 navigateBack，确保消息立即被接收
})

注意事项

1. 适用于H5环境：此插件主要用于uniapp打包成H5后的消息通信

   • App环境：自动使用 webUni.postMessage
   • ***小程序web-view环境：自动使用 wx.miniProgram.postMessage（需要引入 jweixin.js）
   • 需要引入 jweixin.js 才能支持***小程序环境

2. 必须传递data属性：postMessage方法必须传入包含data属性的对象

3. 数据格式：data可以是任意JSON可序列化的对象

4. 小程序消息延迟问题：在小程序的web-view中，如果只发送消息不调用 navigateBack，消息会在页面销毁后才被接收。建议使用 autoNavigateBack: true 选项自动处理

测试验证

此插件经过以下环境测试：

• ✅ uniapp打包成H5
• ✅ App环境（Android/iOS）
• ✅ ***小程序web-view环境
• ✅ ***浏览器
• ✅ Chrome浏览器
• ✅ Safari浏览器
• ✅ Android浏览器
• ✅ iOS Safari
• ✅ Vue2和Vue3

常见问题

Q: 为什么不能使用uni.postMessage？

A: 经过测试，uni.postMessage 在H5环境下无法正常工作，只有 webUni.postMessage 方式有效。

Q: 支持哪些平台？

A: 插件会自动检测运行环境并选择对应的通信方式：

• App环境：使用 webUni.postMessage（DCloud、5+ Runtime）
• ***小程序web-view环境：使用 wx.miniProgram.postMessage（需要引入 jweixin.js）
• 普通H5环境：使用 webUni.postMessage 或 window.parent.postMessage

Q: ***小程序中消息为什么在页面销毁后才收到？

A: 这是***官方的已知问题。在web-view中只调用 postMessage 时，消息会被缓存，直到页面销毁才被小程序接收。解决方案是在发送消息后立即调用 wx.miniProgram.navigateBack()，插件提供了 autoNavigateBack: true 选项来自动处理这个问题。

Q: 如何在***小程序环境中使用？

A: 需要确保在H5页面中引入了 jweixin.js（***JS-SDK）。可以通过以下方式引入：

<!-- 在 template.h5.html 中引入（Vue2） -->
<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>

<!-- 或者在 Vue3 项目中，在 main.js 中动态引入 -->

然后在代码中使用：

// 引入插件
import webviewPostMessage from '@/uni_modules/webview-postmessage/index.js'

// 发送消息并自动返回（解决延迟问题）
webviewPostMessage.postMessage({
  data: { action: 'closeWebView' },
  autoNavigateBack: true
})

Q: ***小程序如何接收消息？

A: 在小程序页面的 web-view 组件上绑定 @message 事件：

<template>
  <web-view :src="url" @message="onMessage"></web-view>
</template>

<script>
export default {
  methods: {
    onMessage(e) {
      // e.detail.data 是一个数组，包含所有发送的消息
      const messages = e.detail.data || [];
      messages.forEach(msg => {
        if (msg.action === 'closeWebView') {
          uni.navigateBack();
        }
        // 处理其他消息...
      });
    }
  }
}
</script>

Q: 可以传递什么类型的数据？

A: 可以传递任何JSON可序列化的数据，包括对象、数组、字符串、数字等。

版本历史

详见 changelog.md

许可证

MIT

作者

如有问题或建议，欢迎反馈。