窗口 API 和数据结构

核心窗口操作

初始化 DLL

函数签名

int JadeView_init(int enable_devtools, const char* log_path, const char* data_directory);

功能描述 初始化 JadeView DLL，启动 GUI 线程。

参数

enable_devtools：是否启用开发者工具（0=禁用，1=启用）
log_path：日志文件路径，NULL 表示不输出日志到文件
data_directory：WebView 数据目录，NULL 表示使用默认值

返回值

1：初始化成功
0：初始化失败

说明

此函数会启动一个新的 GUI 线程，所有窗口操作都在该线程中执行
初始化完成后会发送 "app-ready" 事件

清理所有窗口

函数签名

int cleanup_all_windows();

功能描述 清理所有窗口资源并结束事件循环。

返回值

1：成功
0：失败

窗口创建与管理

创建 WebView 窗口

函数签名

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

功能描述 创建一个新的 WebView 窗口。

参数

url：窗口初始加载的 URL
parent_window_id：父窗口 ID，0 表示无父窗口
options：WebViewWindowOptions 指针，NULL 表示使用默认选项
webview_settings：WebViewSettings 指针，NULL 表示使用默认设置

返回值

成功：返回请求的窗口 ID
失败：返回 0

说明

窗口实际创建是在事件循环线程中异步完成的
函数立即返回请求的窗口 ID
重要：窗口必须在 app-ready 事件触发后才能创建，否则会导致创建失败

关闭窗口

函数签名

int close_window(uint32_t window_id);

功能描述 关闭指定 ID 的窗口，释放窗口资源。

参数

window_id：要关闭的窗口 ID

返回值

1：成功
0：失败

请求重绘

函数签名

int request_redraw(uint32_t window_id);

功能描述 请求指定窗口重绘，刷新窗口内容。

参数

window_id：要重绘的窗口 ID

返回值

1：成功
0：失败

设置窗口全屏

函数签名

int set_window_fullscreen(uint32_t window_id, int fullscreen);

功能描述 设置指定窗口的全屏状态。

版本支持：JadeView 0.2.1+

参数

window_id：窗口 ID
fullscreen：是否全屏，0=不全屏，1=全屏

返回值

1：成功
0：失败

检查窗口是否最大化

函数签名

int is_window_maximized(uint32_t window_id);

功能描述 获取指定窗口是否处于最大化状态。

版本支持：JadeView 0.2.1+

参数

window_id：窗口 ID

返回值

1：窗口已最大化
0：窗口未最大化或窗口不存在

窗口属性设置

设置窗口标题

函数签名

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

功能描述 设置指定窗口的标题。

参数

window_id：窗口 ID
title：新的窗口标题

返回值

1：成功
0：失败

设置窗口大小

函数签名

int set_window_size(uint32_t window_id, double width, double height);

功能描述 设置指定窗口的大小。

参数

window_id：窗口 ID
width：新的宽度（像素）
height：新的高度（像素）

返回值

1：成功
0：失败

设置窗口位置

函数签名

int set_window_position(uint32_t window_id, double x, double y);

功能描述 设置指定窗口的位置。

参数

window_id：窗口 ID
x：新的 X 坐标（像素，相对于屏幕左上角）
y：新的 Y 坐标（像素，相对于屏幕左上角）

返回值

1：成功
0：失败

设置窗口可见性

函数签名

int set_window_visible(uint32_t window_id, int visible);

功能描述 设置指定窗口的可见性。

参数

window_id：窗口 ID
visible：可见性，0=隐藏，1=显示

返回值

1：成功
0：失败

设置窗口焦点

函数签名

int set_window_focus(uint32_t window_id);

功能描述 将焦点设置到指定窗口。

参数

window_id：窗口 ID

返回值

1：成功
0：失败

启用或禁用窗口

函数签名

int set_window_enabled(uint32_t window_id, int enabled);

功能描述 启用或禁用指定窗口。

参数

window_id：窗口 ID
enabled：启用状态，0=禁用，1=启用

返回值

1：成功
0：失败

窗口状态控制

最小化窗口

函数签名

int minimize_window(uint32_t window_id);

