JadeView

https://jade.run/docs
Admin
JadeView is a lightweight, high-performance, cross-platform framework that allows developers to...
Tokens:64,180
Snippets:621
Trust Score:4.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Complete JavaScript integration example

Source: https://jade.run/docs/api/javascript-api

Demonstrates initialization, event listening, and UI-triggered IPC communication.

```JavaScript
// 初始化时设置背景材料
(async function () {
  try {
    await jade.invoke('setBackdrop', 'mica');
  } catch (error) {
    console.error('设置失败:', error);
  }
})();

// 监听窗口状态变化
jade.on('window-state-changed', function (data) {
  console.log('窗口状态变化:', data);
});

// 按钮点击事件处理
document.getElementById('sendBtn').addEventListener('click', async function () {
  const message = document.getElementById('msgInput').value;
  try {
    const result = await jade.invoke('message', message);
    console.log('发送成功:', result);
  } catch (error) {
    console.error('发送失败:', error);
  }
});
```

--------------------------------

### Initialize JadeView Library

Source: https://jade.run

Register the app-ready callback and initialize the library to start the message loop.

```C
#include "jadeview.h"

int main() {
    jade_on("app-ready", app_ready_callback);
    JadeView_init(1, NULL, NULL, "我的应用", "com.example.myapp", 0);
    run_message_loop();
    return 0;
}
```

--------------------------------

### set_login_autostart

Source: https://jade.run/docs/api/system-api

Enables or disables the application to start automatically upon system login.

```APIDOC
## int32_t set_login_autostart(int32_t enable, const char* args)

### Description
Sets or queries whether the application starts automatically upon system login. Supported on Windows and Linux.

### Parameters
- **enable** (int32_t) - Required - 1 to enable autostart, 0 to disable.
- **args** (string) - Optional - Startup arguments appended to the executable path (e.g., "--minimized"). Pass NULL or empty string for no arguments.

### Response
- **Return Value** (int32_t) - 1 for success, 0 for failure (permission or IO error).
```

--------------------------------

### Complete JadeView application lifecycle example

Source: https://jade.run/docs/spec/quickstart

A full implementation showing initialization, event registration, and window creation with detailed options.

```C
#include <stdio.h>
#include <string.h>
#include "JadeView.h"

// 窗口全部关闭事件回调
const char* window_all_closed_callback(uint32_t window_id, const char* event_data) {
    printf("所有窗口已关闭，准备清理资源\n");
    jadeview_exit();
    return NULL;
}

// app-ready 事件回调函数
const char* app_ready_callback(uint32_t window_id, const char* event_data) {
    if (window_id == 1) {  // window_id==1 即成功；event_data 为 JSON，失败时（window_id==0）为纯文本错误码
        printf("JadeView 准备就绪，现在可以创建窗口了\n");
        
        // 创建窗口选项
        WebViewWindowOptions options = {
            .title = "我的第一个窗口",
            .width = 800,
            .height = 600,
            .resizable = 1,
            .frame_style = "normal",
            .theme = "System",
            .x = -1,
            .y = -1,
            .focus = 1
        };
        
        // 创建窗口
        uint32_t new_window_id = create_webview_window(
            "https://www.example.com",
            0,
            &options,
            NULL
        );
        
        if (new_window_id == 0) {
            printf("窗口创建失败\n");
            return NULL;
        }
        
        printf("窗口创建成功，窗口 ID：%u\n", new_window_id);
    } else {
        printf("JadeView 初始化失败：%s\n", event_data ? event_data : "未知错误");
    }
    
    return NULL;
}

int main() {
    // 注册事件
    jade_on("app-ready", app_ready_callback);
    jade_on("window-all-closed", window_all_closed_callback);
    
    // 初始化
    int result = JadeView_init(
        1,                    // enable_devmod
        NULL,                 // log_path
        NULL,                 // data_directory
        "我的应用",            // app_name
        "com.example.myapp",  // app_signature
        0                     // single_instance
    );
    
    if (result == 0) {
        printf("初始化失败\n");
        return 1;
    }
    
    printf("初始化成功，等待 app-ready 事件...\n");
    
    // 运行消息循环（DLL 嵌入场景可选）
    // run_message_loop();
    
    return 0;
}
```

--------------------------------

### Complete Dialog Usage Examples

Source: https://jade.run/docs/api/dialog-frontend-api

Demonstrates file opening, file saving, and confirmation dialog usage in an asynchronous context.

```JavaScript
async function openFile() {
  const result = await jade.dialog.showOpenDialog({
    title: '选择文件',
    properties: ['openFile', 'multiSelections'],
    filters: [
      { name: 'Text Files', extensions: ['txt', 'md'] },
      { name: 'All Files', extensions: ['*'] }
    ]
  });

  if (!result.canceled) {
    console.log('选择的文件:', result.filePaths);
  }
}

async function saveFile() {
  const result = await jade.dialog.showSaveDialog({
    title: '保存文件',
    defaultPath: 'document.txt'
  });

  if (!result.canceled) {
    console.log('保存路径:', result.filePath);
  }
}

async function showConfirm() {
  const result = await jade.dialog.showMessageBox({
    title: '确认操作',
    message: '确定要删除吗？',
    buttons: ['确定', '取消'],
    type: 'warning'
  });

  console.log('用户选择:', result.response);
}

jade.dialog.showErrorBox('错误', '操作失败，请重试');
```

