排列已启动窗口

一键排列已经启动的环境窗口，不会启动未运行的环境。

接口定义：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 状态码与响应中的错误信息，见 错误码与排查。