Skip to main content

FloatScriptWindow：脚本悬浮控制器

FloatScriptWindow 是 AScript 提供的专用脚本管理组件。它通过一个轻量级的悬浮窗，实现了脚本的“启动/停止”控制、实时日志监控及后台进程隔离，是商业脚本交付的常用 UI 方案。

1. 导入模块​

# 导入悬浮控制窗类
from ascript.windows.ui import FloatScriptWindow

2. 核心特性​

  • 🛡️ 进程隔离：支持将脚本逻辑运行在独立子进程中，主 UI 进程不受干扰，崩溃不闪退。
  • 📜 日志回显：重定向 print() 输出，自动实时推送到前端 HTML 界面显示。
  • 📍 置顶悬浮：窗口默认无边框、置顶显示，并支持自定义拖拽区域。
  • 📥 系统托盘：内置托盘图标管理，支持右键菜单显示/隐藏及彻底退出。

3. 构造与生命周期​

🏗️ 初始化 __init__()​

配置悬浮窗的基础外观与运行模式。

代码块：

win = FloatScriptWindow(icon_path, title="AScript", use_process=True, auto_start=False)

参数详解：

  • icon_path (str): 托盘及 UI 使用的图标本地路径。
  • title (str): 窗口标题及托盘显示文字。
  • use_process (bool): 是否使用独立进程运行脚本逻辑。建议设为 True 以保证稳定性。
  • auto_start (bool): 窗口显示后是否自动触发 start 事件执行脚本。

🔔 事件监听 .on()​

使用装饰器绑定脚本的逻辑入口与出口。

代码块：

@win.on("start")
def on_start():
    # 脚本开始运行时的逻辑
    pass

@win.on("stop")
def on_stop():
    # 脚本停止运行时的清理逻辑
    pass

4. 界面交互接口 (Exposed)​

这些方法已被自动暴露给 JS 端调用，用于自定义 HTML 布局：

  • .on_toggle_click(status): 开关切换逻辑。JS 传入 true 启动脚本，false 停止脚本。
  • .drag_window(): 调用后允许用户通过鼠标拖动窗口。通常绑定在 HTML 的标题栏 onmousedown 事件上。
  • .resize_ui(expand): 动态调整窗口大小。expand=True 切换到大窗口（如查看日志），False 回到窄条模式。
  • .hide_window(): 隐藏当前窗口到托盘。

💡 综合实战案例​

import multiprocessing
import time
import sys
from ascript.windows.system import R  # 程序上下文与资源路由
from ascript.windows.ui import LicenseWindow  # 安全验证组件
from ascript.windows.ui import FloatScriptWindow  # 脚本控制台组件

# 初始化控制台：支持自启动 (auto_start) 与 多进程隔离 (use_process)
app = FloatScriptWindow(R.img("logo.ico"), title="我的程序", auto_start=True)

@app.on('start')
def task_start():
    # ---------------------------------------------------------
    # 入口程序 (Entry Point)
    # ---------------------------------------------------------
    """
    [业务逻辑入口]
    当用户点击启动按钮或触发自启动时，此函数将在独立的子进程中运行。
    """
    print(">>> [系统] 业务进程已建立，开始执行自动化任务...")
    i= 0

    # 模拟耗时逻辑操作
    while True:
        print(i)
        time.sleep(0.5)
        i += 1


@app.on('stop')
def task_stop():
    """
    [善后处理回调]
    当用户手动停止或任务结束时触发。
    注意：您有约 3 秒的时间进行资源释放（如关闭文件、数据库断开等）。
    即使此处存在死循环，系统也会在超时后强制回收进程资源。
    """
    print(">>> [系统] 接收到停止信号，正在释放系统资源...")
    # 模拟保存数据逻辑
    time.sleep(1)
    print(">>> [系统] 资源释放完毕，安全退出。")




if __name__ == '__main__':
    # 解决打包后子进程重复启动问题
    app.show()

5. 技术细节说明​

⚙️ 日志重定向原理​

FloatScriptWindow 内部接管了 sys.stdout。当你在脚本中使用 print() 时：

  1. 消息通过 QueueWriter 写入 multiprocessing.Queue。
  2. 主进程监听队列，并将消息转化为 JS 指令：window.addLog('消息内容')。
  3. 前端 HTML 需实现 window.addLog 函数即可实时展示滚动日志。

🖼️ 窗口样式修正​

窗口启动 1.5 秒后会自动调用 _fix_window_once，利用 ctypes 修改 Windows 原生属性：

  • 去除任务栏图标：使窗口更像一个真正的悬浮挂件。
  • 去除系统边框：实现完全自定义的 HTML UI。
HTML 布局建议

该类配套的默认 HTML 文件路径为 R.internal("windows", "tools", "web", "flot_control.html")。如果您需要自定义 UI，请确保您的 JS 代码包含 syncStatus 和 addLog 方法以便 Python 侧同步状态。

此文档已将 FloatScriptWindow 的复杂进程管理与 UI 逻辑封装为易理解的操作手册。至此，所有核心模块文档已整理完毕！