--------------------------------

### Save Dialog Return Values

Source: https://jade.run/docs/api/dialog-api

JSON response examples for successful file selection and user cancellation.

```JSON
{
  "canceled": false,
  "filePath": "D:/Documents/output.txt"
}
```

```JSON
{
  "canceled": true,
  "filePath": null
}
```

--------------------------------

### Initialize JadeView Runtime

Source: https://jade.run/docs/api

Starts the internal GUI thread and event loop. Must be called before any other JadeView functions, and you must wait for the app-ready event before creating windows.

```C
int32_t JadeView_init(
  int32_t enable_devmod,
  const char* log_path,
  const char* data_directory,
  const char* app_name,
  const char* app_signature,
  int32_t single_instance
);
```

--------------------------------

### Get Current Window Theme

Source: https://jade.run/docs/api/window-api

Queries the current theme of the window, returning 1 for Dark and 0 for Light.

```C
int32_t get_window_theme(uint32_t window_id);
```

--------------------------------

### Retrieve Network Time Stamp (Python)

Source: https://jade.run/docs/api/system-api

Example usage of the jade_ntp_now function via ctypes, demonstrating both built-in server list usage and custom server specification.

```Python
import ctypes, datetime
from ctypes import c_char_p, c_int64

dll = ctypes.WinDLL("JadeView.dll")
dll.jade_ntp_now.argtypes = [c_char_p]
dll.jade_ntp_now.restype = c_int64

# 1) 使用内置列表（传 NULL）
ms = dll.jade_ntp_now(None)
if ms >= 0:
    print("UTC:", datetime.datetime.utcfromtimestamp(ms / 1000.0))

# 2) 指定自定义服务器
ms = dll.jade_ntp_now(b"ntp.aliyun.com")

# 3) 空串等价于内置列表
ms = dll.jade_ntp_now(b"")

# 失败返回 -1
if ms < 0:
    print("NTP 获取失败")
```

--------------------------------

### Get Window Count

Source: https://jade.run/docs/api/window-api

Returns the total number of currently active windows.

```C
uint32_t get_window_count(void);
```

--------------------------------

### run_message_loop

Source: https://jade.run/docs/api

Starts the message loop. This function blocks the current thread until the application exits.

```APIDOC
## run_message_loop

### Description
Blocks the current thread and runs the message loop until the application is terminated. Generally optional for DLL integration scenarios.

### Signature
int32_t run_message_loop(void);

### Response
- **int32_t** - Returns when the application shuts down.
```

--------------------------------

### Create WebView Window

Source: https://jade.run

Configure window options and create a WebView instance pointing to a specific URL.

```C
WebViewWindowOptions opts = {
    .title = "我的桌面应用",
    .width = 1024, .height = 768,
    .resizable = 1, .remove_titlebar = 0
};
uint32_t win = create_webview_window(
    "https://myapp.com", 0, &opts, NULL
);
```

--------------------------------

### 注册 app-ready 事件并创建窗口

Source: https://jade.run/docs/spec/quickstart

通过 jade_on 注册回调函数，并在 app-ready 事件触发后使用 create_webview_window 创建窗口。窗口配置通过 WebViewWindowOptions 和 WebViewSettings 结构体定义。

```C
#include <stdio.h>
#include <string.h>
#include "JadeView.h"

// app-ready 事件回调函数
const char* app_ready_callback(uint32_t window_id, const char* event_data) {
    // 判断是否成功
    if (window_id == 1) {  // window_id==1 即成功；event_data 为 JSON，失败时（window_id==0）为纯文本错误码
        printf("JadeView 准备就绪，现在可以创建窗口了\n");
        
        // 创建窗口选项
        WebViewWindowOptions options = {
            .title = "我的第一个窗口",
            .width = 800,
            .height = 600,
            .resizable = 1,
            .frame_style = "normal",  // normal, no-titlebar, borderless, title-overlay
            .transparent = 0,
            .theme = "System",  // Light, Dark, System
            .maximized = 0,
            .maximizable = 1,
            .minimizable = 1,
            .x = -1,  // -1, -1 表示居中
            .y = -1,
            .min_width = 0,
            .min_height = 0,
            .max_width = 0,
            .max_height = 0,
            .fullscreen = 0,
            .focus = 1,
            .hide_window = 0,
            .use_page_icon = 0,
            .content_protection = 0,
            .auto_save_state = 0
        };
        
        // 创建 WebView 设置
        WebViewSettings settings = {
            .autoplay = 0,
            .background_throttling = 0,
            .allow_right_click = 1,
            .ua = NULL,
            .preload_js = NULL,
            .allow_fullscreen = 0,
            .postmessage_whitelist = NULL
        };
        
        // 创建窗口
        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", event_data ? event_data : "未知错误");
    }
    
    return NULL;
}

int main() {
    // 先注册 app-ready 事件
    jade_on("app-ready", app_ready_callback);
    
    // 初始化
    int result = JadeView_init(
        1,
        NULL,
        NULL,
        "我的应用",
        "com.example.myapp",
        0
    );
    
    if (result == 0) {
        printf("初始化失败\n");
        return 1;
    }
    
    printf("初始化成功，等待 app-ready 事件...\n");
    
    // 运行消息循环（可选，在 DLL 嵌入场景下通常不需要
    // run_message_loop();
    
    return 0;
}
```

