add readme
This commit is contained in:
zhugy781
parent
66fb0b7157
commit
6bbfa53d07
376
README.md
376
README.md
@ -1,39 +1,355 @@
|
|||||||
<!--
|
# web_tools
|
||||||
This README describes the package. If you publish this package to pub.dev,
|
|
||||||
this README's contents appear on the landing page for your package.
|
|
||||||
|
|
||||||
For information about how to write a good package README, see the guide for
|
一个用于 Flutter Web 应用与原生应用之间双向通信的桥接工具包。该包提供了完整的消息传递机制，支持 H5 页面与 Flutter 原生应用之间的无缝交互。
|
||||||
[writing package pages](https://dart.dev/tools/pub/writing-package-pages).
|
|
||||||
|
|
||||||
For general information about developing packages, see the Dart guide for
|
## 功能特性
|
||||||
[creating packages](https://dart.dev/guides/libraries/create-packages)
|
|
||||||
and the Flutter guide for
|
|
||||||
[developing packages and plugins](https://flutter.dev/to/develop-packages).
|
|
||||||
-->
|
|
||||||
|
|
||||||
TODO: Put a short description of the package here that helps potential users
|
- 🔄 **双向通信**：支持 H5 向 Flutter 发送消息，以及 Flutter 向 H5 发送消息
|
||||||
know whether this package might be useful for them.
|
- 📡 **事件监听**：基于类型的事件监听机制，支持注册和注销监听器
|
||||||
|
- 🎮 **游戏交互**：封装了游戏相关的常用交互方法（创建游戏、游戏结束等）
|
||||||
|
- 💰 **支付功能**：支持充值、钻石充值、月卡支付等支付相关操作
|
||||||
|
- 📱 **页面跳转**：支持跳转到 H5 页面、首页、申请页面等
|
||||||
|
- 🎯 **任务系统**：支持直播间任务、聊天室任务等多种任务类型
|
||||||
|
- 🌐 **多语言支持**：内置翻译请求功能，支持多语言文本翻译
|
||||||
|
- 📤 **分享功能**：支持分享到各个平台，并监听分享完成事件
|
||||||
|
|
||||||
## Features
|
## 安装
|
||||||
|
|
||||||
TODO: List what your package can do. Maybe include images, gifs, or videos.
|
在 `pubspec.yaml` 文件中添加依赖：
|
||||||
|
|
||||||
## Getting started
|
```yaml
|
||||||
|
dependencies:
|
||||||
TODO: List prerequisites and provide or point to information on how to
|
web_tools:
|
||||||
start using the package.
|
git:
|
||||||
|
url: https://gitea.sdws.shop/xim/web_tools.git
|
||||||
## Usage
|
ref: main
|
||||||
|
|
||||||
TODO: Include short and useful examples for package users. Add longer examples
|
|
||||||
to `/example` folder.
|
|
||||||
|
|
||||||
```dart
|
|
||||||
const like = 'sample';
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Additional information
|
然后运行：
|
||||||
|
|
||||||
TODO: Tell users more about the package: where to find more information, how to
|
```bash
|
||||||
contribute to the package, how to file issues, what response they can expect
|
flutter pub get
|
||||||
from the package authors, and more.
|
```
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 基本使用
|
||||||
|
|
||||||
|
```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 的消息
|
||||||
|
|
||||||
|
```dart
|
||||||
|
// 注册监听器
|
||||||
|
FlutterBridge.instance.on(FromFlutterAppEnum.translateResult.code, (data) {
|
||||||
|
print("收到翻译结果: ${data['data']}");
|
||||||
|
// 处理翻译结果
|
||||||
|
});
|
||||||
|
|
||||||
|
// 使用完毕后记得取消监听
|
||||||
|
FlutterBridge.instance.off(FromFlutterAppEnum.translateResult.code);
|
||||||
|
```
|
||||||
|
|
||||||
|
## API 文档
|
||||||
|
|
||||||
|
### FlutterBridge 类
|
||||||
|
|
||||||
|
`FlutterBridge` 是一个单例类，提供了与 Flutter 原生应用通信的所有方法。
|
||||||
|
|
||||||
|
#### 获取实例
|
||||||
|
|
||||||
|
```dart
|
||||||
|
final bridge = FlutterBridge.instance;
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 消息监听方法
|
||||||
|
|
||||||
|
##### `on(String type, Function(Map<String, dynamic>) callback)`
|
||||||
|
|
||||||
|
注册一个消息监听器。
|
||||||
|
|
||||||
|
- `type`: 消息类型（使用 `FromFlutterAppEnum` 中的 code）
|
||||||
|
- `callback`: 回调函数，接收消息数据
|
||||||
|
|
||||||
|
```dart
|
||||||
|
bridge.on(FromFlutterAppEnum.translateResult.code, (data) {
|
||||||
|
// 处理消息
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
##### `off(String type)`
|
||||||
|
|
||||||
|
取消注册消息监听器。
|
||||||
|
|
||||||
|
- `type`: 要取消监听的消息类型
|
||||||
|
|
||||||
|
```dart
|
||||||
|
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;
|
||||||
|
|
||||||
|
// 注册翻译结果监听器
|
||||||
|
bridge.on(FromFlutterAppEnum.translateResult.code, (data) {
|
||||||
|
final translatedText = data['data']['text'];
|
||||||
|
print('翻译结果: $translatedText');
|
||||||
|
// 更新 UI 显示翻译结果
|
||||||
|
});
|
||||||
|
|
||||||
|
// 发送翻译请求
|
||||||
|
bridge.translateRequest({
|
||||||
|
'text': 'Hello World',
|
||||||
|
'from': 'en',
|
||||||
|
'to': 'zh',
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
void cleanup() {
|
||||||
|
// 清理监听器
|
||||||
|
FlutterBridge.instance.off(FromFlutterAppEnum.translateResult.code);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 完整示例：分享功能
|
||||||
|
|
||||||
|
```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()` 注册的监听器在使用完毕后应该使用 `off()` 取消注册，避免内存泄漏。
|
||||||
|
|
||||||
|
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
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user