appbridgenewplus

一个功能强大且多用途的 Flutter 插件，旨在打通 Flutter 与 WebView 之间的通信。它提供了一个无缝的通信通道和丰富的 H5 原生模块，使H5页面能够轻松调用 UI、导航、下载、设备信息和多媒体等原生能力。

GitHub 仓库: https://github.com/bingbing01121-art/appbridgenewplus

---

✨ 核心功能 (Features)

• ⚡️ 核心桥接: 通过 window.AppBridge 实现 Dart 与 JavaScript 之间稳健的双向通信。
• 📲 原生 UI 控制: 从 H5 端管理系统 UI、状态栏样式及屏幕旋转方向。
• 🧭 导航管理: 处理原生导航栈，支持打开/关闭页面及重定向管理。
• 📥 下载管理器: 内置文件与 APK 下载器，支持下载进度实时回调。
• 🎥 多媒体支持: 集成视频播放器（支持画中画 PiP）及音频能力。
• 🔐 权限管理: 支持从 Web 端直接请求和检查系统权限（如相机、麦克风等）。
• 📱 设备信息: 获取设备详情、网络状态及电池电量信息。
• 💾 数据存储: 原生与 Web 之间安全的键值对存储同步。

🚀 快速开始 (Getting Started)

1. 安装

在您的 pubspec.yaml 中添加依赖：

dependencies:
  appbridgenewplus: ^1.0.1

2. 平台配置

Android

请确保您的 android/app/src/main/AndroidManifest.xml 包含所需权限（根据您使用的模块按需添加）：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 网络权限 -->
    <uses-permission android:name="android.permission.INTERNET"/>
    
    <!-- 存储与下载 -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

    <!-- 多媒体 -->
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
</manifest>

iOS

在 ios/Runner/Info.plist 中添加以下键值，以描述权限用途（App Store 审核必须）：

<key>NSCameraUsageDescription</key>
<string>我们需要访问相机以支持视频功能。</string>
<key>NSMicrophoneUsageDescription</key>
<string>我们需要访问麦克风以支持录音功能。</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>我们需要访问相册以保存下载的文件。</string>
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
    <string>fetch</string>
</array>

📖 使用指南 (Usage)

初始化

在使用 WebView 之前，请先初始化 Appbridgenew 单例。通常建议在 main.dart 或闪屏页中完成。

import 'package:appbridgenewplus/appbridgenewplus.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Appbridgenew().initialize(
    onNavOpen: (url) {
      print("H5 请求打开页面: $url");
      // 在此处处理导航逻辑
    },
    onAppIcon: (styleId) async {
        // 更换应用图标逻辑
        return BridgeResponse.success(true);
    }
  );
  
  runApp(MyApp());
}

嵌入 WebView

使用 AppBridgeWebView 组件加载您的 H5 页面。它会自动注入桥接脚本。

import 'package:appbridgenewplus/app_bridge_webview.dart';

class WebPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: AppBridgeWebView(
        initialUrl: 'https://your-h5-app.com',
        onWebViewCreated: (controller) {
          // 如果需要，可以在此处获取 WebViewController
        },
      ),
    );
  }
}

监听事件 (Dart 端)

您可以监听由 H5 端触发或内部模块产生的特定事件。

Appbridgenew().on('download.progress', (event) {
  print("下载进度: ${event['payload']['progress']}%");
});

---

🛠 架构与初始化流程

(进阶：供希望了解 SDK 内部原理的开发者参考)

1. Flutter AppBridgeWebView 组件初始化

当 AppBridgeWebView 被创建时：

• SDK 将 assets/app_bridge.js 加载到内存中。
• 注册一个名为 AppBridgeChannel 的 JavaScriptChannel。
• 绑定所有 Dart 模块的处理程序（如 core.getVersion, app.getStatus）。

2. JavaScript 接口注入

页面加载完成后：

