跳到主要内容

核心 API

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

生命周期与启动​

初始化运行时（JadeView_init）​

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

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 里你会收到什么​

情况window_idevent_data 大致长什么样
正常启动完成1文本 success
app_name / app_signature 校验失败0JSON：{"ok":false,"code":"...","message":"..."}
GUI 线程崩溃0一段纯文字错误说明

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

运行消息循环（run_message_loop）​

用途：在「exe 自己跑消息循环」的旧集成方式里可能用到。常见 DLL 嵌入场景下，循环已在 JadeView_init 里起的线程中跑，一般不用调。

int32_t run_message_loop(void);

清理全部窗口（cleanup_all_windows）​

用途：关掉所有 JadeView 窗口、收尾资源、让事件循环结束。相当于应用退出前的清理。

int32_t cleanup_all_windows(void);
返回值含义
1已发起关闭与清理。
0失败（例如尚未完成初始化）。

本地协议服务​

设置本地协议服务路径​

用途：将本地目录或 JAPK 资源包注册为 JadeView 内置访问的根目录，并生成一个协议 URL。页面里可以用这个地址加载 JS/CSS/图片，就像小型静态站点，而不必再自己起 Node 或 IIS。

int32_t set_protocol_service_path(
  const char* root_path,
  char* url_buffer,
  size_t buffer_size
);

参数：

  • root_path string - 本地静态资源根。两种形式：
    • 目录：指向包含 index.html 等前端产物的文件夹路径；
    • .japk 文件：指向磁盘上已存在的 JAPK 归档文件。JadeView 会映射该文件并在 JADE:// 下按包内相对路径提供资源（不解压到临时目录）；请求未命中时同样回退到包内的 index.html（SPA）。扩展名匹配不区分大小写（如 .JAPK）。若归档中某些条目为「解包」存储（旁路 .japk.unpacked / 等价目录），实现会尝试从磁盘旁路读取对应字节。
  • url_buffer char* - 输出参数，用于存储生成的协议 URL（NUL 结尾）
  • buffer_size size_t - url_buffer 的字节容量（含结尾 NUL）

返回值：

  • 1 - 成功
  • 0 - 失败（路径无效、缓冲太小、尚未初始化等）

须在 app-ready 成功之后再调。

与旧版 create_local_server 的差异：过去要在参数里单独传 appname，用来拼内置主机名（如 http://jade.{appname}/...）。2.0 改为由 JadeView_init 已登记的 app_name / app_signature 推导协议身份，因此 C API 少一个参数，避免与初始化信息不一致。

旧 API2.0
create_local_server(root_path, appname, url_buffer, buffer_size)set_protocol_service_path(root_path, url_buffer, buffer_size)

版本变化速览​

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 为 Windows 专属，提供有边框+无标题栏+右上角内置标题栏按钮，无需自行实现窗口控制按钮功能。
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 后防抖落盘；关闭时也会再存一次。
注意

2.0 已删掉旧版的 remove_titlebar、borderless、no_center 等字段，必须用 frame_style 和 x/y=-1 居中，否则结构体对不上会静默错位。

网页行为结构（WebViewSettings）​

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

字段控制什么
autoplay媒体能不能自动播放。
background_throttling窗口在后台时是否降低定时器/动画频率省资源。
disable_right_click是否禁用网页右键菜单。
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 加载的内置静态页在实现里会跳过白名单、始终可收。