MPX

🚀 跨平台小程序 WebView 通信库

✨ 特性

🎯 统一 API - 一套代码，支持所有主流小程序平台
🔄 双向通信 - H5 与小程序原生环境无缝交互
💪 TypeScript - 完整的类型定义，开发体验更佳
🛡️ 错误处理 - 完善的错误处理和重试机制
⚡ 高性能 - 优化的通信协议，支持并发控制
🔧 可扩展 - 支持自定义适配器和插件
📱 全平台 - 支持微信、支付宝、字节跳动、百度小程序
🎨 零依赖 - 轻量级设计，无外部依赖

🚀 快速开始

安装

# npm
npm install mpx-webview-bridge

# yarn
yarn add mpx-webview-bridge

# pnpm
pnpm add mpx-webview-bridge

H5 端使用

import MPX from 'mpx-webview-bridge';

// 创建实例
const mpx = new MPX({
  debug: true,
  timeout: 10000
});

// 初始化
await mpx.initialize();

// 调用小程序方法
const systemInfo = await mpx.invoke('getSystemInfo');
console.log('系统信息:', systemInfo);

// 显示提示
await mpx.invoke('showToast', {
  title: '操作成功！',
  icon: 'success'
});

// 监听事件
mpx.on('pageShow', (data) => {
  console.log('页面显示事件:', data);
});

小程序端使用

// pages/webview/webview.js
import { MPXNativeBridge } from 'mpx-webview-bridge/native';

Page({
  onLoad() {
    // 创建桥接器
    this.bridge = new MPXNativeBridge(this);
    
    // 注册方法处理器
    this.bridge.registerMethod('getSystemInfo', async () => {
      return new Promise((resolve) => {
        wx.getSystemInfo({ success: resolve });
      });
    });
  },

  onMessage(e) {
    // 处理来自 H5 的消息
    this.bridge.handleMessage(e.detail.data);
  }
});

🎯 支持平台

平台	状态	版本要求	特殊说明
微信小程序	✅ 完全支持	>= 2.4.0	支持所有基础 API
支付宝小程序	✅ 完全支持	>= 2.0.0	支持支付宝特有 API
字节跳动小程序	✅ 完全支持	>= 2.0.0	支持抖音、今日头条
百度小程序	✅ 完全支持	>= 3.0.0	支持百度智能小程序

📖 详细文档

核心概念

MPX WebView Bridge 基于适配器模式设计，为不同小程序平台提供统一的通信接口：

// 平台自动检测
const mpx = new MPX();
await mpx.initialize();

// 获取当前平台
const platform = mpx.getPlatform(); // 'wechat' | 'alipay' | 'bytedance' | 'baidu'

// 检查方法支持
if (mpx.isSupported('getLocation')) {
  const location = await mpx.invoke('getLocation');
}

配置选项

const mpx = new MPX({
  // 基础配置
  timeout: 10000,           // 请求超时时间（毫秒）
  debug: true,              // 开启调试模式
  
  // 重试配置
  retry: {
    times: 3,               // 重试次数
    delay: 1000,            // 重试延迟（毫秒）
    exponentialBackoff: true // 指数退避
  },
  
  // 性能配置
  maxConcurrentRequests: 10,        // 最大并发请求数
  enablePerformanceMonitoring: true, // 性能监控
  enableDataValidation: true,        // 数据验证
  
  // 错误处理
  errorHandler: (error) => {
    console.error('MPX 错误:', error);
    // 自定义错误处理逻辑
  }
});

方法调用示例

// 系统信息
const systemInfo = await mpx.invoke('getSystemInfo');

// UI 交互
await mpx.invoke('showModal', {
  title: '确认',
  content: '确定要执行此操作吗？'
});

// 页面导航
await mpx.invoke('navigateTo', {
  url: '/pages/detail/detail?id=123'
});

// 数据存储
await mpx.invoke('setStorage', {
  key: 'userInfo',
  data: { name: 'John', age: 30 }
});

// 网络请求
const response = await mpx.invoke('request', {
  url: 'https://api.example.com/data',
  method: 'POST',
  data: { key: 'value' }
});

// 设备功能
const location = await mpx.invoke('getLocation', {
  type: 'gcj02'
});

const images = await mpx.invoke('chooseImage', {
  count: 3,
  sourceType: ['album', 'camera']
});

事件系统

// 监听生命周期事件
mpx.on('pageShow', () => {
  console.log('页面显示');
});

mpx.on('pageHide', () => {
  console.log('页面隐藏');
});

// 监听系统事件
mpx.on('networkStatusChange', (status) => {
  console.log('网络状态变化:', status);
});

// 自定义事件
mpx.on('customEvent', (data) => {
  console.log('收到自定义事件:', data);
});

// 发送事件到小程序
mpx.emit('userAction', {
  action: 'click',
  target: 'button'
});

// 取消监听
mpx.off('pageShow', handler);

错误处理

