NW-HTMLviewer：安卓端 HTML 编辑、预览与云同步工作台

NW-HTMLviewer 是一款工业级的移动端 HTML 编辑器与全屏预览应用，采用 Jetpack Compose + Material 3 设计，支持在安卓手机上直接编辑、预览、调试和管理网页项目。它不仅能做“编辑器”，还具备“文件工作台”和“云端协作”能力，已经从早期的单工场景进化成完整的移动端网页开发环境。

1. 项目简介

很多移动端 HTML 编辑器只解决“看代码”和“看效果”两个维度，很难真正支持网页项目协作。NW-HTMLviewer 的定位更接近“手机端网页工作台”：它把编辑器、预览器、文件管理、离线缓存、编码修复、云盘同步和版本更新检测整合在一起，帮助你在安卓设备上直接维护页面文件，也可以把本地页面和云端网盘形成无缝的工作流。

从当前仓库状态看，项目已经进入 v1.2.0 阶段，除了原本的编辑与预览能力，还新增了百度网盘和 WebDAV 接入、双向同步、冲突处理、内置语言切换以及 Material 3 多主题方案，明显更接近一款可持续使用的生产工具。

2. 功能特性

• 代码编辑：内置 CodeMirror 6（离线打包），支持 HTML / CSS / JS 语法高亮、行号、自动缩进、括号匹配、查找替换、撤销/重做、一键格式整理；并配套自动保存与手动保存。
• 实时预览：支持分屏实时预览与沉浸式全屏预览，编辑后可防抖刷新，布局适合边写边看，减少来回切换。
• 浏览器式预览：前进 / 后退 / 刷新、UA 标识切换、JS 开关、沉浸模式、模拟鼠标（触摸板式光标、单击、双指滚动）、控制台与报错 / 警告抽屉，操作体验接近桌面浏览器。
• 控制台增强：完整拦截 console API，支持多参数、%s / %d / %f / %o 格式化、%c 样式着色、对象点击展开，界面也强化了错误级别标签和可读性。
• 双渲染内核：轻量模式使用系统 WebView，兼容模式使用内置 GeckoView 153；两种内核可以按场景切换，兼顾性能和稳定性。
• 离线资源缓存：首次访问 CDN / 网络资源时自动缓存到 HTML 同目录隐藏文件夹，URL 不变时可直接离线使用，也可手动清理缓存。
• 文件管理：支持目录浏览、列表 / 网格视图、实时搜索、最近打开、收藏、多选批量操作、删除 5 秒撤销、内置模板新建，适合保管网页组件、页面和静态资源。
• 导入与兼容：支持通过系统文档选择器导入外部文件或整个文件夹，无需额外存储权限；自动检测 UTF-8 / GBK / UTF-16，GBK 旧文件也能一键转换为 UTF-8。
• 主题与外观：支持跟随系统 / 浅色 / 深色、自定义主题色，Material 3 提供 8 种色调方案（TonalSpot / Neutral / Vibrant / Expressive / Rainbow / FruitSalad / Monochrome / Fidelity）。
• 多语言：支持简体中文与 English，可在设置中即时切换，且可跟随系统语言。
• 云同步：新增百度网盘（官方 xpan API + OAuth2）与 WebDAV（如坚果云、Nextcloud 等）接入，主页可在本地与云端间切换，基于快照实现双向同步，冲突可逐个询问或选择“新者胜 / 保留双方”。
• 应用更新检测：在设置中的“关于”页面可检查更新，自动匹配 Full / Lite 与当前设备 ABI 的下载链接，国内网络环境可直接使用。

3. 技术栈与架构

从工程结构看，NW-HTMLviewer 不是简单的单页编辑器，而是面向移动端的完整应用架构。

• UI 层：Jetpack Compose + Material 3，动态取色与多种配色方案支持。
• 架构层：MVVM + Repository + Hilt 依赖注入。
• 数据层：Room 负责文件元数据、收藏与最近打开记录；DataStore 负责用户设置。
• 编辑器：CodeMirror 6，资源以离线 bundle 方式打包在 app 内。
• 渲染层：WebView / GeckoView 通过统一 Renderer 抽象接口接入。
• 构建体系：Kotlin 2.3.21 / AGP 8.13 / KSP 2.3.11，最小 SDK 26，构建脚本已配置国内镜像。

其架构目录也很清晰：data 层负责文件、设置、模板、更新与云同步；render 层负责内核抽象；ui 层则细分为 home / editor / settings / cloud / about 等模块，整个应用的职责边界比较明确。

