常见问题
安装与环境
支持哪些操作系统和架构？
Windows 10 / 11，x86（win32）与 x64。模块内静态库按编译目标自动选择。
需要随程序分发 DLL 吗？
不需要。模块以静态库形式联入工程，产物是单个 exe；运行时只依赖 WebView2 Runtime（Win11 自带）。
如何开始使用？
安装模块 → 项目中引用 火山.JadeView → 声明 变量 Jade <类型 = JadeView> → 点击变量旁的闪电图标快速声明事件回调。
初始化与生命周期
初始化 返回假 / 程序启动不起来怎么排查？
给 初始化 的 日志路径 传一个文件路径落盘日志，失败原因会记录在内。常见原因：应用标识太短（建议 ≥6 字符）、数据目录不可写、单实例模式下已有实例在运行（此时本进程会把命令行转发给首实例后退出，属正常行为）。
为什么窗口要在 应用就绪 事件里创建？
创建窗口 依赖运行时就绪。在 初始化 返回前后直接调用会返回 0；JadeView_应用就绪 是初始化完成后的第一入口，在这里建窗才可靠。
哪些事件需要手动订阅？
可拦截事件与特殊事件：窗口即将关闭、即将导航、请求新窗口、下载开始、菜单事件、自定义菜单事件、文件拖放。用 Jade.订阅事件 (订阅_视图事件.xxx) 在 初始化 前订阅；其余普通事件 初始化 时自动订阅。
可拦截事件怎么返回？
返回 1 拦截，返回 0 放行。普通事件的返回值一律忽略。下载开始 语义相反方向注意：SDK 默认拦截下载，回调放行才有下载。
事件与 IPC
接收事件方法怎么写最省事？
声明 变量 Jade <类型 = JadeView> 后点击变量旁的闪电图标，选择要接收的事件即可自动生成方法（名称、参数签名全部匹配）。回调第一件事判断 来源对象 == Jade。
事件回调里能弹同步对话框、做耗时操作吗？
不建议。事件与 IPC 回调可能来自库的工作线程，阻塞会导致前端 invoke 超时甚至界面卡顿。对话框用 _异步 版本；耗时工作交给线程，完成后 发送IPC消息 推结果。
前端 jade.invoke 收不到应答？
依次检查：① 是否先 置IPC频道回调 再 注册IPC通道；② 回调方法是否带 @强制输出 = 真 和正确的 @输出名；③ 回调是否对该通道返回了非空文本（空文本 = 不回传，前端会一直等到超时）；④ 页面是否经协议服务加载（外部域受 源站白名单 限制）。
类成员变量能和事件参数同名吗？
不能。例如成员变量叫 热键ID，而 全局热键 事件的参数也叫 热键ID，编译会报「发现了重复的名称」。成员变量换个名字（如 已注册热键ID）即可。
窗口与外观
Mica / Acrylic 材质不生效？
三个条件：窗口选项.透明窗口 = 真；页面 body 背景透明；系统是 Windows 11（用 Jade.系统.是否为Win11() 判断，非 Win11 降级 置背景色 纯色底）。
页面里的下拉、弹层看起来是透明的？
透明窗口下，页面内半透明浮层会直接透到桌面——CSS backdrop-filter 只能模糊页面内像素，够不着 DWM 材质层。浮层请用不透明底色。
无标题栏窗口怎么实现拖动？
页面元素加 HTML 布尔属性 jade-region-drag（内部可点击区域加 jade-region-no-drag 挖洞），运行时自动注入支持，无需 JS。
取句柄 返回 0？
标准窗口（创建窗口）库有意不暴露 HWND，固定返回 0；只有 创建无边框窗口 创建的窗口返回有效句柄。
对话框与脚本
异步对话框需要手动释放结果吗？
不需要。回调收到的已是稳定的文本型 JSON，底层指针由模块自动管理。
执行脚本 的返回值是执行结果吗？
不是。返回值是递增的请求 id（>0 提交成功，0 失败）。JS 的执行结果经 脚本执行结果 事件按 id 异步回传。
存储与资源
YAML 什么时候能用？
初始化 之后。数据文件存于初始化设置的数据目录，文件名禁止 \ / .. : 等路径穿越字符。
协议服务目录有什么禁忌？
站点目录不要与数据目录相同或嵌套——库持续写数据会触发「写 → 热载刷新」死循环。
JAPK 加载失败怎么排查？
加载字节集 返回负数错误码（-5 签名验证失败、-6 应用名/标识与 初始化 不一致、-9 未设置公钥等，完整表见 API 参考），详情同时经 应用包加载失败 事件回报。免费版打包的 JAPK 请用「填路径」方式加载而非字节集。
平台相关
打包成 GUI 版后看不到 调试输出？
GUI 程序没有控制台。给 初始化 传 日志路径 落盘日志，或开发期用火山 IDE 调试运行查看输出。
文本工程文件编码有什么要求？
火山当前版本的 .wsv / .vprj 等文本工程文件默认 UTF-8 无 BOM。模块内部已自动处理火山文本（UTF-16）与底层（UTF-8）的转换，业务代码无需关心。
版本信息
文档与最新发布的模块版本保持同步，历史变更见仓库 Releases。