# web_tools

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

## 功能特性

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

## 安装

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

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

然后运行：

```bash
flutter pub get
```

## 快速开始

### 基本使用

```dart
import 'package:web_tools/web_tools.dart';

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

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

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

现在 `FlutterBridge.instance.on` 支持注册多个监听器，并且 `on` 方法会返回一个 `VoidCallback` 函数，调用该函数可以精确取消本次注册的监听。此外，新增了 `once` 方法用于一次性监听。

```dart
// 注册监听器 (一对多)
// on 方法返回一个用于取消当前监听的函数
final cancelTranslationListener = FlutterBridge.instance.on(
  FromFlutterAppEnum.translateResult.code,
  (data) {
    print("收到翻译结果: ${data['data']}");
    // 处理翻译结果
  },
);
// 当不再需要某个监听时，调用其返回的函数来精确取消
cancelTranslationListener.call();; 
// 注册另一个监听器
final anotherListener = FlutterBridge.instance.on(
  FromFlutterAppEnum.translateResult.code,
  (data) {
    print("另一个监听器收到翻译结果: ${data['data']}");
  },
);
// 当不再需要某个监听时，调用其返回的函数来精确取消
cancelTranslationListener.call();; 

// 仅监听一次 (一次性监听，不用手动取消，调用一次后自动取消)
FlutterBridge.instance.once(
  FromFlutterAppEnum.shareFinished.code,
  (data) {
    print("分享完成 (一次性监听): $data");
  },
);

// 如果需要移除某个类型的所有监听器，可以使用 off 方法
// 警告：这将移除 FromFlutterAppEnum.translateResult.code 对应的所有监听器
FlutterBridge.instance.off(FromFlutterAppEnum.translateResult.code);
```

## API 文档

### FlutterBridge 类

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

#### 获取实例

```dart
final bridge = FlutterBridge.instance;
```

#### 消息监听方法

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

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

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

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

```dart
// 注册第一个监听器
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
```

##### `off(String type)`

##### `once(String type, Function(Map<String, dynamic>) callback)`

注册一个【一次性】消息监听器。该监听器在收到消息后会自动移除。

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

```dart
bridge.once(FromFlutterAppEnum.shareFinished.code, (data) {
  print("收到分享完成事件: $data");
  // 处理一次性逻辑
});
```

##### `off(String type)`

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

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

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

#### 发送消息方法

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

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

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

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

#### 封装的常用方法

##### 页面操作

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

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

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

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

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

##### 游戏相关

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

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

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

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

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

##### 支付相关

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

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

##### 分享功能

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

##### 翻译功能

```dart
bridge.translateRequest({
  'text': 'Hello',
  'from': 'en',
  'to': 'zh',
});
```

##### 直播间相关

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

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

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

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

##### 任务系统

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

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

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

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

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

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

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

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

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

##### 其他功能

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

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

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

### 枚举类型

#### ToFlutterAppEnum

H5 向 Flutter 发送的消息类型枚举。包含所有可用的消息类型，如：
- `close`: 关闭页面
- `gameExit`: 退出游戏
- `createGame`: 创建游戏
- `toRecharge`: 跳转充值
- `share`: 分享
- 等等...

#### FromFlutterAppEnum

Flutter 向 H5 发送的消息类型枚举。包含：
- `translateResult`: 翻译结果
- `redDiamondRecharge`: 钻石充值结果
- `shareFinished`: 分享完成

## 使用示例

### 完整示例：翻译功能

```dart
import 'package:web_tools/web_tools.dart';

void setupTranslation() {
  final bridge = FlutterBridge.instance;
  
  // 注册翻译结果监听器（once不用手动清理，内部自动清理监听）
  bridge.once(FromFlutterAppEnum.translateResult.code, (data) {
    final translatedText = data['data']['text'];
    print('翻译结果: $translatedText');
    // 更新 UI 显示翻译结果
  });
  
  // 发送翻译请求
  bridge.translateRequest({
    'text': 'Hello World',
    'from': 'en',
    'to': 'zh',
  });
}

```

### 完整示例：分享功能

```dart
import 'package:web_tools/web_tools.dart';

void setupShare() {
  final bridge = FlutterBridge.instance;
  
  // 注册分享完成监听器
  bridge.on(FromFlutterAppEnum.shareFinished.code, (data) {
    print('分享完成');
    // 处理分享完成后的逻辑
  });
  
  // 触发分享
  bridge.share(
    activityId: 'activity_123',
    needShareReport: true,
    extraParams: {'source': 'web'},
  );
}
```

## 注意事项

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

2. **监听器管理**：使用 `on()` 注册的监听器在使用完毕后应该使用`_listener1.call()` 取消注册，避免内存泄漏, `off()` 这将移除对应type的所有监听器。`once()`方法不用手动取消监听，内部自动清理监听。

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](LICENSE) 文件了解详情。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

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