跳到主要内容

窗口 API

窗口 API 提供了创建和管理 WebView 窗口的所有功能，包括创建窗口、导航、调整大小、设置主题等。

以下函数都针对某个 window_id（创建窗口时返回的整数）。没有特殊说明时，成功多为 1，失败为 0。

创建窗口​

创建普通窗口​

创建一个带系统标题栏和边框的浏览器窗口，里面跑 WebView。这是最常用的主窗口创建方式。

uint32_t create_webview_window(
  const char* url,
  uint32_t parent_window_id,
  const WebViewWindowOptions* options,
  const WebViewSettings* webview_settings
);

参数：

  • url string - 第一次打开的网址或本地协议地址

  • parent_window_id uint32_t - 父窗口，0 表示顶层窗口

  • options WebViewWindowOptions* (可选) - 窗口外观配置，可传 NULL 使用默认值

    WebViewWindowOptions 选项：

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

  • webview_settings WebViewSettings* (可选) - 网页行为配置，可传 NULL 使用默认值

    WebViewSettings 选项：

    • autoplay int32_t - 媒体能不能自动播放
    • background_throttling int32_t - 窗口在后台时是否降低定时器/动画频率省资源
    • disable_right_click int32_t - 是否禁用网页右键菜单
    • ua string - 自定义 User-Agent
    • preload_js string - 页面加载前要注入的一段 JS
    • allow_fullscreen int32_t - 网页里全屏 API 是否允许
    • postmessage_whitelist string - 页面 postMessage 是否转发给宿主的白名单，值为一条 UTF-8 字符串（通常接近页面的 origin，如 https://example.com）。库在匹配时：event.origin 等于该字符串，或 origin 以该字符串为后缀，则通过。若指针为 NULL/未设置：当前实现下不会放行任何来源（即收不到 postmessage-received）。通过 set_protocol_service_path 加载的内置静态页在实现里会跳过白名单、始终可收
    • cors_whitelist string - 版本支持 v2.1+， CORS 来源白名单，逗号或分号分隔的域名列表（如 "http://198.18.0.1:8001, http://localhost:3000"）。
      • 严格精确匹配，不支持通配符。设置后仅允许白名单内的来源跨域请求 JadeView 内部 API（invoke、on）；不设置（NULL）或空字符串则不允许任何跨域，无法与程序通信。

返回值：

  • > 0 - 窗口 id，真正画出来可能稍晚，可结合 window-created 等事件
  • 0 - 失败，例如在 app-ready 之前就调用了
注意

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

创建无边框窗口​

创建一个没有系统标题栏的 WebView 窗口，适合自绘标题栏、悬浮工具窗等场景。边框样式固定为无边框。

uint32_t create_borderless_webview_window(
  const char* url,
  const WebViewSettings* webview_settings
);

参数：

  • url string - 第一次打开的网址或本地协议地址
  • webview_settings WebViewSettings* (可选) - 网页行为配置，可传 NULL 使用默认值

返回值：

返回非 0 即 window_id。导航、IPC、执行 JS 和普通窗口一样用这个 id。

获取窗口句柄​

在 C/C++ 里要把窗口交给别的 Win32 API（例如 SetWindowPos、子控件挂靠）时，需要 HWND。

注意：只有用 create_borderless_webview_window 创建的窗口才会返回有效句柄数值；普通 create_webview_window 一律返回 0（库故意不暴露）。