try {
  const result = await mpx.invoke('getLocation');
} catch (error) {
  if (error.code === 'PERMISSION_DENIED') {
    console.log('用户拒绝了位置权限');
  } else if (error.code === 'TIMEOUT') {
    console.log('请求超时，请重试');
  } else {
    console.log('其他错误:', error.message);
  }
}

🔧 高级用法

自定义适配器

class CustomAdapter extends PlatformAdapter {
  name = 'custom';
  
  detect() {
    return typeof window.customPlatform !== 'undefined';
  }
  
  async initialize() {
    // 自定义初始化逻辑
  }
  
  async invoke(method, params) {
    // 自定义方法调用逻辑
  }
}

const mpx = new MPX({
  customAdapters: [CustomAdapter]
});

性能监控

// 开启性能监控
const mpx = new MPX({
  enablePerformanceMonitoring: true
});

// 获取性能指标
const metrics = mpx.getPerformanceMetrics();
console.log('平均响应时间:', metrics.averageResponseTime);
console.log('成功率:', metrics.successRate);

// 获取方法统计
const methodStats = mpx.getMethodStats();
console.log('方法调用统计:', methodStats);

调试工具

// 开启调试模式
const mpx = new MPX({ debug: true });

// 检查平台支持
const support = mpx.checkPlatformSupport([
  'getSystemInfo',
  'getLocation',
  'chooseImage'
]);

// 生成调试报告
const report = mpx.generateDebugReport();
console.log(report);

📚 API 文档

MPX 类方法

方法	描述	参数	返回值
`initialize(options?)`	初始化 MPX 实例	`MPXOptions?`	`Promise<void>`
`invoke<T>(method, params?)`	调用小程序方法	`string, any?`	`Promise<T>`
`on(event, callback)`	监听事件	`string, Function`	`void`
`off(event, callback?)`	取消监听	`string, Function?`	`void`
`emit(event, data?)`	发送事件	`string, any?`	`void`
`getPlatform()`	获取当前平台	-	`Platform`
`isSupported(method)`	检查方法支持	`string`	`boolean`
`destroy()`	销毁实例	-	`void`

支持的小程序方法

点击查看完整方法列表

基础 API

getSystemInfo - 获取系统信息
getNetworkType - 获取网络类型
getStorage / setStorage / removeStorage - 数据存储
request - 网络请求

UI 交互

showToast - 显示提示框
showModal - 显示模态对话框
showActionSheet - 显示操作菜单
showLoading / hideLoading - 显示/隐藏加载提示

页面导航

navigateTo - 跳转页面
redirectTo - 重定向页面
navigateBack - 返回页面
switchTab - 切换 Tab

设备功能

getLocation - 获取位置
chooseImage - 选择图片
previewImage - 预览图片
scanCode - 扫码
makePhoneCall - 拨打电话
setClipboardData / getClipboardData - 剪贴板操作

媒体功能

createInnerAudioContext - 音频播放（百度小程序）
createVideoContext - 视频播放（百度小程序）
getRecorderManager - 录音管理（百度小程序）

🧪 测试

# 运行所有测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

# 运行性能测试
npm run test:performance

# 运行压力测试
npm run test:stress

📦 构建

# 开发构建
npm run build:dev

# 生产构建
npm run build:prod

# 构建并分析包大小
npm run build:analyze

🤝 贡献

我们欢迎所有形式的贡献！请查看贡献指南了解详情。

开发流程

Fork 本仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

开发环境

# 克隆仓库
git clone https://github.com/your-org/mpx.git
cd mpx

# 安装依赖
npm install

# 启动开发模式
npm run dev

# 运行测试
npm test

📄 许可证

本项目基于 MIT 许可证开源。

🙏 致谢

感谢所有为这个项目做出贡献的开发者！

📞 支持

如果您在使用过程中遇到问题，可以通过以下方式获取帮助：

📖 文档
🐛 提交 Issue
💬 讨论区
📧 邮件支持

⭐ 如果这个项目对您有帮助，请给我们一个 Star！

Made with ❤️ by Your Team

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.kiro/specs/mpx		.kiro/specs/mpx
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.npmignore		.npmignore
BUILD_SUMMARY.md		BUILD_SUMMARY.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCS_UPDATE_SUMMARY.md		DOCS_UPDATE_SUMMARY.md
OPTIMIZATION_SUMMARY.md		OPTIMIZATION_SUMMARY.md
PROJECT_STATUS.md		PROJECT_STATUS.md
PUBLISH_CHECKLIST.md		PUBLISH_CHECKLIST.md
PUBLISH_SUCCESS.md		PUBLISH_SUCCESS.md
README.md		README.md
TEST_STRUCTURE_MIGRATION.md		TEST_STRUCTURE_MIGRATION.md
build.config.js		build.config.js
jest.config.cjs		jest.config.cjs
jest.performance.config.cjs		jest.performance.config.cjs
optimization-report.json		optimization-report.json
package.json		package.json
performance-report.json		performance-report.json
pnpm-lock.yaml		pnpm-lock.yaml
rollup.config.js		rollup.config.js
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

qiaojianfeng/MPX

Folders and files

Latest commit

History

Repository files navigation

MPX