API 参考

核心函数

jadeview.init()

初始化 JadeView 应用。必须先通过 jadeview.ipc.on("app-ready", callback) 注册就绪回调，再调用此函数。

jadeview.init(
    app_name: str,            # 应用显示名称
    app_signature: str,       # 应用唯一标识（>=6 字符）
    *,
    enable_devmod: bool = False,     # 是否启用开发者工具
    log_path: str | None = None,     # 日志文件路径
    data_directory: str | None = None,  # 数据根目录
    single_instance: bool = False,   # 是否单实例模式
) -> bool

jadeview.run()

启动消息循环（阻塞当前线程）。在 init() 之后调用。

jadeview.run() -> bool

jadeview.cleanup()

清理所有窗口并准备退出。通常在 window-all-closed 事件回调中调用。

jadeview.cleanup() -> bool

---

jadeview.window — 窗口管理

create_webview_window()

创建标准 WebView 窗口。

window.create_webview_window(
    url: str,                          # 要加载的网址
    parent_window_id: int = 0,         # 父窗口 ID，0 为顶级窗口
    *,
    title: str | None = None,          # 窗口标题
    width: int = 800,                  # 宽度（像素）
    height: int = 600,                 # 高度（像素）
    resizable: int = 1,                # 是否可调整大小
    frame_style: str | None = None,    # 边框样式："normal"/"no-titlebar"/"borderless"
    transparent: int = 0,              # 透明背景
    background_color: str | None = None,  # 背景色 "#RRGGBB"
    always_on_top: int = 0,            # 窗口置顶
    theme: str | None = None,          # "Light"/"Dark"/"System"
    maximized: int = 0,                # 最大化打开
    maximizable: int = 1,              # 允许最大化
    minimizable: int = 1,              # 允许最小化
    x: int = -1, y: int = -1,         # 窗口位置，均为 -1 时居中
    min_width: int = 0, min_height: int = 0,   # 最小尺寸约束
    max_width: int = 0, max_height: int = 0,   # 最大尺寸约束
    fullscreen: int = 0,               # 全屏打开
    focus: int = 1,                    # 创建时获取焦点
    hide_window: int = 0,              # 隐藏创建
    use_page_icon: int = 0,            # 使用网页图标
    content_protection: int = 0,       # 防截屏
    auto_save_state: int = 0,          # 自动记忆窗口位置
    autoplay: int = 0,                 # 自动播放媒体
    background_throttling: int = 1,    # 后台降帧
    disable_right_click: int = 0,      # 禁用右键
    ua: str | None = None,             # 自定义 User-Agent
    preload_js: str | None = None,     # 预注入 JS
    allow_fullscreen: int = 1,         # 允许全屏 API
    postmessage_whitelist: str | None = None,  # postMessage 白名单
) -> int  # window_id（>0 成功，0 失败）

create_borderless_webview_window()

创建无边框 WebView 窗口，可通过 get_window_hwnd() 获取 HWND 进行自定义操作。

window.create_borderless_webview_window(url: str, **webview_settings) -> int

窗口操作函数

函数	说明
set_window_title(window_id, title)	设置窗口标题
set_window_size(window_id, width, height)	设置窗口大小
set_window_position(window_id, x, y)	设置窗口位置
set_window_visible(window_id, visible)	显示/隐藏窗口
set_window_focus(window_id)	使窗口获取焦点
set_window_always_on_top(window_id, always_on_top)	设置窗口置顶
close_window(window_id)	关闭窗口
minimize_window(window_id)	最小化窗口
toggle_maximize_window(window_id)	切换最大化/还原
is_window_maximized(window_id)	查询是否最大化
set_window_fullscreen(window_id, fullscreen)	设置全屏
set_window_enabled(window_id, enabled)	启用/禁用窗口交互
request_redraw(window_id)	请求重绘
get_window_hwnd(window_id)	获取无边框窗口的 HWND

主题与外观

函数	说明
set_window_theme(window_id, theme)	设置主题："Light"/"Dark"/"System"
get_window_theme(window_id)	获取当前主题代码
set_window_backdrop(window_id, backdrop_type)	设置背景效果："mica"/"micaAlt"/"acrylic"
set_window_background_color(window_id, color)	设置背景颜色 "#RRGGBB"

---