--------------------------------

### Get window ID (v2.3)

Source: https://jade.run/docs/api/window-api

Retrieves the JadeView window ID from a given window handle.

```C
size_t get_window_id(int32_t window_id);
```

--------------------------------

### Initialize JadeView and Register Protocol Service

Source: https://jade.run/docs/spec/local-web-resources

Demonstrates initializing the JadeView engine, registering IPC handlers for window management, and mapping a local directory to the JADE:// protocol.

```C
#include <stdio.h>
#include <string.h>
#include "JadeView.h"

// 窗口控制 IPC 回调
const char* minimize_callback(uint32_t window_id, const char* event_data) {
    minimize_window(window_id);
    return jade_text_create("{\"ok\":true}");
}

const char* maximize_callback(uint32_t window_id, const char* event_data) {
    toggle_maximize_window(window_id);
    return jade_text_create("{\"ok\":true}");
}

const char* close_callback(uint32_t window_id, const char* event_data) {
    close_window(window_id);
    return jade_text_create("{\"ok\":true}");
}

const char* app_ready_callback(uint32_t window_id, const char* event_data) {
    if (window_id == 1) {  // window_id==1 即成功；event_data 为 JSON，失败时（window_id==0）为纯文本错误码
        printf("JadeView 准备就绪\n");

        // 注册窗口控制命令
        register_ipc_handler("minimize-window", minimize_callback);
        register_ipc_handler("toggle-maximize", maximize_callback);
        register_ipc_handler("close-window", close_callback);

        // 设置本地协议服务 —— 将 ./web 目录映射到 JADE://com.example.myapp
        char url_buffer[256];
        int result = set_protocol_service_path(
            "./web",              // 本地资源目录
            url_buffer,           // 输出协议 URL 缓冲区
            sizeof(url_buffer),   // 缓冲区大小
            0                     // hot_reload: 0=禁用, 1=启用
        );

        if (result == 1) {
            printf("协议 URL: %s\n", url_buffer);
            // url_buffer 内容类似: JADE://com.example.myapp

            WebViewWindowOptions options = {
                .title = "本地资源示例",
                .width = 800,
                .height = 600,
                .resizable = 1,
                .frame_style = "normal"
            };

            create_webview_window(url_buffer, 0, &options, NULL);
        } else {
            printf("协议服务设置失败\n");
        }
    } else {
        printf("初始化失败: %s\n", event_data ? event_data : "未知");
    }
    return NULL;
}

int main() {
    // 必须在 JadeView_init 之前注册 app-ready
    jade_on("app-ready", app_ready_callback);

    int result = JadeView_init(
        1,                      // enable_devmod
        NULL,                   // log_path
        NULL,                   // data_directory
        "我的应用",              // app_name (应用显示名)
        "com.example.myapp",    // app_signature (小写后用作协议域名)
        0                       // single_instance
    );

    if (result == 0) {
        printf("初始化失败\n");
        return 1;
    }

    printf("JadeView 已启动\n");
    return 0;
}
```

--------------------------------

### Get Printer List

Source: https://jade.run/docs/api/system-api

Retrieves a list of available system printers as a JSON array string.

```C
int32_t jade_get_printer_list(char* buffer, int buffer_size);
```

```JSON
["Microsoft Print to PDF","HP LaserJet Pro MFP M428fdw","Fax"]
```

--------------------------------

### Get Cursor Position

Source: https://jade.run/docs/api/system-api

Retrieves the global screen coordinates of the mouse cursor as a JSON string.

```C
int32_t get_cursor_position(char* buffer, int buffer_size);
```

--------------------------------

### 初始化 JadeView 运行时

Source: https://jade.run/docs/spec/quickstart

调用 JadeView_init 启动 GUI 线程和事件循环。必须在初始化前注册 app-ready 事件以确保后续窗口创建成功。

