web_tools

一个用于 Flutter Web 应用与原生应用之间双向通信的桥接工具包。该包提供了完整的消息传递机制，支持 H5 页面与 Flutter 原生应用之间的无缝交互。

功能特性

• 🔄 双向通信：支持 H5 向 Flutter 发送消息，以及 Flutter 向 H5 发送消息
• 📡 事件监听：基于类型的事件监听机制，支持注册和注销监听器
• 🎮 游戏交互：封装了游戏相关的常用交互方法（创建游戏、游戏结束等）
• 💰 支付功能：支持充值、钻石充值、月卡支付等支付相关操作
• 📱 页面跳转：支持跳转到 H5 页面、首页、申请页面等
• 🎯 任务系统：支持直播间任务、聊天室任务等多种任务类型
• 🌐 多语言支持：内置翻译请求功能，支持多语言文本翻译
• 📤 分享功能：支持分享到各个平台，并监听分享完成事件

安装

在 pubspec.yaml 文件中添加依赖：

dependencies:
  web_tools:
    git:
      url: https://gitea.sdws.shop/xim/web_tools.git
#      ref: main  # 指定分支
      tag: 0.0.1  # 指定版本

然后运行：

flutter pub get

快速开始

基本使用

import 'package:web_tools/web_tools.dart';

// 获取 FlutterBridge 单例实例
final bridge = FlutterBridge.instance;

// 发送消息给 Flutter 应用
bridge.close(); // 关闭当前页面
bridge.toRecharge(); // 跳转到充值页面
bridge.share(
  activityId: 'activity_123',
  needShareReport: true,
);

API 文档

FlutterBridge 类

FlutterBridge 是一个单例类，提供了与 Flutter 原生应用通信的所有方法。

获取实例

final bridge = FlutterBridge.instance;

监听来自 Flutter 的消息 (支持一对多监听)

不走队列。这是“广播”模式

on(String type, Function(Map<String, dynamic>) callback)

注册一个消息监听器。现在支持为同一 type 注册多个监听器。

• type: 消息类型（使用 FromFlutterAppEnum 中的 code）
• callback: 回调函数，接收消息数据

返回 VoidCallback: 调用此函数可以精确地移除当前注册的这个监听器。

// 注册第一个监听器
final cancelListener1 = bridge.on(FromFlutterAppEnum.translateResult.code, (data) {
  print("监听器1收到翻译结果: ${data['data']}");
});

// 注册第二个监听器
final cancelListener2 = bridge.on(FromFlutterAppEnum.translateResult.code, (data) {
  print("监听器2收到翻译结果: ${data['data']}");
});

// 当不再需要第一个监听器时，调用其返回的函数
cancelListener1.call();// 仅移除监听器1
// 当不再需要第二个监听器时，调用其返回的函数
cancelListener2.call();// 仅移除监听器2

off(String type)

取消注册某个 type 的【所有】消息监听器。此方法主要用于需要一次性清空所有同类型监听的场景。

• type: 要取消监听的【所有】消息类型

// 警告：这将移除 FromFlutterAppEnum.translateResult.code 对应的所有监听器
bridge.off(FromFlutterAppEnum.translateResult.code);

发送消息方法

sendToFlutter(String type, Map<String, dynamic> data)

通用方法，向 Flutter 发送消息。

• type: 消息类型（使用 ToFlutterAppEnum 中的 code）
• data: 消息数据

bridge.sendToFlutter(ToFlutterAppEnum.close.code, {});

封装的常用方法

页面操作

// 关闭当前页面
bridge.close();

// 跳转到 H5 页面
bridge.jumpToH5('/path/to/page', '页面标题');

// 跳转到首页
bridge.toHomepage('userId');

// 跳转到充值页面
bridge.toRecharge();

// 跳转到红钻充值页面
bridge.toRedDiamond();

游戏相关

// 创建游戏
bridge.createGame('gameId');

// 想要玩游戏
bridge.wantToPlay('gameId');

// 游戏结束
bridge.gameOver();

// 检查游戏状态
bridge.checkGameState('gameCode');

// 退出游戏
bridge.gameExit();

支付相关

// 月卡支付
bridge.toMonthCardPay(
  'googleProductId',
  'iosProductId',
  otherUserId: 'optionalUserId',
);

// 定向充值
bridge.rechargeItem('itemId');

分享功能

bridge.share(
  activityId: 'activity_123',
  needShareReport: true,
  extraParams: {'key': 'value'},
);

翻译功能（发送翻译消息+监听返回结果）

只有当你调用 sendRequest 方法时，才会走队列

bridge.sendRequest(
  sendType: ToFlutterAppEnum.translateRequest,    // 1. 发送类型
  listenType: FromFlutterAppEnum.translateResult, // 2. 监听类型
  params: {
            'text00001': 'text00001',
            'text00002': 'text00002',
            'text00003': 'text00003',
          }, // 3. 参数
  onSuccess: (data) {
    // 4. 成功回调 (自动排队，安全)
    print("翻译结果: $data");
  },
);

