wallhaven-fast-download

Wallhaven 快速下载脚本：在列表页悬停壁纸卡片时快速预览，一键下载原图，并在下载后尝试自动标记为已看。

功能

• 悬停快速预览：鼠标移到壁纸卡片上，先立即显示当前卡片缩略图，再在后台加载原图并自动替换。
• 真实加载进度：原图传输时显示进度条、已加载大小、总大小和百分比；无法获知总大小时自动退化为实时已加载大小。
• 预览信息保留：预览图底部会显示当前壁纸分辨率，即使弹层遮住原站 hover 信息也能继续查看尺寸。
• 一键下载：点击 ↓ 按钮通过 GM_download 下载原图。
• 下载状态反馈：请求/下载中按钮显示 …，下载成功后短暂显示 ✓，随后恢复为可再次点击的下载按钮。
• 下载标记已看：下载成功后后台模拟访问详情页，Wallhaven 自动标记为已看，避免重复下载。
• CDN 直连与详情页兜底：优先根据卡片信息直连原图 CDN，格式候选均失败时再从详情页解析真实地址。
• 成功结果缓存：只缓存已经成功加载或下载的原图地址，失败后下次操作仍可重新尝试。
• 无外部依赖：纯原生 JS，不依赖 jQuery 或其他库。

安装

使用 Tampermonkey、Violentmonkey 等用户脚本管理器安装 main.js。

脚本匹配范围：

https://wallhaven.cc/*

使用方式

1. 打开 Wallhaven 列表页，例如首页、搜索页或标签页。
2. 将鼠标移到壁纸卡片上，脚本会显示快速预览。
3. 预览刚出现时可能先显示缩略图；左上角角标和底部加载状态存在时，表示原图仍在解析或加载。
4. 预览底部会显示 Wallhaven 卡片中的分辨率信息，例如 3840 x 2160。
5. 点击卡片左上角的 ↓ 按钮下载原图；下载反馈阶段即使鼠标移出卡片，按钮状态也会保持可见。

实现说明

脚本使用原生 DOM API、MutationObserver、GM_xmlhttpRequest 和 GM_download。主要流程如下：

• 通过 MutationObserver 监听列表页卡片变化，并为壁纸卡片注入工具按钮。
• 悬停卡片时立即用页面已有缩略图创建预览层，避免等待原图网络请求。
• 从 Wallhaven 卡片的 .wall-res 节点读取分辨率，并显示在预览图底部。
• 根据卡片中的 Wallpaper ID 和图片格式直接加载 CDN 原图；如果格式候选均失败，再从详情页的 #wallpaper 元素解析真实地址。
• 通过用户脚本请求的进度事件实时展示原图传输大小和百分比；总大小不可知时显示不确定进度条和已加载大小。
• 原图以 Blob 完成传输后替换缩略图，临时对象地址会立即释放，并缓存已验证的 CDN 地址。
• 下载按钮在请求中和成功反馈阶段保持可见，反馈结束后回到 hover/focus 显示逻辑。
• 下载成功后创建隐藏 iframe 访问详情页，借助 Wallhaven 页面行为尝试触发已看标记。

本地检查

本项目没有构建步骤。修改脚本后至少运行：

node --check main.js
node tests/preview-behavior.test.js
node tests/resource-lifecycle.test.js

node --check 只检查 JavaScript 语法，不会验证浏览器环境、用户脚本 API 或 Wallhaven 页面行为。涉及交互变化时，还需要在 Tampermonkey 或 Violentmonkey 中手动验证。

许可证

MIT