appbridgenewplus 1.0.1

A versatile Flutter plugin for native bridging and web view communication. Features UI, navigation, events, downloads, device info, video playback, and more.

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。