jadeview.ipc — 事件与 IPC 通信

on()

订阅事件。

ipc.on(
    event_name: str,    # 事件名称（见 events 模块）
    callback: Callable[[int, str], str | None],
    # callback(window_id, event_data) -> None 放行 / True 拦截 / str 返回数据
) -> int  # callback_id（>0 成功），用于 off() 取消

off()

取消事件订阅。

ipc.off(event_name: str, callback_id: int) -> bool

register_ipc_handler()

注册 IPC 通道处理器，接收前端 jade.invoke() 调用。

ipc.register_ipc_handler(
    channel: str,       # 通道名称
    handler: Callable[[int, str], str | dict | None],
    # handler(window_id, payload) -> None / dict(自动 JSON) / str
) -> bool

send_ipc_message()

向指定窗口的前端发送 IPC 消息。

ipc.send_ipc_message(
    window_id: int,       # 目标窗口 ID
    message_type: str,    # 消息类型（前端通过 jade.on(type, ...) 接收）
    content: str | dict,  # 消息内容（dict 自动转 JSON）
) -> bool

---

jadeview.webview — WebView 操作

函数	说明
navigate_to_url(window_id, url)	导航到指定 URL
reload(window_id)	重新加载当前页面
execute_javascript(window_id, script)	执行 JS（结果通过 javascript-result 事件返回）
set_zoom(window_id, level)	设置缩放级别（1.0 = 100%）
set_content_protection(window_id, enabled)	启用/禁用防截屏

---

jadeview.dialog — 对话框

同步 API

# 打开文件对话框
dialog.show_open_dialog(
    window_id=0, *, title=None, default_path=None,
    button_label=None, filters=None,
    properties="openFile",  # "openFile,openDirectory,multiSelections,showHiddenFiles"
) -> dict | None  # {"canceled": bool, "file_paths": [...]}

# 保存文件对话框
dialog.show_save_dialog(
    window_id=0, *, title=None, default_path=None,
    button_label=None, filters=None,
) -> dict | None  # {"canceled": bool, "file_path": "..."}

# 消息框
dialog.show_message_box(
    window_id=0, *, title=None, message=None, detail=None,
    buttons=None,       # "|" 分隔，如 "确定|取消"
    default_id=0, cancel_id=-1,
    type_="info",       # "none"/"info"/"warning"/"error"/"question"
) -> dict | None  # {"response": int}

# 错误框（简单模式）
dialog.show_error_box(window_id=0, title="错误", content="") -> int

异步 API

异步版本在函数名后加 _async，第一个参数为回调函数：

dialog.show_open_dialog_async(callback, window_id=0, **kwargs) -> bool
dialog.show_save_dialog_async(callback, window_id=0, **kwargs) -> bool
dialog.show_message_box_async(callback, window_id=0, **kwargs) -> bool

---

jadeview.tray — 系统托盘

tray.tray_create() -> int                            # 创建托盘，返回 tray_id
tray.tray_destroy(tray_id) -> bool                   # 销毁托盘
tray.tray_set_visible(tray_id, visible) -> bool      # 显示/隐藏
tray.tray_set_tooltip(tray_id, tooltip) -> bool      # 设置提示文字
tray.tray_set_icon_from_file(tray_id, icon_path) -> bool  # 设置图标（.ico 文件）
tray.tray_set_menu_items(tray_id, items) -> bool     # 设置右键菜单

菜单项格式：

items = [
    {"item_type": 0, "key": "open", "label": "打开"},           # 普通项
    {"item_type": 2, "key": "sep1", "label": ""},               # 分隔线
    {"item_type": 1, "key": "submenu", "label": "子菜单"},       # 子菜单
    {"item_type": 0, "key": "child", "label": "子项", "parent_key": "submenu"},
    {"item_type": 0, "key": "exit", "label": "退出", "dangerous": 1},
]

• item_type：0=普通 / 1=子菜单 / 2=分隔线 / 3=分组
• parent_key：父菜单的 key，用于嵌套子菜单

---

jadeview.notification — 系统通知

notification.show_notification(
    summary: str,                     # 通知标题（必填）
    *,
    body: str | None = None,          # 通知正文
    icon: str | None = None,          # 图标文件绝对路径
    timeout: int = 0,                 # 超时毫秒数（<=0 使用系统默认）
    button1: str | None = None,       # 第一个按钮文字
    button2: str | None = None,       # 第二个按钮文字
    text3: str | None = None,         # 附加文本
    action: str | None = None,        # 动作参数（通过 notification-action 事件回传）
) -> bool

