v2.3.0-beta.4 (Build 26F08)

• YAML 存储 API 扩展

  • 新增 yaml_set_str / yaml_get_str：强制字符串类型存储与读取
  • 新增 yaml_get_all：读取整个 YAML 文件内容
  • 新增 yaml_has：检查指定路径是否存在
  • 新增 yaml_delete / yaml_clear / yaml_delete_file：路径删除、文件清空、文件删除
  • 新增 yaml_keys：列出指定路径下的所有 key
  • 新增 yaml_len：返回数组长度或对象 key 数量

• YAML 路径语法增强

  • yaml_get / yaml_set 支持数组下标语法 [N]
  • yaml_get 支持两阶段查询：buffer 不足时返回所需字节数（含 NUL）

• 窗口事件拦截

  • drag-drop Enter 事件支持同步拦截，宿主返回非空指针拒绝拖拽
  • drag-drop Drop 事件支持同步消费，宿主返回非空指针表示已处理
  • Over / Leave 保持异步通知
  • 无回调注册时行为不变（兼容现有逻辑）

• 自定义窗口拖动区

  • 新增 HTML 属性 jade-region-drag / jade-region-no-drag，不依赖 CSS 即可拖动窗口
  • jade-region-drag 作用于容器及其全部后代；子元素加 jade-region-no-drag 排除（按钮、输入框等可点击元素）
  • 单击拖动移动窗口、双击最大化/还原；支持系统贴边（Aero Snap），窗口最大化时拖动自动还原
  • 右键不弹出系统标题栏菜单（区别于 -webkit-app-region: drag）
  • 与 -webkit-app-region 并存、互不影响

• IPC 通信优化

  • invoke 与广播消息共用发送路径，减少重复封装
  • 前端消息入口收敛到统一 dispatcher，取消多入口分发
  • 高频小事件合并发送：微任务批处理 flush，减少调度开销
  • 外部 jade.invoke / jade.on 调用方式不变，旧消息形态继续兼容

• NTP时间获取

  • 新增 jade_ntp_now API，获取当前网络时间戳（UTC毫秒），北京时间需+8H
  • 支持传入自定义 NTP 服务器地址；传 NULL/空串时回退到内置服务器列表
  • 指定服务器时单次查询超时 3 秒，失败返回 -1（不回退内置列表）

• 修复 YAML 中间节点覆盖问题：非映射且非空时返回 -2，不再覆盖

• 修复 YAML 序列化失败时清空文件的问题：失败返回 -1，不写盘

• 修复 YAML 非原子写入：改用临时文件 + rename，Windows 下增加重试

• 修复 YAML 无文件锁问题：使用 CreateFileW + LockFileEx

• 修复 YAML CString NUL 截断问题：失败时返回 -1

• 修复无边框窗口（borderless）最大化后客户区四边各溢出约 8px、顶部内容被裁掉的问题：WM_NCCALCSIZE 在最大化时按 resize 边框尺寸内缩四边，使客户区正好等于工作区

• yaml_get / yaml_set 返回值新增负数错误码语义

  • -1 IO 错误 / -2 类型不匹配 / -3 目标已存在 / -4 格式解析失败

• yaml_set 自动解析数值与布尔类型，yaml_set_num / yaml_set_bool 合并到 yaml_set

• 迁移 serde_yaml → serde_yml

• jade_ntp_now 签名变更：新增 const char* ntp_server 参数（ABI 变更，旧调用传 NULL 即保持原行为）

• 拆分 src/ffi/c_api.rs（约 4300 行）为 src/ffi/c_api/ 下的功能子模块（lifecycle / window / tray / dialog / yaml_store / system），对外导出的 C API 保持不变

• build.rs 头文件生成增强：按子模块扫描 FFI 函数、递归扫描事件名常量；修复 cbindgen 类型未变化时误判失败导致头文件无法刷新的问题

• jade.invoke 路径优化，预期提升 5% ~ 20%

• 广播消息路径收敛，预期提升 20% ~ 60%

• 高频小事件合并发送，消息数减少约 50% ~ 90%

• IPC 发送去掉整条消息克隆：小消息发送开销降低约 5%~15%；大载荷消息（≤253MB）拷贝与内存峰值降低约 50% 也收录于 2.2.4

• 事件分发减少分配：高频事件每次少一次回调列表克隆；多订阅者分发的序列化与分配由 K 次降为 1 次（订阅者越多收益越大） 也收录于 2.2.4

• 静态资源内容缓存：重复资产请求免去磁盘读取与 MIME 重算，单请求延迟降低约 70%~95%（视磁盘冷热）