size_t get_window_hwnd(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

导航与脚本​

导航到 URL​

让指定窗口里的网页打开另一个地址（http、file、自定义协议等）。

int32_t navigate_to_url(uint32_t window_id, const char* url);

参数：

  • window_id uint32_t - 目标窗口 id
  • url string - 要导航到的地址

刷新页面​

重新加载当前页，和用户按 F5 类似。

int32_t reload_webview_window(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

执行 JavaScript​

往页面里注入并执行一段 JavaScript。

若需要执行结果，通过事件 javascript-result 等取回（见 事件类型）。

返回值只表示「请求有没有提交成功」，不是 JS 的返回值。

int32_t execute_javascript(uint32_t window_id, const char* script);

参数：

  • window_id uint32_t - 目标窗口 id
  • script string - 要执行的 JavaScript 代码

设置网页缩放​

整页缩放，例如 1.0 为 100%，1.5 为 150%。

int32_t set_webview_zoom(uint32_t window_id, double level);

参数：

  • window_id uint32_t - 目标窗口 id
  • level double - 缩放比例

标题、位置、大小、显示​

设置窗口标题​

改变窗口标题栏上显示的文字（和 HTML 里的 <title> 可以不同）。

int32_t set_window_title(uint32_t window_id, const char* title);

参数：

  • window_id uint32_t - 目标窗口 id
  • title string - 新的窗口标题

设置窗口大小​

按像素改变窗口宽度和高度。

int32_t set_window_size(uint32_t window_id, int32_t width, int32_t height);

参数：

  • window_id uint32_t - 目标窗口 id
  • width int32_t - 新的宽度（像素）
  • height int32_t - 新的高度（像素）

设置窗口位置​

按像素改变窗口在屏幕上的位置。

int32_t set_window_position(uint32_t window_id, int32_t x, int32_t y);

参数：

  • window_id uint32_t - 目标窗口 id
  • x int32_t - 新的 X 坐标
  • y int32_t - 新的 Y 坐标

显示或隐藏窗口​

显示或隐藏窗口（最小化以外的显隐）。

int32_t set_window_visible(uint32_t window_id, int32_t visible);

参数：

  • window_id uint32_t - 目标窗口 id
  • visible int32_t - 非 0 显示，0 隐藏

让窗口获得焦点​

让该窗口拿到键盘焦点。

int32_t set_window_focus(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

设置窗口置顶​

是否置顶，不被其它普通窗口挡住。

int32_t set_window_always_on_top(uint32_t window_id, int32_t always_on_top);

参数：

  • window_id uint32_t - 目标窗口 id
  • always_on_top int32_t - 非 0 置顶，0 取消置顶

请求重绘​

通知系统重画客户区（一般很少需要手动调用）。

int32_t request_redraw(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

最大化、全屏、是否可点​

最小化窗口​

把窗口收到任务栏。

int32_t minimize_window(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

切换最大化状态​

在最大化和还原之间切换一下。

int32_t toggle_maximize_window(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

查询是否最大化​

查询当前是不是最大化状态。

int32_t is_window_maximized(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

返回值：

  • 1 - 当前是最大化状态
  • 0 - 当前不是最大化状态

设置全屏​

进入或退出全屏（铺满显示器，不是单纯最大化）。请求会异步生效；也可监听 window-fullscreen 事件。

int32_t set_window_fullscreen(uint32_t window_id, int32_t fullscreen);

参数：

  • window_id uint32_t - 目标窗口 id
  • fullscreen int32_t - 非 0 进入全屏，0 退出全屏

启用或禁用窗口​

禁用窗口时用户点不了上面控件（像模态对话框背后的灰窗）；传非 0 恢复。

int32_t set_window_enabled(uint32_t window_id, int32_t enabled);

参数：

  • window_id uint32_t - 目标窗口 id
  • enabled int32_t - 非 0 启用，0 禁用

主题、背景、防录屏​

设置窗口明暗主题​

控制窗口和 WebView 使用浅色、深色还是跟随系统主题。

更细的说明见 主题管理。

int32_t set_window_theme(uint32_t window_id, const char* theme);

参数：

  • window_id uint32_t - 目标窗口 id
  • theme string - 主题字符串，可选值：Light、Dark、System

获取当前窗口主题​

查询当前窗口使用的主题。

int32_t get_window_theme(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

设置窗口背景材质​

Windows 11 下设置云母、亚克力等系统背景材质。

可用字符串见 主题管理。

int32_t set_window_backdrop(uint32_t window_id, const char* backdrop_type);

参数：

  • window_id uint32_t - 目标窗口 id
  • backdrop_type string - 背景材质类型

设置窗口背景色​

设置窗口背景色（十六进制字符串）。

int32_t set_window_background_color(uint32_t window_id, const char* background_color_hex);

参数：

  • window_id uint32_t - 目标窗口 id
  • background_color_hex string - 背景色十六进制字符串，如 #FF0000

设置内容保护​

打开后，部分截屏/录屏软件较难采到窗口内容（效果因系统和采集方式而异）。

int32_t set_content_protection(uint32_t window_id, int32_t content_protection);

参数：

  • window_id uint32_t - 目标窗口 id
  • content_protection int32_t - 非 0 启用保护，0 禁用保护

边框样式​

运行时修改窗口边框样式​

动态修改窗口的边框样式，无需重新创建窗口。

int32_t set_window_frame_style(uint32_t window_id, const char* frame_style);

参数：

  • window_id uint32_t - 目标窗口 id
  • frame_style string - 边框样式字符串，可选值：normal（有边框+标题栏）、no-titlebar（有边框+无标题栏）、borderless（无边框+无标题栏）、title-overlay（有边框+无标题栏+内置标题栏按钮）

自定义标题栏覆盖层样式（Windows 专属）​

自定义 title-overlay 样式窗口的标题栏按钮覆盖层外观。

int32_t set_titlebar_overlay_style(
    uint32_t window_id,
    int32_t height,
    const char* icon_color_hex,
    const char* hover_bg_hex
);

参数：

  • window_id uint32_t - 目标窗口 id
  • height int32_t - 按钮高度（像素），传 0 或负数使用默认值 32
  • icon_color_hex string (可选) - 图标颜色，格式为 #RRGGBB（如 "#FFFFFF"），传 NULL 使用默认颜色
  • hover_bg_hex string (可选) - 非关闭按钮悬浮背景色，格式为 #RRGGBB 或 #RRGGBBAA（支持透明度，如 "#00000080"），传 NULL 使用默认深灰色
信息

关闭按钮悬浮背景色固定为红色（#E81123），图标固定为白色，不受此 API 影响。

打印​

打印 WebView 内容​

打开 Windows 标准打印对话框，打印当前 WebView 内容。

int32_t jade_print(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

返回值：

  • 1 - 打印对话框已打开
  • 0 - 失败（窗口不存在或不支持打印）
注意

此功能仅 Windows 平台支持。

关闭窗口​

发起关闭；若页面注册了 beforeunload 且用户选择留下，关闭可能被推迟或取消，具体以 WebView 与页面脚本为准。

int32_t close_window(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

获取窗口数量​

查询当前 JadeView 里还有几个窗口没关。

uint32_t get_window_count(void);