```C
#include "JadeView.h"

int main() {
    // 初始化 JadeView
    // 参数说明：
    // 1. enable_devmod: 开发者模式（1=启用，0=禁用）
    // 2. log_path: 日志文件路径，NULL 表示不写文件
    // 3. data_directory: 数据根目录，NULL 使用默认
    // 4. app_name: 应用显示名
    // 5. app_signature: 应用唯一标识（至少6个字符）
    // 6. single_instance: 是否单实例（1=单实例，0=多实例）
    int result = JadeView_init(
        1,           // enable_devmod
        NULL,        // log_path
        NULL,        // data_directory
        "我的应用",   // app_name
        "com.example.myapp",  // app_signature
        0            // single_instance
    );
    
    if (result == 0) {
        printf("初始化失败\n");
        return 1;
    }
    
    printf("初始化成功，等待 app-ready 事件...\n");
    
    // 在 app-ready 事件后才能创建窗口
    
    return 0;
}
```

--------------------------------

### Create a standard WebView window

Source: https://jade.run/docs/api/window-api

Initializes a browser window with a system title bar and border. Use this for primary application windows.

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

--------------------------------

### Get Window Bounds

Source: https://jade.run/docs/api/window-api

Retrieves window position and size as a JSON string. Supported since v2.2.

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

--------------------------------

### create_webview_window

Source: https://jade.run/docs/api/window-api

Creates a standard browser window with a system title bar and border, hosting a WebView.

```APIDOC
## create_webview_window

### Description
Creates a standard browser window with a system title bar and border, hosting a WebView. This is the primary method for creating main application windows.

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

### Parameters
- **url** (string) - The initial URL or local protocol address to load.
- **parent_window_id** (uint32_t) - The parent window ID; 0 indicates a top-level window.
- **options** (WebViewWindowOptions*) - Optional window appearance configuration.
- **webview_settings** (WebViewSettings*) - Optional webview behavior configuration.

### Returns
- **uint32_t** - The window ID if successful (> 0), or 0 if failed.
```

--------------------------------

### Message Box Return Value

Source: https://jade.run/docs/api/dialog-api

Example of the JSON response indicating the index of the button clicked by the user.

```JSON
{
  "response": 0
}
```

--------------------------------

### jade.dialog.showOpenDialog(options)

Source: https://jade.run/docs/api/dialog-frontend-api

显示打开文件对话框，允许用户选择一个或多个文件。

```APIDOC
## jade.dialog.showOpenDialog(options)

### Description
显示打开文件对话框，用于选择一个或多个文件。

### Parameters
- **options** (Object) - Required
  - **title** (string) - Optional - 对话框标题
  - **defaultPath** (string) - Optional - 默认打开路径
  - **buttonLabel** (string) - Optional - 确认按钮的自定义标签
  - **filters** (Array) - Optional - 文件过滤器数组，格式 [{ name: string, extensions: string[] }]
  - **properties** (Array) - Optional - 字符串数组
  - **blocking** (boolean) - Optional - 对话框期间是否禁用父窗口，默认 true

### Returns
- **Promise<Object>**
  - **canceled** (boolean) - 是否取消
  - **filePaths** (Array) - 选择的文件路径数组

### Example
```javascript
const result = await jade.dialog.showOpenDialog({
  title: '选择图片',
  filters: [
    { name: 'Images', extensions: ['jpg', 'png'] },
    { name: 'All Files', extensions: ['*'] }
  ],
  properties: ['openFile', 'multiSelections']
});

if (!result.canceled) {
  console.log('选择的文件:', result.filePaths);
}
```
```

--------------------------------

### Manage Login Autostart

Source: https://jade.run/docs/api/system-api

Functions to enable, disable, or query the application's autostart status on system login.

```C
// enable: 1=启用，0=取消；args: 追加到可执行路径后的启动参数（NULL / 空 = 无）
int32_t set_login_autostart(int32_t enable, const char* args);
```

```C
int32_t get_login_autostart(void);
```

--------------------------------

### WebViewWindowOptions

Source: https://jade.run/docs/spec/custom-titlebar

创建窗口时的配置选项，用于指定标题栏样式。

```APIDOC
## WebViewWindowOptions

### Description
用于 create_webview_window 的配置结构体，通过 frame_style 字段控制标题栏行为。

### Fields
- **frame_style** (const char*) - 标题栏样式，可选值："title-overlay"（内置覆盖层）或 "no-titlebar"（完全自定义）
```

--------------------------------

### get_login_autostart

Source: https://jade.run/docs/api/system-api

Queries the current autostart status of the application.

```APIDOC
## int32_t get_login_autostart(void)

### Description
Checks if the application is currently configured to start automatically upon system login.

### Response
- **Return Value** (int32_t) - 1 if autostart is enabled, 0 if not.
```

--------------------------------

### SDK 文档目录结构示例

Source: https://jade.run/docs/spec/contributing-sdk

建议的 SDK 文档文件组织结构，采用 Markdown 格式。

```markdown
docs/
  your-sdk-name/
    index.md          # 主页
    quickstart.md     # 快速开始
    api-reference.md  # API 参考
    advanced.md       # 高级用法
    examples.md       # 示例代码
    faq.md            # 常见问题
```

--------------------------------

### Get window handle (HWND)

Source: https://jade.run/docs/api/window-api

Retrieves the native HWND for a window to use with Win32 APIs. Note that prior to version 2.3, this only returns valid handles for borderless windows.

