API 参考

app = JadeUIApp()

app.initialize(
    enable_dev_tools=False,  # 是否启用开发者工具 (F12)
    log_file=None,           # 日志文件路径
    data_directory=None,     # WebView 数据目录
    app_name=None,           # 应用名称 (JadeView 2.x)
    app_signature=None,      # 应用签名，占位值至少 6 个字符 (JadeView 2.x)
    single_instance=False,   # 单实例模式 (JadeView 2.x)
)

app.run()

app.quit()

if app.is_ready():
    print("应用已就绪")

version = app.get_webview_version()
print(f"WebView 版本: {version}")  # 例如: "120.0.2210.144"

@app.on_ready
def setup():
    window = Window("My App")
    window.show()

@app.on_window_all_closed
def cleanup():
    print("所有窗口已关闭")

window = Window(
    title="Window",          # 窗口标题
    width=800,               # 宽度
    height=600,              # 高度
    url=None,                # 初始 URL
    **options                # 其他选项
)

window.show(url=None)  # 可选传入 URL

window.hide()

window.close()

window.focus()

window.minimize()

window.maximize()

window.restore()

window.set_fullscreen(True)   # 进入全屏
window.set_fullscreen(False)  # 退出全屏

window.toggle_fullscreen()

window.set_title("New Title")
# 或使用属性
window.title = "New Title"

window.set_size(1280, 720)

window.set_min_size(400, 300)

window.set_max_size(1920, 1080)  # 0 表示无限制

window.set_position(100, 100)

window.center()

window.set_visible(True)
window.set_visible(False)

window.set_always_on_top(True)

window.set_resizable(False)

window.set_skip_taskbar(True)
window.set_skip_taskbar(False)

window.set_no_activate(True)
window.set_no_activate(False)

window.set_level("topmost")  # topmost / normal / bottom / desktop

from jadeui import Theme

window.set_theme(Theme.LIGHT)  # 浅色
window.set_theme(Theme.DARK)   # 深色
window.set_theme(Theme.SYSTEM) # 跟随系统

theme = window.get_theme()

from jadeui import Backdrop

window.set_backdrop(Backdrop.MICA)     # Mica 效果
window.set_backdrop(Backdrop.MICA_ALT) # Mica Alt 效果
window.set_backdrop(Backdrop.ACRYLIC)  # Acrylic 效果

window.load_url("https://example.com")
# 或
window.navigate("https://example.com")

window.execute_js("console.log('Hello!')")
# 或
window.eval("document.title = 'New Title'")

window.reload()

hwnd = window.get_hwnd()

count = Window.get_window_count()

window = Window.get_window_by_id(1)

window_id = Window.get_id_from_hwnd(hwnd)

windows = Window.get_all_windows()

from jadeui import Window

window = Window(title="事件示例")

@window.on_resized
def handle_resize(width: int, height: int):
    print(f"窗口大小: {width} x {height}")

@window.on_moved
def handle_move(x: int, y: int):
    print(f"窗口位置: ({x}, {y})")

@window.on_focused
def handle_focus():
    print("窗口获得焦点")

@window.on_closing
def handle_closing():
    if has_unsaved_changes:
        return True  # 阻止关闭
    return False

@window.on_page_loaded
def handle_loaded(url: str):
    print(f"页面加载完成: {url}")

window.show()

from jadeui import Window, Events

window = Window(title="事件示例")

# 参数已自动解析，不需要 json.loads
@window.on(Events.WINDOW_RESIZED)
def on_resize(width: int, height: int):
    print(f"窗口大小: {width} x {height}")

@window.on(Events.WEBVIEW_DID_FINISH_LOAD)
def on_page_load(url: str):
    print(f"页面加载完成: {url}")

window.show()

from jadeui import Window

window = Window(title="文件拖放示例")

@window.on_file_dropped
def on_file_drop(files: list, x: int, y: int):
    print(f"拖放了 {len(files)} 个文件到位置 ({x}, {y})")
    for file_path in files:
        print(f"  - {file_path}")

window.show()

@window.on("drag-drop")
def on_drag_drop(data):
    print(data["type"], data.get("paths", []))
    # JadeView 2.3 起，enter/drop 阶段返回 True 或非空字符串可同步拦截/消费
    return False

from jadeui import Window

window = Window(title="下载事件示例")

@window.on_download_started
def on_download(url: str, filename: str):
    print(f"下载请求: {filename}")
    print(f"来源: {url}")
    
    # 阻止可执行文件下载
    if filename.endswith((".exe", ".msi", ".bat")):
        print("已阻止可执行文件下载")
        return True
    
    # 阻止来自不信任域名的下载
    if "untrusted-site.com" in url:
        return True
    
    return False  # 允许下载

