# android｜ios-webview-page **Repository Path**: jpw_code/android-ios-webview-page ## Basic Information - **Project Name**: android｜ios-webview-page - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-10 - **Last Updated**: 2026-09-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # WebView 混合应用框架（Android + iOS + H5 桥接） 一套可直接用于生产的 **WebView 混合应用骨架**：原生壳负责设备能力与系统集成， 业务全部用 H5 写；两端桥接 API **同名同义**，同一套前端代码两端通用。 本仓库同时是**框架模板**：新应用从 `master` 开一条 `app/<名称>` 分支即可开发， 框架的新能力与修复可以合并进应用分支，应用里做出来的通用能力也能回流框架。 详见 [docs/BRANCH-WORKFLOW.md](docs/BRANCH-WORKFLOW.md)。 --- ## 能力总览（四个桥） | 桥对象 | 方法数 | 覆盖能力 | 文档 | | --- | --- | --- | --- | | `window.nativeJS` | 28 | 提示音、震动、通知、**每日定时提醒**、**文本朗读(TTS)**、**系统栏/安全区**、音量、屏幕常亮/休眠、心跳保活、系统信息、页面/浏览器跳转、下载、拉起三方 App、退出 | [JSBridge 指南](docs/android/JSBRIDGE-GUIDE.md) | | `window.nativeHardware` | 25 | 蓝牙（开关/配对/扫描）、传感器（加速度/陀螺/磁场/光线/距离/气压）、平衡仪、屏幕旋转锁定、手电筒、电池、网络类型、屏幕亮度 | 同上 §10 | | `window.nativeNfc` | 9 | 读 UID / NDEF、主动会话与被动监听、错误事件、连续读 | [NFC 方案](docs/NFC-BRIDGE.md) | | `window.nativeWidget` | 9 | 桌面卡片数据推送、一键添加到桌面、点击深链路由 | [桌面卡片方案](docs/WIDGET-CARD.md) | 前端配套 SDK 位于 [`sdk/`](sdk/)：`native-bridge.js`（UMD）/ `native-bridge.ts` / `native-bridge.d.ts`， 内置**浏览器降级**（不在 App 内时所有方法安全返回 `false`/`null`，页面照常运行）。 --- ## 目录结构 ``` sdk/ H5 桥接 SDK（JavaScript / TypeScript / 类型声明 + 冒烟测试） assets/ App 图标母版 app-logo.svg + 两端图标派生脚本 tools/ 分支工作流护栏、卡片布局检查 docs/ 框架文档（JSBridge / HTTP 桥 / 原生存储与更新 / NFC / 桌面卡片 / 每日提醒 / 朗读 / 页面切换与后退问答 / iOS 侧滑返回 / 分支工作流） demos/ 两个演示前端（纯 HTML、Vue3+Vite），演示全部桥能力与业务流程 native-android/ Android 壳（Java）：WebView 容器 + 四个桥 + 桌面卡片 + 启动页 native-ios/ iOS 壳（Swift/ObjC）：WKWebView 容器 + 四个桥 + WidgetKit 扩展 ├─ Sources/ 容器、四个桥、Info.plist（由 project.yml 生成） ├─ Widget/ WidgetKit 桌面卡片扩展 └─ project.yml XcodeGen 工程定义（含项目配置区与 scheme 声明） ``` **应用分支只改**：`app-web/`（前端工程）、两端资源目录里的业务页面、带 `[项目配置]` 标记的行、 `assets/app-logo.svg`、`docs/project/`、约定的项目扩展目录。 **新建应用先设应用标识**：`tools/branch.sh new-app <名称>` 会自动设成 `com.panvu.<名称>` （含 iOS 卡片 Bundle ID、URL scheme、App Group，共 6 处），避免同一框架下的多个应用互相覆盖； 校验用 `python3 tools/set-app-id.py --check`。详见 [docs/BRANCH-WORKFLOW.md](docs/BRANCH-WORKFLOW.md) §3.1。 完整清单与判定规则见 [docs/BRANCH-WORKFLOW.md](docs/BRANCH-WORKFLOW.md) §3。 --- ## 快速开始 **环境**：JDK 17、Android SDK（compileSdk 34）、Xcode 26 + [XcodeGen](https://github.com/yonaskolb/XcodeGen)、Node 20+、Python 3（Pillow）。 ```bash # Android：编译 debug APK cd native-android && ./gradlew assembleDebug # iOS：由 project.yml 生成工程并编译（Info.plist / scheme 都是生成的，别手改） cd native-ios && xcodegen generate xcodebuild -project WebViewDemo.xcodeproj -scheme WebViewDemo -sdk iphonesimulator build # H5 SDK 自检 node sdk/tests/smoke.js # 换 App 图标：只改母版，两端资源由脚本派生 ./assets/build-icons.sh # 桌面卡片布局检查（RemoteViews 只允许带 @RemoteView 的控件，改布局后务必跑） python3 native-android/tools/check_widget_layout.py ``` 演示前端（含全部桥能力的可点测试入口）： ```bash cd demos/pda-vue3 && npm install && npm run dev # 浏览器直接打开即可（自动降级） ``` --- ## 项目配置区 一套代码要服务多个应用，**项目身份值集中在带 `[项目配置]` 标记的地方**： ```bash grep -rn "\[项目配置\]" native-android native-ios | grep -v Binary ``` | 位置 | 内容 | | --- | --- | | `native-android/app/build.gradle` 顶部【项目配置区】 | 包名、应用名、版本、MAIN_URL、配色、行为开关 | | `native-android/app/src/main/AndroidManifest.xml` | 权限、硬件特性 | | `native-ios/project.yml` | 包名、显示名、版本、URL scheme、App Group（改完需 `xcodegen generate`） | | `native-ios/*.entitlements`、`native-ios/Widget/*.entitlements` | App Group、NFC 能力 | | `assets/app-logo.svg` | 应用图标母版 | --- ## 分支模型（框架模板 + 应用分支） ```bash tools/branch.sh new-app <名称> # 从 master 建 app/<名称> tools/branch.sh status # 查看相对 master 的改动（项目文件 / 框架文件分类） tools/branch.sh pull-framework # 把框架更新合并进当前应用分支 tools/branch.sh check # 判断某提交能否安全回流框架（只动框架文件 + 无项目字样） tools/branch.sh backport # 回流到 master ``` 首次使用建议执行一次：`git config core.hooksPath .githooks`（拦截误推/强推 master）， 并在 Gitee 侧把 `master` 设为保护分支。 --- ## 文档索引 | 文档 | 内容 | | --- | --- | | [docs/android/JSBRIDGE-GUIDE.md](docs/android/JSBRIDGE-GUIDE.md) | 前端调用指南：四个桥的完整方法表、SDK 用法、TypeScript 类型、浏览器降级、常见坑 | | [docs/android/USAGE.md](docs/android/USAGE.md) | Android 壳的使用与定制：构建配置、权限、组件、NFC、桌面卡片、FAQ | | [docs/NFC-BRIDGE.md](docs/NFC-BRIDGE.md) | NFC 方案：场景研究、两端能力边界、接口设计、卡型选型、实现状态 | | [docs/WIDGET-CARD.md](docs/WIDGET-CARD.md) | 桌面卡片方案：为什么卡片不能跑 HTML、数据契约、两端实现与限制、排查手册 | | [docs/DAILY-REMINDER.md](docs/DAILY-REMINDER.md) | 每日定时提醒：接口契约、两端调度实现、为什么用非精确闹钟、降级写法与排查手册 | | [docs/TTS-SPEAK.md](docs/TTS-SPEAK.md) | 文本朗读：为什么 WebView 里 Web Speech API 不可用、两端 TTS 实现、语速映射、事件回调与排查手册 | | [docs/SYSTEM-BAR.md](docs/SYSTEM-BAR.md) | 系统栏与标题栏：HTML 能不能设置系统栏（不能）、沉浸式 + 图标黑白、`getSafeArea()` / `setStatusBarStyle()`、CSS 变量写法 | | [docs/NATIVE-STORE.md](docs/NATIVE-STORE.md) | **原生存储与检查更新**：为什么数据要写一份到原生侧（localStorage 会被清）、`nativeJS.store*` 契约与真机实测、`openAppStore` 与"检查更新"的三级降级策略、对单机免备案判定的影响 | | [docs/HTTP-BRIDGE.md](docs/HTTP-BRIDGE.md) | **HTTP 桥与 axios 风格封装**：为什么内置页面直接 fetch 会踩 CORS/ATS/Cookie、桥接口契约（含两端实现要点）、`http.get/post/create/拦截器/错误形状` 用法、与服务端的配置清单 | | [docs/NAVIGATION-QA.md](docs/NAVIGATION-QA.md) | **页面切换与后退问答手册**：上一页被「刷新」是重挂载还是整页重载、空白帧、滚动丢失、哪些页面该缓存、iOS 侧滑为何整页重载、手势自己怎么实现、诊断工具箱与上线自检清单 | | [docs/ios/SAFE-AREA.md](docs/ios/SAFE-AREA.md) | iOS 安全区与状态栏：为什么内容会滚进状态栏、容器与页面谁留白、沉浸式开关、几何排查入口 | | [docs/ios/DEV-PREVIEW.md](docs/ios/DEV-PREVIEW.md) | iOS 开发预览：直连本机 dev server（环境变量 / 项目配置两种开法、ATS 与本地网络权限、排查表） | | [docs/ios/SWIPE-BACK.md](docs/ios/SWIPE-BACK.md) | iOS 侧滑返回：系统手势为什么会让单页应用整页刷新（pushState 历史项被当成真实导航）、`PanvuWebViewCanBack` 开关、页面侧参考实现与验证方法 | | [docs/IOS-RELEASE.md](docs/IOS-RELEASE.md) | **iOS 上架检查清单**：非公开 API、隐私清单、ATS、出口合规、能力裁剪、审核指南要点与自检命令 | | [docs/BRANCH-WORKFLOW.md](docs/BRANCH-WORKFLOW.md) | 分支模型、创建应用、拉框架更新、回流通用能力、纪律速查 | --- ## 平台差异（务必了解） | 能力 | Android | iOS | | --- | --- | --- | | NFC 读卡触发 | 贴卡即回调（被动监听） | **必须由页面发起**会话（系统弹读卡界面） | | NFC 卡型 | 几乎全部 | 不支持 Mifare Classic（选 NTAG / ICODE） | | 桌面卡片 | `RemoteViews`，布局只能用带 `@RemoteView` 的控件 | WidgetKit（SwiftUI），需 App Group | | 通知前台展示 | 直接弹出并点亮屏幕 | 需 `willPresent`（框架已实现），不能编程点屏 | | 长震动 | 可循环 | CoreHaptics 近似，框架统一为「循环 + 10 秒上限」 | | 额外配置 | 普通权限 | NFC Tag Reading / App Groups 等能力需在开发者后台开启并重签 profile | --- ## 质量保障（可复用脚本） | 脚本 | 作用 | | --- | --- | | `node sdk/tests/smoke.js` | SDK 运行期冒烟（降级、包装、事件接管、卡片） | | `python3 native-android/tools/check_widget_layout.py` | 卡片布局控件白名单 + `R.id` 引用一致性 | | `./assets/build-icons.sh` | 由母版派生两端图标（幂等） | | `tools/branch.sh check ` | 回流前检查（防止项目配置进入框架） | 开发时建议：改动后跑一遍上面的脚本，并确保 `./gradlew assembleDebug` 与 `xcodegen generate && xcodebuild -scheme WebViewDemo` 均通过。