JadeView

核心 API

说明如何启动 JadeView、以及创建窗口时用到的两个结构体各字段分别控制什么。其它函数分栏见左侧。

生命周期与启动

初始化运行时（JadeView_init）

用途：启动库内部的 GUI 线程和事件循环，并登记你的应用叫什么、数据放哪、要不要单实例。调用成功后，你还需等 app-ready 事件，再创建窗口或走本地协议。

C
int32_t JadeView_init(
  int32_t enable_devmod,
  const char* log_path,
  const char* data_directory,
  const char* app_name,
  const char* app_signature,
  int32_t single_instance
);
参数说明
enable_devmod是否打开开发向能力（如 DevTools、调试快捷键）。正式发布一般传 0。
log_path日志写到哪个文件；传 NULL 表示不写文件（是否打控制台由实现决定）。
data_directory数据根路径；NULL 或空则用系统默认（如 %LOCALAPPDATA%）。真正给 WebView 用的目录还会拼上 app_signature 相关子目录。
app_name应用显示名，必填，给协议、通知等场景用。
app_signature应用唯一标识，必填，至少 6 个字符，用来生成数据目录名、单实例管道名等；写错会导致初始化失败。
single_instance非 0 时：整台机器只允许一个你的进程；再开一次会把命令行发给第一次启动的进程，当前这次 JadeView_init 会返回 0。
返回值含义
1已去启动 GUI，但还没就绪，必须等 app-ready。
0没启动起来（参数错、或作为第二实例被踢掉等）。

app-ready 里你会收到什么

成功与失败的 event_data 格式不同（成功是 JSON、失败是纯文本），判定成功只看 window_id == 1，不要靠解析 event_data：

情况window_idevent_data 大致长什么样
正常启动完成1JSON：{"ok":true,"message":"success"}
app_name / app_signature 校验失败0纯文本 "<code>: <message>"（code 为 missing_app_name / missing_app_signature / app_signature_too_short）

程序运行期间的崩溃不走 app-ready，而是通过独立的 crash 事件上报。

请在 JadeView_init 之前 就 jade_on("app-ready", ...)，否则会漏掉第一条通知。

运行消息循环（run_message_loop）

用途：在「exe 自己跑消息循环」的旧集成方式里可能用到。它会阻塞当前线程，直到应用关停（如调用 jadeview_exit）才返回。常见 DLL 嵌入场景下，循环已在 JadeView_init 里起的线程中跑，此函数为可选、一般不用调（与快速上手一致）。

C
int32_t run_message_loop(void);

退出应用（jadeview_exit） v2.4

用途：关掉所有 JadeView 窗口、收尾资源、让事件循环结束。自 v2.4 起，该函数默认等待 GUI 事件循环和 JadeView 自有后台线程完成退出，成功返回后才适合卸载 DLL。

C
int32_t jadeview_exit(void);
返回值含义
1关闭、清理和等待均已完成。
0失败（例如尚未完成初始化）。

jadeview_exit 原始 API 自 v2.2 提供；上面的版本角标表示 v2.4 的退出等待行为更新。

带超时退出（jadeview_exit_wait） v2.4

用途：发起完整退出并等待 GUI 事件循环结束，可由宿主指定最大等待时间。适合 DLL 集成场景在 FreeLibrary 前确认 JadeView 已停止执行代码。

C
int32_t jadeview_exit_wait(uint32_t timeout_ms);
参数说明
timeout_ms等待超时时间，单位为毫秒。传 0 时按最小等待时间处理。
返回值含义
1退出清理已完成，GUI 线程和 JadeView 自有后台线程已完成收尾。
0在指定时间内未完成退出，宿主不得立即卸载 DLL；应稍后再次调用等待。

本地协议服务相关 API（set_protocol_service_path、register_resource、unregister_resource、clear_window_resources）已移至 本地协议服务 独立文档。

右键菜单相关 API（jade_menu_item_create 等）已移至 右键菜单 独立文档。

版本变化速览

2.4 新增与增强

符号 / 能力是干什么的文档
jadeview_exit_wait带超时等待 GUI 事件循环和 JadeView 自有后台线程退出，供 DLL 卸载前确认运行时已停止。带超时退出
webview_go_back / webview_go_forward / webview_can_go_back / webview_can_go_forward原生前进 / 后退导航，以及同步查询是否可前进 / 后退。WebView API
set_webview_permission_handler / clear_webview_permission_handler注册 / 清除统一网页权限处理器，集中允许或拒绝摄像头、麦克风、录屏、文件访问等权限。网页权限 API
WebViewSettings.profile_nameWindows 命名 Profile 会话隔离，用于隔离 Cookie、存储与缓存；Linux 接受但忽略。核心结构体

2.3 新增与增强

符号 / 能力是干什么的文档
yaml_set_str / yaml_get_str / yaml_get_all / yaml_has / yaml_delete / yaml_clear / yaml_delete_file / yaml_keys / yaml_lenYAML 存储接口大幅扩展；并新增数组下标语法 [N]、两阶段查询、负数错误码、原子写入与文件锁。YAML 存储 API
jade_ntp_now通过 NTP 获取网络 UTC 时间戳，不依赖本机时钟；可指定服务器或用内置列表并发查询。系统集成 API
jade-region-drag / jade-region-no-drag基于 HTML 属性的自定义窗口拖动区，不依赖 CSS，右键不弹系统标题栏菜单。窗口交互控制
drag-drop 同步拦截enter / drop 支持同步拦截/消费（回调返回非空指针），over / leave 保持异步。事件类型
IPC 通信链路优化invoke 与广播共用发送路径、高频小事件合并发送；对外接口与旧消息形态兼容。IPC 通信 API

