跳到主要内容

窗口 API

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

页面导航、脚本执行、DevTools、打印等 WebView 相关操作见 WebView API。

以下函数都针对某个 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）或空字符串则不允许任何跨域，无法与程序通信。
    注意

    以下结构在 v2.2 开始支持

    • autofill int32_t - 是否启用账号/密码自动填充。0 = 禁用，1 = 启用。
    • general_autofill_enabled int32_t - 是否启用通用表单自动填充（姓名/地址/电话等）。0 = 禁用，1 = 启用。
    • incognito int32_t - 是否以无痕/隐私浏览模式运行。0 = 正常模式，1 = 无痕模式。开启后页面渲染会变慢。
    • disable_clipboard int32_t - 是否禁用剪贴板读写权限。0 = 允许，1 = 禁用。
    • proxy_url string - 代理URL，支持 HTTP 和 SOCKS5 代理（如 "http://127.0.0.1:7890" 或 "socks5://127.0.0.1:1080"）。NULL 表示不使用代理。
    • focused int32_t - WebView 初始是否自动获取焦点。0 = 不获取焦点，1 = 自动聚焦（默认 1）。

返回值：

  • > 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

位置、尺寸与标题​

设置窗口标题​

改变窗口标题栏上显示的文字（和 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 坐标

获取窗口位置和尺寸（get_window_bounds）​

注意

v2.2 开始支持。

int32_t get_window_bounds(uint32_t window_id, char* buffer, int buffer_size);

参数：

  • window_id uint32_t - 目标窗口 id
  • buffer char* - 输出缓冲区
  • buffer_size int - 缓冲区大小

返回值： 1 = 成功，buffer 写入 JSON {"x":0,"y":0,"width":800,"height":600}；0 = 失败

显隐与焦点​

显示或隐藏窗口​

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

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 取消置顶

设置忽略鼠标事件（set_window_ignore_cursor_events）​

注意

v2.2 开始支持。

设置窗口是否忽略鼠标事件（鼠标穿透），适用于悬浮窗 / overlay 场景。

int32_t set_window_ignore_cursor_events(uint32_t window_id, int ignore);
  • 参数：window_id、ignore（1 = 忽略鼠标事件/穿透，0 = 正常）
  • 返回值：1 = 成功，0 = 失败

窗口状态​

最小化窗口​

把窗口收到任务栏。

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 退出全屏

查询窗口是否最小化（is_window_minimized）​

注意

v2.2 开始支持。

int32_t is_window_minimized(uint32_t window_id);
  • 参数：window_id uint32_t
  • 返回值：1 = 已最小化，0 = 否

查询窗口是否可见（is_window_visible）​

注意

v2.2 开始支持。

int32_t is_window_visible(uint32_t window_id);
  • 参数：window_id uint32_t
  • 返回值：1 = 可见，0 = 不可见

查询窗口是否聚焦（is_window_focused）​

注意

v2.2 开始支持。

int32_t is_window_focused(uint32_t window_id);
  • 参数：window_id uint32_t
  • 返回值：1 = 已聚焦，0 = 否

查询窗口是否全屏（is_window_fullscreen）​

注意

v2.2 开始支持。

int32_t is_window_fullscreen(uint32_t window_id);
  • 参数：window_id uint32_t
  • 返回值：1 = 全屏，0 = 否

窗口约束​

设置窗口最小尺寸（set_window_min_size）​

注意

v2.2 开始支持。

int32_t set_window_min_size(uint32_t window_id, int32_t width, int32_t height);
  • 参数：window_id、width（最小宽度）、height（最小高度）
  • 返回值：1 = 成功，0 = 失败

设置窗口最大尺寸（set_window_max_size）​

注意

v2.2 开始支持。

int32_t set_window_max_size(uint32_t window_id, int32_t width, int32_t height);
  • 参数：window_id、width（最大宽度）、height（最大高度）
  • 返回值：1 = 成功，0 = 失败

设置窗口是否可调整大小（set_window_resizable）​

注意

v2.2 开始支持。

int32_t set_window_resizable(uint32_t window_id, int32_t resizable);
  • 参数：window_id、resizable（1 = 可调整，0 = 不可）
  • 返回值：1 = 成功，0 = 失败

启用或禁用窗口​

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

int32_t set_window_enabled(uint32_t window_id, int32_t enabled);

参数：

  • window_id uint32_t - 目标窗口 id
  • enabled 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。按钮宽度固定 45 像素
  • icon_color_hex string (可选) - 图标颜色，格式为 #RRGGBB（如 "#FFFFFF"），传 NULL 使用默认颜色
  • hover_bg_hex string (可选) - 非关闭按钮悬浮背景色，格式为 #RRGGBB 或 #RRGGBBAA（支持透明度，如 "#00000080"），传 NULL 使用默认深灰色
信息

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

设置窗口明暗主题​

控制窗口和 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 request_redraw(uint32_t window_id);

参数：

  • window_id uint32_t - 目标窗口 id

任务栏特效​

设置任务栏进度条（set_window_progress）​

注意

v2.2 开始支持。

在任务栏按钮上显示进度条（如下载进度、安装进度等）。

int32_t set_window_progress(uint32_t window_id, int progress, int state);
  • 参数：
    • window_id uint32_t
    • progress int - 进度值（0–100）
    • state int - 状态：0=无进度，1=正常，2=暂停(黄色)，3=错误(红色)，4=不确定
  • 返回值：1 = 成功，0 = 失败
注意

仅 Windows 平台。

任务栏图标闪烁（flash_window）​

注意

v2.2 开始支持。

闪烁任务栏图标以吸引用户注意（如收到消息时）。

int32_t flash_window(uint32_t window_id, uint32_t count);
  • 参数：window_id uint32_t；count uint32_t - 闪烁次数，0 = 停止闪烁
  • 返回值：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);