# ImageBrowser

**Repository Path**: jacelin/ImageBrowser

## Basic Information

- **Project Name**: ImageBrowser
- **Description**: 用QT C++实现有一个网页浏览器，基于edge内核，专门用于一键下载网页上的网片资源，非常好用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-19
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ImageBrowser（一键下图神器）


专用于一键下图的网页浏览器，基于Edge内核，小而轻便、功能强大。
页面由 **Microsoft Edge WebView2** 渲染，外壳为 **Qt 5 Widgets** 无边框窗体。

![软件界面](软件界面.png)

---

## 1. 功能与使用

### 1.1 主要功能

| 能力 | 说明 |
|------|------|
| 多标签浏览 | 新建 / 关闭 / 拖拽排序；标签右键可关左侧、右侧、其他 |
| 导航 | 后退、前进、刷新、主页；地址栏输入 URL 后回车或点 GO |
| 一键下图 | 扫描当前页主体图片并批量保存到所选目录 |
| 右键菜单 | 复制文字、复制图片、图片另存为、复制链接、在新标签打开 |
| 右键存图 | 勾选后，右键图片不再弹菜单，直接保存到预设目录 |
| 下载面板 | 打开 WebView2 内置下载浮层，查看进行中的下载 |
| 清除数据 | 可选清除缓存 / Cookie / 历史 / 本地存储 / Service Worker；也可彻底清缓存并重启 |
| 会话记忆 | 记住打开的标签、当前标签、窗口位置与大小（写在程序目录旁的 `.config`） |

### 1.2 基本使用

1. 安装 [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/)（Windows 10/11 多数已自带）。
2. 运行 `dist\ImageBrowser.exe`（需同目录有 `WebView2Loader.dll` 及 Qt 运行库）。
3. 在地址栏输入网址并回车，或点主页在新标签打开默认主页（默认 `https://cn.bing.com/`）。
4. **批量存图**：点「一键下图」→ 选择保存目录 → 等待完成。
5. **单张存图**：
   - 未勾选「右键存图」：页面上右键图片 →「图片另存为…」
   - 勾选「右键存图」：先选保存目录，之后右键图片即自动保存
6. **清缓存**：点清除按钮，按需勾选数据类型后确认；需要更干净时可「彻底清除所有」（会重启并删除 `cache/`）。

配置文件：`ImageBrowser.exe` 同目录下的 `.config`（Ini），含主页、上次保存目录、会话 URL 等。无独立设置窗口，主页等可通过修改该文件调整。

### 1.3 构建

**环境**：Windows + Qt 5.14.2 MinGW 32-bit（推荐）+ 本机 WebView2 Runtime。

```bat
set QMAKE_EXE=C:\Qt\Qt5.14.2\5.14.2\mingw73_32\bin\qmake.exe
set MINGW_MAKE=C:\Qt\Qt5.14.2\Tools\mingw730_32\bin\mingw32-make.exe
build_qt.bat
```

输出：`dist\ImageBrowser.exe`（脚本会部署依赖 DLL）。

也可在 Qt Creator 中打开 `ImageBrowser.pro` 构建，并将 `WebView2Loader.dll` 放到可执行文件同目录。另提供 `CMakeLists.txt` 作为备选。

---

## 2. 技术实现

### 2.1 用了哪些技术

| 技术 | 角色 |
|------|------|
| **Qt 5 Widgets / Gui / Network / Concurrent** | 窗体、工具栏、标签页、对话框、网络下载、线程池 |
| **Microsoft Edge WebView2** | 嵌入式 Chromium 内核：渲染网页、执行 JS、下载浮层 |
| **Win32 COM** | 通过 `ICoreWebView2*` 等接口驱动 WebView2 |
| **WebView2Loader.dll** | 动态加载本机 WebView2 Runtime，创建 Environment / Controller |
| **页面 JS 桥接脚本** | 拦截右键 / 新窗口，经 `chrome.webview.postMessage` 与 C++ 通信 |
| **Chrome DevTools Protocol (CDP)** | 清除缓存、Cookie、本地存储等浏览数据 |
| **WinInet（回退）** | Qt 网络下载失败时的备用 HTTP 下载 |
| **QSettings (Ini)** | 持久化主页、会话、窗口几何等 |

WebView2 **不是** Qt 专用库，而是微软提供的 Windows 嵌入式浏览器控件；本项目用 Qt 做 UI 壳，再把 WebView2 嵌进每个标签对应的 `QWidget`。

### 2.2 分层结构