• 媒体流分片去锁内克隆：HTTP Range 请求（视频/音频拖动）每分片不再在锁内克隆整条资源记录，改用共享句柄 + 原子计数，高频分片的元数据处理开销降低约 60%~85%

• 消息保活改为事件驱动：run_message_loop 取消 100ms 轮询，常驻 CPU 占用归零，退出即时响应

• NTP 并行查询：内置服务器列表并发查询、先到先用，弱网/坏节点场景最坏耗时由约 24s 降到约 3~4s

• NTP 时间戳健壮性：防御异常回包导致的时间戳计算下溢

• YAML 与资源接口微优化：减少每次调用的重复系统调用、锁与字符串解析开销；资源 / 分批接口参数解析统一为轻量扫描，默认图标缓存命中缩短锁临界区

收益最明显的场景：多窗口广播、高频状态同步、拖拽类小消息、SPA 资产加载/刷新、媒体流分片、弱网或不可达 NTP 节点环境。

标注 也收录于 x.y.z 的条目，表示同一改动已回合并到对应的维护版本，低版本用户升级后即可获得相同优化。\n\n---\n本版本的文档参考在 beta 目录中

v2.3.0-beta.3 (Build 26F01)

• YAML 存储 API 扩展

  • 新增 yaml_set_str / yaml_get_str：强制字符串类型存储与读取
  • 新增 yaml_get_all：读取整个 YAML 文件内容
  • 新增 yaml_has：检查指定路径是否存在
  • 新增 yaml_delete / yaml_clear / yaml_delete_file：路径删除、文件清空、文件删除
  • 新增 yaml_keys：列出指定路径下的所有 key
  • 新增 yaml_len：返回数组长度或对象 key 数量

• YAML 路径语法增强

  • yaml_get / yaml_set 支持数组下标语法 [N]
  • yaml_get 支持两阶段查询：buffer 不足时返回所需字节数（含 NUL）

• 窗口事件拦截

  • drag-drop Enter 事件支持同步拦截，宿主返回非空指针拒绝拖拽
  • drag-drop Drop 事件支持同步消费，宿主返回非空指针表示已处理
  • Over / Leave 保持异步通知
  • 无回调注册时行为不变（兼容现有逻辑）

• IPC 通信优化

  • invoke 与广播消息共用发送路径，减少重复封装
  • 前端消息入口收敛到统一 dispatcher，取消多入口分发
  • 高频小事件合并发送：微任务批处理 flush，减少调度开销
  • 外部 jade.invoke / jade.on 调用方式不变，旧消息形态继续兼容

• NTP时间获取

  • 新增 jade_ntp_now API，获取当前网络时间戳（UTC毫秒），北京时间需+8H
  • 支持传入自定义 NTP 服务器地址；传 NULL/空串时回退到内置服务器列表
  • 指定服务器时单次查询超时 3 秒，失败返回 -1（不回退内置列表）

• 修复 YAML 中间节点覆盖问题：非映射且非空时返回 -2，不再覆盖

• 修复 YAML 序列化失败时清空文件的问题：失败返回 -1，不写盘

• 修复 YAML 非原子写入：改用临时文件 + rename，Windows 下增加重试

• 修复 YAML 无文件锁问题：使用 CreateFileW + LockFileEx

• 修复 YAML CString NUL 截断问题：失败时返回 -1

• yaml_get / yaml_set 返回值新增负数错误码语义

  • -1 IO 错误 / -2 类型不匹配 / -3 目标已存在 / -4 格式解析失败

• yaml_set 自动解析数值与布尔类型，yaml_set_num / yaml_set_bool 合并到 yaml_set

• 迁移 serde_yaml → serde_yml

• jade_ntp_now 签名变更：新增 const char* ntp_server 参数（ABI 变更，旧调用传 NULL 即保持原行为）

• 拆分 src/ffi/c_api.rs（约 4300 行）为 src/ffi/c_api/ 下的功能子模块（lifecycle / window / tray / dialog / yaml_store / system），对外导出的 C API 保持不变

• build.rs 头文件生成增强：按子模块扫描 FFI 函数、递归扫描事件名常量；修复 cbindgen 类型未变化时误判失败导致头文件无法刷新的问题

• jade.invoke 路径优化，预期提升 5% ~ 20%

• 广播消息路径收敛，预期提升 20% ~ 60%

• 高频小事件合并发送，消息数减少约 50% ~ 90%