• SDK 将 window.AppBridge 对象注入到 WebView 上下文中。
• 该对象为 H5 开发者提供了如 window.AppBridge.core.getVersion() 等方法。

3. 通信流程

1. H5 调用: JS 调用 window.AppBridge.method()。
2. 桥接: 参数和一个唯一的 callId 被序列化为 JSON。
3. 传输: JSON 通过 AppBridgeChannel.postMessage() 发送给 Flutter。
4. Dart 处理: Flutter 执行对应的 Dart 方法。
5. 响应: Flutter 通过 window.AppBridge._handleResponse() 将结果返回给 JS。

Libraries

app_bridge_webview

appbridgenewplus

AppBridgeNew 插件的核心实现。 该文件定义了 AppBridge 类的单例模式，负责管理所有模块（如核心、事件、应用、导航、UI、存储等）， 并处理 Flutter 侧与 H5 页面以及原生功能之间的通信、事件分发和方法路由。 它是整个 AppBridge 体系的入口点和调度中心。

appbridgenewplus_method_channel

该文件提供了 AppbridgenewPlatform 的 MethodChannel 实现。 它负责 Flutter 应用程序与原生平台（Android/iOS）之间的具体通信， 通过方法通道处理 H5 页面发出的功能请求，并接收原生平台的回调事件。

appbridgenewplus_platform_interface

comic_reader_page

event_service

该文件定义了一个应用范围的事件服务 EventService， 采用单例模式设计，主要用于广播和监听应用内的各种事件， 尤其是在此上下文中，它被用于日志记录和通知功能。

payment_info_page

该文件定义了支付信息页面 PaymentInfoPage， 用于展示支付结果的详细信息，包括订单号、商品 ID、支付类型和支付状态。 这是一个简单的 StatelessWidget，旨在接收并显示这些支付相关数据。

webrtc_live/broadcaster_screen

该文件实现了直播主播端的核心功能和 UI BroadcasterScreen。 它负责管理本地视频流（摄像头和麦克风）、与信令服务器进行通信以处理观众连接、 发送和接收 WebRTC SDP Offer/Answer 以及 ICE Candidate。 此外，它还提供了直播前的房间管理（创建房间、设置密码）、直播中的控制（切换摄像头、麦克风静音）、 观众管理（禁言、踢人）以及聊天和礼物动画等丰富的交互功能。

webrtc_live/danmaku_view

该文件实现了直播间弹幕（子弹幕）显示的核心组件。 它包括了弹幕消息的数据模型 DanmakuMessage、 管理和渲染所有弹幕的叠加层 Widget DanmakuOverlay， 以及单个弹幕从屏幕一侧滚动到另一侧的动画逻辑 _DanmakuItem。 弹幕通过泳道管理机制确保不重叠。

webrtc_live/gift_animation_widget

该文件定义了礼物动画 Widget GiftAnimationWidget。 此 Widget 负责在直播或视频播放界面显示用户赠送的礼物动画， 例如显示一个飞行的火箭图标和赠送文本。 它使用 Flutter 的动画系统实现复杂的组合动画效果（移动、渐隐、缩放）， 并在动画完成后通过回调通知父组件进行清理。

webrtc_live/heart_animation_widget

该文件定义了心形动画 Widget HeartAnimationWidget。 此 Widget 负责在直播或视频播放界面显示用户点赞或发送的“心形”效果， 通过组合 Flutter 的动画（缩放、渐隐、滑动）， 呈现一个从屏幕底部指定位置升起并逐渐消失的心形动画。 动画完成后通过回调通知父组件进行清理。

webrtc_live/viewer_page

该文件实现了直播观众端的核心功能和 UI ViewerPage。 它负责与信令服务器建立连接、发现和加入可用的直播房间、 接收主播的音视频流和数据通道消息（如聊天、点赞、礼物）。 此外，它还提供了观众的昵称管理、房间列表显示、密码验证、 弹幕显示、聊天互动以及接收主播的踢人或禁言通知等功能。

webrtc_live/webrtc_config