---
title: "subscribe"
description: "显式向宿主订阅一个已注册事件。"
---


> 显式向宿主订阅一个已注册事件。

## 签名

```ts
KSM.subscribe(event: string): Promise<void>
```

## 平台与权限

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

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `event` | `string` |是 |已注册事件名 |

## 返回值

`Promise<void>`。宿主确认订阅后完成。

## 行为

- 发送 `event.subscribe` 协议命令。
- 成功后把事件加入桥接的订阅跟踪集合，供 WebView 重建后恢复。
- 宿主订阅表按窗口或路由上下文维护，重复订阅是幂等的。
- 不自动注册前端监听器；只订阅不收事件不会产生业务效果。
- `webview.reloaded` 是系统事件，不需要主动订阅。

## 示例

```ts
await KSM.subscribe('window.resized');

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

//清理时同时移除监听器和显式订阅
off();
await KSM.unsubscribe('window.resized');
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` |事件名未注册 |
|普通 `Error` |桥接未初始化 |
| `INVALID_ARGS` |宿主拒绝未注册事件 |
| `TIMEOUT` |宿主未在默认时间内响应 |

## 相关

- [unsubscribe](/docs/kasumi/api/events/unsubscribe)
- [on](/docs/kasumi/api/events/on)