收益最明显的场景：多窗口广播、高频状态同步、日志/进度/拖拽类小消息、大量连续触发的 UI 事件。\n\n---\n本版本的文档参考在 beta 目录中

v2.3.0-beta.2 (Build 26F02)

• YAML 存储 API 扩展

  • 新增 yaml_set_str / yaml_get_str：强制字符串类型存储与读取
  • 新增 yaml_get_all：读取整个 YAML 文件内容
  • 新增 yaml_has：检查指定路径是否存在
  • 新增 yaml_delete / yaml_clear / yaml_delete_file：路径删除、文件清空、文件删除
  • 新增 yaml_keys：列出指定路径下的所有 key
  • 新增 yaml_len：返回数组长度或对象 key 数量

• YAML 路径语法增强

  • yaml_get / yaml_set 支持数组下标语法 [N]
  • yaml_get 支持两阶段查询：buffer 不足时返回所需字节数（含 NUL）

• 窗口事件拦截

  • drag-drop Enter 事件支持同步拦截，宿主返回非空指针拒绝拖拽
  • drag-drop Drop 事件支持同步消费，宿主返回非空指针表示已处理
  • Over / Leave 保持异步通知
  • 无回调注册时行为不变（兼容现有逻辑）

• IPC 通信优化

  • invoke 与广播消息共用发送路径，减少重复封装
  • 前端消息入口收敛到统一 dispatcher，取消多入口分发
  • 高频小事件合并发送：微任务批处理 flush，减少调度开销
  • 外部 jade.invoke / jade.on 调用方式不变，旧消息形态继续兼容

• NTP时间获取

  • 新增 jade_time_now API，获取当前网络时间戳（UTC毫秒），北京时间需+8H

• 修复 YAML 中间节点覆盖问题：非映射且非空时返回 -2，不再覆盖

• 修复 YAML 序列化失败时清空文件的问题：失败返回 -1，不写盘

• 修复 YAML 非原子写入：改用临时文件 + rename，Windows 下增加重试

• 修复 YAML 无文件锁问题：使用 CreateFileW + LockFileEx

• 修复 YAML CString NUL 截断问题：失败时返回 -1

• yaml_get / yaml_set 返回值新增负数错误码语义

  • -1 IO 错误 / -2 类型不匹配 / -3 目标已存在 / -4 格式解析失败

• yaml_set 自动解析数值与布尔类型，yaml_set_num / yaml_set_bool 合并到 yaml_set

• 迁移 serde_yaml → serde_yml

• jade.invoke 路径优化，预期提升 5% ~ 20%

• 广播消息路径收敛，预期提升 20% ~ 60%

• 高频小事件合并发送，消息数减少约 50% ~ 90%

收益最明显的场景：多窗口广播、高频状态同步、日志/进度/拖拽类小消息、大量连续触发的 UI 事件。\n\n---\n本版本的文档参考在 beta 目录中

v2.3.0-beta.1 (Build 26F01)

• 新增 - yaml_set_str 接口，强制字符串存储

• 新增 - yaml_get_str 接口，内部 CoTaskMemAlloc 返回字符串指针，调用方 CoTaskMemFree 释放

• 新增 - yaml_get_all 接口，读取整个 YAML 文件

• 新增 - yaml_has 接口，检查路径是否存在

• 新增 - yaml_delete 接口，删除指定路径

• 新增 - yaml_clear 接口，清空文件为 {}

• 新增 - yaml_delete_file 接口，删除文件

• 新增 - yaml_keys 接口，列出路径下的所有 key

• 新增 - yaml_len 接口，返回数组长度/对象 key 数

• 新增 - yaml_get 两阶段查询支持，返回值 ≥ 2 时表示所需字节数（含 NUL）

• 新增 - yaml_get/yaml_set 路径语法支持数组下标 [N]

• 新增 - drag-drop 事件拦截支持

  Enter 事件：同步回调，宿主返回非空指针则拒绝拖拽
  Drop 事件：同步回调，宿主返回非空指针表示已消费，空指针表示未消费
  Over/Leave 事件：保持异步通知
  无回调注册时保持 return true（兼容现有行为）

• 修复 - YAML 中间节点覆盖问题：非映射且非空时返回 -2，不覆盖

• 修复 - YAML 序列化失败时清空文件的问题：失败返回 -1，不写盘

• 修复 - YAML 非原子写入：使用临时文件 + rename，Windows 加重试

• 修复 - YAML 无文件锁：使用 CreateFileW + LockFileEx

• 修复 - YAML CString NUL 截断问题：失败返回 -1

