快速开始

本指南将帮助你快速上手 JadeView，创建你的第一个 WebView 窗口。

前置条件

下载 JadeView 库

在开始之前，请确保：

Windows 10/11 操作系统
已下载 JadeView DLL 和头文件 (jadeview.dll 和 jadeview.h)，可从 GitHub Releases 下载：https://github.com/JadeViewDocs/library/releases
对 C 语言有基本了解

安装 WebView2

在 Windows 系统上使用 JadeView，需要安装 Microsoft Edge WebView2 Runtime：

下载地址：Microsoft Edge WebView2 Runtime
详细安装指南：WebView2 安装指南

JadeView 是一个基于 Rust 开发的 WebView 窗口库，设计上注重性能、安全性和易用性。本页面将详细介绍 JadeView 的性能特性和设计理念。

步骤 1：初始化 DLL

首先，你需要初始化 JadeView DLL。这将启动 GUI 线程和事件循环。

#include "jadeview.h"

int main() {
    // 初始化 DLL，启用开发者工具，不输出日志到文件，使用默认数据目录
    int result = JadeView_init(1, NULL, NULL);
    
    if (result == 0) {
        printf("DLL 初始化失败\n");
        return 1;
    }
    
    printf("DLL 初始化成功\n");
    
    return 0;
}

参数说明

enable_devtools：是否启用开发者工具，0=禁用，1=启用
log_path：日志文件路径，NULL 或空字符串表示不输出日志到文件
data_directory：WebContext 数据目录，NULL 或空字符串表示使用默认目录

返回值

1：成功
0：失败

步骤 2：注册 app-ready 事件

初始化完成后，你需要注册 app-ready 事件监听器。重要：窗口必须在 app-ready 事件触发后才能创建，否则会导致创建失败。

#include "jadeview.h"

// app-ready 事件回调函数
// app-ready 事件说明：
// - 触发条件：应用初始化完成
// - 参数1：整数，1表示成功，0表示失败
// - 参数2：字符串，"success"或失败原因文本
int app_ready_callback(int success, const char* reason) {
    // 检查初始化是否成功
    if (success == 1 && reason && strcmp(reason, "success") == 0) {
        printf("JadeView 准备就绪，现在可以创建窗口了\n");
        
        // 创建窗口选项
        // 关于 WebViewWindowOptions 的详细说明：[/guides/reference/data-structures#webview-窗口选项结构体](/guides/reference/data-structures#webview-窗口选项结构体)
        WebViewWindowOptions options = {
            .title = "我的第一个窗口",
            .width = 800,
            .height = 600,
            .resizable = 1,
            .remove_titlebar = 0
        };
        
        // 创建 WebView 设置
        // 关于 WebViewSettings 的详细说明：[/guides/reference/data-structures#webview-设置结构体](/guides/reference/data-structures#webview-设置结构体)
        WebViewSettings settings = {
            .autoplay = 0, // 是否允许自动播放媒体，0=禁用，1=启用
            .background_throttling = 0, // 背景限速策略，0=默认（启用背景限速），1=禁用背景限速。在Windows11下，**只有当该功能开启时**，窗口不可见时自动为WebView开启效能模式
                                        // 背景限速是浏览器的性能优化机制，当页面在后台时会降低 JavaScript 执行速度
                                        // 某些场景下（如后台持续运行计算）需要禁用此功能
            .disable_right_click = 0, // 是否禁用右键菜单，0=启用，1=禁用
            .allow_fullscreen = 0, // 是否允许页面全屏，0=false，1=true
            .postmessage_whitelist = NULL // PostMessage 白名单，单个域名字符串，用于限制可接收的 PostMessage 来源
        };
        
        // 创建窗口
        uint32_t new_window_id = create_webview_window(
            "https://www.example.com",
            0,
            &options,
            &settings
        );
        
        if (new_window_id == 0) {
            printf("窗口创建失败\n");
        } else {
            printf("窗口创建成功，窗口 ID：%u\n", new_window_id);
        }
    } else {
        printf("JadeView 初始化失败：%s\n", reason ? reason : "未知错误");
    }
    
    return 0;
}

