排列已啟動視窗

一鍵排列已經啟動的環境視窗，不會啟動未執行的環境。

介面定義：ApiFox POST · 核對日期：2026-10-21。

請求

POST /api/arrangeWindows

使用客戶端 API 頁面顯示的服務地址和 api-key。示例埠 9000 僅作演示，必須替換為實際埠；認證說明見 概述。

JSON 請求體

欄位按 ApiFox 示例整理，可選行為見呼叫說明。

引數	型別	必填	說明
ids	integer[]	否	可選。僅排列指定環境；不傳則排列所有已啟動環境
monitorIndex	integer	否	可選。目標顯示器序號，從 1 開始；不傳使用主顯示器

cURL 示例

curl --request POST 'http://127.0.0.1:9000/api/arrangeWindows' \
  --header 'api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "ids": [
    1,
    2
  ],
  "monitorIndex": 1
}'

排列所有已啟動環境

curl --request POST 'http://127.0.0.1:9000/api/arrangeWindows' \
  --header 'api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

響應示例

{
  "success": true,
  "data": {
    "arrangedCount": 2,
    "arrangedIds": [
      1,
      2
    ],
    "skipped": [],
    "monitor": {
      "index": 1,
      "main": true,
      "width": 3840,
      "height": 2160
    }
  }
}

欄位說明

欄位	型別	說明
data.arrangedCount	integer	成功排列的視窗數
data.arrangedIds	integer[]	成功排列的環境 ID
data.skipped	object[]	跳過項；包含 id 和 reason
data.monitor	object / null	顯示器資訊；無排列目標時可為 null
data.monitor.index	integer	從 1 開始的顯示器序號
data.monitor.main	boolean	是否主顯示器
data.monitor.width / height	integer	顯示器寬度 / 高度

呼叫說明

• 當前客戶端僅 Windows 支援視窗排列。macOS / Linux 返回 HTTP 501，不應當作網路異常重試。
• 請求體可省略，或傳 {}：排列所有已啟動環境，預設主顯示器。ids: [] 表示空選擇，不等於省略 ids。
• ids 最多 1000 項，未執行的環境會跳過；monitorIndex 是從 1 開始的顯示器序號。
• 檢查 arrangedCount、arrangedIds 和 skipped，不要只根據 success 判斷所有視窗都已排列。沒有可排列環境時可能成功返回 0 和 monitor: null。

常見錯誤

HTTP 狀態	code	說明
400	INVALID_MONITOR_INDEX	顯示器序號越界；其他非法引數也會返回 400
409	NO_MONITORS / BROWSER_WINDOWS_NOT_READY	未檢測到顯示器或環境視窗尚未就緒
501	WINDOW_ARRANGEMENT_UNSUPPORTED	當前平臺不支援視窗排列

請求失敗時同時檢查 HTTP 狀態碼與響應中的錯誤資訊，見 錯誤碼與排查。