Skip to main content

WebWindow：基于 Web 的自定义 UI 界面

WebWindow 类是 AScript 的核心 UI 组件。它允许开发者使用标准的 HTML/CSS/JS 技术栈构建跨平台的桌面交互界面，并实现了 Python 与 JavaScript 之间的双向异步通信（RPC）。

1. 导入模块​

# 导入网页窗口类
from ascript.windows.ui import WebWindow

2. 核心方法 (Methods)​

🏗️ 初始化 __init__()​

指定 UI 布局文件的路径，创建一个窗口实例。

代码块：

win = WebWindow(html_path, project_root=None)

参数详解：

  • html_path (str): HTML 文件的本地路径（建议配合 R.ui() 使用以确保路径适配）。
  • project_root (str | None): 项目根目录。默认会自动获取当前脚本所在目录。

🔗 暴露接口 expose()​

装饰器方法。用于将 Python 函数注册到窗口环境中，使其能被前端 JavaScript 直接调用。

代码块：

@win.expose
def your_function(arg1, arg2):
    return "result"

🖥️ 显示窗口 show()​

配置窗口属性并启动渲染进程。该方法会启动 UI 事件循环。

代码块：

win.show(title="AScript Window", debug=False, **kwargs)

参数详解：

  • title (str): 窗口标题栏文字。
  • debug (bool): 是否开启开发者工具。开启后可按 F12 或右键进行元素审查。
  • width / height (int): 初始窗口宽高。
  • resizable (bool): 是否允许用户拉伸窗口大小。
  • kwargs: 额外支持系统原生窗口的其他配置参数。

3. JS 与 Python 交互实战​

Python 端：提供数据与服务​

from ascript.windows.ui import WebWindow
from ascript.windows.system import Device, R

# 1. 实例化并加载 res/ui/index.html
win = WebWindow(R.ui("index.html"))

@win.expose
def get_device_info():
    """将 Python 端的系统信息封装后返回"""
    return {
        "id": Device.id,
        "os": Device.os.type,
        "resolution": Device.screen.physical
    }

@win.expose
def start_task(task_name, count):
    """接收前端传来的参数并执行逻辑"""
    print(f"执行任务: {task_name}, 次数: {count}")
    return "任务已成功启动"

win.show(debug=True)

前端 JS 端：异步调用​

系统会自动在 window 对象下注入 callPython 方法。该方法返回一个 Promise。

// 建议：监听准备就绪事件（可选）
window.addEventListener('onPythonReady', () => {
    console.log("AScript 桥接环境已就绪");
});

// 异步调用 Python 函数示例
async function handleAction() {
    try {
        // 1. 调用带参数的 Python 函数
        const status = await window.callPython("start_task", "主线自动化", 5);
        console.log(status); // 输出: "任务已成功启动"
        
        // 2. 获取 Python 返回的复杂对象
        const info = await window.callPython("get_device_info");
        document.getElementById("dev_id").innerText = info.id;
    } catch (err) {
        console.error("调用 Python 出错:", err);
    }
}

4. 技术特性​

  • 🚀 零延迟渲染：基于 file:// 协议读取本地磁盘资源，UI 加载不受网络环境影响。
  • 💉 自动注入：无需在 HTML 中手动引入任何 .js 桥接库，环境会自动注入 callPython。
  • 🔄 全异步通信：JS 调用 Python 采用非阻塞模式，确保前端动画或交互在大运算量下依然流畅。
  • 🛡️ 安全隔离：Python 端的执行异常会被捕获并传递给 Promise 的 catch 回调，不会导致 UI 窗口闪退。
交互建议

由于 Python 与 JS 之间的通信是跨进程的，建议传输的数据尽量保持简洁（如使用字典或基础类型）。若需传输大量数据，建议在 Python 端处理好后分批返回。

您是否需要我为您生成此文档中提到的 R 资源管理类的参考手册？