WebView

include/XBase/WebView.h · XBase::WebView

网页由系统 WebView2 渲染在游戏窗口内的独立子窗口里；XBase 负责生命周期、面板位置、输入焦点与状态查询，宿主只提交 URL、可见性和尺寸。

运行时要求

Windows 10/11 安装 WebView2 运行时（Evergreen）。
加载器由 XBase 统一放在 <游戏根目录>\XBase\WebView2Loader.dll，宿主发布包不需要自带
入口先用 IsRuntimeAvailable() 判断，不可用时不要启用相关 UI。

API

C++

struct State {
    bool initialized;
    bool visible;
    bool loading;
    bool canGoBack;
    bool canGoForward;
    int lastError;
    std::string url;
    std::string title;
};

bool IsRuntimeAvailable();
bool Init();
bool IsInitialized();
void NotifyGameInit();
void Process();
void Shutdown();

bool Navigate(const std::string& url);
bool SetHtml(const std::string& html);
void Reload();
bool GoBack();
bool GoForward();
void SetZoom(float factor);

void SetVisible(bool visible);
bool IsVisible();
void SetBounds(const Rect& bounds);
State GetState();
bool Close();

bool UsesCaptureMode();
void DrawPanel(const Rect& bounds);
void ForwardPanelInput(const Rect& bounds, Vec2 mouse, bool mouseDown, float wheelDelta);

void SetStateCallback(StateCallback callback);

using MessageHandler = std::function<void(const std::string& json)>;
void SetMessageHandler(MessageHandler handler);
bool PostJson(const std::string& json);
bool InjectScript(const std::string& script);
bool MapFolder(const std::string& hostName, const std::string& folderPath);

SetMessageHandler() 接收网页用 chrome.webview.postMessage 发来的原始 JSON，回调在游戏线程执行；PostJson() 反向投递，网页用 chrome.webview 的 message 事件接收；InjectScript() 在页面脚本之前注入代码，控制器尚未创建时会排队。需要现成的调用约定时用 WebBridge。

全屏抓帧模式

独占全屏时 DWM 不合成子窗口，HWND 覆盖层永远不可见，此时 UsesCaptureMode() 返回真，宿主改用抓帧贴图：

DrawPanel() 在 SetBounds() 提交的同一矩形内绘制最新一帧（抓帧解码后上传 D3D9 贴图），宿主在占位控件之后调用即可。
ForwardPanelInput() 把鼠标位置换算成页面坐标，转发悬停、点击与滚轮（UI::IsLastItemHovered() + UI::GetMousePosition() + Hooks::ConsumeWheelDelta()）。
抓帧与面板同尺寸，1:1 显示不缩放；静止时用 PNG 保证清晰度，交互时改用 JPEG 把抓帧间隔压到 120ms，空闲间隔 500ms，点击与滚轮后立即重抓。
抓帧模式不抢焦点，游戏与菜单热键保持可用；受限于位图转发，页面内的文本输入与输入法不可用，帧率也低于原生渲染。
想要原生渲染与文字输入时，让游戏进入窗口或无边框模式（Hooks::SetWindowMode(WindowMode::Borderless)）；窗口由 DWM 合成后本页自动回落到原生覆盖层，抓帧模式随之关闭。

隐藏与关闭

SetVisible(false) 只隐藏面板，浏览器与宿主窗口保持存活，再次显示几乎瞬时完成，对应窗口的最小化
Close() 释放浏览器与宿主窗口，内存归还系统，之后再次 SetVisible(true) 或 Navigate 会重新创建，对应窗口的关闭
菜单关闭等临时场景用隐藏，长期不用或需要回收内存时用关闭；Shutdown() 是卸载路径，与两者都不同

生命周期与边界