int main() {
    // 注意：必须在初始化 DLL 之前注册 app-ready 事件
    // 否则可能无法收到 app-ready 事件
    jade_on("app-ready", app_ready_callback);
    
    // 初始化 DLL
    int result = JadeView_init(1, NULL, NULL);
    
    if (result == 0) {
        printf("DLL 初始化失败\n");
        return 1;
    }
    
    return 0;
}

参数说明

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

返回值

返回请求的窗口 ID，如果创建失败返回 0

步骤 3：运行消息循环

在初始化 DLL 并注册事件后，你需要运行消息循环来处理窗口事件。

#include "jadeview.h"

// app-ready 事件回调函数
// 参数1：整数，1表示成功，0表示失败
// 参数2：字符串，"success"或失败原因文本
int app_ready_callback(int success, const char* reason) {
    // 检查初始化是否成功
    if (success == 1 && reason && strcmp(reason, "success") == 0) {
        // 创建窗口
        // ... 窗口创建代码 ...
    } else {
        printf("JadeView 初始化失败：%s\n", reason ? reason : "未知错误");
    }
    return 0;
}

int main() {
    // 注意：必须在初始化 DLL 之前注册 app-ready 事件
    // 否则可能无法收到 app-ready 事件
    jade_on("app-ready", app_ready_callback);
    
    // 初始化 DLL
    int result = JadeView_init(1, NULL, NULL);
    
    if (result == 0) {
        printf("DLL 初始化失败\n");
        return 1;
    }
    
    // 运行消息循环
    run_message_loop();
    
    return 0;
}

步骤 4：注册其他事件回调

你可以在 app-ready 事件中创建窗口后，注册其他窗口事件回调函数。

#include "jadeview.h"

// 窗口事件回调函数
int window_event_callback(uint32_t window_id, const char* event_type, const char* event_data) {
    printf("窗口事件：window_id=%u, type=%s, data=%s\n", window_id, event_type, event_data);
    return 0; // 允许操作
}

// 页面加载事件回调函数
void page_load_callback(uint32_t window_id, const char* url, const char* status) {
    printf("页面加载：window_id=%u, url=%s, status=%s\n", window_id, url, status);
}

// 文件拖放事件回调函数
void file_drop_callback(uint32_t window_id, const char* file_path, const char* mime_type, double x, double y) {
    printf("文件拖放：window_id=%u, path=%s, mime=%s, x=%f, y=%f\n", window_id, file_path, mime_type, x, y);
}

// app-ready 事件回调函数
// 参数1：整数，1表示成功，0表示失败
// 参数2：字符串，"success"或失败原因文本
int app_ready_callback(int success, const char* reason) {
    // 检查初始化是否成功
    if (success == 1 && reason && strcmp(reason, "success") == 0) {
        printf("JadeView 准备就绪，现在可以创建窗口了\n");
        
        // 创建窗口
        WebViewWindowOptions options = {
            .title = "我的第一个窗口",
            .width = 800,
            .height = 600
        };
        
        uint32_t new_window_id = create_webview_window(
            "https://www.example.com",
            0,
            &options,
            NULL
        );
        
        // 设置事件处理器
        // :::caution 即将移除
        // set_window_event_handlers 函数计划在 JadeView 0.2.1 版本中移除，请使用 `jade_on` 函数作为替代方案
        // :::
        set_window_event_handlers(
            0, // 兼容旧 API，不再使用
            window_event_callback,
            page_load_callback,
            file_drop_callback
        );
    } else {
        printf("JadeView 初始化失败：%s\n", reason ? reason : "未知错误");
    }
    
    return 0;
}

int main() {
    // 注意：必须在初始化 DLL 之前注册 app-ready 事件
    // 否则可能无法收到 app-ready 事件
    jade_on("app-ready", app_ready_callback);
    
    // 初始化 DLL
    int result = JadeView_init(1, NULL, NULL);
    
    if (result == 0) {
        printf("DLL 初始化失败\n");
        return 1;
    }
    
    // 运行消息循环
    run_message_loop();
    
    return 0;
}

步骤 5：清理资源

应用程序退出前，应该调用 cleanup_all_windows 清理所有资源。

#include "jadeview.h"

// app-ready 事件回调函数
int app_ready_callback(uint32_t window_id, const char* event_type, const char* event_data) {
    // 创建窗口
    // ... 窗口创建代码 ...
    return 0;
}

