WallpaperApi

本页说明壁纸专用 IPC。首次开发请阅读开发桌面壁纸，宿主实现细节见设计与实现记录。

接口与调用范围

接口	壁纸页面	管理页面	用途
ready(): Promise<void>	是	否	初始资源及监听器准备完成后报告就绪
getState(): Promise<WallpaperState>	是	是	获取当前部署状态
getEnvironment(): Promise<WallpaperEnvironment>	是	是	获取锁屏、电源、前台全屏状态
openConfigPage(): Promise<void>	是	否	打开当前壁纸声明的独立设置窗口
deploy(options): Promise<WallpaperState>	否	是	按 widgetName 启用或替换壁纸
close(widgetName?): Promise<WallpaperState>	否	是	关闭匹配的壁纸；无参数时关闭当前壁纸
openDevTools(widgetName): Promise<void>	否	是	打开当前匹配壁纸的独立调试窗口
onStateChanged(callback): () => void	是	是	订阅部署状态，返回取消订阅函数
onEnvironmentChanged(callback): () => void	是	是	订阅环境状态，返回取消订阅函数

调用这些接口需要 Widget.js 的 Electron 桥接；普通浏览器预览应跳过 IPC。

专用壁纸页面随现有组件包发布，通过 WallpaperWidget 声明。仅支持 Windows 主屏；页面只接收鼠标移动与左键事件，不接收键盘、滚轮或右键，也不获得输入焦点。

声明

import { WallpaperWidget } from '@widget-js/core'

export default new WallpaperWidget({
  name: 'cn.example.wallpaper',
  lang: 'zh-CN',
  title: { 'zh-CN': '动态壁纸' },
  description: { 'zh-CN': '响应鼠标移动的网页壁纸' },
  path: '/wallpaper',
  previewImage: '/wallpaper-preview.png',
  keywords: [],
})

将该定义加入组件包 widgets 列表，并为 /wallpaper 注册专用页面路由。无需传入网格宽高。宿主使用主屏完整尺寸；页面按 innerWidth/innerHeight 或 CSS 100vw/100vh 布局，并监听 resize。壁纸应使用独立入口，避免执行需要普通组件 IPC、键盘或配置窗口的初始化代码。

页面准备完成

import { WallpaperApi } from '@widget-js/core'

// 在必要资源与事件监听器准备完成后调用，而非等动画播放完毕。
await WallpaperApi.ready()

const unsubscribe = WallpaperApi.onEnvironmentChanged((state) => {
  // locked / suspended / displayOff / fullscreen
  // 壁纸自己决定是否暂停动画、静音或降低帧率。
  console.log(state)
})
const environment = await WallpaperApi.getEnvironment()
// 页面销毁或组件卸载时调用 unsubscribe()。

宿主等待页面 ready 和原生挂载同时完成；整个窗口准备阶段最多 30 秒。超时关闭壁纸、清除恢复选择并通知用户。每次异常恢复都重新等待 ready。宿主不会强制暂停或静音。

fullscreen 表示检测到前台窗口覆盖主屏，约每 500ms 检查；它不是 Windows 全局遮挡计算。displayOff 来自控制台显示电源通知。休眠期间进程无法执行，恢复后的通知供页面重新同步。

管理界面

import { WallpaperApi } from '@widget-js/core'

const unsubscribe = WallpaperApi.onStateChanged(state => console.log(state))
const current = await WallpaperApi.getState()
const result = await WallpaperApi.deploy({
  widgetName: 'cn.example.wallpaper',
  // 未安装组件时可提供插件生成的 widget.json 地址。
  // packageJsonUrl: 'https://example.com/widget/widget.json',
})
// 返回状态可能为 error；此时宿主已经显示失败通知。
await WallpaperApi.close('cn.example.wallpaper')
unsubscribe()

close(widgetName) 只关闭匹配的当前壁纸，避免旧卡片关闭另一张壁纸；省略参数关闭当前壁纸。状态为 idle/loading/running/recovering/error，包含 widgetName、error、recoveryAttempts 和递增 revision。查询与订阅并用时应忽略比现有 revision 更小的结果。

同名壁纸部署中或运行中重复部署不会新建窗口；替换其他壁纸先关闭旧窗口，失败后露出系统壁纸，不回滚旧页面。运行异常最多恢复 3 次，成功运行 60 秒才清零计数。正常退出保留启动恢复选择；主动关闭、初次失败或重试耗尽清除选择。

专用壁纸 preload 提供 ready/getState/getEnvironment/openConfigPage 和两种订阅，不提供 deploy/close/openDevTools 或其他普通组件 API。壁纸页面无法通过该桥接修改部署。使用标准 Web API 实现动画与资源加载即可；持久化 Web 存储按组件包隔离。

状态结构

interface WallpaperState {
  status: 'idle' | 'loading' | 'running' | 'recovering' | 'error'
  widgetName?: string
  error?: string
  recoveryAttempts: number
  revision: number
}

interface WallpaperEnvironment {
  locked: boolean
  suspended: boolean
  displayOff: boolean
  fullscreen: boolean
}

设置入口由 configPage 声明；openConfigPage() 只能由当前壁纸主框架调用。设置窗口与壁纸使用相同的包分区，可以通过同源 localStorage 和 storage 事件同步数据。管理卡片通过 WidgetApi.openConfigPageByName(widgetName) 打开设置。详情见设置页面。

输入注意事项

物理输入始终继续交给 Windows。宿主只在允许的桌面空白位置复制鼠标移动和左键消息给壁纸；图标与其他窗口优先。不要使用输入框、滚动交互或右键菜单。网页左键反应与桌面点击、框选可能同时发生；Windows 新式菜单漏判时，左键既可能关闭菜单也可能触发壁纸，这延续了已验证原型的行为。