Window management - : Central de Documentação do Alibaba Cloud

Fluxo de trabalho

Crie uma sessão com um ambiente de área de trabalho de computador em nuvem.
Liste as janelas para identificar os aplicativos abertos.
Selecione uma janela de destino pelo título, nome do processo ou ID da janela.
Controle a janela: ative, maximize, minimize, redimensione ou feche-a.
Gerencie o foco para evitar que outras janelas interrompam a automação.

Pré-requisitos

Uma sessão do AgentBay com ambiente de área de trabalho

import os
from agentbay import AgentBay, CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("The AGENTBAY_API_KEY environment variable is required")

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 created: {session.session_id}")
else:
    print(f"Failed to create session: {result.error_message}")
    exit(1)

Listar janelas

Chame list_root_windows() para obter todas as janelas de aplicativo de nível superior na área de trabalho. Janelas raiz referem-se a janelas de aplicativo de nível superior, não à janela raiz do X11.

Parâmetros

Nome	Tipo	Obrigatório	Padrão	Descrição
`timeout_ms`	int	Não	3000	Tempo limite em milissegundos.

Retorna: WindowListResult

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

if result.success:
    windows = result.windows
    print(f"Found {len(windows)} windows")

    for window in windows:
        print(f"Title: {window.title}")
        print(f"Window ID: {window.window_id}")
        print(f"Process: {window.pname if window.pname else 'N/A'}")
        print(f"PID: {window.pid if window.pid else 'N/A'}")
        print(f"Position: ({window.absolute_upper_left_x}, {window.absolute_upper_left_y})")
        print(f"Size: {window.width}x{window.height}")
        print(f"Child windows: {len(window.child_windows)}")
        print("---")
else:
    print(f"Error listing windows: {result.error_message}")

Atributos do objeto Window

Atributo	Tipo	Descrição
`window_id`	int	Identificador exclusivo da janela.
`title`	str	Título ou texto descritivo da janela.
`absolute_upper_left_x`	Optional[int]	Coordenada X do canto superior esquerdo.
`absolute_upper_left_y`	Optional[int]	Coordenada Y do canto superior esquerdo.
`width`	Optional[int]	Largura da janela em pixels.
`height`	Optional[int]	Altura da janela em pixels.
`pid`	Optional[int]	ID do processo proprietário da janela.
`pname`	Optional[str]	Nome do processo proprietário da janela.
`child_windows`	List[Window]	Janelas filhas aninhadas nesta janela.

Controlar o estado da janela

Todos os métodos de controle de janela aceitam um parâmetro window_id (int) e retornam um BoolResult. Obtenha o window_id primeiro com list_root_windows():

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

Ativar uma janela

Traga uma janela para o primeiro plano e conceda a ela o foco de entrada.

activate_result = session.computer.activate_window(window_id)

if activate_result.success:
    print("Window activated successfully")
else:
    print(f"Failed to activate window: {activate_result.error_message}")

Maximizar uma janela

Expanda uma janela para preencher toda a área da tela.

maximize_result = session.computer.maximize_window(window_id)

if maximize_result.success:
    print("Window maximized successfully")
else:
    print(f"Failed to maximize window: {maximize_result.error_message}")

Minimizar uma janela

Oculte uma janela na barra de tarefas.

minimize_result = session.computer.minimize_window(window_id)

if minimize_result.success:
    print("Window minimized successfully")
else:
    print(f"Failed to minimize window: {minimize_result.error_message}")

Restaurar uma janela

Restaure uma janela maximizada ou minimizada ao tamanho e à posição anteriores.

restore_result = session.computer.restore_window(window_id)

if restore_result.success:
    print("Window restored successfully")
else:
    print(f"Failed to restore window: {restore_result.error_message}")

Colocar uma janela em tela cheia

Defina uma janela para o modo de tela cheia.

fullscreen_result = session.computer.fullscreen_window(window_id)

if fullscreen_result.success:
    print("Window set to full screen")
else:
    print(f"Failed to set window to full screen: {fullscreen_result.error_message}")

Redimensionar uma janela

Altere as dimensões de uma janela para valores específicos em pixels.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`window_id`	int	Sim	Identificador da janela de destino.
`width`	int	Sim	Nova largura em pixels.
`height`	int	Sim	Nova altura em pixels.

resize_result = session.computer.resize_window(window_id, 800, 600)

if resize_result.success:
    print("Window resized to 800x600")
else:
    print(f"Failed to resize window: {resize_result.error_message}")

Fechar uma janela

Feche permanentemente uma janela. Use com cautela: a janela e quaisquer dados não salvos podem ser perdidos.

close_result = session.computer.close_window(window_id)

if close_result.success:
    print("Window closed successfully")
else:
    print(f"Failed to close window: {close_result.error_message}")

Gerenciar foco

Chame focus_mode() para impedir que janelas roubem o foco da janela ativa. Esse recurso é útil durante automações, pois processos em segundo plano podem abrir caixas de diálogo ou notificações que interrompem o fluxo de trabalho.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`on`	bool	Sim	`True` para ativar o modo de foco; `False` para desativá-lo.

Retorna: BoolResult

# Enable focus mode to prevent focus stealing
try:
    session.computer.focus_mode(True)
    print("Focus mode enabled - Windows will not steal focus")
except Exception as e:
    print(f"Failed to enable focus mode: {e}")

# Disable focus mode
try:
    session.computer.focus_mode(False)
    print("Focus mode disabled")
