WallpaperMachine Web壁纸教程:HTML/JS动态壁纸如何在Mac桌面运行
WallpaperMachine Web壁纸教程:HTML/JS动态壁纸如何在Mac桌面运行
WallpaperMachine 是一款免费、开源的 macOS 应用(Apple Silicon,macOS 15+),它让你在 Mac 桌面上运行来自 Steam 创意工坊的 Wallpaper Engine 壁纸。它的 Web 壁纸支持是核心亮点之一:任何由 HTML、CSS 和 JavaScript 编写的 Web 壁纸,都能直接在你的 Mac 桌面上跑起来——鼠标悬停、点击、音频频谱响应一个不少。这篇文章面向新手,讲清楚这些 HTML/JS 动态壁纸背后完整的运行原理。
什么是 Web 壁纸?
在 WallpaperMachine 的壁纸库中,每个项目都由一个 project.json 描述。当其中的 "type" 字段是 "web" 时,这个壁纸就是一个网页项目:
"file"字段指定入口页面,通常是index.html- 壁纸可以包含 JS 模块、CSS、图片、音频、WebAssembly 文件等任意 Web 资源
- 页面通过
window.wallpaperPropertyListener这个对象与宿主应用通信
和 Scene(3D 场景)壁纸、视频壁纸不同,Web 壁纸完全不走内置的渲染引擎,而是在系统自带的 WebKit 浏览器内核(就是 Safari 用的那套)里加载运行。这意味着:
- 你看到的就是"原汁原味"的网页效果,three.js、Spine、Canvas 都能用
- 支持 ES Modules、
fetch()等现代 Web API - 创意工坊里的 Web 壁纸不需要任何转换,下载即可用
💡 应用启动时会自带一张示例壁纸,你可以参考 Resources/StarterWallpaper/preview.jpg 预览它的效果,对应项目文件是 project.json。
从 project.json 到桌面:渲染流程全景
一条 Web 壁纸从"文件"变成"桌面动画",要经过这样一条链路:
1️⃣ Rust Bridge 识别并路由项目
应用内嵌的 Rust 渲染桥(Renderer/Bridge/)扫描壁纸库,发现 WallpaperProjectType::Web 的项目后,不会把它交给 C++ 场景引擎,而是通过 build_web() 为每个被分配的显示器(包括镜像屏)生成一份 WebWallpaperDesc 描述符,包含:项目路径、入口文件、目标帧率、渲染缩放、音量、静音状态,以及用户属性的当前值。这份描述符通过 uniffi 接口 web_wallpapers() 暴露给 Swift 层。
2️⃣ WebWallpaperHost 为每块屏幕开一个窗口
Swift 侧的 WebWallpaperHost.swift 是 Web 壁纸的"总管家"。它每次读取快照都会和现有的页面对账(diff):哪个显示器需要新页面就创建,哪个被撤销了就销毁。每个显示器对应一个独立的 WebWallpaperWindow 窗口,里面装着一个 WKWebView。
3️⃣ 桌面级窗口:藏在桌面之下
这个窗口的配置很讲究(见 WebWallpaperWindow.swift),它复用了渲染引擎为 Scene 壁纸使用的窗口形态:
| 配置 | 值 | 作用 |
|---|---|---|
level |
桌面窗口层级 | 壁纸永远在普通应用窗口之下 |
ignoresMouseEvents |
true |
鼠标事件穿透,不会挡住你操作桌面 |
collectionBehavior |
.canJoinAllSpaces 等 |
切换 Spaces(全屏空间)壁纸照样显示 |
canBecomeKey |
false |
永远不抢占键盘焦点 |
canHide |
false |
Cmd-H 隐藏应用时,壁纸不跟着消失 |
constrainFrameRect |
覆盖整屏 | 壁纸延伸到菜单栏之下,实现真正的"铺满" |
4️⃣ 切换壁纸不闪黑屏
换成 Web 壁纸时不会出现"先黑屏再加载"的体验:WebWallpaperHost 会先把旧壁纸的定格画面扣在新页面窗口上,等页面加载完成并多留 500 毫秒确保真正画出了第一帧,再把旧画面淡出。开启"减弱动态效果"时则直接切换,不做淡入淡出。
主机协议:页面如何和"桌子下面"的应用说话
Web 壁纸的交互体验之所以接近 Windows 上的 Wallpaper Engine,关键在于宿主注入了一套协议脚本,源码集中在 Shared/WebWallpaperProtocol.swift。
四个在文档加载前注入的脚本
页面启动时,WebKit 会先执行四个"垫片脚本",补齐 WebKit 和 Chromium(Wallpaper Engine 在 Windows 上用的内核)之间的差距:
- 文件请求兼容:WebKit 对
file://的fetch()返回状态码 0 且无响应头,而 Chromium 返回 200 +Content-Type。垫片脚本把本地文件的响应"补"成 200,这样检查response.ok的资源加载器、调用WebAssembly.instantiateStreaming的 Unity/Emscripten 程序都能正常启动 requestIdleCallback垫片(Shared/WebWallpaperIdleCallbacks.swift):macOS 的 WebKit 没有这个 API,很多壁纸在启动时直接调用它。垫片按规范模拟了 50ms 的空闲周期,不装的话页面会在这一行直接抛TypeError,什么都画不出来- Windows 字体别名(Shared/WebWallpaperFontAliases.swift):页面里写
SimHei、Segoe UI这些 Windows 字体在 Mac 上根本不存在。垫片会为每个缺失字体声明@font-face,把黑体系映射到苹方、SimSun映射到宋体、Segoe UI映射到 PT Sans(还按数字宽度做了 98.7% 的微调),保证排版观感尽量一致 - 主帧协议脚本:只有主框架能拿到完整的
wallpaperPropertyListenerAPI 和通往宿主的消息通道,iframe 子框架拿不到,防止嵌入的远程页面冒领音频或文件
wallpaperPropertyListener:作者 API
页面通过监听 window.wallpaperPropertyListener 接收宿主推送,主要事件有:
| 事件 | 触发时机 |
|---|---|
applyUserProperties({ id: { value } }) |
加载后推送全部属性;之后每次"应用"只推发生变化的属性 |
applyGeneralProperties({ fps }) |
加载后推送一次,之后显示器目标帧率变化时再推 |
setPaused(bool) |
播放/暂停、电量策略暂停、窗口遮挡暂停 |
userDirectoryFilesAddedOrChanged(...) |
监控中的 fetchall 文件夹文件增删 |
反过来,页面可以主动调用 wallpaperRegisterAudioListener、wallpaperRegisterMedia*Listener、wallpaperRequestRandomFileForProperty 等函数,所有页面发起的请求都通过唯一一条名为 mweWallpaper 的消息通道(WKScriptMessageHandler)送达宿主——整个宿主只有一个入口需要"不信任页面",安全边界非常清晰。
一个容易踩坑的细节:给 wallpaperPropertyListener 赋值这个动作本身不会触发投递。页面在渲染中(比如 React 组件体内)反复赋值监听器不会造成死循环;早于监听器注册到达的属性、暂停状态、目录文件,会在注册完成后的下一轮统一"补发",所以延迟加载模块的页面也能正常启动。
鼠标如何"穿透"到壁纸?
窗口是鼠标透明的(ignoresMouseEvents = true),那悬停、点击、拖拽是怎么送到页面的?答案是全局事件监控 + 模拟注入,实现见 WebWallpaperMouseForwarder.swift:
- 应用装了一个全局
NSEvent监控器(只在至少有一个已加载且未被暂停的页面时存在),不需要辅助功能或输入监控权限 - 只有当鼠标指针下压着的是"桌面层"(Finder 图标、系统壁纸、小组件,即窗口层级低于 0)时才转发事件;你操作自己的应用窗口时,壁纸完全无感
- 因为 WebKit 没有公开的 hover 接口,代码通过私有接口
_simulateMouseMove:/_simulateMouseExit:模拟悬停;WebWallpaperWindow只对 WebKit 谎报自己是 key window(WebKit 只对"激活窗口"做悬停命中),AppKit 侧依然不会把任何事件路由给它 - 移动事件按页面绘制节奏节流(
WebWallpaperMoveThrottle):1000Hz 的鼠标不会让主线程每个报告都重建一次事件,但按下、拖拽、抬起、滚动、移出从不延迟或丢弃 - 右键菜单被协议脚本取消(WebKit 自己的菜单永远不会弹出);页面内鼠标拖图片不会触发 WebKit 的原生拖拽,避免在桌面丢出一张副本文件
由此带来的行为值得记住:
- ✅ 悬停、点击、拖拽、右键、滚轮都能到达页面
- ✅ 点击桌面上的 Finder 图标也会同时触发页面事件(指针是"镜像"而非"捕获")
- ✅ 设置里有"点击壁纸时保持窗口位置"开关,可关掉 macOS 的"点击壁纸显示桌面",防止每次点击都把窗口推走
- ❌ 键盘事件不会转发——壁纸窗口永远不成为 key window,不会抢走你正在输入的内容
帧率控制与省电:Web 壁纸的"性能闸门"
WebKit 不给页面任何帧率控制权,页面甚至可以直接无视收到的 fps 值。WallpaperMachine 在 Shared/WebWallpaperFramePacer.swift 里解决这件事:
🎯 帧率限制:协议脚本直接包装页面的 requestAnimationFrame。回调被限制到目标帧率,并落在槽位之后第一个显示帧上执行,带着那一帧自己的时间戳——页面里基于时间(而非帧数)的动画逻辑完全不受影响。40fps 在 60Hz 上就是"三帧跑两帧"的均值节奏;卡顿超过一个间隔后按限制恢复,而不是爆发式补帧。
📐 内部渲染缩放:WebKit 没有可供宿主缩小的渲染目标,所以"内部渲染缩放"(性能设置里,50%–100%)以 window.devicePixelRatio 乘数的方式进入页面。缩放低于 1 时脚本接管该属性的读取;回到 1 就交还 WebKit 原生实现。缩放变化时会触发一次 resize 事件,按 devicePixelRatio 重建 canvas/WebGL 缓冲的页面会自动跟进。
⏸ 挂起(Suspension):不指望页面"配合"
页面被遮挡或暂停时,setPaused 只是"可选"的礼貌回调,页面可以无视它。所以宿主做了更彻底的挂起:暂停全部媒体播放,并把 WebView 从窗口树中移除——这是 inactiveSchedulingPolicy = .suspend 生效的条件。一张被挂起的页面:不跑动画帧、不跑定时器、不跑 CSS 动画迭代、收不到任何指针事件,但 JavaScript 状态完整保留(绝不通过重新加载来暂停)。挂起瞬间会拍一张定格留在窗口容器里,供 Mission Control 的桌面海报同步识别。多块屏幕独立计算:A 屏被挡住只挂起 A 屏的页面,B 屏照常跑。
🔁 崩溃恢复:WebKit 内容进程反复崩溃时,宿主按指数退避重启,且有一个"窗口期预算"——只有页面稳定运行达到阈值,崩溃历史才清零,不会无限重启。重启后的新文档会全量重放已提交的状态(属性、帧率、暂停),和手动刷新效果一致。
音频响应与媒体集成
🎵 音频响应(在检查器的"通用设置"中逐壁纸开启):
- 页面调用
wallpaperRegisterAudioListener后,收到一个 128 个浮点数的频谱数组(0–63 左声道,64–127 右声道) - 送达频率上限 30Hz;页面挂起期间停止送达,恢复后按序补发
- 声音停止时,泵会以固定节奏持续推送全零频谱(1.5 秒内每轮都推,之后每秒一次),让频谱柱能"落到底"而不是僵在半空
- 一个共享的轮询器(WebWallpaperAudioPump.swift)服务所有屏幕,没有任何页面订阅时系统音频采集链路直接不打开
📀 媒体集成(默认开启):系统"正在播放"会话(MediaRemote 适配器,见 App/Services/SystemMedia/)会推给页面 wallpaperRegisterMedia* 系列监听器——播放状态、歌曲属性、封面、时间轴。你的网页频谱/歌词可视化可以直接跟着 Spotify 或 Apple Music 动。
🔇 页面声音:静音和音量滑杆独立作用于页面输出(HTML 音视频元素 + 整页 WebAudio),镜像屏会选举唯一发声方,不会出现两个屏幕重复出声。
调试技巧:用 Safari 打开 Web 壁纸的开发者工具
这是很多用户不知道的彩蛋(详见 docs/features/web-wallpapers.md):
- Safari → 设置 → 高级 → 打开"在菜单栏中显示'开发'菜单"
- WallpaperMachine → 设置 → 存储 → 故障排查 → 打开 允许检查 Web 壁纸
- Safari → 开发 菜单里就会出现这台 Mac 上正在运行的所有壁纸页面,点一下即可打开 Web Inspector
该开关对运行中的页面立即生效、无需重载,发布版本默认关闭。注意:开启期间,任何使用这台 Mac 的 Safari 的人都能看到你壁纸页面的 JavaScript。
macOS 26+ 还有更多:可以把 Web 壁纸设为屏幕保护程序(原生扩展呈现,使用已提交属性与隔离文件副本,无音频、无交互);但"锁屏动画"不支持 Web 项目——该组合会被标记为"不适用",而不是报错。
已知限制(新手须知)
| 限制 | 说明 |
|---|---|
| 键盘不转发 | 壁纸窗口永远不成为 key window |
| 每帧至多一次指针移动 | 页面绘制慢,指针"手感"也会跟着慢 |
帧率限制只作用于主帧 requestAnimationFrame |
setInterval、CSS 动画、Web Worker 各跑各的节奏;按帧数插值的页面在 30fps 下可能抖动 |
渲染缩放只帮"会读 devicePixelRatio"的页面 |
只在启动时读一次的页面,重载前保持全分辨率 |
| 文件请求垫片够不到 Web Worker | worker 内 fetch 本地文件仍得到状态码 0 |
<video> 色彩管理差异 |
WebKit 会把流色彩标签转成显示色彩空间,与 Chromium 的 sRGB 直显略有出入 |
FAQ:常见问题
Q:为什么我下载的 Web 壁纸是黑屏?
先确认项目文件完整(入口 index.html 存在且未越出项目目录);打开 Safari 开发者工具看控制台报错,多半是 JS 异常。检查器里失败页面会提供"重试壁纸"按钮。
Q:鼠标在壁纸上点击为什么还触发了 Finder 的"显示桌面"? 指针事件是镜像而非捕获。去 设置 → 桌面与锁屏,打开"点击壁纸时保持窗口位置"即可。
Q:Web 壁纸会拖慢电脑吗? 会随页面复杂度变化。善用帧率限制和内部渲染缩放:低电量、低电量模式、过热时应用会自动降到"降低画质"档位,无需手动干预。
Q:普通图片能成为"Web 壁纸"吗?
可以。应用会把静态图片打包成 web 类型项目托管,走完全相同的管线。
结语
WallpaperMachine 的 Web 壁纸支持,本质上是在 macOS 桌面上复刻了一套 Wallpaper Engine 的 CEF 宿主环境:协议对齐、API 垫片、字体回退、帧率闸门、挂起省电、崩溃恢复,再加上鼠标穿透和 Safari 可调试性。你不需要任何配置,下载一个 "type": "web" 的项目,桌面上就动起来了。
延伸阅读:

