窗口管理-阿里云帮助中心

本文介绍使用无影 AgentBay SDK 对云电脑进行窗口管理的相关能力。如何控制窗口状态、位置以及焦点，并与云环境中的桌面窗口进行交互。

概述

Computer Use模块为桌面环境提供全面的窗口管理功能，包括：

窗口发现 - 列出并查找系统中的窗口。
窗口状态控制 - 最大化、最小化、恢复与关闭窗口。
窗口定位 - 调整窗口大小与重新定位。
焦点管理 - 控制窗口焦点与激活状态。
桌面自动化 - 构建复杂的桌面自动化工作流。

创建会话

创建具有桌面环境的会话。

import os
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY 环境变量是必需的")

agent_bay = AgentBay(api_key=api_key)

params = CreateSessionParams(image_id="linux_latest")
result = agent_bay.create(params)

if result.success:
    session = result.session
    print(f"会话已创建: {session.session_id}")
else:
    print(f"创建会话失败: {result.error_message}")
    exit(1)

列出窗口

获取桌面环境中所有可用窗口的信息。

result = session.computer.list_root_windows(timeout_ms=5000)

if result.success:
    windows = result.windows
    print(f"找到 {len(windows)} 个窗口")
    # 执行结果: 找到 0 个窗口 (当没有打开窗口时)
    # 或: 找到 5 个窗口 (当应用程序正在运行时)
    
    for window in windows:
        print(f"标题: {window.title}")
        # 执行结果: 标题: Google Chrome
        print(f"窗口ID: {window.window_id}")
        # 执行结果: 窗口ID: 12345678
        print(f"进程: {window.pname if window.pname else 'N/A'}")
        # 执行结果: 进程: chrome
        print(f"PID: {window.pid if window.pid else 'N/A'}")
        # 执行结果: PID: 9876
        print(f"位置: ({window.absolute_upper_left_x}, {window.absolute_upper_left_y})")
        # 执行结果: 位置: (100, 50)
        print(f"尺寸: {window.width}x{window.height}")
        # 执行结果: 尺寸: 1280x720
        print(f"子窗口: {len(window.child_windows)}")
        # 执行结果: 子窗口: 0
        print("---")
else:
    print(f"列出窗口时出错：{result.error_message}")

参数:

timeout_ms (int, 可选): 超时时间（毫秒）。默认为 3000。

窗口对象属性:

window_id (int): 窗口的唯一标识符。
title (str): 窗口标题/说明文字。
absolute_upper_left_x (Optional[int]): 窗口左上角的X坐标。
absolute_upper_left_y (Optional[int]): 窗口左上角的Y坐标。
width (Optional[int]): 窗口宽度（像素）。
height (Optional[int]): 窗口高度（像素）。
pid (Optional[int]): 拥有该窗口的进程ID。
pname (Optional[str]): 拥有该窗口的进程名称。
child_windows (List[Window]): 子窗口列表。

窗口控制操作

控制窗口状态和位置。

激活窗口

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    activate_result = session.computer.activate_window(window_id)
    # 执行结果: 窗口激活成功
    
    if activate_result.success:
        print("窗口激活成功")
    else:
        print(f"激活窗口失败: {activate_result.error_message}")

最大化窗口

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    maximize_result = session.computer.maximize_window(window_id)
    # 执行结果: 窗口最大化成功
    
    if maximize_result.success:
        print("窗口最大化成功")
    else:
        print(f"窗口最大化失败: {maximize_result.error_message}")

最小化窗口

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    minimize_result = session.computer.minimize_window(window_id)
    # 执行结果: 窗口最小化成功
    
    if minimize_result.success:
        print("窗口最小化成功")
    else:
        print(f"窗口最小化失败: {minimize_result.error_message}")

恢复窗口

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    restore_result = session.computer.restore_window(window_id)
    # 执行结果: 窗口恢复成功
    
    if restore_result.success:
        print("窗口恢复成功")
    else:
        print(f"窗口恢复失败: {restore_result.error_message}")

调整窗口大小

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    resize_result = session.computer.resize_window(window_id, 800, 600)
    # 执行结果: 窗口调整为 800x600
    
    if resize_result.success:
        print("窗口调整为 800x600")
    else:
        print(f"窗口大小调整失败: {resize_result.error_message}")

