Youshu Bridge

用于 Flutter WebView 和网页之间通信的桥梁库。

安装

npm install youshu-bridge

使用方法

在网页中使用

import bridge from "youshu-bridge";

// 调用任何原生方法
try {
  const result = await bridge.anyMethodName(params);
  console.log("调用成功:", result);
} catch (error) {
  console.error("调用失败:", error);
}

// 示例：获取位置
try {
  const location = await bridge.getLocation();
  console.log("当前位置:", location);
} catch (error) {
  console.error("获取位置失败:", error);
}

// 示例：支付
try {
  const result = await bridge.pay({
    orderId: "123456",
    amount: 100,
  });
  console.log("支付成功:", result);
} catch (error) {
  console.error("支付失败:", error);
}

// 示例：分享
try {
  const result = await bridge.share({
    title: "分享标题",
    content: "分享内容",
    url: "https://example.com",
  });
  console.log("分享成功:", result);
} catch (error) {
  console.error("分享失败:", error);
}

在 Flutter 中使用

在 Flutter 端，您需要设置 WebView 并注入 YSBridge 对象：

import 'package:webview_flutter/webview_flutter.dart';

// 创建 WebView 控制器
final WebViewController controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..addJavaScriptChannel(
    'YSBridge',
    onMessageReceived: (JavaScriptMessage message) async {
      final data = jsonDecode(message.message);
      final method = data['method'];
      final params = data['params'];
      final callbackId = data['callbackId'];

      try {
        dynamic result;

        // 根据方法名处理不同的请求
        switch (method) {
          case 'getLocation':
            // 处理获取位置
            result = await handleGetLocation();
            break;

          case 'pay':
            // 处理支付
            result = await handlePay(params);
            break;

          case 'share':
            // 处理分享
            result = await handleShare(params);
            break;

          default:
            // 处理其他方法
            result = await handleCustomMethod(method, params);
        }

        // 发送成功响应
        controller.runJavaScript('''
          window.postMessage('${jsonEncode({
            'callbackId': callbackId,
            'data': result
          })}', '*');
        ''');
      } catch (e) {
        // 发送错误响应
        controller.runJavaScript('''
          window.postMessage('${jsonEncode({
            'callbackId': callbackId,
            'error': e.toString()
          })}', '*');
        ''');
      }
    },
  )
  ..loadRequest(Uri.parse('your_web_page_url'));

消息格式

发送到 Flutter 的消息格式

{
  method: string;      // 方法名
  params?: any;        // 参数
  callbackId: string;  // 回调ID
}

Flutter 返回的消息格式

{
  callbackId: string;  // 回调ID
  data?: any;         // 响应数据
  error?: string;     // 错误信息
}

通信流程

1. 网页端调用方法：

   const result = await bridge.methodName(params);

2. 消息发送到 Flutter：

   window.YSBridge.postMessage(
     JSON.stringify({
       method: "methodName",
       params: params,
       callbackId: "unique_id",
     })
   );

3. Flutter 处理消息并返回结果：

   // 在 WebViewJavascriptChannel 的 onMessageReceived 中处理
   // 处理完成后通过 window.postMessage 返回结果

4. 网页端接收结果：

   // 通过 window.addEventListener('message') 接收结果
   // 根据 callbackId 找到对应的 Promise 并 resolve/reject

特点

1. 完全动态的方法调用

   • 不需要预定义方法
   • 可以直接调用任何原生方法
   • 支持 Promise 异步调用

2. 简单的使用方式

   const result = await bridge.anyMethodName(params);

3. 灵活的消息处理

   • 消息格式简单
   • 支持任意类型的数据
   • 统一的错误处理

4. 无需更新

   • 当 app 端添加新的方法时，网页端可以直接调用
   • 不需要更新 npm 包