window.show()

ipc = IPCManager()

def handler(window_id: int, message: str) -> int:
    print(f"收到: {message}")
    return 1

ipc.register_handler("channel-name", handler)

ipc.send(window_id, "channel-name", "message content")

ipc.remove_handler("channel-name")

channels = ipc.list_handlers()

@ipc.on("greet")
def handle_greet(window_id, message):
    print(f"收到: {message}")
    ipc.send(window_id, "response", "Hello!")
    return 1

server = LocalServer()

url = server.start(
    app_name="myapp",    # 兼容保留，JadeView 2.x 底层不再使用
    root_path="./web",   # 静态根目录
    hot_reload=False,    # 是否启用热重载（JAPK 文件上会强制关闭）
    japk=None,           # 可选：.japk 路径（优先于 root_path）
    from_memory=False,   # True：配合已内存加载的 JAPK（见 jadeui.japk.Japk）
)
print(f"服务器运行在: {url}")

server.stop()

url = server.get_url("index.html")

router = Router(ipc=None)  # 可传入 IPCManager 实例

router.page(
    path="/",                    # 路由路径
    template="pages/home.html",  # 模板文件
    title="首页",                # 页面标题
    icon="🏠",                   # 图标 (侧边栏显示)
    show_in_nav=True,            # 是否显示在导航栏
)

window = router.mount(
    title="My App",          # 窗口标题
    web_dir="web",           # Web 文件目录
    width=1024,              # 窗口宽度
    height=768,              # 窗口高度
    sidebar_width=220,       # 侧边栏宽度
    theme="system",          # 主题
    initial_path="/",        # 初始路由
    template=None,           # 自定义模板 (None 使用内置)
    head_links=[],           # 额外 CSS 链接
    scripts=[],              # 额外 JS 脚本
    **window_options         # 其他窗口选项
)

router.go("/settings")
router.go("/user/123")  # 带参数

router.set_theme("light")  # light, dark, system

router.set_backdrop("mica")  # mica, micaAlt, acrylic

from jadeui import Dialog

# 阻塞模式（默认）
Dialog.show_open_dialog(
    window_id=1,
    title="选择图片",
    default_path="C:/",
    filters=[
        {"name": "图片", "extensions": ["png", "jpg", "gif"]},
        {"name": "所有文件", "extensions": ["*"]}
    ],
    properties=["openFile", "multiSelections"]
)

# 非阻塞模式 + 回调
def on_result(result):
    print(f"选中: {result}")

Dialog.show_open_dialog(
    window_id=1,
    title="选择文件",
    properties=["openFile"],
    blocking=False,
    callback=on_result
)

Dialog.show_save_dialog(
    window_id=1,
    title="保存文档",
    default_path="document.txt",
    filters=[{"name": "文本文件", "extensions": ["txt"]}]
)

Dialog.show_message_box(
    window_id=1,
    title="确认删除",
    message="确定要删除这个文件吗？",
    detail="此操作不可撤销",
    type_="warning",
    buttons=["删除", "取消"],
    default_id=1,
    cancel_id=1
)

Dialog.show_error_box(1, "错误", "文件读取失败！")

Dialog.confirm("确定要退出吗？")
Dialog.confirm("删除文件？", title="确认", ok_label="删除", cancel_label="取消")

Dialog.alert("操作成功！")
Dialog.alert("请注意！", type_="warning")

Dialog.error("文件保存失败！")

from jadeui import MessageBoxType

MessageBoxType.NONE      # "none"
MessageBoxType.INFO      # "info"
MessageBoxType.WARNING   # "warning"
MessageBoxType.ERROR     # "error"
MessageBoxType.QUESTION  # "question"

from jadeui import OpenDialogProperties

OpenDialogProperties.OPEN_FILE         # "openFile"
OpenDialogProperties.OPEN_DIRECTORY    # "openDirectory"
OpenDialogProperties.MULTI_SELECTIONS  # "multiSelections"
OpenDialogProperties.SHOW_HIDDEN_FILES # "showHiddenFiles"

from jadeui import Notification

Notification.config(
    app_name="我的应用",
    icon="C:/path/to/icon.ico"  # 绝对路径
)

Notification.show("提示", "操作已完成")
Notification.show("下载中", "正在下载文件...", timeout=5000)

