2e93f8c282
- 配置驱动的 WebView App 壳 (Kotlin) - auto_package.py 一键打包脚本（改 URL/名称/图标/包名） - 完整 WebView 功能：JS/DOM存储/定位/下拉刷新/进度条 - JS↔Native 桥接 (Toast/分享/剪贴板) - 自适应图标 + 多分辨率图标支持 - Gradle 8.10 + AGP 8.7.3 + Kotlin 2.1.0
211 lines
6.0 KiB
Markdown
211 lines
6.0 KiB
Markdown
# 📱 EasyAppShell
|
||
|
||
**一个极简的配置化 Android WebView 壳项目。**
|
||
|
||
把你任何移动端 Web 项目打包成一个真正的 Android App —— 改改 URL、换个图标、改个名字，重新编译就是一个全新的 App。
|
||
|
||
---
|
||
|
||
## ✨ 特性
|
||
|
||
- **纯 WebView 壳** — 体积小、速度快，只有一个 Activity
|
||
- **配置驱动** — 所有设置都在 `config.json` 里，改配置 = 改 App
|
||
- **一键打包** — `auto_package.py` + 改 URL、改名字、换图标一步到位
|
||
- **JS↔Native 桥接** — 前端可以调 Toast、分享、剪贴板等原生能力
|
||
- **完整 WebView 功能** — JavaScript、DOM 存储、定位、下拉刷新、进度条
|
||
- **自适应图标** — 支持 Android 8+ 自适应图标
|
||
- **安全配置** — 默认仅 HTTPS，支持白名单/黑名单
|
||
|
||
---
|
||
|
||
## 🚀 一分钟快速开始
|
||
|
||
### 前置条件
|
||
|
||
| 工具 | 说明 |
|
||
|------|------|
|
||
| **Java 17+** | JDK，用于编译 Android 代码 |
|
||
| **Android SDK** | 编译 Android App 所需 |
|
||
| **Python 3.6+** | 运行自动打包脚本 |
|
||
| **Pillow** (可选) | `pip install Pillow`，用于自动处理图标 |
|
||
|
||
设置 Android SDK 环境变量（根据你安装的路径）:
|
||
|
||
```bash
|
||
# Windows
|
||
set ANDROID_HOME=C:\Users\你的用户名\AppData\Local\Android\Sdk
|
||
|
||
# macOS / Linux
|
||
export ANDROID_HOME=~/Library/Android/sdk
|
||
```
|
||
|
||
> **没有 Android SDK？** 安装 [Android Studio](https://developer.android.com/studio)，打开 SDK Manager 安装 SDK 35。
|
||
|
||
### 打包你的第一个 App
|
||
|
||
```bash
|
||
# 1. 进入项目目录
|
||
cd EasyAppShell
|
||
|
||
# 2. 一键打包（改 URL + 名称 + 图标）
|
||
python auto_package.py \
|
||
--url https://你的网站.com \
|
||
--name "我的第一个 App" \
|
||
--icon /path/to/icon.png
|
||
|
||
# 3. 在 dist/ 目录下找到 APK，安装到手机！
|
||
```
|
||
|
||
### 仅改配置不构建
|
||
|
||
```bash
|
||
python auto_package.py --url https://你的网站.com --name "测试版" --no-build
|
||
# 然后手动:
|
||
./gradlew assembleDebug
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 完整参数说明
|
||
|
||
### `auto_package.py`
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--url` | ✅ | WebView 加载的主 URL |
|
||
| `--name` | ✅ | App 显示名称 |
|
||
| `--icon` | ❌ | 图标文件路径 (PNG/JPEG, 建议 1024×1024) |
|
||
| `--package` | ❌ | Android 包名 (默认: `com.easyappshell.{name}`) |
|
||
| `--output` | ❌ | APK 输出目录 (默认: `dist/`) |
|
||
| `--http` | ❌ | 允许 HTTP 混合内容 |
|
||
| `--portrait` | ❌ | 锁定竖屏 |
|
||
| `--landscape` | ❌ | 锁定横屏 |
|
||
| `--version` | ❌ | App 版本号 (默认: `1.0.0`) |
|
||
| `--build` | ❌ | Build 编号 (默认: 1) |
|
||
| `--release` | ❌ | 构建 Release 版（需要签名） |
|
||
| `--keystore` | ❌ | Keystore 文件路径 |
|
||
| `--keystore-pass` | ❌ | Keystore 密码 |
|
||
| `--key-alias` | ❌ | Key 别名 |
|
||
| `--key-pass` | ❌ | Key 密码 |
|
||
| `--no-build` | ❌ | 只生成配置文件，不构建 |
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
# 最简用法
|
||
python auto_package.py --url https://mytool.com --name "我的工具"
|
||
|
||
# 带自定义图标、锁定竖屏
|
||
python auto_package.py --url https://shop.com --name "商城" \
|
||
--icon ~/icons/shop.png --portrait
|
||
|
||
# Release 构建（需签名）
|
||
python auto_package.py --url https://app.com --name "正式版" \
|
||
--release --keystore release.keystore --keystore-pass 123456 --key-alias mykey
|
||
|
||
# 多个 App 共存（不同包名）
|
||
python auto_package.py --url https://app1.com --name "应用一" --package com.example.app1
|
||
python auto_package.py --url https://app2.com --name "应用二" --package com.example.app2
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ 手动配置（config.json）
|
||
|
||
你也可以直接编辑 `app/src/main/assets/config.json` 来精细调控：
|
||
|
||
```json
|
||
{
|
||
"app_name": "EasyAppShell",
|
||
"main_url": "https://example.com",
|
||
"enable_js": true,
|
||
"enable_dom_storage": true,
|
||
"status_bar_color": "#2196F3",
|
||
"enable_swipe_refresh": true,
|
||
"orientation": "unspecified",
|
||
"allowed_origin_whitelist": ["*"],
|
||
"blocked_hosts": [],
|
||
"extra_http_headers": {}
|
||
}
|
||
```
|
||
|
||
全部配置项说明见文件内的注释。
|
||
|
||
---
|
||
|
||
## 🌐 JS → Native 桥接
|
||
|
||
前端页面可以通过 `window.NativeBridge` 调用原生功能：
|
||
|
||
```javascript
|
||
// 弹出 Toast
|
||
window.NativeBridge.showToast("操作成功");
|
||
|
||
// 分享链接
|
||
window.NativeBridge.shareUrl("标题", "https://example.com");
|
||
|
||
// 复制到剪贴板
|
||
window.NativeBridge.copyToClipboard("要复制的内容");
|
||
|
||
// 获取 App 版本
|
||
var version = window.NativeBridge.getAppVersion();
|
||
```
|
||
|
||
此功能可在 config.json 中关闭：`"allow_javascript_interface": false`
|
||
|
||
---
|
||
|
||
## 🏗 项目结构
|
||
|
||
```
|
||
EasyAppShell/
|
||
├── auto_package.py # ★ 一键打包脚本
|
||
├── app/
|
||
│ ├── build.gradle.kts # App 构建配置
|
||
│ └── src/main/
|
||
│ ├── assets/
|
||
│ │ ├── config.json # ★ 核心配置文件
|
||
│ │ └── error.html # 网络错误页
|
||
│ ├── java/.../
|
||
│ │ ├── MainActivity.kt # 主 Activity
|
||
│ │ ├── WebAppConfig.kt # 配置解析
|
||
│ │ └── NativeBridge.kt # JS↔Native 桥接
|
||
│ ├── res/ # 资源文件
|
||
│ └── AndroidManifest.xml # 清单文件
|
||
├── build.gradle.kts # 顶层构建
|
||
├── settings.gradle.kts
|
||
└── gradlew / gradlew.bat # Gradle Wrapper
|
||
```
|
||
|
||
---
|
||
|
||
## ❓ 常见问题
|
||
|
||
**Q: 打包出来的 APK 有多大？**
|
||
A: Debug 版约 3-5MB，Release 版约 2-3MB（经过 ProGuard 压缩）。
|
||
|
||
**Q: 如何生成 Release 签名？**
|
||
A: 使用 Android Studio 或 `keytool` 生成 keystore：
|
||
```bash
|
||
keytool -genkey -v -keystore my-release-key.keystore \
|
||
-alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000
|
||
```
|
||
|
||
**Q: 可以支持多个页面/导航吗？**
|
||
A: 这是个 WebView 壳，路由交给你的 Web 项目处理。WebView 支持返回键后退。
|
||
|
||
**Q: 为什么安装后 App 名称还是 EasyAppShell？**
|
||
A: 你可能遗漏了 `--name` 参数，或需要重新运行打包脚本。
|
||
|
||
**Q: 我修改了 config.json 但构建后没生效？**
|
||
A: 检查 `assets/config.json` 的路径是否正确，然后 clean 再构建：
|
||
```bash
|
||
./gradlew clean assembleDebug
|
||
```
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT
|