plugins
Window
查看 MarkdownKasumi 窗口插件的方法、尺寸语义、权限和平台差异。
理解 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。事件载荷是物理内容区尺寸：
interface KSMWindowResizedPayload {
width: number;
height: number;
}这与 window.setSize 的逻辑外框像素不同。前端布局应使用 CSS 视口或物理内容区换算，
不要把外框尺寸直接当作内容区尺寸。
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 | 请求超时或窗口销毁 |
capabilities.commands，不要只按平台字符串判断。window.resized 时确认尺寸单位是物理内容区像素。
评论