---

jadeview.tools — 工具函数

版本与系统信息

函数	说明
jadeview_version()	获取 JadeView 版本号
get_webview_version()	获取 WebView2 运行时版本号
is_windows_11()	是否为 Windows 11
get_window_count()	当前窗口数量
get_locale()	系统语言设置，如 "zh-CN"
get_displays_info()	所有显示器信息
get_path(name)	系统路径：home/appData/temp/desktop/documents/downloads 等

YAML 配置存储

tools.yaml_set(file_name, key_path, value) -> bool  # 写入
tools.yaml_get(file_name, key_path) -> str | None    # 读取

协议服务（本地文件服务器）

tools.set_protocol_service_path(root_path) -> str | None  # 返回 base URL

URL Scheme 与文件关联

tools.register_url_scheme(scheme) -> bool        # 注册自定义协议
tools.unregister_url_scheme(scheme) -> bool
tools.register_file_association(extension, friendly_name) -> bool
tools.unregister_file_association(extension) -> bool

全局热键

tools.register_global_hotkey(modifiers, vk) -> int    # 返回 hotkey_id
tools.unregister_global_hotkey(hotkey_id) -> bool

• modifiers 支持：整数位掩码、"CTRL+ALT"、["CTRL", "SHIFT"]
• vk 支持：整数虚拟键码、"F1"、"K"、"Enter" 等字符串

数据目录

tools.clear_data_directory() -> bool  # 清除应用数据目录（不可逆）

---

jadeview.events — 事件常量

应用生命周期

常量	值	说明
APP_READY	"app-ready"	应用就绪
SECOND_INSTANCE	"second-instance"	第二个实例启动

窗口生命周期

常量	值	说明
WINDOW_CREATED	"window-created"	窗口已创建
WINDOW_CLOSING	"window-closing"	窗口即将关闭（可拦截）
WINDOW_CLOSED	"window-closed"	窗口已关闭
WINDOW_DESTROYED	"window-destroyed"	窗口已销毁
WINDOW_ALL_CLOSED	"window-all-closed"	所有窗口已关闭

窗口状态

常量	值	说明
WINDOW_RESIZED	"window-resized"	大小改变
WINDOW_STATE_CHANGED	"window-state-changed"	最大化状态改变
WINDOW_FULLSCREEN	"window-fullscreen"	全屏状态改变
WINDOW_MOVED	"window-moved"	位置改变
WINDOW_FOCUSED	"window-focused"	获得焦点
WINDOW_BLURRED	"window-blurred"	失去焦点

WebView / 导航

常量	值	说明
WEBVIEW_WILL_NAVIGATE	"webview-will-navigate"	即将导航（可拦截）
WEBVIEW_DID_START_LOADING	"webview-did-start-loading"	开始加载
WEBVIEW_DID_FINISH_LOAD	"webview-did-finish-load"	加载完成
WEBVIEW_NEW_WINDOW	"webview-new-window"	新窗口请求（可拦截）
WEBVIEW_PAGE_TITLE_UPDATED	"webview-page-title-updated"	页面标题变化
WEBVIEW_DOWNLOAD_STARTED	"webview-download-started"	下载开始
JAVASCRIPT_RESULT	"javascript-result"	JS 执行结果
FILE_DROP	"file-drop"	文件拖放
POSTMESSAGE_RECEIVED	"postmessage-received"	收到 postMessage

托盘 / 通知 / 热键 / 主题

常量	值	说明
TRAY_MENU_COMMAND	"tray-menu-command"	托盘菜单项被点击
TRAY_EVENT	"tray-event"	托盘图标交互
NOTIFICATION_SHOWN	"notification-shown"	通知已显示
NOTIFICATION_DISMISSED	"notification-dismissed"	通知已关闭
NOTIFICATION_FAILED	"notification-failed"	通知失败
NOTIFICATION_ACTION	"notification-action"	通知按钮被点击
GLOBAL_HOTKEY	"global-hotkey"	全局热键触发
THEME_CHANGED	"theme-changed"	主题变化