---
title: "Window"
description: "Kasumi 窗口插件的方法、尺寸语义、权限和平台差异。"
---


> 理解 Window 插件的窗口标题、尺寸、生命周期、平台矩阵和宿主配置。

## 模块边界

Window 插件只控制当前 WebView 所属应用窗口，不创建独立窗口，不提供位置、置顶、全屏切换
或窗口内多 View 布局。多 WebView 布局由宿主原生代码管理。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/window.ts` | 参数守卫和命令封装 |
| 协议清单 | `protocol/plugins.json` | `window` 插件和五个命令归属 |
| Windows 插件 | `windows/src/plugins/ksm_window_plugin.cpp` | Win32 窗口控制 |
| Android 插件 | `KSMWindowPlugin.kt` | 关闭当前 Activity |

## 平台与权限

| 命令 | Windows | Android | 权限 | 返回 |
| --- | --- | --- | --- | --- |
| `window.setTitle` | 支持 | `NOT_SUPPORTED` | `window.control` | `{ updated }` |
| `window.minimize` | 支持 | `NOT_SUPPORTED` | `window.control` | `{ updated }` |
| `window.maximize` | 支持 | `NOT_SUPPORTED` | `window.control` | `{ updated }` |
| `window.setSize` | 支持 | `NOT_SUPPORTED` | `window.control` | `{ updated }` |
| `window.close` | 支持 | 支持 | `window.control` | `{ closed }` |

Android 的 `window.close` 关闭当前 Activity，不结束整个应用进程。需要退出应用时使用
`KSM.app.exit()`。

## 方法与配置

| 方法 | 参数 | 说明 |
| --- | --- | --- |
| `setTitle(title)` | 非空字符串 | 修改当前窗口标题 |
| `minimize()` | 无 | 最小化当前窗口 |
| `maximize()` | 无 | 最大化当前窗口 |
| `setSize({ width, height })` | 正整数 | 设置窗口外框逻辑像素 |
| `close()` | 无 | 关闭当前窗口 |

`window.setSize` 最小尺寸为 `320 × 240`，按当前窗口 DPI 转换为物理像素，并夹取到当前
显示器工作区。窗口最大化、最小化或全屏时返回 `NOT_SUPPORTED`，不会自动恢复。

应用配置 `windows.decorations: false` 只隐藏系统标题栏，不创建窗口按钮。应用需要自行
绘制标题栏、拖动区域和关闭控件。

## 事件与尺寸

调整成功后会继续发送 `window.resized`。事件载荷是物理内容区尺寸：

```ts
interface KSMWindowResizedPayload {
  width: number;
  height: number;
}
```

这与 `window.setSize` 的逻辑外框像素不同。前端布局应使用 CSS 视口或物理内容区换算，
不要把外框尺寸直接当作内容区尺寸。

## 示例

```ts
const { commands } = await KSM.capabilities();

if (commands.includes('window.setTitle')) {
  await KSM.window.setTitle('Kasumi Workspace');
}

if (commands.includes('window.setSize')) {
  await KSM.window.setSize({
    width: 1200,
    height: 800
  });
}

await KSM.window.close();
```

## 平台差异

| 项 | Windows | Android |
| --- | --- | --- |
| 标题 | Win32 窗口标题 | 不提供 |
| 最小化 / 最大化 | Win32 窗口状态 | 不提供 |
| 逻辑尺寸调整 | DPI 换算与工作区夹取 | 不提供 |
| 关闭 | 关闭 WebView 所属窗口 | 关闭当前 Activity |
| 标题栏配置 | `windows.decorations` | 默认沉浸式全屏 |

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | 标题为空、尺寸不是正整数 |
| `PERMISSION_DENIED` | 当前窗口未授予 `window.control` |
| `NOT_SUPPORTED` | 平台不支持，或窗口已最大化、最小化、全屏 |
| `IO_ERROR` | 原生窗口操作失败 |
| `TIMEOUT` / `CANCELLED` | 请求超时或窗口销毁 |

## 排查路径

1. 检查 `capabilities.commands`，不要只按平台字符串判断。
2. Android 的标题、最小化、最大化和尺寸调整不在能力列表中。
3. 尺寸不生效时检查窗口状态和显示器工作区。
4. 无标题栏应用需要自行提供可拖拽区域和关闭控件。
5. 多 WebView 场景关闭单个 View 应调用宿主的 View 关闭接口，而不是窗口插件。
6. 收到 `window.resized` 时确认尺寸单位是物理内容区像素。