Init() 只检查运行时并登记请求，不会立刻创建浏览器；真正的环境与控制器创建延迟到宿主请求页面之后（Navigate、SetHtml、SetVisible(true) 都会登记请求）的 Process() 安全点执行，因此不会在渲染钩子里重入消息循环，未使用网页时也不会启动浏览器进程。
创建是异步的；完成后 GetState().initialized 为真，之前提交的 Navigate/SetHtml 会自动补发，若期间已请求显示则直接可见。
领域卸载时若创建仍在进行，会等待回调到达后自行释放控制器并销毁宿主窗口，避免父窗口句柄被复用。
SetBounds() 接收与 UI::GetDisplaySize() 同坐标系的矩形（ImGui 显示像素，通常按菜单内容区计算），XBase 内部按游戏客户区比例换算并裁剪到游戏窗口内。
网页渲染为窗口期覆盖层，无法被 ImGui 裁剪，宿主应把矩形限制在菜单窗口可见区域内（菜单滚动时用 UI::GetCurrentWindowRect() 求交集）。
显示时网页子窗口取得焦点，游戏收不到键盘输入；隐藏时焦点交还游戏窗口。独占全屏下不取焦点，改由抓帧模式呈现。
面板聚焦期间按键只到达网页子窗口，XBase 通过加速键事件与系统状态轮询补齐输入，菜单热键仍然可用。
菜单关闭后面板自动隐藏，宿主无需在关闭流程里手动调用 SetVisible(false)。
关闭菜单、切换场景或新游戏时调用 SetVisible(false)；NotifyGameInit() 会自动隐藏。
窗口化与无边框模式下网页渲染为窗口期覆盖层，由 DWM 合成；独占全屏切换为抓帧贴图，两种状态都由 XBase 自动判定。
浏览器数据目录位于 %APPDATA%\com.yuinijika.xbase\webview2，由 XBase 创建，不落在游戏目录内。
导航、标题、前进后退状态通过事件更新，SetStateCallback() 可在游戏线程收到变化通知。

版本能力

Capability	SA	VC	III
WebView	✅	✅	✅

实现位于 Win32/COM 层，不访问游戏内存与插件地址；真实可用性由 IsRuntimeAvailable() 在运行时判定。

本地页面

file: 协议下每个页面都是独立安全源，模块脚本与带 crossorigin 的请求会被拦下，因此本地界面必须映射成虚拟主机再加载：

C++

XBase::WebView::Init();
XBase::WebView::MapFolder("xmenu.local", XBase::Platform::CurrentModuleDirectory());
XBase::WebView::Navigate("https://xmenu.local/ui.html");

映射目录下的脚本、样式与 fetch('./config.json') 都按同源处理。

独占全屏

独占全屏时 HWND 覆盖层不参与合成，UsesCaptureMode() 为真，此时：

用 DrawPanel(bounds) 把抓帧画面画出来，必须放在真实的 ImGui 窗口内，否则会被塞进默认 Debug 窗口
用 ForwardPanelInput(bounds, mouse, mouseDown, wheelDelta) 转发鼠标与滚轮
帧率明显低于窗口模式，界面应提示用户切到窗口或无边框模式

API

C++

struct State {
    bool initialized;
    bool visible;
    bool loading;
    bool canGoBack;
    bool canGoForward;
    int lastError;
    std::string url;
    std::string title;
};

bool IsRuntimeAvailable();
bool Init();
bool IsInitialized();
void NotifyGameInit();
void Process();
void Shutdown();

bool Navigate(const std::string& url);
bool SetHtml(const std::string& html);
void Reload();
bool GoBack();
bool GoForward();
void SetZoom(float factor);

void SetVisible(bool visible);
bool IsVisible();
void SetBounds(const Rect& bounds);
State GetState();
bool Close();

bool UsesCaptureMode();
void DrawPanel(const Rect& bounds);
void ForwardPanelInput(const Rect& bounds, Vec2 mouse, bool mouseDown, float wheelDelta);

void SetStateCallback(StateCallback callback);

using MessageHandler = std::function<void(const std::string& json)>;
void SetMessageHandler(MessageHandler handler);
bool PostJson(const std::string& json);
bool InjectScript(const std::string& script);
bool MapFolder(const std::string& hostName, const std::string& folderPath);

全屏抓帧模式

独占全屏时 DWM 不合成子窗口，HWND 覆盖层永远不可见，此时 UsesCaptureMode() 返回真，宿主改用抓帧贴图：

DrawPanel() 在 SetBounds() 提交的同一矩形内绘制最新一帧（抓帧解码后上传 D3D9 贴图），宿主在占位控件之后调用即可。

ForwardPanelInput() 把鼠标位置换算成页面坐标，转发悬停、点击与滚轮（UI::IsLastItemHovered() + UI::GetMousePosition() + Hooks::ConsumeWheelDelta()）。