Notification.with_buttons(
    "下载完成",
    "video.mp4 已下载",
    "打开",       # 第一个按钮
    "忽略",       # 第二个按钮（可选）
    action="download_123"  # 动作标识符
)

from jadeui import Notification, Events

@Notification.on(Events.NOTIFICATION_ACTION)
def on_action(data):
    # data = {
    #     "action": "action_0",      # 按钮索引
    #     "title": "打开",           # 按钮文本
    #     "arguments": "download_123" # 你传入的 action 参数
    # }
    print(f"按钮点击: {data}")

@Notification.on(Events.NOTIFICATION_DISMISSED)
def on_dismissed(data):
    print("通知被关闭")

Notification.info("标题", "内容")
Notification.success("标题", "内容")
Notification.warning("标题", "内容")
Notification.error("标题", "内容")

from jadeui import Notification, Events

# 1. 配置应用信息
Notification.config(app_name="我的应用", icon="C:/app/icon.ico")

# 2. 监听按钮点击事件
@Notification.on(Events.NOTIFICATION_ACTION)
def on_action(data):
    action_id = data.get("arguments")  # 获取 action 参数
    button = data.get("action")        # 按钮索引

    if action_id == "download_123":
        if button == "action_0":
            print("用户点击了「打开」")
        elif button == "action_1":
            print("用户点击了「忽略」")

# 3. 发送通知
Notification.with_buttons(
    "下载完成",
    "video.mp4 已下载",
    "打开",
    "忽略",
    action="download_123"
)

from jadeui import Clipboard

Clipboard.write_text("Hello JadeUI")
text = Clipboard.read_text()

from jadeui import System

print(System.is_windows_11())
print(System.locale())
print(System.displays())
print(System.get_path("desktop"))
print(System.jadeview_version())
print(System.webview_version())

from jadeui import Menu, Window

window = Window(title="Menu Demo", disable_right_click=False)

Menu.attach_context_menu(window, [
    {"label": "刷新", "on_click": lambda: window.reload()},
    {"type": "separator"},
    {"label": "copy", "type": "native"},  # WebView2 原生菜单 Name
    {
        "label": "更多",
        "type": "submenu",
        "children": [
            {"label": "关于", "on_click": lambda: print("about")},
        ],
    },
])

from jadeui import Storage

Storage.set("settings", "window.width", 1024)
Storage.set_str("settings", "literal", "true")

print(Storage.get("settings", "window.width"))
print(Storage.get_all("settings", {}))
print(Storage.keys("settings", "window"))
print(Storage.length("settings", "window"))

from jadeui import Tray

tray = Tray()
tray.set_tooltip("JadeUI App")
tray.set_icon("C:/app/icon.ico")
tray.set_menu([
    {"key": "show", "label": "显示窗口", "on_click": lambda: window.show()},
    {"type": "separator", "key": "sep"},
    {"key": "quit", "label": "退出", "dangerous": True, "on_click": app.quit},
])
tray.show()

from jadeui import HotKey

@HotKey.register("Ctrl+Alt+J")
def on_hotkey():
    window.flash(3)

hotkey_id = HotKey.register("Alt+F1", lambda: print("F1"))
HotKey.unregister(hotkey_id)

# 方法形式
emitter.on("event", callback)

# 装饰器形式
@emitter.on("event")
def callback(data):
    pass

emitter.off("event", callback)  # 移除特定监听器
emitter.off("event")            # 移除该事件所有监听器

emitter.emit("event", arg1, arg2, key=value)

@emitter.once("event")
def callback():
    pass  # 只会被调用一次

emitter.remove_all_listeners("event")  # 特定事件
emitter.remove_all_listeners()         # 所有事件

count = emitter.listener_count("event")

names = emitter.event_names()

from jadeui import Theme

Theme.LIGHT   # "Light"
Theme.DARK    # "Dark"
Theme.SYSTEM  # "System"

from jadeui import Backdrop

Backdrop.MICA      # "mica"
Backdrop.MICA_ALT  # "micaAlt"
Backdrop.ACRYLIC   # "acrylic"

from jadeui import Events

# 应用生命周期事件
Events.APP_READY          # "app-ready"
Events.WINDOW_ALL_CLOSED  # "window-all-closed"
Events.BEFORE_QUIT        # "before-quit"