2.0 新增与换名接口（相对旧版）

符号是干什么的
create_borderless_webview_window做一个没有系统标题栏的 WebView 窗口。
get_window_hwnd只有上面这种窗口才能拿到 HWND 给别的 Win32 API 用。
set_protocol_service_path把本地文件夹挂成内置协议根，页面用生成的基地址加载静态资源（替代旧的 create_local_server）。
yaml_set / yaml_get在数据目录里读写 YAML 配置。
getPath / getLocale / get_displays_info常用路径、系统界面语言、多显示器信息。
clear_data_directory清空本应用数据目录（要带确认令牌）。
jadeview_version读 JadeView 自身版本串。
register_url_scheme 等自定义协议、文件关联。
register_global_hotkey 等全局热键（收到 global-hotkey 事件）。
托盘相关见 系统托盘。

核心结构体

窗口选项结构（WebViewWindowOptions）

用途：描述第一个画面长什么样、能不能拖大小、在屏幕哪出现。字段顺序必须与 JadeView.h 中结构体声明一致，少填、多填或类型错位都会导致静默读错内存。

字段控制什么
title窗口标题栏上的文字。
width / height初始宽高（像素）。
resizable用户能不能用鼠标拖边缘改大小。
frame_style要系统边框+标题栏、只要边框不要标题栏、完全无边框、还是无边框+内置标题栏按钮覆盖层（normal / no-titlebar / borderless / title-overlay）。title-overlay 提供有边框+无标题栏+右上角内置标题栏按钮（每个按钮宽度 46 像素，高度默认 32 像素），无需自行实现窗口控制按钮功能（Windows 与 Linux 均支持，Linux 自 v2.3.0-beta.6 起）。
transparent是否透明背景（和 WebView、系统能力有关）。
background_color窗口背景色字符串（如带 # 的十六进制）。
always_on_top是否总在最前。
theme浅色 / 深色 / 跟随系统（Light、Dark、System）。
maximized打开时是否最大化。
maximizable / minimizable标题栏上是否允许最大/最小化按钮生效。
x / y窗口左上角坐标；两个都是 -1 表示让系统帮你居中。
min_* / max_*允许的最小、最大尺寸；0 通常表示不限制。
fullscreen打开时是否全屏。
focus打开后是否抢键盘焦点。
hide_window非 0 时先创建但不显示（适合先加载再 show）。
use_page_icon是否用网页 favicon 当初步窗口图标。
content_protection是否开启防录屏/截屏类保护。
auto_save_state非 0：在数据目录下的 window_state.yaml 里按 window_id 记录窗口最后一次有效的物理左上角坐标；下次用同一 window_id 创建时，若该位置仍落在某块屏的工作区内，则恢复位置（宽高、是否最大化仍以本次创建参数为准）。移动停止约 450ms 后防抖落盘；关闭时也会再存一次。
skip_taskbar非 0：窗口不进任务栏 / Alt-Tab。追加在结构体末尾以保持字段顺序兼容。
no_activate非 0：不抢焦点，点击或显示窗口时不激活它。追加在结构体末尾以保持兼容。

网页行为结构（WebViewSettings）

用途：控制 WebView 里网页的行为（自动播放、右键、UA 等）。传 NULL 表示全用默认。

字段控制什么
autoplay媒体能不能自动播放。
background_throttling窗口在后台时是否降低定时器/动画频率省资源。
allow_right_click是否允许网页右键菜单。0 = 禁用，1 = 允许。
ua自定义 User-Agent。
preload_js页面加载前要注入的一段 JS。
allow_fullscreen网页里全屏 API 是否允许。
postmessage_whitelist页面 postMessage 是否转发给主进程的白名单，值为一条 UTF-8 字符串（通常接近页面的 origin，如 https://example.com）。库在匹配时：event.origin 等于该字符串，或 origin 以该字符串为后缀，则通过。若指针为 NULL/未设置：当前实现下不会放行任何来源（即收不到 postmessage-received）。通过 set_protocol_service_path 加载的内置静态页在实现里会跳过白名单、始终可收。
cors_whitelistCORS 跨域来源白名单，逗号分隔多个域名；用于放行页面对这些来源的跨域请求。
autofill是否启用账号/密码自动填充。0 = 禁用，1 = 启用。(2.2 新增)
general_autofill_enabled是否启用通用表单自动填充（姓名/地址/电话等）。0 = 禁用，1 = 启用。(2.2 新增)
incognito是否以无痕/隐私浏览模式运行。0 = 正常模式，1 = 无痕模式。开启后页面渲染会变慢。(2.2 新增)
disable_clipboard是否禁用剪贴板读写权限。0 = 允许，1 = 禁用。(2.2 新增)
proxy_url代理URL，支持 HTTP 和 SOCKS5 代理（如 "http://127.0.0.1:7890" 或 "socks5://127.0.0.1:1080"）。NULL 表示不使用代理。(2.2 新增)
focusedWebView 初始是否自动获取焦点。0 = 不获取焦点，1 = 自动聚焦（默认 1）。(2.2 新增)
profile_nameWindows 命名 Profile 会话隔离：不同名称之间 Cookie、LocalStorage、IndexedDB、缓存相互隔离；相同名称共享。NULL 或空字符串使用默认 Profile。当前仅 Windows 生效，Linux 接受但忽略。(2.4 新增)

系统集成相关 API（get_cursor_position、clipboard_read_text、clipboard_write_text、jade_print_dialog、jade_get_printer_list）已移至 系统集成 API 独立文档。

Next
窗口 API