全屏窗口

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    fullscreen_result = session.computer.fullscreen_window(window_id)
    # 执行结果: 窗口设置为全屏
    
    if fullscreen_result.success:
        print("窗口设置为全屏")
    else:
        print(f"设置全屏失败: {fullscreen_result.error_message}")

关闭窗口

# 注意: 使用时需谨慎，因为它会永久关闭窗口
result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    close_result = session.computer.close_window(window_id)
    
    if close_result.success:
        print("窗口关闭成功")
    else:
        print(f"关闭窗口失败: {close_result.error_message}")

完整的窗口控制函数

import time

def control_window(session, window_id):
    print(f"控制窗口ID: {window_id}")
    
    try:
        session.computer.activate_window(window_id)
        print("窗口已激活")
    except Exception as e:
        print(f"激活失败: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.maximize_window(window_id)
        print("窗口已最大化")
    except Exception as e:
        print(f"最大化失败: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.minimize_window(window_id)
        print("窗口已最小化")
    except Exception as e:
        print(f"最小化失败: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.restore_window(window_id)
        print("窗口已恢复")
    except Exception as e:
        print(f"恢复失败: {e}")
    
    try:
        session.computer.resize_window(window_id, 800, 600)
        print("窗口调整为 800x600")
    except Exception as e:
        print(f"大小调整失败: {e}")

windows = session.computer.list_root_windows()
if windows.success and windows.windows:
    control_window(session, windows.windows[0].window_id)

焦点管理

控制系统焦点行为以防止焦点被抢占。

try:
    session.computer.focus_mode(True)
    # 执行结果: 焦点模式启用 - 窗口不会抢占焦点
    print("焦点模式启用 - 窗口不会抢占焦点")
except Exception as e:
    print(f"启用焦点模式失败: {e}")

try:
    session.computer.focus_mode(False)
    # 执行结果: 焦点模式禁用
    print("焦点模式禁用")
except Exception as e:
    print(f"禁用焦点模式失败: {e}")

参数:

on (bool): True 启用焦点模式，False 禁用焦点模式。

获取活动窗口

获取当前活动窗口的信息。

# 注意: 如果当前没有活动窗口可能会失败
result = session.computer.get_active_window(timeout_ms=5000)

if result.success:
    active_window = result.window
    # 当窗口处于活动状态时的执行结果:
    # 活动窗口:
    #   标题: Google Chrome
    #   窗口ID: 87654321
    #   进程: chrome
    #   PID: 4321
    #   位置: (0, 0)
    #   尺寸: 1920x1080
    print(f"活动窗口:")
    print(f"  标题: {active_window.title}")
    print(f"  窗口ID: {active_window.window_id}")
    print(f"  进程: {active_window.pname}")
    print(f"  PID: {active_window.pid}")
    print(f"  位置: ({active_window.absolute_upper_left_x}, {active_window.absolute_upper_left_y})")
    print(f"  尺寸: {active_window.width}x{active_window.height}")
else:
    # 当没有窗口处于活动状态时的执行结果:
    # 获取活动窗口失败: 响应错误 (如果没有窗口处于活动状态时的预期结果)
    print(f"获取活动窗口失败: {result.error_message}")

参数:

timeout_ms (int, 可选): 超时时间（毫秒）。默认为 3000。

完整工作流程示例

展示如何启动应用程序并控制其窗口的完整示例。

import os
import time
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY 环境变量是必需的")

agent_bay = AgentBay(api_key=api_key)

params = CreateSessionParams(image_id="linux_latest")
result = agent_bay.create(params)

if not result.success:
    print(f"创建会话失败: {result.error_message}")
    exit(1)

session = result.session
print(f"会话已创建: {session.session_id}")
# 执行结果: 会话已创建: session-04bdwfj7u688ec96t

print("步骤 1: 查找已安装的应用程序...")
apps_result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)
# 执行结果: 找到 76 个应用程序

if not apps_result.success:
    print(f"获取应用程序失败: {apps_result.error_message}")
    agent_bay.delete(session)
    exit(1)

target_app = None
for app in apps_result.data:
    if "chrome" in app.name.lower():
        target_app = app
        break

if not target_app:
    print("未找到 Google Chrome")
    agent_bay.delete(session)
    exit(1)

print(f"找到应用程序: {target_app.name}")
# 执行结果: 找到应用程序: Google Chrome

print("步骤 2: 启动应用程序...")
start_result = session.computer.start_app(target_app.start_cmd)

if not start_result.success:
    print(f"启动应用程序失败: {start_result.error_message}")
    agent_bay.delete(session)
    exit(1)

print(f"应用程序已启动，共启动 {len(start_result.data)} 个进程")
# 执行结果: 应用程序已启动，共启动 6 个进程

print("步骤 3: 等待应用程序窗口加载...")
time.sleep(5)

print("步骤 4: 查找应用程序窗口...")
windows_result = session.computer.list_root_windows()

if not windows_result.success:
    print(f"列出窗口失败: {windows_result.error_message}")
    agent_bay.delete(session)
    exit(1)

app_window = None
for window in windows_result.windows:
    if target_app.name.lower() in window.title.lower():
        app_window = window
        break

if not app_window and windows_result.windows:
    app_window = windows_result.windows[0]
    print("使用第一个可用窗口")

if app_window:
    print(f"找到窗口: {app_window.title}")
    # 执行结果: 找到窗口: Welcome to Google Chrome
    
    print("步骤 5: 控制窗口...")
    try:
        session.computer.activate_window(app_window.window_id)
        print("窗口已激活")
        # 执行结果: 窗口已激活
        
        time.sleep(1)
        session.computer.maximize_window(app_window.window_id)
        print("窗口已最大化")
        # 执行结果: 窗口已最大化
        
        time.sleep(1)
        session.computer.resize_window(app_window.window_id, 1024, 768)
        print("窗口调整为 1024x768")
        # 执行结果: 窗口调整为 1024x768
        
    except Exception as e:
        print(f"窗口控制失败: {e}")

print("清理会话...")
agent_bay.delete(session)
print("工作流程完成!")
# 执行结果: 会话删除成功

API 参考

窗口管理器方法

方法	参数	返回值	描述
`list_root_windows()`	`timeout_ms: int = 3000`	`WindowListResult`	列出所有根窗口
`get_active_window()`	`timeout_ms: int = 3000`	`WindowInfoResult`	获取当前活动窗口
`activate_window()`	`window_id: int`	`BoolResult`	激活窗口
`maximize_window()`	`window_id: int`	`BoolResult`	最大化窗口
`minimize_window()`	`window_id: int`	`BoolResult`	最小化窗口
`restore_window()`	`window_id: int`	`BoolResult`	恢复窗口
`close_window()`	`window_id: int`	`BoolResult`	关闭窗口
`fullscreen_window()`	`window_id: int`	`BoolResult`	使窗口全屏
`resize_window()`	`window_id: int`<br/>`width: int`<br/>`height: int`	`BoolResult`	调整窗口大小
`focus_mode()`	`on: bool`	`BoolResult`	切换焦点模式

返回类型

WindowListResult

success (bool): 操作是否成功。
windows (List[Window]): 窗口对象列表。
error_message (str): 如果操作失败则返回错误消息。
request_id (str): 唯一请求标识符。

Window

window_id (int): 窗口的唯一标识符。
title (str): 窗口标题/说明文字。
absolute_upper_left_x (Optional[int]): 左上角的X坐标。
absolute_upper_left_y (Optional[int]): 左上角的Y坐标。
width (Optional[int]): 窗口宽度（像素）。
height (Optional[int]): 窗口高度（像素）。
pid (Optional[int]): 拥有该窗口的进程ID。
pname (Optional[str]): 拥有该窗口的进程名称。
child_windows (List[Window]): 子窗口列表。

WindowInfoResult

success (bool): 操作是否成功。
window (Window): 窗口对象。
error_message (str): 如果操作失败则返回错误消息。
request_id (str): 唯一请求标识符。

BoolResult

success (bool): 操作是否成功。
data (bool): 操作结果数据。
error_message (str): 如果操作失败则返回错误消息。
request_id (str): 唯一请求标识符。