```C
size_t get_window_hwnd(uint32_t window_id);
```

--------------------------------

### JadeView_init

Source: https://jade.run/docs/api/japk-load-memory

Initializes the JadeView environment before loading any JAPK packages.

```APIDOC
## int JadeView_init(int mode, const char* data_path, const char* cache_path, const char* app_name, const char* app_signature, int flags)

### Description
Initializes the JadeView SDK. This must be called before any other operations.

### Parameters
- **mode** (int) - Required - Initialization mode.
- **app_name** (const char*) - Required - Application name.
- **app_signature** (const char*) - Required - Application signature string.
```

--------------------------------

### 创建无边框窗口 (C)

Source: https://jade.run/docs/spec/custom-titlebar

使用 create_borderless_webview_window 函数创建无边框窗口，该函数不依赖 frame_style 选项。

```c
#include <stdio.h>
#include <string.h>
#include "JadeView.h"

const char* app_ready_callback(uint32_t window_id, const char* event_data) {
  if (window_id == 1) {  // window_id==1 即成功；event_data 为 JSON，失败时（window_id==0）为纯文本错误码
    // 创建无边框窗口
    // 注意：create_borderless_webview_window 的签名为 (url, settings)，不接收 WebViewWindowOptions，
    // 无边框/无标题栏由该函数本身决定，无法也无需通过 options.frame_style 指定。

    uint32_t new_window_id = create_borderless_webview_window(
      "https://your-app.local",
      NULL  // WebViewSettings*，可为 NULL
    );

    // 获取 HWND 用于额外的 Win32 操作
    size_t hwnd = get_window_hwnd(new_window_id);
  }
  return NULL;
}

int main() {
  jade_on("app-ready", app_ready_callback);
  JadeView_init(1, NULL, NULL, "我的应用", "com.example.myapp", 0);
  return 0;
}
```

--------------------------------

### 使用主题设置 (C)

Source: https://jade.run/docs/spec/quickstart

通过 WebViewWindowOptions 配置窗口初始主题，并使用 set_window_theme 在运行时动态切换主题。

```C
#include <stdio.h>
#include <string.h>
#include "JadeView.h"

const char* app_ready_callback(uint32_t window_id, const char* event_data) {
    if (window_id == 1) {  // window_id==1 即成功；event_data 为 JSON，失败时（window_id==0）为纯文本错误码
        printf("创建带主题的窗口\n");
        
        WebViewWindowOptions options = {
            .title = "主题示例",
            .width = 800,
            .height = 600,
            .theme = "Dark",  // 使用深色主题
            .background_color = "#1e1e1e"
        };
        
        uint32_t new_window_id = create_webview_window(
            "https://www.example.com",
            0,
            &options,
            NULL
        );
        
        if (new_window_id != 0) {
            // 运行时切换主题
            set_window_theme(new_window_id, "Light");
            // 设置窗口背景
            set_window_background_color(new_window_id, "#ffffff");
        }
    }
    return NULL;
}

int main() {
    jade_on("app-ready", app_ready_callback);
    JadeView_init(1, NULL, NULL, "主题示例", "com.example.theme", 0);
    return 0;
}
```

--------------------------------

### Create a borderless WebView window

Source: https://jade.run/docs/api/window-api

Initializes a window without a system title bar, suitable for custom UI or floating tool windows.

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

--------------------------------

### SDK 安装命令示例

Source: https://jade.run/docs/spec/contributing-sdk

展示如何通过 npm 安装 SDK。

```bash
npm install my-sdk-name
```

--------------------------------

### 使用 showOpenDialog 选择文件

Source: https://jade.run/docs/api/dialog-frontend-api

调用系统原生文件打开对话框，支持通过 filters 限制文件类型及 properties 配置选择模式。

```javascript
const result = await jade.dialog.showOpenDialog({
  title: '选择图片',
  filters: [
    { name: 'Images', extensions: ['jpg', 'png'] },
    { name: 'All Files', extensions: ['*'] }
  ],
  properties: ['openFile', 'multiSelections']
});

if (!result.canceled) {
  console.log('选择的文件:', result.filePaths);
}
```

--------------------------------

### 通过命令行安装 WebView2 Runtime

Source: https://jade.run/docs/spec/webview2-installation

使用常青引导程序进行标准安装或静默安装，适用于自动化部署场景。

```shell
# 使用常青引导程序安装
MicrosoftEdgeWebView2Setup.exe

# 静默安装（无用户界面）
MicrosoftEdgeWebView2Setup.exe /silent /install
```

--------------------------------

### SDK 介绍文档结构示例

Source: https://jade.run/docs/spec/contributing-sdk

SDK 文档主页的推荐内容结构，包含核心特性和适用场景。

```markdown
# 我的 SDK 名称

## 什么是我的 SDK

我的 SDK 是一个用于...的库，提供了...功能。

## 核心特性

- 特性 1
- 特性 2
- 特性 3

## 适用场景

我的 SDK 适用于以下场景：
- 场景 1
- 场景 2
- 场景 3
```