• 调整 - yaml_get/yaml_set 返回值增加负数错误码

  -1 IO 错误 / -2 类型不匹配 / -3 目标已存在 / -4 格式解析失败

• 调整 - yaml_set 已自动解析数值/布尔类型，无需单独的 yaml_set_num/yaml_set_bool

• 迁移 - serde_yaml → serde_yml\n\n---\n本版本的文档参考在 beta 目录中

v2.3.0-beta.0 (Build 26F02)

JadeView v2.3 已发布！本版本带来了完整的 YAML 配置文件操作 API、拖拽事件拦截支持，以及多项稳定性修复。

重要变更

YAML 配置文件操作 API

新增一组 YAML 文件操作接口，支持读写、查询、删除等完整生命周期管理：

• yaml_set / yaml_set_str — 写入配置项，yaml_set 自动推断类型，yaml_set_str 强制字符串存储
• yaml_get / yaml_get_str — 读取配置项，支持两阶段查询模式（buffer 为空时返回所需字节数）
• yaml_get_all — 读取整个 YAML 文件内容
• yaml_has — 检查路径是否存在
• yaml_delete — 删除指定路径
• yaml_clear — 清空文件为 {}
• yaml_delete_file — 删除文件
• yaml_keys — 列出路径下的所有 key
• yaml_len — 返回数组长度 / 对象 key 数

路径语法支持数组下标 [N]，如 servers[0].host。所有写入操作使用原子写入（临时文件 + rename）和文件锁（CreateFileW + LockFileEx）保证数据安全。

拖拽事件拦截

新增 drag-drop 事件拦截支持，宿主进程可控制拖拽行为：

• Enter 事件：同步回调，返回非空指针拒绝拖拽进入
• Drop 事件：同步回调，返回非空指针表示已消费（不传递到网页），空指针表示未消费
• Over / Leave 事件：保持异步通知
• 无回调注册时保持 return true（兼容现有行为）

问题修复

• 修复 YAML 中间节点覆盖问题：非映射且非空时返回 -2，不覆盖
• 修复 YAML 序列化失败时清空文件的问题：失败返回 -1，不写盘
• 修复 YAML 非原子写入：使用临时文件 + rename，Windows 加重试
• 修复 YAML 无文件锁：使用 CreateFileW + LockFileEx
• 修复 YAML CString NUL 截断问题：失败返回 -1

破坏性变更

行为变更：yaml_get / yaml_set 返回值

返回值增加负数错误码：-1 IO 错误 / -2 类型不匹配 / -3 目标已存在 / -4 格式解析失败。此前部分错误场景返回 0，现在统一返回对应负数。

行为变更：yaml_set 自动类型推断

yaml_set 已自动解析数值 / 布尔类型，无需单独的 yaml_set_num / yaml_set_bool。如需强制字符串存储，请使用 yaml_set_str。

依赖变更

• 迁移 serde_yaml → serde_yml

v2.2.3 (Build 26F01)

• 调整 - 无边框窗口时，如果边框是可调整大小的，仍可以手动拉伸窗口大小。
• 优化 - 自定义标题栏覆盖层的标题栏按钮图标显示

  更加符合原生图标，全平台强制使用Win11风格图标

• 修复使用set_window_frame_style修改边框部分样式时可能无法生效的问题
• set_window_frame_style API标记为不可靠API（不推荐使用的API），因Windows自身的窗口Dwm管理机制，导致在某些情况下无法生效。

v2.2.2 (Build 26F04)

• 修复 IPC 大数据响应（超过 64KB）无法返回前端的问题
• 精简内部调试日志，减少日志文件体积

JadeView v2.2.1 (Build 26F01)

• 代码减法，减少 DLL 体积
• no-titlebar 和 titlebaroverlay 模式下，清除非Win11系统下 DWM 绘制的细边黑色框线
• 修复 set_titlebar_overlay_style 在窗口未创建完成时调用无效的问题
• 修复 titlebaroverlay 模式下鼠标悬浮标题栏按钮不显示提示文本（tooltip）的问题
• 修复事件广播在多窗口场景下性能下降的问题

JadeView v2.2.0 (Build 26F06)

彻底完善了 v2 的能力
这次更新，我们终于把那些你一直想要、却一直没给的东西做出来了：右键菜单完全由你掌控、本地文件安全暴露（以前根本做不到）、开发时热载自动刷新、性能飞跃，还一口气加了 32 个全新 C API。

v2.2 不是一个小版本，它值得一次大版本号跃升。

---