int main() {
    // 注意：必须在初始化 DLL 之前注册 app-ready 事件
    // 否则可能无法收到 app-ready 事件
    jade_on("app-ready", app_ready_callback);
    
    // 初始化 DLL
    int result = JadeView_init(1, NULL, NULL);
    
    if (result == 0) {
        printf("DLL 初始化失败\n");
        return 1;
    }
    
    // 运行消息循环
    run_message_loop();
    
    // 清理所有窗口和资源
    cleanup_all_windows();
    
    return 0;
}

完整示例

以下是一个完整的示例程序，展示了正确的窗口创建流程：

#include <stdio.h>
#include "jadeview.h"

// 窗口事件回调函数
int window_event_callback(uint32_t window_id, const char* event_type, const char* event_data) {
    printf("窗口事件：window_id=%u, type=%s, data=%s\n", window_id, event_type, event_data);
    return 0;
}

// 页面加载事件回调函数
void page_load_callback(uint32_t window_id, const char* url, const char* status) {
    printf("页面加载：window_id=%u, url=%s, status=%s\n", window_id, url, status);
}

// 文件拖放事件回调函数
void file_drop_callback(uint32_t window_id, const char* file_path, const char* mime_type, double x, double y) {
    printf("文件拖放：window_id=%u, path=%s, mime=%s, x=%f, y=%f\n", window_id, file_path, mime_type, x, y);
}

// app-ready 事件回调函数
// 参数1：整数，1表示成功，0表示失败
// 参数2：字符串，"success"或失败原因文本
int app_ready_callback(int success, const char* reason) {
    // 检查初始化是否成功
    if (success == 1 && reason && strcmp(reason, "success") == 0) {
        printf("JadeView 准备就绪，现在可以创建窗口了\n");
        
        // 创建窗口选项
        WebViewWindowOptions options = {
            .title = "我的第一个窗口",
            .width = 800,
            .height = 600,
            .resizable = 1,
            .remove_titlebar = 0
        };
        
        // 创建窗口
        uint32_t new_window_id = create_webview_window(
            "https://www.example.com",
            0,
            &options,
            NULL
        );
        
        if (new_window_id == 0) {
            printf("窗口创建失败\n");
            return 0;
        }
        
        printf("窗口创建成功，窗口 ID：%u\n", new_window_id);
        
        // 设置事件处理器
        // :::caution 即将移除
        // set_window_event_handlers 函数计划在 JadeView 0.2.1 版本中移除，请使用 `jade_on` 函数作为替代方案
        // :::
        set_window_event_handlers(
            0,
            window_event_callback,
            page_load_callback,
            file_drop_callback
        );
    } else {
        printf("JadeView 初始化失败：%s\n", reason ? reason : "未知错误");
    }
    
    return 0;
}

int main() {
    // 注意：必须在初始化 DLL 之前注册 app-ready 事件
    // 否则可能无法收到 app-ready 事件
    jade_on("app-ready", app_ready_callback);
    
    // 初始化 DLL
    int result = JadeView_init(1, NULL, NULL);
    if (result == 0) {
        printf("DLL 初始化失败\n");
        return 1;
    }
    
    printf("DLL 初始化成功，等待 app-ready 事件...\n");
    
    // 运行消息循环
    run_message_loop();
    
    // 清理所有窗口和资源
    cleanup_all_windows();
    
    return 0;
}

下一步

现在你已经成功创建了第一个 WebView 窗口！接下来你可以：

探索更多窗口管理 API
了解事件系统
学习如何设置主题
查看完整 API 参考

Web SDK

Python SDK

易语言 SDK

前置条件​

下载 JadeView 库​

安装 WebView2​

步骤 1：初始化 DLL​

参数说明​

返回值​

步骤 2：注册 app-ready 事件​

参数说明​

返回值​

步骤 3：运行消息循环​

步骤 4：注册其他事件回调​

步骤 5：清理资源​

完整示例​

下一步​

前置条件

下载 JadeView 库

安装 WebView2

步骤 1：初始化 DLL

参数说明

返回值

步骤 2：注册 app-ready 事件

参数说明

返回值

步骤 3：运行消息循环

步骤 4：注册其他事件回调

步骤 5：清理资源

完整示例

下一步