--------------------------------

### Navigate to URL

Source: https://jade.run/docs/api/webview-api

Navigates the specified window to a new URL. Supports custom headers as a JSON string.

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

--------------------------------

### WSL2 环境配置环境变量

Source: https://jade.run/docs/spec/compatibility

在 WSL2 (WSLg) 环境下运行 JadeView 时，需设置这些环境变量以解决渲染和输入问题。

```shell
export GDK_BACKEND=x11                              # Wayland 输入异常，改用 X11
export WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS=1   # WSL 无 user namespace，否则渲染进程起不来
export WEBKIT_DISABLE_DMABUF_RENDERER=1             # 关闭 DMABUF，避免黑屏
# 中文字体：sudo apt install -y fonts-wqy-zenhei
```

--------------------------------

### 读取整个文件 (yaml_get_all)

Source: https://jade.run/docs/api/yaml-storage-api

读取整个 YAML 文件内容并以 JSON 字符串形式返回。

```c
int yaml_get_all(const char* file_name, char* buffer, size_t buffer_size);
```

--------------------------------

### 注册与注销自定义 URL 协议

Source: https://jade.run/docs/api/system-api

用于在系统中登记自定义 URL 协议，以便通过特定链接启动应用程序。调用前必须确保已完成 JadeView_init 初始化。

```C
int32_t register_url_scheme(const char* scheme);
int32_t unregister_url_scheme(const char* scheme);
```

--------------------------------

### app-ready

Source: https://jade.run/docs/api/event-types

Triggered when JadeView initialization is complete. All window creation and API calls must occur after this event.

```APIDOC
## app-ready

### Description
Triggered when JadeView initialization is complete. All window creation and API calls must occur after this event; calls made before this will fail.

### Event Data
- **window_id** (integer) - 1 indicates success, 0 indicates failure.
- **event_data** (string/JSON) - Success returns a JSON object; failure returns a plain text error message.
```

--------------------------------

### 获取 WebView 版本

Source: https://jade.run/docs/api/tools-api

获取本机 WebView2 运行时的版本号，而非 JadeView DLL 的版本。

```C
int32_t get_webview_version(char* buffer, size_t buffer_size);
```

--------------------------------

### JadeView_init

Source: https://jade.run/docs/api

Initializes the GUI thread and event loop. Must be called before other operations, and the application should wait for the 'app-ready' event.

```APIDOC
## JadeView_init

### Description
Starts the internal GUI thread and event loop. After calling this, the application must wait for the 'app-ready' event before creating windows.

### Signature
int32_t JadeView_init(int32_t enable_devmod, const char* log_path, const char* data_directory, const char* app_name, const char* app_signature, int32_t single_instance);

### Parameters
- **enable_devmod** (int32_t) - Required - Whether to enable development features like DevTools.
- **log_path** (const char*) - Required - Path to the log file; pass NULL to disable file logging.
- **data_directory** (const char*) - Required - Root directory for application data.
- **app_name** (const char*) - Required - Display name of the application.
- **app_signature** (const char*) - Required - Unique identifier for the application (min 6 chars).
- **single_instance** (int32_t) - Required - If non-zero, restricts the application to a single process instance.

### Response
- **1** (int32_t) - GUI thread started, waiting for 'app-ready'.
- **0** (int32_t) - Initialization failed.
```

--------------------------------

### Set Tray Icon from File

Source: https://jade.run/docs/api/tray-api

Loads the tray icon from an image file such as .ico.

```C
int32_t tray_set_icon_from_file(uint32_t tray_id, const char* icon_path_utf8);
```

--------------------------------

### 设置窗口背景材质

Source: https://jade.run/docs/api/theme-management

仅适用于 Windows 11，用于应用系统背景材质如 Mica 或亚克力。backdrop_type 参数大小写不敏感。

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

--------------------------------

### 检查 WebView2 Runtime 版本

Source: https://jade.run/docs/spec/compatibility

通过注册表查询当前安装的 WebView2 Runtime 版本。

```shell
reg query "HKLM\SOFTWARE\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" /v pv
```

--------------------------------

### tray_create

Source: https://jade.run/docs/api/tray-api

Creates a system tray icon. If a tray already exists, it returns the existing tray_id.

```APIDOC
## uint32_t tray_create(void)

### Description
Creates a system tray icon. If a tray already exists, it returns the existing tray_id.

### Returns
- **uint32_t** - The tray_id, which must be used for subsequent tray API calls.
```

--------------------------------

### Open DevTools

Source: https://jade.run/docs/api/webview-api

Opens the DevTools window. Requires devtools to be enabled during window initialization. Supported since v2.2.

```C
int32_t open_devtools(uint32_t window_id);
```

--------------------------------

### Main process IPC handlers and initialization

Source: https://jade.run/docs/spec/ipc-communication

Registers IPC handlers for requests and initializes the JadeView application.

