2 函数 · 桌面窗口 + app 节点 · MIT(webview/webview 0.12.0)

webview 函数参考

桌面窗口扩展(第 16 扩展):脚本侧仅暴露两个可用性探测 API;窗口控制由宿主 class: "app" 服务节点持有——启动显示加载窗、服务就绪自动打开界面、关窗优雅停机。无 webview 环境自动降级 headless。

可用性探测(2 函数)

xsWebviewAvailable 探测

当前环境是否支持 webview 窗口(Windows:WebView2 Runtime 已安装)。脚本用它决定 UI 层是否启用浏览器跳转等桌面行为。

bool xsWebviewAvailable(void);

xsWebviewVersion 版本

后端版本字符串(借用指针;不可用时 NULL)。v1 窗口生命周期不进脚本——由 app 节点全权管理。

const char* xsWebviewVersion(void);

app 服务节点

xs.json 中 "class": "app" 的服务节点 = 本地 HTTP 服务 + webview 桌面窗口:

  • 启动:加载窗先显示(本地 HTTP 就绪前);服务就绪自动打开主界面
  • 停机:用户关窗即触发优雅停机(等效 Ctrl+C 五阶段);window.close: "hide" 则隐藏不停机,再次双击经单实例检测唤起既有窗口
  • 降级:无 WebView2 Runtime 的环境按 install_fallback 兜底(见下矩阵)
  • 与单文件发布组合:xs pack 打包后 = 双击即用的单 exe 桌面应用

平台与变体降级矩阵

构建变体平台WebView2 状态行为
webview 扩展WindowsRuntime 已装完整功能:加载窗、就绪自动开 URL、close 语义
webview 扩展WindowsRuntime 缺失按 install_fallback:ask 问询 / silent 静默安装 / headless 直接降级;安装失败一律落 headless
webview 扩展Linux—(无窗口后端)headless:服务照常,日志打 [xs] app 'main': open http://127.0.0.1:<port>/ in a browser
无扩展任意—同 headless,外加一行 webview extension not built in, window ignored;class: "app" 配置始终可解析(跨变体同一份 xs.json)

前端永远 best-effort:窗口线程任何失败(创建失败、无 Runtime、用户拒绝安装、UI 线程异常)只降级为日志,绝不让引擎装配与停机链走 fail 路径——窗口是显示层,服务是本体。WebView2 渲染器为独立进程,页面崩溃不传染 xs。

window 描述符 9 字段(title / width / height / min_width / min_height / url / devtools / close / install_fallback)的逐字段约束见 xs.json 字段参考 · app 节点;port: 0 自动分配与粘滞语义亦在该页。

零运行时 DLL:导入表仅系统 DLL;WebView2Loader.dll 运行时从已装 Runtime 目录定位。二进制增量约 296 KB。设计细节见仓库 docs/Webview扩展与app节点设计.md。