可用性探测(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 扩展 | Windows | Runtime 已装 | 完整功能:加载窗、就绪自动开 URL、close 语义 |
| webview 扩展 | Windows | Runtime 缺失 | 按 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。