# 窗口事件
Events.WINDOW_CREATED         # "window-created"
Events.APP_WINDOW_CREATED     # "app-window-created"
Events.WINDOW_CLOSED          # "window-closed"
Events.WINDOW_CLOSING         # "window-closing"
Events.WINDOW_RESIZED         # "window-resized"
Events.WINDOW_STATE_CHANGED   # "window-state-changed"
Events.WINDOW_FULLSCREEN      # "window-fullscreen" (需 1.2+)
Events.WINDOW_MOVED           # "window-moved"
Events.WINDOW_FOCUSED         # "window-focused"
Events.WINDOW_BLURRED         # "window-blurred"
Events.WINDOW_DESTROYED       # "window-destroyed"
Events.RESIZED                # "resized" (旧兼容格式)

# WebView 事件
Events.WEBVIEW_WILL_NAVIGATE      # "webview-will-navigate"
Events.WEBVIEW_DID_START_LOADING  # "webview-did-start-loading"
Events.WEBVIEW_DID_FINISH_LOAD    # "webview-did-finish-load"
Events.WEBVIEW_NEW_WINDOW         # "webview-new-window"
Events.WEBVIEW_PAGE_TITLE_UPDATED # "webview-page-title-updated"
Events.WEBVIEW_PAGE_ICON_UPDATED  # "webview-page-icon-updated"
Events.FAVICON_UPDATED            # "favicon-updated"
Events.JAVASCRIPT_RESULT          # "javascript-result"
Events.WEBVIEW_DOWNLOAD_STARTED   # "webview-download-started" (需 0.3.1+)
Events.POSTMESSAGE_RECEIVED       # "postmessage-received" (需 1.0.2+)

# 文件事件
Events.FILE_DROP          # "file-drop"

# 主题事件
Events.THEME_CHANGED      # "theme-changed"

# 通知事件 (需 1.3.0+)
Events.NOTIFICATION_ACTION    # "notification-action" (用户点击按钮)
Events.NOTIFICATION_SHOWN     # "notification-shown" (通知成功显示)
Events.NOTIFICATION_DISMISSED # "notification-dismissed" (通知被关闭)
Events.NOTIFICATION_FAILED    # "notification-failed" (通知显示失败)

# 其他事件
Events.UPDATE_WINDOW_ICON # "update-window-icon"
Events.IPC_MESSAGE        # "ipc-message"

from jadeui import Window

window = Window(title="事件示例")

# 参数已自动解析，提供 IDE 类型提示
@window.on_resized
def on_resize(width: int, height: int):
    print(f"窗口大小改变: {width} x {height}")

@window.on_moved
def on_move(x: int, y: int):
    print(f"窗口位置: ({x}, {y})")

@window.on_focused
def on_focus():
    print("窗口获得焦点")

@window.on_blurred
def on_blur():
    print("窗口失去焦点")

@window.on_page_loaded
def on_page_load(url: str):
    print(f"页面加载完成: {url}")

# 阻止窗口关闭
@window.on_closing
def on_closing():
    return True  # 返回 True 阻止关闭

# 拦截新窗口请求
@window.on_new_window
def on_new_window(url: str, frame_name: str):
    print(f"拦截新窗口: {url}")
    window.navigate(url)  # 在当前窗口打开
    return True  # 阻止打开新窗口

# 监听文件下载事件 (需 0.3.1+)
@window.on_download_started
def on_download(url: str, filename: str):
    print(f"下载请求: {filename} from {url}")
    if filename.endswith(".exe"):
        return True  # 阻止 exe 文件下载
    return False

# 监听全屏状态改变 (需 1.2+)
@window.on_fullscreen_changed
def on_fullscreen(is_fullscreen: bool):
    print(f"全屏状态: {is_fullscreen}")

window.show()

from jadeui import RGBA

color = RGBA(r=255, g=128, b=64, a=255)

from jadeui import JadeUIError, WindowCreationError

try:
    window = Window(title="Test")
    window.show()
except WindowCreationError as e:
    print(f"窗口创建失败: {e}")
except JadeUIError as e:
    print(f"JadeUI 错误: {e}")

from jadeui import create_app, Window

app = create_app(
    enable_dev_tools=True,
    log_file="app.log"
)

@app.on_ready
def setup():
    Window(title="My App").show()

app.run()

from jadeui import utils

path = utils.get_resource_path("assets/icon.png")

from jadeui import utils

utils.show_error("错误", "发生了一个错误")

from jadeui import utils

utils.ensure_directory("./data/cache")

from jadeui import download_dll

download_dll(force=False)  # force=True 强制重新下载

from jadeui import ensure_dll

ensure_dll()

from jadeui import find_dll

path = find_dll()

from jadeui import get_architecture

arch = get_architecture()  # "x64" 或 "x86"