92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# HImage
|
||
|
||
HImage 是一款使用 Rust、egui/eframe 和 wgpu 构建的桌面图片浏览器。当前首版面向 Windows 10/11 x64。核心目录、解码和视图逻辑不依赖 Windows API。
|
||
|
||
## 功能
|
||
|
||
- 打开单张图片或文件夹，也可以将图片或文件夹拖入窗口。
|
||
- 仅浏览当前目录，按文件名自然排序，并支持首尾循环切换；按 `F5` 重新扫描目录。
|
||
- 支持 JPEG（含 EXIF 方向）、PNG、BMP、WebP、TIFF、ICO、GIF 和 SVG。
|
||
- GIF 按帧延时和循环设置播放。TIFF、APNG 和动画 WebP 当前仅显示首幅。
|
||
- SVG 按静态图像渲染；缩放时在后台重新栅格化，不执行脚本，也不获取网络资源。
|
||
- 解码在后台运行，并隔离已取消的请求；GIF 帧队列容量为 1。
|
||
- 解码器分配预算为 128 MiB，最多同时执行一个解码任务。预留合成、帧队列和显示缓冲空间后，目标峰值预算为 512 MiB（不含图形驱动和字体）。位图单边最大 16384 像素，SVG 源文件最大 16 MiB。上传纹理尺寸受设备上限与 8192 像素限制，超出时会缩小显示；超出其他限制时会显示错误。
|
||
|
||
## 使用方法
|
||
|
||
直接打开图片、打开文件夹、拖入图片或文件夹，或从命令行传入路径：
|
||
|
||
```powershell
|
||
HImage.exe "图片路径或文件夹路径"
|
||
```
|
||
|
||
| 操作 | 功能 |
|
||
| --- | --- |
|
||
| 鼠标滚轮 | 以鼠标位置为锚点缩放 |
|
||
| 左键拖动 | 平移图片 |
|
||
| 左右方向键 | 切换上一张/下一张 |
|
||
| 窗口两侧半透明三角按钮 | 切换上一张/下一张 |
|
||
| `+` / `-` | 放大 / 缩小 |
|
||
| `0` | 适应窗口 |
|
||
| `1` | 显示原始尺寸 |
|
||
| `Ctrl+O` | 打开图片 |
|
||
| `Ctrl+Shift+O` | 打开文件夹 |
|
||
| `F5` | 重新扫描当前目录 |
|
||
|
||
## 构建
|
||
|
||
需要安装 Rust（项目固定使用 `rust-toolchain.toml` 中的工具链）以及 Visual Studio 2022 Build Tools 的“使用 C++ 的桌面开发”组件和 Windows SDK。
|
||
|
||
```powershell
|
||
cargo fmt --check
|
||
cargo clippy --all-targets -- -D warnings
|
||
cargo test
|
||
cargo build --release --locked
|
||
```
|
||
|
||
开发运行示例：
|
||
|
||
```powershell
|
||
cargo run -- "图片或目录路径"
|
||
```
|
||
|
||
本项目优先使用全局 Rust，不需要 `.tools` 下的 Rust 工具链。
|
||
|
||
## 打包
|
||
|
||
使用 Inno Setup 6.6 或更新版本编译安装程序：
|
||
|
||
```powershell
|
||
./scripts/package.ps1 -Iscc "C:/Program Files (x86)/Inno Setup 6/ISCC.exe"
|
||
```
|
||
|
||
打包输出为 `dist/HImage.exe` 和 `dist/HImage-Setup.exe`。全用户安装需要管理员权限，程序日常运行不需要。安装器会创建开始菜单和卸载入口，并可选注册“打开方式”；不会更改默认图片应用。程序当前未签名。
|
||
|
||
## 项目结构
|
||
|
||
- `src/browser.rs`：目录浏览和文件排序
|
||
- `src/decode.rs`：图片解码和动画帧队列
|
||
- `src/view.rs`：缩放和视图状态
|
||
- `src/main.rs`：应用界面与入口
|
||
- `platform/windows`：Windows 安装配置
|
||
|
||
Linux/macOS 仅预留源码结构，尚未完成实机验证或打包。未来 Linux 构建还需要启用 eframe 的 X11/Wayland 后端和文件对话框依赖。
|
||
|
||
## 许可
|
||
|
||
项目内置 Noto Sans SC 字体，许可证见 `assets/fonts/OFL.txt`。依赖版本由 `Cargo.lock` 锁定；发布包附带第三方许可证目录。
|
||
|
||
## 验证记录
|
||
|
||
截至 2026-11-02，在 Windows x64、全局 stable Rust 1.99.1 / Cargo 1.99.1 和 Visual Studio 2022 Build Tools 环境中：
|
||
|
||
- 11 项单元测试通过，覆盖自然排序、空目录、循环、缩放锚点、中文字体渲染、静态解码、EXIF 旋转、GIF 循环/延时/帧处置、SVG 和分配限制。
|
||
- 格式检查、Clippy（警告视为错误）和 Release 构建通过。
|
||
- 实际窗口检查覆盖中文界面、文件对话框、中文及空格路径、SVG 显示和自然排序切图。
|
||
- 安装器已在隔离目录完成全用户安装、覆盖升级和卸载测试，均返回 0；卸载后程序和测试用“打开方式”注册项均已清理。
|
||
- 尚未在其他 DPI、Windows 10、Linux 或 macOS 实机验证。拖放和快速连续切图已实现，尚未完成 UI 自动化验证。
|
||
|
||
## 仓库
|
||
|
||
[https://git.honulla.com/hokori/HImage](https://git.honulla.com/hokori/HImage)
|