115 lines
4.2 KiB
Markdown
115 lines
4.2 KiB
Markdown
# web_android_shell
|
||
|
||
Android 平板专用 H5 壳应用 — Monorepo 多品牌架构。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
web_android_shell/
|
||
├── apps/ # 品牌应用（每个品牌一个 Flutter App）
|
||
│ └── quanxue/ # 全学通
|
||
├── packages/
|
||
│ ├── web_shell_core/ # 核心库（WebView 引擎 + Bridge + 服务）
|
||
│ └── web_android_shell/ # 旧版入口（已迁移至 apps/quanxue）
|
||
├── flavors/ # 品牌配置 + 品牌资源
|
||
│ ├── quanxue.yaml # 品牌配置
|
||
│ └── quanxue/ # 品牌资源（图标、启动页）
|
||
│ ├── icon.png
|
||
│ ├── icon_foreground.png
|
||
│ └── splash.png
|
||
├── tool/
|
||
│ ├── generate_app.dart # 一键生成新品牌应用
|
||
│ └── flutter_run_fresh.ps1 # Windows 调试脚本（自动杀旧进程）
|
||
└── doc/ # 项目文档
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 运行已有品牌
|
||
|
||
```bash
|
||
cd apps/quanxue
|
||
flutter run
|
||
```
|
||
|
||
### 2. 生成新品牌
|
||
|
||
```bash
|
||
# 1) 在 flavors/ 下创建品牌配置
|
||
cp flavors/quanxue.yaml flavors/新品牌.yaml
|
||
# 2) 修改配置中的 app_name, application_id, app_key, theme, branding
|
||
# 3) 准备品牌资源（参见下方规格要求）
|
||
mkdir flavors/新品牌
|
||
cp 你的图标.png flavors/新品牌/icon.png
|
||
cp 你的前景图.png flavors/新品牌/icon_foreground.png
|
||
cp 你的启动图.png flavors/新品牌/splash.png
|
||
# 4) 运行生成脚本
|
||
dart run tool/generate_app.dart 新品牌
|
||
```
|
||
|
||
生成脚本会自动完成：
|
||
- 创建 Flutter 应用 → `apps/新品牌/`
|
||
- 添加 `web_shell_core` 依赖
|
||
- 覆写 `MainActivity` 继承 `CoreShellActivity`
|
||
- 更新 `AndroidManifest.xml` 应用名
|
||
- 生成品牌入口 `main.dart`
|
||
- 复制品牌资源到生成目录
|
||
- 添加 `flutter_launcher_icons` / `flutter_native_splash` 依赖
|
||
- 自动生成应用图标和启动页
|
||
|
||
### 3. 品牌配置格式
|
||
|
||
```yaml
|
||
app_name: "全学通" # 应用名
|
||
application_id: "com.wanmake.quanxue" # 包名
|
||
app_key: "quanxue_prod" # 业务标识
|
||
theme:
|
||
accent_color: "0xFF3ED37B" # 主题色
|
||
bg_color: "0xFFFFFFFF" # 背景色
|
||
text_color: "0xFF1F2937" # 主文字色
|
||
muted_text_color: "0xFF6B7280" # 次要文字色
|
||
branding:
|
||
icon: "icon.png" # 应用图标（相对于 flavors/<品牌>/）
|
||
icon_background: "#FFFFFF" # 自适应图标背景色
|
||
icon_foreground: "icon_foreground.png" # 自适应图标前景
|
||
splash: "splash.png" # 启动页图片
|
||
splash_color: "#FFFFFF" # 启动页背景色
|
||
```
|
||
|
||
### 4. 品牌资源规格
|
||
|
||
| 资源 | 文件名 | 最小尺寸 | 格式 | 说明 |
|
||
|---|---|---|---|---|
|
||
| 应用图标 | `icon.png` | 1024×1024 | PNG | 正方形，用于生成各尺寸 launcher icon |
|
||
| 自适应图标前景 | `icon_foreground.png` | 1024×1024 | PNG (透明背景) | 主体内容需居中，四周留 **25% 安全区** |
|
||
| 启动页图片 | `splash.png` | 1152×1152 | PNG | 用于生成 Android 12+ 和旧版启动页 |
|
||
|
||
> **提示：** 资源文件放置在 `flavors/<品牌名>/` 目录下，`branding` 中的路径相对于此目录。如果省略 `branding` 段，脚本会跳过图标和启动页生成。
|
||
|
||
## 调试说明
|
||
|
||
部分教育平板设备使用 `Ctrl+C` 结束 `flutter run` 后，旧进程可能留在后台影响 WebView 启动。
|
||
|
||
**推荐做法：**
|
||
- 调试结束时在 `flutter run` 控制台按 `q` 退出
|
||
- 或使用调试脚本自动杀旧进程再启动：
|
||
|
||
```powershell
|
||
.\tool\flutter_run_fresh.ps1 # 自动选设备
|
||
.\tool\flutter_run_fresh.ps1 -d F136A # 指定设备
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|---|---|
|
||
| 框架 | Flutter 3.x (Dart 3.11+) |
|
||
| WebView | `webview_flutter` + `webview_flutter_android` |
|
||
| 宿主能力 | `image_picker` · `file_picker` · `permission_handler` · `url_launcher` |
|
||
| 原生层 | Kotlin Plugin + Java `CoreShellActivity` |
|
||
| 代码规范 | `very_good_analysis` |
|
||
|
||
## 平台约束
|
||
|
||
**仅支持 Android 平板。** iOS / Web / Desktop 平台已移除。
|