# 📱 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