• 监听 context-menu 事件，获取完整上下文（坐标、目标类型、链接/选中文本、默认菜单项列表）

• 用 jade_menu_item_* API 自由创建命令、分隔线、复选框、单选、子菜单，或直接复用 WebView2 原生项（kind=5，如 copy/paste/saveImageAs）
• 动态控制启用/勾选，用户点击后返回自定义 item_id
  👉 文档

• register_resource：传入本地文件路径，生成 token 化 URL（/---jade---resource--?token=xxx）

• 前端只能看到 token，真实路径永不泄露

• 支持 Range 请求（视频拖动秒切）、自动 MIME、窗口关闭自动清理、最多 4096 条注册
  👉 文档

• set_protocol_service_path 新增 hot_reload 参数，开发时启用后监听资源目录变更，自动清除缓存并刷新页面

• 内置 150ms 防抖，不再需要手动刷新
  👉 文档

场景	优化	效果
窗口创建 / IPC	常驻线程替代 thread::spawn	窗口创建快 1.5–4ms
SPA 静态资源缓存	淘汰全清 → 保留最近 1024 条	淘汰后首次加载 10–100ms → 1–5ms
页面导航	移除冗余日志	每次节省 5–20μs
启动速度	综合优化	+10%~20%
IPC/事件系统	调度优化	+5~30%

---

分类	API
窗口状态查询	get_window_bounds, is_window_minimized, is_window_visible, is_window_focused, is_window_fullscreen → 文档
窗口约束	set_window_min_size, set_window_max_size, set_window_resizable → 文档
DevTools 控制	open_devtools, close_devtools, is_devtools_open → 文档
鼠标穿透	set_window_ignore_cursor_events → 文档
任务栏特效	set_window_progress, flash_window → 文档
系统集成	鼠标位置、剪贴板读写、打印机列表 → 文档
对话框增强	jade_print_dialog, show_about_dialog → 文档
浏览数据清除	clear_browsing_data → 文档
窗口位置尺寸	获取 JSON 格式位置和尺寸 → 文档
托盘图标增强	set_tray_icon_from_data（二进制数据） → 文档
退出应用	jadeview_exit 替代 cleanup_all_windows → 文档
导航扩展	navigate_to_url 支持自定义请求头 → 文档
智能编码转换	smart_convert_encoding → 文档

---

事件	说明	文档
drag-drop	替代 file-drop，覆盖 enter/over/drop/leave 完整拖拽生命周期	→
crash	崩溃时返回错误代码（不泄露源码）	→
app-ready	统一格式：成功 window_id=1, data="success"；失败 window_id=0, data=错误描述	→
webview-download-completed	下载完成时触发	→
devtools-open-state	DevTools 打开/关闭时触发	→
context-menu 增强	新增 default_menu_names 字段（默认菜单项列表）	→

---

函数签名：

// hot_reload: 是否启用热载模式 (0=禁用, 1=启用)，仅文件系统模式有效
int32_t JADEVIEW_CALL set_protocol_service_path(const char* root_path, char* url_buffer, size_t buffer_size, int32_t hot_reload);

• 从 3 个参数 升级为 4 个参数
• 旧代码调用必须补充 hot_reload=0 保持兼容
• 仅文件系统模式生效，启用后自动监听文件变更并刷新页面
  👉 文档

navigate_to_url 新增 headers_json 参数（向后兼容）
👉 文档

• 新增 jadeview_exit()，废弃 cleanup_all_windows() → 文档
• 新增 smart_convert_encoding() 智能转码 API → 文档

---

• autofill – 账号密码自动填充（Windows WebView2 1.0.902+）
• general_autofill_enabled – 通用表单自动填充
• incognito – 无痕模式（不保存 cookie/缓存）
• disable_clipboard – 禁用剪贴板（Windows/Linux）
• proxy_url – HTTP CONNECT 或 SOCKS5 代理
• focused – 初始是否获取焦点（Windows/Linux）
  👉 平台支持详情

---

1. JAPK 加载异常：超过最大输出长度时返回错误而非崩溃，通过加载失败事件通知。
2. 路径获取锁不一致：一次加锁同时读取数据目录和执行路径，保证原子性。
3. 最大化窗口顶部裁切：修复无边框窗口最大化后内容被裁切 8px 的问题。
4. 启动窗口时偶发慢速：优化窗口创建时的渲染速度。

---

v2.2 是一次高含金量的大版本，强烈建议所有开发者适配升级。

v2.1.1

• 修复一些自定义标题栏覆盖层的问题

并向上天祭祀了一名攻城狮