功能描述 最小化指定窗口。

参数

window_id：窗口 ID

返回值

1：成功
0：失败

切换最大化状态

函数签名

int toggle_maximize_window(uint32_t window_id);

功能描述 切换指定窗口的最大化/还原状态。

参数

window_id：窗口 ID

返回值

1：成功
0：失败

说明：

如果窗口当前是最大化状态，则还原为正常大小
如果窗口当前是正常大小，则最大化窗口

设置窗口置顶

函数签名

int set_window_always_on_top(uint32_t window_id, int always_on_top);

功能描述 设置指定窗口是否始终置顶。

参数

window_id：窗口 ID
always_on_top：置顶状态，0=取消置顶，1=设置置顶

返回值

1：成功
0：失败

设置内容保护

函数签名

int set_content_protection(uint32_t window_id, int content_protection);

功能描述 设置指定窗口的内容保护状态，启用后禁止窗口内容被截图捕获。

版本支持：JadeView 1.1+

参数

window_id：窗口 ID
content_protection：内容保护状态，0=关闭内容保护，1=开启内容保护

返回值

1：成功
0：失败

窗口事件处理

注册窗口事件处理器

即将移除

该函数计划在 JadeView 0.2.1 版本中移除，请使用 jade_on 函数作为替代方案。

函数签名

int set_window_event_handlers(
    uint32_t window_id,
    WindowEventCallback window_event_cb,
    PageLoadCallback page_load_cb,
    FileDropCallback file_drop_cb
);

功能描述 设置全局窗口事件处理器，适用于所有窗口。

参数

window_id：窗口 ID，兼容旧 API，不再使用
window_event_cb：窗口事件回调函数
page_load_cb：页面加载事件回调函数
file_drop_cb：文件拖放事件回调函数

返回值

1：成功
0：失败

数据结构

RGBA 颜色结构体

定义

typedef struct {
    int r;
    int g;
    int b;
    int a;
} RGBA;

字段说明

字段	类型	说明
`r`	int	红色通道值，范围 0-255
`g`	int	绿色通道值，范围 0-255
`b`	int	蓝色通道值，范围 0-255
`a`	int	alpha 通道值，范围 0-255，0 表示完全透明，255 表示完全不透明

功能描述 用于表示 RGBA 颜色，与易语言的 JadeRgb 结构完全匹配。

WebViewSettings 结构体

定义

typedef struct {
    int autoplay;
    int background_throttling;
    int disable_right_click;
    const char* ua;
    const char* preload_js;
    int allow_fullscreen;
    const char* postmessage_whitelist;
} WebViewSettings;

字段说明

字段	类型	说明
`autoplay`	int	是否允许自动播放媒体，0=禁用，1=启用
`background_throttling`	int	背景限速策略，0=默认（启用背景限速），1=禁用背景限速
`right_click`	int	是否启用右键菜单，0=禁用（默认），1=启用，JadeView v1.3以前的版本 0为启用右键菜单
`ua`	const char*	自定义 User-Agent 字符串指针，NULL 表示使用默认 UA
`preload_js`	const char*	预载 JavaScript 代码字符串指针，NULL 表示不预载 JS
`allow_fullscreen`	int	是否允许页面全屏，0=false，1=true（版本支持：JadeView 0.2.1+）
1.0开始支持`postmessage_whitelist`	const char*	PostMessage 白名单，单个域名字符串，用于限制可接收的 PostMessage 来源

功能描述 用于设置 WebView 的高级选项。

WebViewWindowOptions 结构体

定义

typedef struct {
    const char* title;
    int width;
    int height;
    int resizable;
    int remove_titlebar;
    int transparent;
    RGBA background_color;
    int always_on_top;
    int no_center;
    const char* theme;
    int maximized;
    int maximizable;
    int minimizable;
    int x;
    int y;
    int min_width;
    int min_height;
    int max_width;
    int max_height;
    int fullscreen;
    int focus;
    int hide_window;
    int use_page_icon;
    int borderless;
    int content_protection;
} WebViewWindowOptions;

字段说明