```
┌──────────────────────────────────────────────────────────┐
│  表现层：MainWindow（Qt Widgets）                          │
│  无边框窗口、地址栏、标签栏、菜单、一键下图、清缓存对话框      │
├──────────────────────────────────────────────────────────┤
│  宿主层：WebViewHost（每标签一个 QWidget）                   │
│  创建/持有 Controller，同步窗口大小，转发导航与信号            │
├──────────────────────────────────────────────────────────┤
│  COM 适配层：webview2_api.h + 辅助模块                       │
│  精简 ICoreWebView2* 声明；browsingdata / download_dialog   │
├──────────────────────────────────────────────────────────┤
│  运行时：WebView2Loader → Edge WebView2 Runtime              │
│  用户数据目录：程序目录下 cache/                              │
├──────────────────────────────────────────────────────────┤
│  页面层：桥接 JS + 网页 DOM                                  │
│  postMessage ↔ C++；ExecuteScript 采图 / fetch 回退         │
└──────────────────────────────────────────────────────────┘
```

各层职责简述：

1. **MainWindow**  
   只关心产品交互：哪个按钮、哪个标签、存到哪、是否直存。通过 `WebViewHost` 的公开方法与信号驱动浏览器，不直接碰 COM。

2. **WebViewHost**  
   把一个 `QWidget` 的 `HWND` 交给 WebView2 Controller；负责导航、注入桥接脚本、接收 `WebMessage`、执行采图脚本，再以 Qt 信号通知上层。

3. **COM / SDK 适配**  
   - `webview2_api.h`：项目内精简的接口与 IID，降低对完整 SDK 生成代码的依赖  
   - `webview_browsingdata.*`：用 CDP 清浏览数据  
   - `webview_download_dialog.*`：打开 WebView2 内置下载对话框  

4. **WebView2 Runtime**  
   真正跑 Chromium 的进程；与宿主通过 COM 异步回调通信。多个标签**共享同一个** `ICoreWebView2Environment`，各自创建 Controller。

5. **页面 JS**  
   在文档创建时注入；把右键、新开标签等事件转成 JSON 消息发给 C++，避免依赖默认浏览器菜单行为。

### 2.3 技术如何结合（典型流程）

**打开网页**

```
地址栏回车 → MainWindow::navigateCurrent
  → WebViewHost::navigate
  → ICoreWebView2::Navigate
  → SourceChanged / DocumentTitleChanged
  → urlChanged / titleChanged → 更新地址栏与标签标题
```

**右键菜单 / 右键存图**

```
页面 contextmenu（JS preventDefault）
  → chrome.webview.postMessage({ type: 'contextmenu', ... })
  → WebMessageReceived → WebViewHost::handleWebMessage
  → contextMenuRequested
  → MainWindow：弹菜单，或勾选「右键存图」时直接下载
```

**一键下图**

```
「一键下图」→ 选目录
  → WebViewHost::collectBodyImageUrls（ExecuteScript 扫 DOM）
  → 得到 URL 列表
  → MainWindow::downloadUrlToFile（Qt Network / 线程池）
      失败 → WinInet
      单张仍失败 → 页面内 fetch/canvas（fetchUrlToBase64）回退
```

**新标签**

```
页面 _blank / 中键 / window.open
  → JS postMessage 或 NewWindowRequested（Handled=true）
  → newWindowRequested → MainWindow::addBrowserTab
  → 新 WebViewHost，复用共享 Environment 创建 Controller
```

**清除浏览数据**

```
清除对话框勾选种类
  → WebViewHost::clearBrowsingData
  → CDP（Network / Storage / Page 等）
「彻底清除」→ 写 .purge_cache → 重启
  → main() 在创建 WebView2 Environment 之前删除 cache/
```

### 2.4 关键源码

| 路径 | 作用 |
|------|------|
| `src/main.cpp` | 入口；启动前按标志清理 cache；设置 AppUserModelID |
| `src/mainwindow.*` | 主界面与全部用户功能 |
| `src/webviewhost.*` | WebView2 宿主、JS 桥、采图 |
| `src/webview2_api.h` | 精简 COM 接口声明 |
| `src/webview_browsingdata.*` | CDP 清除浏览数据 |
| `src/webview_download_dialog.*` | 内置下载浮层 |
| `ImageBrowser.pro` / `build_qt.bat` | 主构建路径 |
| `third_party/WebView2/` | WebView2 SDK 头文件等 |

---

## 作者信息

| 项 | 内容 |
|----|------|
| 作者 | jace |
| 工程创建日期 | 2026/7/19 |

---

## 许可与依赖说明

- 应用自身代码按仓库许可使用。
- WebView2 相关组件遵循 Microsoft 的 WebView2 / Edge 许可与运行时条款（见 `third_party/WebView2/` 下 NOTICE / LICENSE）。