---
title: "Tray"
description: "显示或隐藏系统托盘图标。"
---


> 显示或隐藏系统托盘图标。

## 模块边界

`tray` 只暴露托盘图标显隐命令。菜单、点击行为、通知气泡由宿主服务实现，不包含在前端
契约内。

| 方法 | 协议命令 | Windows | Android |
| --- | --- | --- | --- |
| `KSM.tray.show()` | `tray.show` | 支持 | 不支持 |
| `KSM.tray.hide()` | `tray.hide` | 支持 | 不支持 |

Android 调用这些命令返回 `NOT_SUPPORTED`。

## 返回值

`show` 返回 `{ shown: boolean }`，`hide` 返回 `{ hidden: boolean }`。

## 示例

```ts
import { KSM } from 'kasumi-bridge';

const { shown } = await KSM.tray.show();
if (shown) {
  // 通过窗口按钮隐藏主窗口，保留托盘入口
}
```

## 当前实现状态

- Windows 宿主已挂载命令，默认实现只判断窗口句柄是否存在，不会创建真实托盘图标。
- 生产环境需要在 `KSMWindowsHostServices` 中接入 `Shell_NotifyIconW`、菜单消息和
  窗口销毁清理。

## 错误与边界

- Android：`NOT_SUPPORTED`。
- 未实现托盘时不要返回成功状态；`shown` / `hidden` 必须反映真实托盘状态。

## 排查

| 现象 | 优先检查 |
| --- | --- |
| `shown` 为 `false` | 窗口句柄、NOTIFYICONDATA 初始化、资源图标 |
| 托盘点击无响应 | 回调消息号、窗口消息泵、菜单命令映射 |