```C
#include <stdio.h>
#include <string.h>
#include "JadeView.h"

// 处理 get-config
const char* get_config_callback(uint32_t window_id, const char* event_data) {
    return jade_text_create("{\"theme\":\"dark\",\"version\":\"2.1\"}");
}

// 处理 do-action
const char* do_action_callback(uint32_t window_id, const char* event_data) {
    printf("do-action 收到: %s\n", event_data);

    // 处理完后向渲染进程推送结果
    send_ipc_message(window_id, "data-update",
        "{\"status\":\"saved\"}");

    return jade_text_create("{\"ok\":true}");
}

const char* app_ready_callback(uint32_t window_id, const char* event_data) {
    if (window_id == 1) {  // window_id==1 即成功；event_data 为 JSON，失败时（window_id==0）为纯文本错误码
        // 注册 IPC 处理器
        register_ipc_handler("get-config", get_config_callback);
        register_ipc_handler("do-action", do_action_callback);

        // 创建窗口
        WebViewWindowOptions options = {
            .title = "IPC 示例",
            .width = 800,
            .height = 600,
            .frame_style = "normal"
        };

        create_webview_window("https://example.com", 0, &options, NULL);
    }
    return NULL;
}

int main() {
    jade_on("app-ready", app_ready_callback);

    int result = JadeView_init(
        1, NULL, NULL,
        "IPC 示例",
        "com.example.ipc",
        0
    );
    if (result == 0) {
        printf("初始化失败\n");
        return 1;
    }

    printf("JadeView 已启动\n");
    return 0;
}
```

--------------------------------

### 注册与注销全局热键

Source: https://jade.run/docs/api/system-api

在焦点不在应用窗口时注册全局快捷键，成功后返回热键 ID。在 Linux Wayland 环境下该功能不可用。

```C
uint32_t register_global_hotkey(uint32_t modifiers, uint32_t vk);
int32_t unregister_global_hotkey(uint32_t hotkey_id);
```

--------------------------------

### 验证 Node.js 安装

Source: https://jade.run/docs/api/japk

检查 Node.js 环境是否已正确安装。

```Shell
node --version
```

--------------------------------

### 设置窗口任务栏可见性

Source: https://jade.run/docs/api/window-api

控制窗口是否出现在任务栏和 Alt-Tab 切换列表中。适用于悬浮工具窗或挂件。

```C
int32_t set_window_skip_taskbar(uint32_t window_id, int32_t skip);
```

--------------------------------

### 调用系统对话框 (jade.dialog)

Source: https://jade.run/docs/api/javascript-api

用于调起原生系统对话框，所有方法均返回 Promise。options 参数语义与 Electron 的 dialog 接口类似。

```javascript
const result = await jade.dialog.showOpenDialog({ /* options */ });
await jade.dialog.showSaveDialog({ /* options */ });
await jade.dialog.showMessageBox({ /* options */ });
await jade.dialog.showErrorBox('出错了', '文件读取失败');
```

--------------------------------

### Configure MCP Server

Source: https://jade.run/docs/spec/mcp

Add this configuration to your AI tool's MCP settings to enable JadeView documentation access.

```json
{
  "mcpServers": {
    "jade_view": {
      "url": "https://mcp.jade.run/mcp",
      "transport": "http"
    }
  }
}
```

--------------------------------

### 设置本地协议服务路径

Source: https://jade.run/docs/api/local-server-api

将本地目录或 JAPK 资源包注册为内置访问根目录。须在 app-ready 成功之后调用。

```C
int32_t set_protocol_service_path(
  const char* root_path,
  char* url_buffer,
  size_t buffer_size,
  int hot_reload
);
```

--------------------------------

### Renderer process IPC interaction

Source: https://jade.run/docs/spec/ipc-communication

Demonstrates initializing data requests, event subscription, and triggering main process actions via jade.invoke.

```JavaScript
// 1. 初始化时向主进程请求数据
(async function() {
    try {
        const config = await jade.invoke('get-config', {});
        console.log('配置:', config);
    } catch (e) {
        console.error('请求失败:', e);
    }
})();

// 2. 订阅主进程通知
jade.on('data-update', (data) => {
    document.getElementById('status').textContent = data.status;
});

// 3. 按钮触发主进程操作
document.getElementById('btn').onclick = async () => {
    const result = await jade.invoke('do-action',
        { action: 'save', value: 'hello' });
    console.log('结果:', result);
};
```

--------------------------------

### JadeView_get_app_signature

Source: https://jade.run/docs/api/japk-load-memory

返回 JadeView_init 时设置的 app_signature。

```APIDOC
## JadeView_get_app_signature

### Description
返回 JadeView_init 时设置的 app_signature（与是否已加载、包类型无关）。

### Signature
char* JadeView_get_app_signature(void);

### Returns
- **string** - 应用标识字符串，调用方需用 jade_text_free 释放
```

--------------------------------

### second-instance

Source: https://jade.run/docs/api/event-types

Triggered in the first instance when a second instance of the application is launched.

```APIDOC
## second-instance

### Description
Triggered in the first instance when a second instance of the application is launched, providing the command-line arguments of the second instance.

### Parameters
- **event_data** (object) - Contains `argv` array with command-line arguments
- **window_id** (integer) - Fixed to 0
```