4. 快速上手

应用的文件根目录默认位于应用专属目录中，安装后无需额外存储权限即可使用。下面是最常用的操作流程。

4.1 新建、打开与导入文件

在首页文件管理中可以直接新建空白页面或从模板库创建项目，也可以打开现有文件；如果你有外部网页目录，可通过系统文件选择器导入到当前目录，支持文件和文件夹导入，并自动去重同名项。

4.2 编辑与实时预览

在编辑器中输入 HTML / CSS / JS，开启分屏模式后可边写边看，实现“编辑即所见”。如果需要更大的可视区域，可切换全屏预览，隐藏系统栏后页面将更接近桌面浏览器的工作习惯。

4.3 浏览器式调试

预览界面支持前进、后退、刷新，还可以切换 UA 标识、启用/关闭 JS、模拟鼠标点击与滚动、查看控制台输出和错误 / 警告信息。这些能力让它不仅适合“展示网页”，也适合“排查页面的问题”。

4.4 切换渲染内核

在设置中选择渲染内核：轻量模式使用系统 WebView，资源占用低，适合大多数日常页面；兼容模式使用内置 GeckoView 153，适合需要稳定渲染行为的页面。首次切换时需初始化内核，属于正常现象。

4.5 离线缓存与文件管理

首次加载带 CDN 的页面时，应用会把网络资源下载并保存到同目录隐藏缓存文件夹中，之后页面即使在离线状态下也能正常显示。文件管理也支持长按多选、批量删除/移动/复制/分享，误删文件还可在 5 秒内撤销恢复。

4.6 云同步工作流

进入“本地 ⇄ 云端”视图后，你可以接入百度网盘或 WebDAV，并将本地 HTML 文件同步到云端。云端文件打开后可直接缓存，保存时自动回传，系统支持快照式双向同步，冲突时能逐条弹窗确认，配置“新者胜”或“保留双方”策略也更方便处理协同时的版本差异。

5. 构建与发行版

项目使用 Gradle 构建，依赖已走国内镜像，适合在国内环境直接编译。Release 产品按 ABI 拆分，通常只需要安装 arm64-v8a 版本即可覆盖大多数主流安卓设备。

• Full 版：包含 GeckoView 兼容内核，功能完整，适合完整开发体验。
• Lite 版：仅使用系统 WebView，不含 GeckoView，体积明显更小，适合轻量部署。

常用构建命令如下：

./gradlew assembleDebug
./gradlew testDebugUnitTest
./gradlew assembleRelease
./gradlew assembleLiteDebug
./gradlew assembleLiteRelease

从仓库说明看，Full / Lite 发行包都已提供 GitHub Releases，并支持根据设备 ABI 自动下载对应安装包。

6. 已知限制

• 模拟鼠标、控制台收集、离线资源缓存等能力主要依赖系统 WebView；Gecko 内核使用持久磁盘缓存，功能上与 WebView 并不完全对等。
• GeckoView 没有公开的 evaluateJavascript / console / request 拦截 API，因此某些浏览器级扩展能力需要通过 WebExtension 或其他方式补足。
• 文件根目录默认位于应用专属目录（例如 Android/data/<package>/files/HTMLviewer），无需存储权限；外部目录浏览（SAF）尚未完全实现。
• GeckoView 无法直接加载 file:///android_asset/，因此内存 HTML 预览要使用特殊的加载方式，部分相对资源路径在分屏预览中仍然不解析。
• 云同步中，百度网盘默认远端目录为 /apps/HTMLviewer，云端 HTML 同级静态资源不会自动随文件下载，WebDAV 也建议优先使用 HTTPS。

7. 总结

如果说早期的 NW-HTMLviewer 只是一款“手机上的 HTML 编辑器”，那么当前版本已经明显升级成“移动端 HTML 工作台”。它不只有编辑与预览，还具备文件管理、编码兼容、离线缓存、多语言支持、Material 3 主题和云盘同步，是在安卓设备上处理静态网页、原型页面或小型前端调试任务的实用工具。

对经常需要在线写代码、离线查看效果、同步到网盘并回传更新的人来说，这类“编辑 + 预览 + 协作”的组合方案非常有吸引力。它的价值不只是能在手机上看网页，而是让移动端具备接近桌面端的网页工作流能力。

项目：NW-HTMLviewer（v1.2.0），开源协议：Apache-2.0，适合安卓移动端 HTML 开发与页面调试场景。