Web Interactive Wallpaper.zh.CN

Web 交互型壁纸

VirtualPaper 支持将打包为 .zip、.rar 或 .7z 格式的交互式 web 壁纸。

---

包结构

压缩包根目录必须包含 project.json，以及 HTML 入口文件和各类资源：

my-wallpaper.zip
├── project.json        ← 必需，VP 清单文件
├── index.html          ← HTML 入口（路径在 project.json 中配置）
├── preview.jpg         ← 库中显示的缩略图（路径在 project.json 中配置）
├── style.css
├── main.js
└── assets/
    └── ...

project.json

此文件 必须存在。缺少该文件或指定的入口文件不存在时，导入将失败。

{
  "title":       "我的壁纸",
  "description": "一个简短描述。",
  "authors":     "你的名字",
  "tags":        "自然;抽象;暗色",
  "file":        "index.html",
  "preview":     "preview.jpg"
}

字段	必填	默认值	描述
title	否	文件名	在壁纸库中显示。
description	否	""	在详情面板中显示。
authors	否	""	作者名称。
tags	否	""	分号分隔的标签，用于过滤。
file	是	index.html	HTML 入口文件的相对路径。
preview	否	preview.jpg	缩略图相对路径。若缺失，库中将显示占位图。

---

播放器如何渲染你的页面

压缩包解压后，VirtualPaper.PlayerWeb.exe 加载 default.html——一个内置的播放器壳，内部包含 base.js 和 run.js。你的页面被嵌入在一个 <iframe> 中：

WebView2
└── default.html（内置播放器壳）
    ├── base.js（特效滤镜、时间感知、mouseOut 转发）
    └── run.js（resourceLoad、play、视差、播放/音频控制）
        └── <iframe src="https://wallpaper.localhost/<wpId>/index.html">
                └── 你的 index.html

壳负责处理与宿主进程的所有通信。你无需在页面中实现任何 JS 回调。 鼠标事件、播放控制、特效滤镜和时间感知均由内置壳管理。

你的 index.html 就是一个普通的网页——按照编写独立 Web 应用的方式编写即可。

---

鼠标交互

你的页面可以通过标准 DOM 事件使用光标存在性：

• 内置的 base.js 在光标离开壁纸区域时向 document 派发原生的 mouseleave 事件。
• 你的页面可以正常监听 document.addEventListener('mouseleave', ...) 和 document.addEventListener('mousemove', ...)——光标覆盖 iframe 时，iframe 会正常接收指针事件。

不支持从 iframe 外部转发光标坐标和点击事件。光标必须实际位于 iframe 上方，指针事件才能传递到你的页面。

---

WebView2 环境

设置	值
虚拟主机	https://wallpaper.localhost/<wpId>/ —— 你的整个解压目录在该源下均可访问
Web 安全	禁用（--disable-web-security）——允许跨域本地文件访问
用户数据目录	%Temp%\VirtualPaper\WebView2\（隔离，无共享浏览器状态）
右键菜单	生产构建中禁用
下载	自动取消
新窗口 / 弹窗	已拦截

HTML 中所有相对路径引用的资源均相对于虚拟主机 URL 解析，标准的 <script src="...">、<link href="..."> 和 fetch(...) 调用均按预期工作。

---

注意事项

• 播放器级别不拦截外部网络请求，但建议壁纸保持离线自包含。
• iframe 内部（你的页面）崩溃不会影响 VirtualPaper 主服务。
• project.json 中的 tags 字段使用分号作为分隔符（如 "自然;抽象"）。