---
title: "events"
description: "监听宿主推送的普通事件与系统事件，并管理事件订阅生命周期。"
---


> 监听宿主推送的普通事件与系统事件，并管理事件订阅生命周期。

## 模块边界

`events` 负责前端监听器、宿主订阅和系统事件恢复，不负责定义业务消息协议。
可用事件名由 `protocol/commands.json` 的 `events` 段定义，当前只有
`window.resized` 和 `webview.reloaded`。

实现入口是 `frontend/src/bridge/ksm.ts` 和 `frontend/src/bridge/bus.ts`。

## 方法索引

|方法 |用途 |
| --- | --- |
| [on](/docs/kasumi/api/events/on) |注册监听器并自动管理首个订阅和最后一个退订 |
| [subscribe](/docs/kasumi/api/events/subscribe) |显式订阅普通事件 |
| [unsubscribe](/docs/kasumi/api/events/unsubscribe) |显式退订普通事件 |
| [webview.reloaded](/docs/kasumi/api/events/webview-reloaded) |系统重建事件 |
| [window.resized](/docs/kasumi/api/events/window-resized) |窗口尺寸变化事件 |

## 监听与订阅

推荐使用 `KSM.events.on()`，它会在第一个监听器注册时自动订阅，在最后一个监听器
移除时自动退订：

```ts
const off = KSM.events.on<{ width: number; height: number }>(
  'window.resized',
  ({ width, height }) => {
    console.info(width, height);
  }
);

//页面组件卸载时调用
off();
```

`KSM.on()` 与 `KSM.events.on()` 等价。显式调用 `subscribe()` 和 `unsubscribe()`
适合需要直接控制宿主订阅表的高级场景；混用时必须自己保证订阅计数与监听器数量一致。

## 事件语义

|事件 |类型 |订阅 |载荷 |
| --- | --- | --- | --- |
| `window.resized` |普通事件 |需要 | `{ width, height }` |
| `webview.reloaded` |系统事件 |不需要 |空对象 |

## 重建恢复

WebView 重建时，宿主主动发送 `webview.reloaded`。前端桥接会：

1. 丢弃重建前的未完成请求。
2. 失效能力缓存。
3. 重新查询能力。
4. 重新订阅重建前登记的事件。

业务代码不需要监听该事件来执行这些基础恢复，也不应自行重复实现一份能力刷新。

## 常见风险

- `on()` 收到未知事件名会立即抛 `TypeError`。
- 未保留返回值会让监听器和宿主订阅无法释放。
- 显式 `subscribe()` 和 `unsubscribe()` 不参与自动监听计数。
- 跨窗口 `message` 来源会被默认传输层拒绝。
- 事件监听只保证当前桥接生命周期，`dispose()` 后全部失效。

## 相关

- [core](/docs/kasumi/api/core)
- [types](/docs/kasumi/api/types)