except Exception as e:
    print(f"Failed to disable focus mode: {e}")

Obter a janela ativa

Chame get_active_window() para recuperar a janela com foco atual. Este método pode falhar se nenhuma janela estiver ativa.

Retorna: WindowInfoResult

result = session.computer.get_active_window()

if result.success:
    active_window = result.window
    print(f"Active window:")
    print(f"  Title: {active_window.title}")
    print(f"  Window ID: {active_window.window_id}")
    print(f"  Process: {active_window.pname}")
    print(f"  PID: {active_window.pid}")
    print(f"  Position: ({active_window.absolute_upper_left_x}, {active_window.absolute_upper_left_y})")
    print(f"  Size: {active_window.width}x{active_window.height}")
else:
    print(f"Failed to get active window: {result.error_message}")

Exemplo completo

Encontre um aplicativo, inicie-o, localize sua janela e controle-a.

import os
import time
from agentbay import AgentBay, CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("The AGENTBAY_API_KEY environment variable is required")

agent_bay = AgentBay(api_key=api_key)

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

if not result.success:
    print(f"Failed to create session: {result.error_message}")
    exit(1)

session = result.session
print(f"Session created: {session.session_id}")

# Step 1: Find installed applications
print("Step 1: Find installed applications...")
apps_result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)

if not apps_result.success:
    print(f"Failed to get applications: {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 not found")
    agent_bay.delete(session)
    exit(1)

print(f"Found application: {target_app.name}")

# Step 2: Start the application
print("Step 2: Start the application...")
start_result = session.computer.start_app(target_app.start_cmd)

if not start_result.success:
    print(f"Failed to start application: {start_result.error_message}")
    agent_bay.delete(session)
    exit(1)

print(f"Application started, {len(start_result.data)} processes launched")

# Step 3: Wait for the window to load
print("Step 3: Wait for the application window to load...")
time.sleep(5)

# Step 4: Find the application window
print("Step 4: Find the application window...")
windows_result = session.computer.list_root_windows()

if not windows_result.success:
    print(f"Failed to list windows: {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("Using the first available window")

if app_window:
    print(f"Found window: {app_window.title}")

    # Step 5: Control the window
    print("Step 5: Control the window...")
    try:
        session.computer.activate_window(app_window.window_id)
        print("Window activated")

        time.sleep(1)
        session.computer.maximize_window(app_window.window_id)
        print("Window maximized")

        time.sleep(1)
        session.computer.resize_window(app_window.window_id, 1024, 768)
        print("Window resized to 1024x768")

    except Exception as e:
        print(f"Window control failed: {e}")

# Clean up
print("Cleaning up session...")
agent_bay.delete(session)
print("Workflow complete!")

Referência da API

Métodos

Método	Parâmetros	Tipo de retorno	Descrição
`list_root_windows()`	`timeout_ms: int = 3000`	`WindowListResult`	Lista todas as janelas de aplicativo de nível superior.
`get_active_window()`	None	`WindowInfoResult`	Obtém a janela ativa no momento.
`activate_window()`	`window_id: int`	`BoolResult`	Ativa uma janela e concede foco a ela.
`maximize_window()`	`window_id: int`	`BoolResult`	Maximiza uma janela.
`minimize_window()`	`window_id: int`	`BoolResult`	Minimiza uma janela.
`restore_window()`	`window_id: int`	`BoolResult`	Restaura uma janela do estado maximizado ou minimizado.
`close_window()`	`window_id: int`	`BoolResult`	Fecha uma janela.
`fullscreen_window()`	`window_id: int`	`BoolResult`	Define uma janela para o modo de tela cheia.
`resize_window()`	`window_id: int`, `width: int`, `height: int`	`BoolResult`	Redimensiona uma janela para as dimensões especificadas.
`focus_mode()`	`on: bool`	`BoolResult`	Ativa ou desativa a prevenção contra roubo de foco.

Tipos de retorno

WindowListResult

Atributo	Tipo	Descrição
`success`	bool	Indica se a operação foi bem-sucedida.
`windows`	List[Window]	Lista de objetos de janela.
`error_message`	str	Mensagem de erro caso a operação tenha falhado.
`request_id`	str	Identificador exclusivo da solicitação.

WindowInfoResult

Atributo	Tipo	Descrição
`success`	bool	Indica se a operação foi bem-sucedida.
`window`	Window	Objeto da janela.
`error_message`	str	Mensagem de erro caso a operação tenha falhado.
`request_id`	str	Identificador exclusivo da solicitação.

BoolResult

Atributo	Tipo	Descrição
`success`	bool	Indica se a operação foi bem-sucedida.
`data`	bool	Dados resultantes da operação.
`error_message`	str	Mensagem de erro caso a operação tenha falhado.
`request_id`	str	Identificador exclusivo da solicitação.

Window

Atributo	Tipo	Descrição
`window_id`	int	Identificador exclusivo da janela.
`title`	str	Título ou texto descritivo da janela.
`absolute_upper_left_x`	Optional[int]	Coordenada X do canto superior esquerdo.
`absolute_upper_left_y`	Optional[int]	Coordenada Y do canto superior esquerdo.
`width`	Optional[int]	Largura da janela em pixels.
`height`	Optional[int]	Altura da janela em pixels.
`pid`	Optional[int]	ID do processo proprietário da janela.
`pname`	Optional[str]	Nome do processo proprietário da janela.
`child_windows`	List[Window]	Lista de janelas filhas.