直播间相关

// 检查开播状态
bridge.checkStartBroadcaster();

// 直播间发言任务
bridge.taskLiveRoomChat();

// 直播间送礼任务
bridge.taskLiveRoomGift();

// 直播间其他任务
bridge.taskLiveRoomOther();

任务系统

// 完善个人信息
bridge.shouldCompleteProfile();

// 观看时长任务
bridge.shouldWatchDuration();

// 发送公屏消息任务
bridge.shouldSendPublicMessage();

// 上麦互动任务
bridge.shouldMicInteraction();

// 发送私信任务
bridge.shouldSendPrivateMessage();

// 发布动态任务
bridge.shouldPostFeed();

// 分享房间任务
bridge.shouldShareRoom();

// 佩戴装扮任务
bridge.shouldWearDecoration();

// 前往语音房任务
bridge.shouldGoToVoiceRoom();

其他功能

// 跳转到申请页面
bridge.toApplyAdmissionPage();

// 显示直播预约选择器
bridge.shouLiveBookingPicker();

// 通用交互
bridge.commonInteraction('interactionType', targetId: 'targetId');

枚举类型

ToFlutterAppEnum

H5 向 Flutter 发送的消息类型枚举。包含所有可用的消息类型，如：

• close: 关闭页面
• gameExit: 退出游戏
• createGame: 创建游戏
• toRecharge: 跳转充值
• share: 分享
• 等等...

FromFlutterAppEnum

Flutter 向 H5 发送的消息类型枚举。包含：

• translateResult: 翻译结果
• redDiamondRecharge: 钻石充值结果
• shareFinished: 分享完成

使用示例

完整示例：翻译功能

import 'package:web_tools/web_tools.dart';

//需要翻译的map
var textMap = <String, String>{};

void setupTranslation() {
    // 使用 sendRequest (发送请求并队列监听回调，内部自动释放监听回调)，该方法只监听一次，
    // 如果需要多次监听，请使用 FlutterBridge.instance.on，并且手动释放监听回调
    FlutterBridge.instance.sendRequest(
      sendType: ToFlutterAppEnum.translateRequest,    // 1. 发送类型
      listenType: FromFlutterAppEnum.translateResult, // 2. 监听类型
      params: textMap, // 3. 参数
      onSuccess: (data) {
        // 4. 成功回调 (自动排队，安全)
        print("翻译结果: $data");
        
        final Map<String, String> result =
            data.map((key, value) => MapEntry(key, value.toString()));

        textMap.clear();// 清空临时变量
        FlutterBridge.instance.textMap.addAll(translated);//全局变量追加翻译结果
        update(['your_id']);
      },
    );
  }

完整示例：分享功能

import 'package:web_tools/web_tools.dart';

class SantaLogic extends GetxController {
  
  // 1. 定义一个变量来持有取消函数
  VoidCallback? _cancelShareListener;

  @override
  void onReady() {
    super.onReady();
    
    // 2. 注册监听（需要监听分享回调时）
    // on 方法现在会返回一个取消函数，专门用来取消“这一个”监听
    _cancelShareListener = FlutterBridge.instance.on(
      FromFlutterAppEnum.shareFinished.code, 
      (data) {
        print("SantaLogic: 收到分享成功的广播");
        // 执行业务，比如刷新任务列表
        requestTaskInfo(); 
      }
    );
    // 1. 触发分享(有些分享不需要监听，只需要触发分享)
    FlutterBridge.instance.share(
      activityId: 'activity_123',
      needShareReport: true,
      extraParams: {'source': 'web'},
    );    
  }

  @override
  void onClose() {
    // 3. ⚠️⚠️⚠️ 如果注册了监听，必须在页面销毁时调用取消函数
    // 如果不调用，SantaLogic 即使退出了，这个闭包还在 Bridge 里，
    // 下次分享成功时，代码还会跑，且 SantaLogic 无法被垃圾回收！
    _cancelShareListener?.call();
    
    super.onClose();
  }
}

注意事项

1. 单例模式：FlutterBridge 使用单例模式，在整个应用中只有一个实例。

2. 监听器管理：使用 on() 注册的监听器在使用完毕后必须使用_listener1.call() 取消注册，避免内存泄漏, off() 慎用，这将移除对应type的所有监听器。sendRequest()方法是融合了发送消息+监听回调，不用手动取消监听，内部自动清理监听。并且只监听一次，防止多次回调。

3. 消息格式：所有消息都遵循 {'type': '消息类型', 'data': {...}} 的格式。

4. 平台限制：此包仅适用于 Flutter Web 平台，因为它使用了 dart:html。

5. JS 互操作：需要确保原生应用提供了 sendMessageToNative JavaScript 函数。

开发环境要求

• Dart SDK: ^3.5.3
• Flutter: >=1.17.0

依赖项

• flutter: Flutter SDK
• js: ^0.6.3 (用于 JavaScript 互操作)

许可证

查看 LICENSE 文件了解详情。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

项目主页: https://gitea.sdws.shop/xim/web_tools.git