--------------------------------

### SDK 基本使用示例

Source: https://jade.run/docs/spec/contributing-sdk

展示如何初始化 SDK 并调用异步方法，包含错误处理。

```javascript
import { MySDK } from 'my-sdk-name';

// 初始化 SDK
const sdk = new MySDK({
  apiKey: 'your-api-key'
});

// 使用 SDK 功能
async function main() {
  try {
    const result = await sdk.someMethod();
    console.log(result);
  } catch (error) {
    console.error(error);
  }
}

main();
```

--------------------------------

### Show Save File Dialog

Source: https://jade.run/docs/api/dialog-api

Displays a synchronous 'Save As' dialog. The returned JSON string must be freed using jade_text_free().

```C
char* jade_dialog_show_save_dialog(const FileDialogParams* params);
```

--------------------------------

### C 语言内存加载示例

Source: https://jade.run/docs/api/japk-load-memory

展示了从文件读取 JAPK 数据到内存并调用 JadeView_load_from_bytes 进行加载的完整流程。

```c
#include "JadeView.h"

void load_from_memory_example() {
    // 1. 初始化
    JadeView_init(1, NULL, NULL, "MyApp", "com.example.app", 0);

    // 2. 读取 JAPK 文件到内存
    FILE* f = fopen("app.japk", "rb");
    fseek(f, 0, SEEK_END);
    size_t size = ftell(f);
    fseek(f, 0, SEEK_SET);
    uint8_t* data = malloc(size);
    fread(data, 1, size, f);
    fclose(f);

    // 3. 从内存加载（混淆包，无需公钥）
    int rc = JadeView_load_from_bytes(data, size);
    if (rc != 0) {
        printf("加载失败: %d\n", rc);
        free(data);
        return;
    }

    // 4. 获取协议 URL（内存加载时传入空字符串）
    char url_buffer[256];
    set_protocol_service_path("", url_buffer, sizeof(url_buffer), 0);  // 第 4 参 hot_reload，内存加载传 0
    // url_buffer 内容类似: JADE://{app_signature}/（app_signature 为 JadeView_init 第 5 参，小写）

    // 5. 创建窗口使用该 URL
    WebViewWindowOptions options = {
        .title = "JAPK 内存加载",
        .width = 800,
        .height = 600,
        .frame_style = "normal"
    };
    create_webview_window(url_buffer, 0, &options, NULL);

    free(data);
}
```

```c
// 设置公钥后，只接受签名包
JadeView_set_public_key("QeeOu5LQdQooeyOID6h/ChFEo5RhbAFoKgslznp5Nbk=");

int rc = JadeView_load_from_bytes(data, size);
// 此时只接受 JAPKV002 签名包
```

--------------------------------

### jade_text_create / jade_text_free

Source: https://jade.run/docs/api/tools-api

文本内存管理函数。

```APIDOC
## char* jade_text_create(const char* text)
## void jade_text_free(char* ptr)

### Description
jade_text_create 将 UTF-8 文本拷贝到堆上并返回指针；jade_text_free 用于释放该指针。
```

--------------------------------

### 使用 jade_on 注册事件回调

Source: https://jade.run/docs/spec/quickstart

通过定义回调函数并使用 jade_on 绑定事件名称，实现对应用准备就绪、窗口关闭及页面加载完成等状态的监听。

```C
#include <stdio.h>
#include <string.h>
#include "JadeView.h"

// 窗口关闭事件回调
const char* window_close_callback(uint32_t window_id, const char* event_data) {
    printf("窗口 %u 即将关闭\n", window_id);
    return NULL;  // 返回 NULL 允许关闭，返回错误信息阻止关闭
}

// 页面加载完成事件回调
const char* page_loaded_callback(uint32_t window_id, const char* event_data) {
    printf("页面已加载：%s\n", event_data);
    return NULL;
}

// app-ready 事件回调
const char* app_ready_callback(uint32_t window_id, const char* event_data) {
    if (window_id == 1) {  // window_id==1 即成功；event_data 为 JSON，失败时（window_id==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
        );
        
        if (new_window_id != 0) {
            // 注册窗口特定事件
            jade_on("window-closed", window_close_callback);
            jade_on("webview-did-finish-load", page_loaded_callback);
        }
    }
    return NULL;
}

int main() {
    jade_on("app-ready", app_ready_callback);
    
    int result = JadeView_init(
        1,
        NULL,
        NULL,
        "我的应用",
        "com.example.myapp",
        0
    );
    
    if (result == 0) {
        printf("初始化失败\n");
        return 1;
    }
    
    printf("初始化成功\n");
    
    return 0;
}
```

--------------------------------

### Set Window Fullscreen

Source: https://jade.run/docs/api/window-api

Enters or exits fullscreen mode. The request is processed asynchronously.

```C
int32_t set_window_fullscreen(uint32_t window_id, int32_t fullscreen);
```
Tokens:
Raw