Window API

Window 窗口层。#include "webview/window.hpp"。由 App::createWindow 创建，返 shared_ptr<Window>。

创建配置 Opts

Window::opts() 链式（返 OptsBuilder）：

字段	类型	说明
`title(s)`	wstring	标题
`size(w,h)`	int	尺寸
`position(x,y)`	int	位置
`center(bool)`	bool	居中
`url(s)`	wstring	加载地址
`icon(s)`	wstring	图标资源
`frameless(bool)`	bool	无边框
`transparent(bool)`	bool	透明
`alwaysOnTop(bool)`	bool	置顶
`resizable/minimizable/maximizable(bool)`	bool	可缩放等
`bootSplashHtml(s)`	wstring	启动屏

opts.url / opts.compression 须为字符串字面量（构建期扫描）。

方法	说明
`loadURL(url)`	加载（打包/远程/file 三分支）
`loadFile(path)`	本地文件
`loadHTML(html)`	直接 HTML
`reload()`	刷新
`goBack()` / `goForward()`	前进后退

控制

方法	说明
`show()` / `hide()`	显隐
`close()` / `destroy()`	关闭
`minimize()` / `maximize()` / `restore()`	状态
`setFullScreen(bool)`	全屏
`setResizable(bool)`	可缩放
`setClosable(bool)` / `setFocusable(bool)`	可关/可聚焦
`setAlwaysOnTop(bool)`	置顶
`setOpacity(f)`	透明度

几何

方法	说明
`getBounds()` / `setBounds(r)`	边界
`setSize(w,h)`	尺寸
`setPosition(x,y)`	位置
`setMinimumSize(w,h)` / `setMaximumSize(w,h)`	最小/最大
`setAspectRatio(r)`	宽高比
`center()`	居中

多屏

方法	说明
`monitor()`	当前显示器
`isOnPrimary()`	是否主屏
`moveToDisplay(d)`	搬屏

图标 / DevTools

方法	说明
`setIcon(s)` / `icon()`	图标
`openDevTools()` / `closeDevTools()`	开发者工具
`isDevToolsOpen()`	状态
`executeJavaScript(js)`	执行 JS

taskbar

方法	说明
`setProgress(f)` / `setProgressState(s)`	进度
`flashFrame(bool)`	闪烁
`setBadge(n)`	角标
`setSkipTaskbar(bool)`	显隐
`setThumbnailClip(r)` / `setThumbnailToolbar(b)`	缩略图

持久化

方法	说明
`saveWindowState()` / `restoreWindowState()`	窗口状态

父子 / 模态

方法	说明
`setParent(p)` / `parent()`	父窗
`children()`	直接子
`setModal(bool)`	模态

方法	说明
`cookies(url, cb)`	异步查 cookie（`cb(vector<Cookie>)`）
`setCookie(name, value, url, domain, path)`	同步写 cookie。domain 空则从 url 提取
`deleteCookie(name, domain)`	同步删 cookie
`clearCookies(done)`	异步清空

Cookie 结构：{name, value, domain, path, secure, httpOnly, isSession, expires}（wstring + bool + double）。

cpp

// 设 cookie
win->setCookie(L"token", L"abc", L"https://example.com/page");

// 查全部
win->cookies(L"", [](const std::vector<Window::Cookie>& all) {
    for (auto& c : all) { /* c.name, c.value ... */ }
});

// 删
win->deleteCookie(L"token", L"");
win->clearCookies();

TIP

setCookie 底层走 ICoreWebView2CookieManager::CreateCookie + AddOrUpdateCookie，同步。Domain/Path 不可在创建后修改——此 API 创建时即传入。

下载拦截

对标 Electron session.on('will-download')。需 ICoreWebView2_4（Edge 100+），QI 失败静默降级。

方法	说明
`onDownloadStarting(cb)`	注册下载拦截回调

cpp

struct DownloadInfo {
    wstring url, mimeType, contentDisposition;
    int64_t totalBytes = -1;  // -1 = 未知
};
struct DownloadResult {
    bool cancel = false;
    wstring resultFilePath;   // 空 = 默认路径
};

win->onDownloadStarting([](const DownloadInfo& info) -> DownloadResult {
    if (info.mimeType == L"application/pdf") {
        return {false, L"C:\\Saved\\doc.pdf"};  // 自定义保存路径
    }
    if (info.url.find(L"unwanted") != wstring::npos) {
        return {true, L""};  // 取消下载
    }
    return {};  // 用默认
});

回调返回 DownloadResult：cancel=true 阻断下载；resultFilePath 设自定义路径。put_Handled(TRUE) 禁用 WebView2 默认下载对话框。

事件 / RPC

方法	说明
`on(WindowEvent, fn)` / `on(PageEvent, fn)`	订阅事件
`onBeforeClose(fn)`	可取消关闭
`on(name, fn)`	注册 RPC 槽
`call<T>(name, args...)`	同步调 JS
`send(name, args...)`	即发即忘

详见 Bridge API。

Window API ​

创建配置 Opts ​

导航 ​

控制 ​

几何 ​

多屏 ​

图标 / DevTools ​

taskbar ​

持久化 ​

父子 / 模态 ​

Cookie ​

下载拦截 ​

事件 / RPC ​