窗口 API
窗口与网页视图是两类独立对象:一个 Window 可以拥有多个 WebView,销毁某个 WebView 不会关闭窗口或其它视图,销毁 Window 会先销毁其全部 WebView。
窗口操作(标题、尺寸、位置、显隐、层级、主题、关闭等)使用 Window ID;页面操作(导航、历史、缩放、页面 URL、DevTools、打印、IPC、资源注册等)使用 WebView ID。两类 ID 共用一个不复用的编号空间,错类型传入会被明确拒绝。
本页的三个创建入口 create_webview_window / create_borderless_webview_window / create_window 都返回 Window ID,创建后立刻用 get_default_webview(window_id) 取得默认 WebView ID,不需要等待创建事件。独立创建 / 挂载视图的入口见 WebView API。非零创建 ID 只表示请求已受理,不代表原生实例已就绪;Ready 表示原生实例可操作,页面加载完成由独立事件报告。
页面级接口见 WebView API;网页权限请求的统一拦截见 网页权限 API。除特别说明外,本页函数成功多为 1、失败为 0。
配置以 struct_size / abi_version 开头,默认初始化函数签名为 window_options_default(out, sizeof(*out)),成功返回 JADE_OK;创建时传 NULL 使用默认值。详见 V3 ABI。
创建窗口
创建普通窗口(create_webview_window)
创建带系统标题栏和边框的浏览器窗口,并在其中创建默认 WebView。这是最常用的主窗口创建方式。
uint32_t create_webview_window(const char* url, uint32_t parent_window_id, const struct WebViewWindowOptions* options, const struct WebViewSettings* webview_settings);参数:
urlstring- 第一次打开的网址或本地协议地址parent_window_iduint32_t- 父窗口,0表示顶层窗口optionsconst struct WebViewWindowOptions*(可选) - 窗口外观配置,见窗口配置;NULL使用默认值webview_settingsconst struct WebViewSettings*(可选) - 网页行为配置,字段说明见 WebView API;NULL使用默认值
返回值: 非零为已受理的 Window ID;0 表示失败(例如在 app-ready 之前调用)。窗口真正画出可能稍晚,可结合 window-created 事件。
创建无边框窗口(create_borderless_webview_window)
创建一个没有系统标题栏的 WebView 窗口,适合自绘标题栏、悬浮工具窗等场景,边框路径固定为无边框。
uint32_t create_borderless_webview_window(const char* url, const struct WebViewSettings* webview_settings);参数:
urlstring- 第一次打开的网址或本地协议地址webview_settingsconst struct WebViewSettings*(可选) - 网页行为配置,字段说明见 WebView API;NULL使用默认值
返回值: 非零为已受理的 Window ID。页面级操作仍需先用 get_default_webview(window_id) 取得 WebView ID。
窗口配置(WebViewWindowOptions)
typedef struct WebViewWindowOptions {
uint32_t struct_size;
uint32_t abi_version;
const char *title;
int32_t width;
int32_t height;
int32_t resizable;
int32_t noframe;
const char *title_bar_style;
int32_t transparent;
const char *background_color;
int32_t always_on_top;
const char *theme;
int32_t maximized;
int32_t maximizable;
int32_t minimizable;
int32_t x;
int32_t y;
int32_t min_width;
int32_t min_height;
int32_t max_width;
int32_t max_height;
int32_t fullscreen;
int32_t focus;
int32_t hide_window;
int32_t use_page_icon;
int32_t content_protection;
int32_t auto_save_state;
int32_t skip_taskbar;
int32_t no_activate;
const char *background_material;
int32_t titlebar_back;
int32_t titlebar_refresh;
int32_t titlebar_icon;
} WebViewWindowOptions;| 字段 | C 类型 | 说明 |
|---|---|---|
title | const char* | 窗口标题栏文字 |
width / height | int32_t | 初始宽高(像素) |
resizable | int32_t | 是否允许用户拖动边缘调整大小 |
noframe | int32_t | 1 使用无边框实现,0 保留系统边框,默认 0;无边框优先于系统标题栏 |
title_bar_style | const char* | default 系统标题栏、hidden 隐藏标题栏、BarOverlay 隐藏标题栏并启用按钮覆盖层;NULL 等同 default |
titlebar_back | int32_t | 返回按钮开关,0/1,默认 1;仅在当前页面可回退时显示,Windows 两种标题栏共用 |
titlebar_refresh | int32_t | 刷新按钮开关,0/1,默认 1;Windows 两种标题栏共用 |
titlebar_icon | int32_t | 默认标题栏窗口图标显示开关:0/1,默认 1;不影响任务栏图标 |
transparent | int32_t | 透明背景(受 WebView 与系统能力影响) |
background_color | const char* | 背景色 #RRGGBB 或 #RRGGBBAA,例如 "#ffffff00" |
always_on_top | int32_t | 是否总在最前 |
theme | const char* | 窗口主题(Light / Dark / System) |
maximized | int32_t | 打开时是否最大化 |
maximizable / minimizable | int32_t | 标题栏上最大化 / 最小化按钮是否生效 |
x / y | int32_t | 窗口左上角坐标,-1 表示居中 |
min_width / min_height | int32_t | 最小宽高,0 表示不限制 |
max_width / max_height | int32_t | 最大宽高,0 表示不限制 |
fullscreen | int32_t | 打开时是否全屏 |
focus | int32_t | 打开后是否抢键盘焦点 |
hide_window | int32_t | 默认 0(创建后显示);非 0 时先创建但不显示,适合先加载再显示 |
use_page_icon | int32_t | 是否用网页 favicon 作初始窗口图标(从 exe 提取图标仅 Windows) |
content_protection | int32_t | 防录屏 / 截屏类保护(仅 Windows 生效;Linux/X11 无系统级等价,设置不报错但无实际效果) |
auto_save_state | int32_t | 0 关闭、1 开启自动保存窗口状态 |
skip_taskbar | int32_t | 不进任务栏 / Alt-Tab(0 否、1 是),运行时可用 set_window_skip_taskbar |
no_activate | int32_t | 点击 / 显示时不激活窗口(0 否、1 是),运行时可用 set_window_no_activate |
background_material | const char* | 创建时背景材质:default / mica / micaAlt / acrylic(不区分大小写),NULL 为 default |
noframe 与 title_bar_style 的组合语义(外观取决于平台与窗口管理器):
noframe | title_bar_style | 效果 |
|---|---|---|
0 | default | 系统边框和标题栏 |
0 | hidden | 隐藏标题栏,使用可调整边框路径 |
1 | default 或 hidden | 无边框路径 |
0 或 1 | BarOverlay | 按 noframe 选择边框路径,同时启用标题栏按钮覆盖层 |
default 使用系统边框和标题栏;BarOverlay 启用标题栏按钮覆盖层,只占按钮实际区域,不预留页面顶部高度,自定义标题内容需自行避让。左侧导航按钮在两种样式下均可显示,返回仅在有可回退历史时出现。按钮配色与高度见 set_titlebar_style。
background_material 的非默认值仅 Windows 11 可用:需在窗口显示和 WebView 创建前设置,且页面本身使用透明背景才能看到材质;Linux 与 Windows 11 以前会拒绝创建,系统设置失败时窗口进入失败状态。
使用非空配置前必须先调用 window_options_default,它会初始化尺寸等必要字段;仅把结构体清零不够。宿主绑定的完整字段布局必须与 include/JadeView.h 一致。
创建空窗口(create_window)
创建不带任何 WebView 的原生窗口。要往窗口里挂视图,见 WebView API。
uint32_t create_window(uint32_t parent_window_id, const struct WebViewWindowOptions* options);parent_window_iduint32_t- 父窗口 ID,无父窗口传0optionsconst struct WebViewWindowOptions*- 与两个一步创建入口共用同一套配置- 返回值:
uint32_t,非零为已受理的 Window ID
典型调用顺序
/* 创建窗口:返回 Window ID */
uint32_t window_id = create_webview_window(url, 0, NULL, NULL);
/* 取默认视图,之后所有页面操作都用 WebView ID */
uint32_t view_id = get_default_webview(window_id);
send_ipc_message(view_id, "message", "hello");需要在一个窗口里放多个视图时,用 WebView API 的 add_webview / add_webview_to_window 挂载额外视图。
对象查询与状态
获取窗口句柄(get_window_hwnd)
在 C/C++ 里要把窗口交给别的 Win32 API(例如 SetWindowPos、子控件挂靠)时,需要 HWND。
size_t get_window_hwnd(uint32_t window_id);window_iduint32_t- 目标 Window ID- 返回值:
size_t原生窗口句柄
由窗口句柄取窗口 ID(get_window_id)
uint32_t get_window_id(size_t hwnd);hwndsize_t- 原生窗口句柄(HWND)- 返回值:
uint32_t该窗口的 Window ID
获取默认 WebView(get_default_webview)
uint32_t get_default_webview(uint32_t window_id);窗口创建后立即取得默认 WebView ID,无需等待事件。window_id 是 Window ID;默认关联被清空后可结合 get_window_state 的 default_webview_id 字段判断。
指定默认 WebView(set_default_webview)
int32_t set_default_webview(uint32_t window_id, uint32_t webview_id);把窗口的默认关联指向指定视图。window_id 是 Window ID,webview_id 是 WebView ID。
列出窗口的所有视图(get_window_webviews / free_webview_id_array)
int32_t get_window_webviews(uint32_t window_id, struct WebViewIdArray* out_array);
void free_webview_id_array(struct WebViewIdArray* array);结果通过 WebViewIdArray 返回,用完必须调用 free_webview_id_array 释放内部数组。
typedef struct WebViewIdArray {
const uint32_t *ids;
size_t count;
} WebViewIdArray;查询父窗口(get_webview_parent_window_id)
uint32_t get_webview_parent_window_id(uint32_t webview_id);传入 WebView ID,返回其所属 Window ID。
查询对象状态(get_window_state / get_webview_state)
int32_t get_window_state(uint32_t window_id, struct JadeObjectState* out);
int32_t get_webview_state(uint32_t webview_id, struct JadeObjectState* out);两个函数分别接受 Window ID 与 WebView ID,状态写入同一个结构体:
typedef struct JadeObjectState {
uint32_t kind;
uint32_t state;
uint32_t parent_window_id;
uint32_t default_webview_id;
int32_t error_code;
} JadeObjectState;| 字段 | C 类型 | 含义 |
|---|---|---|
kind | uint32_t | 对象种类(Window / WebView) |
state | uint32_t | 生命周期状态,取值见下表 |
parent_window_id | uint32_t | WebView 所属窗口;Window 对象上不适用 |
default_webview_id | uint32_t | 窗口当前默认视图;已清空为 0 |
error_code | int32_t | 对象进入失败状态时的错误码 |
对象生命周期状态常量(include/JadeView.h):
| 常量 | 值 | 含义 |
|---|---|---|
JADE_STATE_RESERVED | 1 | 已占位 |
JADE_STATE_CONFIGURED | 2 | 已配置 |
JADE_STATE_CREATING | 3 | 创建中 |
JADE_STATE_READY | 4 | 原生实例可操作 |
JADE_STATE_CLOSING | 5 | 关闭中 |
JADE_STATE_DESTROYING | 6 | 销毁中 |
JADE_STATE_DESTROYED | 7 | 已销毁 |
JADE_STATE_FAILED | 8 | 失败 |
JADE_STATE_CRASHED | 9 | 崩溃 |
请求结果另有一套更细的
1 accepted / 2 waiting / 3 succeeded / 4 failed / 5 cancelled编号,见核心 API。两者不要混用。
获取窗口数量(get_window_count)
查询当前还有几个窗口没关。
uint32_t get_window_count(void);位置、尺寸与标题
设置窗口标题
改变窗口标题栏上显示的文字(和 HTML 里的 <title> 可以不同)。
int32_t set_window_title(uint32_t window_id, const char* title);window_iduint32_t- 目标 Window IDtitlestring- 新的窗口标题
设置窗口大小
按像素改变窗口宽度和高度。
int32_t set_window_size(uint32_t window_id, int32_t width, int32_t height);window_iduint32_t- 目标 Window IDwidth/heightint32_t- 新的宽高(像素)
设置窗口位置
按像素改变窗口在屏幕上的位置。
int32_t set_window_position(uint32_t window_id, int32_t x, int32_t y);window_iduint32_t- 目标 Window IDx/yint32_t- 新的坐标
获取窗口位置和尺寸(get_window_bounds)
int32_t get_window_bounds(uint32_t window_id, char* buffer, int32_t buffer_size);window_iduint32_t- 目标 Window IDbufferchar*- 输出缓冲区buffer_sizeint32_t- 缓冲区大小- 返回值:
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_iduint32_t- 目标 Window IDvisibleint32_t- 非0显示,0隐藏
让窗口获得焦点
int32_t set_window_focus(uint32_t window_id);window_iduint32_t- 目标 Window ID
设置窗口置顶
int32_t set_window_always_on_top(uint32_t window_id, int32_t always_on_top);window_iduint32_t- 目标 Window IDalways_on_topint32_t- 非0置顶,0取消置顶
设置忽略鼠标事件(set_window_ignore_cursor_events)
设置窗口是否忽略鼠标事件(鼠标穿透),适用于悬浮窗 / overlay 场景。
int32_t set_window_ignore_cursor_events(uint32_t window_id, int32_t ignore);- 参数:
window_id;ignore(1忽略鼠标事件 / 穿透,0正常) - 返回值:
1成功,0失败
窗口标志与层级
适用于侧边 Dock、悬浮面板、桌面挂件、启动器等场景:让窗口不出现在任务栏 / Alt-Tab、常驻时不抢焦点,或把窗口压到桌面壁纸层。
不进任务栏 / Alt-Tab(set_window_skip_taskbar)
int32_t set_window_skip_taskbar(uint32_t window_id, int32_t skip);- 参数:
window_id;skip(1不进任务栏 / Alt-Tab,0恢复) - 返回值:
1成功,0失败
Windows:加 WS_EX_TOOLWINDOW 并去 WS_EX_APPWINDOW;Linux:GTK skip-taskbar-hint。
不抢焦点(set_window_no_activate)
让窗口在点击 / 显示时都不获得激活焦点,适合常驻的悬浮面板。
int32_t set_window_no_activate(uint32_t window_id, int32_t no_activate);- 参数:
window_id;no_activate(1不抢焦点,0恢复) - 返回值:
1成功,0失败
Windows:WS_EX_NOACTIVATE(SetWindowLongPtr);Linux:GTK accept-focus=false。
设置窗口层级(set_window_level)
一次性设定窗口处于哪个层级,比单纯的「置顶」更灵活。
// level: "topmost" | "normal" | "bottom" | "desktop"
int32_t set_window_level(uint32_t window_id, const char* level);- 参数:
window_id;levelstring- 层级字符串,取值见下表 - 返回值:
1成功,0失败
| level | 行为 | 实现 |
|---|---|---|
topmost | 置顶,盖在普通窗口之上 | set_always_on_top(true)(跨平台) |
normal | 普通层,取消置顶 / 置底 | 取消 always-on-top / always-on-bottom |
bottom | 压在其它窗口下方 | set_always_on_bottom(true)(跨平台) |
desktop | 贴桌面壁纸层(最小化所有窗口才见,类挂件) | 先 bottom;Windows 寄生 Progman / WorkerW,Linux 设 GTK WindowTypeHint::Desktop |
topmost / normal / bottom 跨平台稳定;desktop(壁纸层)为 best-effort,与窗口管理器行为相关,建议真机验证。寄生失败时至少退化为 bottom。
设置内容保护(set_content_protection)
打开后,部分截屏 / 录屏软件较难采到窗口内容(效果因系统和采集方式而异)。也可在创建时用 WebViewWindowOptions.content_protection 直接置位。
int32_t set_content_protection(uint32_t window_id, int32_t content_protection);window_iduint32_t- Window ID(不是 WebView ID)content_protectionint32_t- 非0启用保护,0禁用保护
窗口状态
最小化窗口
int32_t minimize_window(uint32_t window_id);window_iduint32_t- 目标 Window ID
切换最大化状态
int32_t toggle_maximize_window(uint32_t window_id);window_iduint32_t- 目标 Window ID
查询是否最大化
int32_t is_window_maximized(uint32_t window_id);window_iduint32_t- 目标 Window ID- 返回值:
1是最大化状态,0不是
设置全屏
进入或退出全屏(铺满显示器,不是单纯最大化)。请求会异步生效,也可监听 window-fullscreen 事件。
int32_t set_window_fullscreen(uint32_t window_id, int32_t fullscreen);window_iduint32_t- 目标 Window IDfullscreenint32_t- 非0进入全屏,0退出全屏
查询窗口是否最小化(is_window_minimized)
int32_t is_window_minimized(uint32_t window_id);- 参数:
window_iduint32_t - 返回值:
1已最小化,0否
查询窗口是否可见(is_window_visible)
int32_t is_window_visible(uint32_t window_id);- 参数:
window_iduint32_t - 返回值:
1可见,0不可见
查询窗口是否聚焦(is_window_focused)
int32_t is_window_focused(uint32_t window_id);- 参数:
window_iduint32_t - 返回值:
1已聚焦,0否
查询窗口是否全屏(is_window_fullscreen)
int32_t is_window_fullscreen(uint32_t window_id);- 参数:
window_iduint32_t - 返回值:
1全屏,0否
窗口约束
设置窗口最小尺寸(set_window_min_size)
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)
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)
int32_t set_window_resizable(uint32_t window_id, int32_t resizable);- 参数:
window_id、resizable(1可调整,0不可) - 返回值:
1成功,0失败
启用或禁用窗口
禁用窗口时用户点不了上面控件(像模态对话框背后的灰窗)。
int32_t set_window_enabled(uint32_t window_id, int32_t enabled);window_iduint32_t- 目标 Window IDenabledint32_t- 非0启用,0禁用
外观与样式
运行时修改窗口边框样式(set_window_frame)
动态切换窗口的边框路径与标题栏样式,无需重新创建窗口。本接口是运行期切换边框与标题栏样式的唯一入口。
int32_t set_window_frame(uint32_t window_id, int32_t noframe, const char* title_bar_style);参数:
window_iduint32_t- Window ID(不是 WebView ID)noframeint32_t-1使用无边框实现,0保留系统边框;无边框优先于系统标题栏title_bar_styleconst char*-default系统标题栏、hidden隐藏标题栏、BarOverlay隐藏标题栏并启用按钮覆盖层;NULL等同default
返回值:1 表示已入队受理,0 表示拒绝。无效样式不会入队,错误通过 jade_last_error_code / jade_last_error_message 读取。
noframe | title_bar_style | 效果 |
|---|---|---|
0 | default | 系统边框和标题栏 |
0 | hidden | 隐藏标题栏,使用可调整边框路径 |
1 | default 或 hidden | 无边框路径 |
0 或 1 | BarOverlay | 按 noframe 选择边框路径,同时启用标题栏按钮覆盖层 |
set_window_frame(window_id, 1, "hidden");创建时的对应配置字段见本页「窗口配置」小节。noframe=0, title_bar_style=hidden 使用去标题栏路径,noframe=1 使用无边框路径;覆盖层在 Windows 使用原生实现,Linux 使用默认 WebView 注入实现。
设置标题栏组件(set_titlebar_components)
int32_t set_titlebar_components(uint32_t window_id, int32_t back,
int32_t refresh, int32_t icon, int32_t minimize, int32_t maximize);
// 允许返回、显示刷新和窗口图标;允许最小化、最大化。
set_titlebar_components(window_id, 1, 1, 1, 1, 1);Windows 专用。五个开关均为 0/1,每次调用设置全部五项:
| 参数 | 含义 |
|---|---|
back | 是否允许返回按钮;有可回退历史时自动显示,否则隐藏 |
refresh | 是否显示默认标题栏或 BarOverlay 的刷新按钮 |
icon | 是否显示默认标题栏的窗口图标,不影响任务栏图标;BarOverlay 不绘制图标,只保存设置供切回默认标题栏使用 |
minimize | 是否允许最小化,与创建期 minimizable 一致 |
maximize | 是否允许最大化,与创建期 maximizable 一致 |
back=0始终隐藏返回按钮,back=1仅在有可回退历史时显示;刷新按钮在页面加载期间禁用,点击重新加载当前页。- 标题文字不受此接口控制;最小化、最大化开关不改变关闭按钮。
- 左侧按钮在
title_bar_style=default和BarOverlay下显示。BarOverlay只占按钮实际区域,不预留页面顶部高度,自定义标题内容需自行避让。 - 创建期的
titlebar_back/titlebar_refresh/titlebar_icon默认均为1,运行期调用会更新这组设置;切换标题栏样式后设置保留。 - 配色由
set_titlebar_style控制。
返回值:1 已受理,0 拒绝;可用 jade_last_error_code/message 查原因。非 Windows 返回平台错误,非 0/1 参数返回参数错误。应在窗口创建就绪后调用。
window.set_titlebar_components(back=True, refresh=True, icon=True, minimize=True, maximize=True)设置标题栏样式(set_titlebar_style)
Windows 专用,统一设置默认标题栏和 BarOverlay 的高度与按钮配色。
int32_t set_titlebar_style(uint32_t window_id, int32_t height,
const char* background_color, const char* foreground_color,
const char* button_background_color,
const char* button_hover_background_color, const char* button_hover_foreground_color);| 参数 | 含义 |
|---|---|
window_id | 目标 Window ID,不是 WebView ID |
height | -1 保持;0 恢复默认;自定义高度为 20–100 逻辑像素,超出范围会被拒绝 |
background_color | 标题栏背景色,仅默认标题栏使用 |
foreground_color | 标题文字与按钮常态图标共用的前景色,默认跟随主题。窗口失焦时,标题文字与未悬浮按钮使用淡化前景色 |
button_background_color | 所有按钮的常态背景色,默认透明 |
button_hover_background_color | 除关闭按钮外的悬浮背景色 |
button_hover_foreground_color | 除关闭按钮外的悬浮图标色 |
颜色支持 #RRGGBB、#RRGGBBAA、rgb(r,g,b) 和 rgba(r,g,b,a),其中 a 为 0–1。每次调用更新全部颜色。传 NULL 或空串 "" 会清除该项自定义颜色,恢复当前窗口主题下的默认样式。默认标题栏和 BarOverlay 都适用。非法颜色使整次调用被拒绝。关闭按钮始终保留红色悬浮背景和白色图标。
BarOverlay 不绘制标题栏背景或标题文字,但保留设置供切回默认标题栏使用。样式在切换窗口帧后保留,窗口销毁时清理。
覆盖层属于 Window,空窗口也可使用;页面导航、缩放或默认 WebView 销毁不影响按钮。全屏时按钮隐藏,退出后恢复。宿主 EXE 需声明 Windows 8 或更新版本的兼容清单。
返回 1 表示已受理,0 表示拒绝,可通过 jade_last_error_code/message 查询原因。非 Windows 返回平台错误。
window.set_titlebar_style(
height=40,
background_color="#202124",
foreground_color="#F5F5F5",
button_background_color="#00000000",
button_hover_background_color="#3367D6",
button_hover_foreground_color="#FFFFFF",
)Python 传 None、空串 "" 或省略颜色参数,都会恢复该项默认样式。
设置窗口明暗主题
控制窗口和 WebView 使用浅色、深色还是跟随系统主题。更细的说明见 主题管理。
int32_t set_window_theme(uint32_t window_id, const char* theme);window_iduint32_t- 目标 Window IDthemestring- 主题字符串:Light/Dark/System
获取当前窗口主题
int32_t get_window_theme(uint32_t window_id);window_iduint32_t- 目标 Window ID- 返回值:
1深色(Dark),0浅色(Light)。System主题按当前系统明暗解析;窗口不存在或主题未知时返回0
设置窗口背景材质
Windows 11 下设置云母、亚克力等系统背景材质,可用字符串见 主题管理。
int32_t set_window_backdrop(uint32_t window_id, const char* backdrop_type);window_iduint32_t- 目标 Window IDbackdrop_typestring- 背景材质类型
仅 Windows 11。Linux(WebKitGTK)无系统材质等价物,调用为 no-op 并返回 0、无视觉效果。如需半透明 / 纯色背景,请用 set_window_background_color 或窗口的 transparent + background_color 选项。
设置窗口背景色
int32_t set_window_background_color(uint32_t window_id, const char* background_color_hex);window_iduint32_t- 目标 Window IDbackground_color_hexstring- 背景色十六进制字符串,如#FF0000
请求重绘
通知系统重画客户区(一般很少需要手动调用)。
int32_t request_redraw(uint32_t window_id);window_iduint32_t- 目标 Window ID
任务栏特效
设置任务栏进度条(set_window_progress)
在任务栏按钮上显示进度条(如下载进度、安装进度等)。
int32_t set_window_progress(uint32_t window_id, int32_t progress, int32_t state);- 参数:
window_iduint32_tprogressint32_t- 进度值(0–100)stateint32_t- 状态:0无进度、1正常、2暂停(黄色)、3错误(红色)、4不确定
- 返回值:
1成功,0失败
仅 Windows 平台。
任务栏图标闪烁(flash_window)
int32_t flash_window(uint32_t window_id, uint32_t count);- 参数:
window_iduint32_t;countuint32_t- 闪烁次数,0停止闪烁 - 返回值:
1成功,0失败
仅 Windows 平台。
关闭窗口
关闭窗口(close_window)
发起关闭;若页面注册了 beforeunload 且用户选择留下,关闭可能被推迟或取消,具体以 WebView 与页面脚本为准。
int32_t close_window(uint32_t window_id);window_iduint32_t- 目标 Window ID
关闭流程
前端调用 window.close()、点击标题栏关闭按钮或按 Alt+F4 时,所有关闭方式走同一条流程:
- 先派发
window-closing(宿主可拦截,回调返回非空指针即阻止关闭,见 事件类型); - 关闭窗口并派发
window-closed; - 最后一个窗口关闭时派发
window-all-closed。
- 标题栏关闭按钮可拦截:与
window.close()、Alt+F4 一致,可被window-closing回调拦住。 close_window():走「程序化关闭」语义,绕过window-closing直接关闭窗口。
关闭来源与页面地址: window-closing 回调的 event_data 区分来源——{"source":"system"} 表示用户发起(Alt+F4、系统关闭按钮、标题栏关闭按钮);{"source":"frontend","url":"<页面当前地址>"} 表示由前端 window.close() 发起。页面地址由 JadeView 直接读取 WebView 当前地址得到,不采用页面自报值。
兜底: 窗口若未经正常关闭流程就被销毁,仍会补发 window-closed(以及所有窗口都关闭时的 window-all-closed)并清理窗口状态,宿主不会漏收关闭通知。
最大化或固定尺寸窗口仍保留标题栏按钮。