排列已啟動視窗
一鍵排列已經啟動的環境視窗,不會啟動未執行的環境。
介面定義:ApiFox POST · 核對日期:2026-10-21。
請求
http
POST /api/arrangeWindows使用客戶端 API 頁面顯示的服務地址和 api-key。示例埠 9000 僅作演示,必須替換為實際埠;認證說明見 概述。
JSON 請求體
欄位按 ApiFox 示例整理,可選行為見呼叫說明。
| 引數 | 型別 | 必填 | 說明 |
|---|---|---|---|
ids | integer[] / string[] / mixed | 否 | 正整數或數字字串陣列,最多 1000 項;省略為全部已啟動環境,[] 為不排列;重複項去重 |
monitorIndex | integer | 否 | 正整數,從 1 開始;省略使用主顯示器;超過實際顯示器數量會報錯 |
cURL 示例
bash
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
}'排列所有已啟動環境
bash
curl --request POST 'http://127.0.0.1:9000/api/arrangeWindows' \
--header 'api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{}'響應示例
json
{
"success": true,
"data": {
"arrangedCount": 2,
"arrangedIds": [
1,
2
],
"skipped": [],
"monitor": {
"index": 1,
"main": true,
"width": 3840,
"height": 2160
}
}
}目前客戶端回應欄位
| 欄位 | 型別 | 用法 |
|---|---|---|
success | boolean | 請求處理成功標記;不代表每筆資料均已寫入 |
data.arrangedCount | integer | 實際排列的視窗數量 |
data.arrangedIds | integer[] | 成功排列的環境 ID |
data.skipped | object[] | 未排列項目及原因;可能部分成功 |
data.monitor | object / null | 目標顯示器資訊;沒有排列目標時可能為 null |
欄位說明
| 欄位 | 型別 | 說明 |
|---|---|---|
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 狀態碼與響應中的錯誤資訊,見 錯誤碼與排查。
ids 可混用正整數與純數字正整數字串,重複 ID 會去重。未執行的環境會列入 skipped,不代表全部失敗。



