web_shell_flutter/packages/web_shell_core

web_shell_core

Android 平板专用的 H5 壳核心库。所有品牌应用共享此库，只需传入 ShellEnvironment 即可启动。

功能

模块	说明
WebView 引擎	自动兼容低版本 Android WebView，支持 texture / hybrid 双渲染模式自动切换
启动恢复	看门狗超时检测 → 渲染模式降级 → 深度清理 → 自动重试
JS Bridge	window.AppShell 协议，支持 8 种 Action（pickImage · captureImage · pickFile · openExternal · requestPermissions · reloadPage · goBack · closeApp）
旧相机兼容	Monkey-patch openCamera / captureImage 兼容老 H5 页面
媒体服务	相机拍照 · 图库选图 · 文件选择 · base64 / dataUrl / uri 三种序列化格式
权限服务	camera · microphone · location · photos · videos · storage 统一映射
导航服务	URL scheme 白名单路由，非 WebView 协议自动跳转外部应用
壳层 UI	启动加载动画 · 错误恢复页 · 进度条 · 不支持平台兜底页

使用方式

import 'package:web_shell_core/web_shell_core.dart';

void main() {
  runShellApp(
    ShellEnvironment(
      appName: '全学通',
      appKey: 'quanxue_prod',
      accentColor: Color(0xFF3ED37B),
      backgroundColor: Color(0xFFFFFFFF),
      textColor: Color(0xFF1F2937),
      mutedTextColor: Color(0xFF6B7280),
      initialUrl: 'example.com/login',  // 可选，不传使用默认地址
    ),
  );
}

代码结构

lib/
├── core_app.dart                 # 库入口 + part 指令 + runShellApp()
├── web_shell_core.dart           # 公开 API 导出
└── src/
    ├── config/
    │   ├── shell_environment.dart # 品牌配置数据类
    │   └── url_resolver.dart      # URL 解析与归一化
    ├── engine/
    │   ├── compatibility.dart     # Android WebView 兼容检测
    │   └── recovery.dart          # 启动看门狗 + 错误映射
    ├── bridge/
    │   ├── bridge_protocol.dart   # JS Bridge 注入与响应
    │   ├── bridge_actions.dart    # Action handler（占位）
    │   └── legacy_camera_compat.dart # 旧相机 JS 兼容层
    ├── services/
    │   ├── media_service.dart     # 相机/图库/文件 + 序列化
    │   ├── permission_service.dart # 权限类型映射
    │   └── navigation_service.dart # URL 路由 + 外链跳转
    ├── ui/
    │   ├── shell_app.dart         # MaterialApp 入口
    │   ├── shell_page.dart        # WebView 主页面
    │   ├── launch_overlay.dart    # 启动加载动画
    │   ├── error_overlay.dart     # 错误恢复页
    │   ├── progress_bar.dart      # 顶部进度条
    │   └── unsupported_platform_page.dart # 平台兜底页
    └── testing/
        └── test_hooks.dart        # 测试钩子（@visibleForTesting）

测试

cd packages/web_shell_core
flutter test

当前 67 个测试用例，覆盖：

• 平台检测 · URL 解析 · 兼容性策略 · 错误映射
• Bridge 注入/响应/异常处理 · 媒体序列化 · 权限映射
• 导航路由 · 所有独立 UI 组件

平台约束

仅支持 Android。其他平台会展示兜底提示页。

Android 原生层

CoreShellActivity（Java）提供：

• WebView 数据目录隔离（避免多进程冲突）
• 旧进程自动终止
• WebView 信息查询（SDK 版本、WebView 包名/版本号）
• WebView 状态深度重置