App API
App 单例，管理层。#include "webview/app.hpp"。
获取：App::instance()。
窗口
| 方法 | 说明 |
|---|---|
createWindow(Opts) | 建窗，返 shared_ptr<Window> |
windows() | 所有活窗口 |
getById(id) / getByHwnd(hwnd) | 按标识查 |
focused() | 当前焦点窗口 |
topLevelWindows() | 顶层窗口（无父） |
查询
| 方法 | 说明 |
|---|---|
findByTitle(s) / findByUrl(s) | 按标题/url 查 |
getByState(state) | 按状态查 |
childWindowsOf(w) / descendantsOf(w) | 子窗口 |
激活 / MRU
| 方法 | 说明 |
|---|---|
activate(w) | 激活 |
nextWindow() / previousWindow() | MRU 循环 |
mostRecentActive() | 最近活跃 |
分组
| 方法 | 说明 |
|---|---|
setGroup(w, name) | 归组 |
windowsInGroup(name) | 组内窗口 |
closeGroup(name) / activateGroup(name) | 组操作 |
批量
| 方法 | 说明 |
|---|---|
minimizeAll() / restoreAll() | 全最小化/还原 |
closeAll() / closeAllExcept(w) | 关窗 |
cascade() | 层叠 |
tile(TileMode) | 网格平铺 |
广播
| 方法 | 说明 |
|---|---|
broadcast(name, args...) | 即发即忘向所有窗口 |
显示器
| 方法 | 说明 |
|---|---|
primaryDisplay() | 主显示器 |
allDisplays() | 全部显示器 |
shell / 剪贴板
| 方法 | 说明 |
|---|---|
openExternal(url) | 系统默认程序打开 |
showItemInFolder(path) | 资源管理器定位 |
clipboardReadText() / clipboardWriteText(s) | 剪贴板文本 |
对话框
| 方法 | 说明 |
|---|---|
showMessageBox(title, text, flags) | 消息框 |
showOpenDialog(opts) | 打开文件 |
showSaveDialog(opts) | 保存文件 |
托盘
| 方法 | 说明 |
|---|---|
createTray() | 建托盘 |
setQuitToTray(bool) | 关闭转驻留 |
快捷键
| 方法 | 说明 |
|---|---|
registerHotKey(mods, key) / unregisterHotKey(mods, key) | 注册/注销 |
onHotKey(fn) | 触发回调 |
单实例
| 方法 | 说明 |
|---|---|
requestSingleInstanceLock() | 申请锁，false=已有实例 |
onSecondInstance(fn) | 第二实例启动回调 |
taskbar
| 方法 | 说明 |
|---|---|
setProgress(f) / setProgressState(s) | 进度 |
flashFrame(bool) | 闪烁 |
setBadge(n) | 角标 |
setSkipTaskbar(bool) | 显隐 |
setThumbnailClip(rect) / setThumbnailToolbar(btns) | 缩略图 |
持久化
| 方法 | 说明 |
|---|---|
saveState() / restoreState() | 状态存/恢复 |
网络与环境配置
须 createWindow 前调（env 建后返 false），clearCache 任意时。详见 网络与环境配置。
| 方法 | 说明 |
|---|---|
setUserAgent(s) / userAgent() | HTTP User-Agent（command-line --user-agent=） |
setProxy(s) / proxy() | 代理（command-line --proxy-server=，Chromium 格式） |
setUserDataFolder(s) / userDataFolder() | cache+cookies 总目录（env param） |
clearCache() | CDP Network.clearBrowserCache（不重启） |
自动更新
对标 Electron autoUpdater。WinHTTP 零依赖，JSON manifest 静态文件托管。
| 方法 | 说明 |
|---|---|
setFeedURL(url) / feedURL() | 设/读更新 manifest JSON 地址 |
setVersion(ver) / version() | 设/读当前 app 版本（"1.0.0"） |
checkForUpdates(autoDownload = true) | 检查更新；true 自动下载，false 仅通知 |
downloadUpdate() | 手动下载（需先 checkForUpdates(false) + 收到 UpdateAvailable） |
cancelDownload() | 取消进行中的下载 |
quitAndInstall() | 替换 exe（批处理中介） + 重启 |
事件（app.on(AppEvent::xxx, fn)）：
| 事件 | payload | 触发时机 |
|---|---|---|
UpdateChecking | — | 开始检查 |
UpdateAvailable | UpdateInfo{version, url, releaseNotes, pubDate} | 发现新版本 |
UpdateNotAvailable | — | 已是最新 |
UpdateDownloadProgress | UpdateProgress{percent, bytesPerSecond, transferred, total} | 下载中（每个 64KB chunk） |
UpdateDownloaded | UpdateInfo{..., filePath} | 下载完成，可调 quitAndInstall |
UpdateError | wstring 错误消息 | 任何环节失败 |
示例：
cpp
auto& app = App::instance();
app.setVersion(L"1.0.0");
app.setFeedURL(L"https://update.example.com/latest.json");
app.on(AppEvent::UpdateAvailable, [](const UpdateInfo& info) {
// info.version = "1.2.0"
});
app.on(AppEvent::UpdateDownloaded, [](const UpdateInfo& info) {
// 下载完成，提示用户重启
app.quitAndInstall();
});
app.on(AppEvent::UpdateError, [](const std::wstring& err) {
// 显示错误
});
app.checkForUpdates(); // 启动时检查服务端：纯静态 JSON 文件 latest.json，CMake 构建时自动生成：
json
{"version":"1.2.0","url":"https://update.example.com/app-1.2.0.exe","notes":"...","pub_date":"2026-07-24"}生命周期
| 方法 | 说明 |
|---|---|
run() | 进消息循环 |
quit() / exit() | 退出 |
on(AppEvent, fn) | 进程事件 |
onBeforeQuit(fn) | 退出前（可取消） |