抓帧与面板同尺寸，1:1 显示不缩放；静止时用 PNG 保证清晰度，交互时改用 JPEG 把抓帧间隔压到 120ms，空闲间隔 500ms，点击与滚轮后立即重抓。

抓帧模式不抢焦点，游戏与菜单热键保持可用；受限于位图转发，页面内的文本输入与输入法不可用，帧率也低于原生渲染。

想要原生渲染与文字输入时，让游戏进入窗口或无边框模式（Hooks::SetWindowMode(WindowMode::Borderless)）；窗口由 DWM 合成后本页自动回落到原生覆盖层，抓帧模式随之关闭。

隐藏与关闭

SetVisible(false) 只隐藏面板，浏览器与宿主窗口保持存活，再次显示几乎瞬时完成，对应窗口的最小化

Close() 释放浏览器与宿主窗口，内存归还系统，之后再次 SetVisible(true) 或 Navigate 会重新创建，对应窗口的关闭

菜单关闭等临时场景用隐藏，长期不用或需要回收内存时用关闭；Shutdown() 是卸载路径，与两者都不同

生命周期与边界

Init() 只检查运行时并登记请求，不会立刻创建浏览器；真正的环境与控制器创建延迟到宿主请求页面之后（Navigate、SetHtml、SetVisible(true) 都会登记请求）的 Process() 安全点执行，因此不会在渲染钩子里重入消息循环，未使用网页时也不会启动浏览器进程。

创建是异步的；完成后 GetState().initialized 为真，之前提交的 Navigate/SetHtml 会自动补发，若期间已请求显示则直接可见。

领域卸载时若创建仍在进行，会等待回调到达后自行释放控制器并销毁宿主窗口，避免父窗口句柄被复用。

SetBounds() 接收与 UI::GetDisplaySize() 同坐标系的矩形（ImGui 显示像素，通常按菜单内容区计算），XBase 内部按游戏客户区比例换算并裁剪到游戏窗口内。

网页渲染为窗口期覆盖层，无法被 ImGui 裁剪，宿主应把矩形限制在菜单窗口可见区域内（菜单滚动时用 UI::GetCurrentWindowRect() 求交集）。

显示时网页子窗口取得焦点，游戏收不到键盘输入；隐藏时焦点交还游戏窗口。独占全屏下不取焦点，改由抓帧模式呈现。

面板聚焦期间按键只到达网页子窗口，XBase 通过加速键事件与系统状态轮询补齐输入，菜单热键仍然可用。

菜单关闭后面板自动隐藏，宿主无需在关闭流程里手动调用 SetVisible(false)。

关闭菜单、切换场景或新游戏时调用 SetVisible(false)；NotifyGameInit() 会自动隐藏。

窗口化与无边框模式下网页渲染为窗口期覆盖层，由 DWM 合成；独占全屏切换为抓帧贴图，两种状态都由 XBase 自动判定。

浏览器数据目录位于 %APPDATA%\com.yuinijika.xbase\webview2，由 XBase 创建，不落在游戏目录内。

导航、标题、前进后退状态通过事件更新，SetStateCallback() 可在游戏线程收到变化通知。

Capability

III

WebView

✅

本地页面

file: 协议下每个页面都是独立安全源，模块脚本与带 crossorigin 的请求会被拦下，因此本地界面必须映射成虚拟主机再加载：

C++

XBase::WebView::Init();
XBase::WebView::MapFolder("xmenu.local", XBase::Platform::CurrentModuleDirectory());
XBase::WebView::Navigate("https://xmenu.local/ui.html");

映射目录下的脚本、样式与 fetch('./config.json') 都按同源处理。

独占全屏

独占全屏时 HWND 覆盖层不参与合成，UsesCaptureMode() 为真，此时：

用 DrawPanel(bounds) 把抓帧画面画出来，必须放在真实的 ImGui 窗口内，否则会被塞进默认 Debug 窗口

用 ForwardPanelInput(bounds, mouse, mouseDown, wheelDelta) 转发鼠标与滚轮

帧率明显低于窗口模式，界面应提示用户切到窗口或无边框模式

运行时要求

API

全屏抓帧模式

隐藏与关闭

生命周期与边界

版本能力

本地页面

独占全屏

评论

On this page

运行时要求

API

全屏抓帧模式

隐藏与关闭

生命周期与边界

版本能力

本地页面

独占全屏