---
title: "on"
description: "注册事件监听器，并自动管理宿主订阅。"
---


> 注册事件监听器，并自动管理宿主订阅。

## 签名

```ts
KSM.events.on<TPayload>(
  event: string,
  listener: (payload: TPayload) => void
): () => void

KSM.on<TPayload>(
  event: string,
  listener: (payload: TPayload) => void
): () => void
```

`KSM.on()` 直接委托给 `KSM.events.on()`。

## 平台与权限

| Windows | Android |权限 |
| --- | --- | --- |
|支持 |支持 |无 |

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `event` | `string` |是 |已注册事件名 |
| `listener` | `(payload) => void` |是 |事件到达时调用 |

## 返回值

返回一个幂等清理函数。调用后移除该监听器；最后一个监听器移除时自动退订。

## 行为

- 第一个监听器注册时异步发送 `event.subscribe`。
- 订阅失败时移除刚注册的监听器，并恢复监听计数。
- 后续监听器只加入前端监听集合，不重复订阅。
- 清理函数会同步移除监听器，并在计数归零时异步发送 `event.unsubscribe`。
- `webview.reloaded` 虽然可以注册监听，但前端已经内置恢复处理；业务代码不需要
为恢复能力而注册它。

## 示例

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

//组件卸载
off();
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` |事件名未注册 |
|普通 `Error` |桥接未初始化 |
|异步订阅错误 |订阅 Promise 被拒绝，监听器被移除 |

## 相关

- [subscribe](/docs/kasumi/api/events/subscribe)
- [window.resized](/docs/kasumi/api/events/window-resized)