字段	类型	说明
`title`	const char*	窗口标题，留空自动跟随页面标题
`width`	int	窗口宽度，默认 800
`height`	int	窗口高度，默认 600
`resizable`	int	窗口是否可调整大小，0=不可调整，1=可调整，默认 1
`remove_titlebar`	int	是否去除标题栏，0=显示标题栏，1=去除标题栏，默认 0
`transparent`	int	窗口是否透明，0=不透明，1=透明，默认 0
`background_color`	RGBA	窗口背景色，仅当 transparent=0 时有效
`always_on_top`	int	窗口是否始终置顶，0=不置顶，1=置顶，默认 0
`no_center`	int	是否不居中，0=居中，1=不居中，默认 0
`theme`	const char*	窗口主题，可选值："Light"、"Dark"、"System"，默认 "System"
`maximized`	int	窗口是否最大化，0=不最大化，1=最大化，默认 0
`maximizable`	int	窗口是否可最大化，0=不可最大化，1=可最大化，默认 1
`minimizable`	int	窗口是否可最小化，0=不可最小化，1=可最小化，默认 1
`x`	int	窗口 X 坐标，-1 表示居中，默认 -1
`y`	int	窗口 Y 坐标，-1 表示居中，默认 -1
`min_width`	int	窗口最小宽度，默认 0
`min_height`	int	窗口最小高度，默认 0
`max_width`	int	窗口最大宽度，默认 0
`max_height`	int	窗口最大高度，默认 0
`fullscreen`	int	窗口是否全屏，0=不全屏，1=全屏，默认 0
`focus`	int	窗口是否获得焦点，0=不获得焦点，1=获得焦点，默认 1
`hide_window`	int	窗口是否隐藏，0=显示窗口，1=隐藏窗口，默认 0
`use_page_icon`	int	是否使用页面图标，0=使用主进程图标，1=使用页面图标，默认 0
`borderless`	int	无边框选项，1为无边框，去除边框和系统阴影，默认 0（版本支持：JadeView 0.2.1+）
`content_protection`	int	内容保护，禁止被截图捕获，0=关闭，1=开启，默认 0（版本支持：JadeView 1.1+）

回调函数类型定义

WindowEventCallback

全局通用事件回调函数类型定义，无论是IPC事件还是程序事件，都可以使用此回调函数。

定义

typedef int (*WindowEventCallback)(uint32_t window_id, const char* event_type, const char* event_data);

参数说明

参数	类型	说明
`window_id`	uint32_t	窗口 ID
`event_type`	const char*	事件类型
`event_data`	const char*	事件数据

返回值说明

返回值	说明
`0`	允许操作
`1`	阻止操作
`const char*`	前端通讯可以直接返回文本，或返回由 `jade_text_create` 创建的安全文本指针

Web SDK

Python SDK

易语言 SDK

核心窗口操作​

初始化 DLL​

清理所有窗口​

窗口创建与管理​

创建 WebView 窗口​

关闭窗口​

请求重绘​

设置窗口全屏​

检查窗口是否最大化​

窗口属性设置​

设置窗口标题​

设置窗口大小​

设置窗口位置​

设置窗口可见性​

设置窗口焦点​

启用或禁用窗口​

窗口状态控制​

最小化窗口​

切换最大化状态​

设置窗口置顶​

设置内容保护​

窗口事件处理​

注册窗口事件处理器​

数据结构​

RGBA 颜色结构体​

WebViewSettings 结构体​

WebViewWindowOptions 结构体​

回调函数类型定义​

WindowEventCallback​

核心窗口操作

初始化 DLL

清理所有窗口

窗口创建与管理

创建 WebView 窗口

关闭窗口

请求重绘

设置窗口全屏

检查窗口是否最大化

窗口属性设置

设置窗口标题

设置窗口大小

设置窗口位置

设置窗口可见性

设置窗口焦点

启用或禁用窗口

窗口状态控制

最小化窗口

切换最大化状态

设置窗口置顶

设置内容保护

窗口事件处理

注册窗口事件处理器

数据结构

RGBA 颜色结构体

WebViewSettings 结构体

WebViewWindowOptions 结构体

回调函数类型定义

WindowEventCallback