api
事件与尺寸变化
查看 MarkdownKasumi 事件订阅、WebView 重载恢复与窗口尺寸变化。
订阅窗口尺寸变化，并正确处理 WebView 重载后的订阅恢复。
event 只负责宿主向当前 WebView 推送事件，不提供跨窗口广播、持久队列或历史回放。事件名和
载荷以 protocol/commands.json 为准。
实现入口：
| 入口 | 责任 |
|---|---|
frontend/src/bridge/ksm.ts | KSM.events.on、subscribe、unsubscribe 和重载恢复 |
frontend/src/bridge/bus.ts | 本地监听器和事件派发 |
windows/src/bridge/ksm_router.cpp | Windows 订阅表和 window.resized |
android/app/src/main/java/dev/kasumi/app/bridge/KSMRouter.kt | Android 订阅表和事件载荷 |
| 方法 / 事件 | Windows | Android | 权限 |
|---|---|---|---|
KSM.events.on(event, listener) | 支持 | 支持 | 无 |
KSM.subscribe(event) / event.subscribe | 支持 | 支持 | 无 |
KSM.unsubscribe(event) / event.unsubscribe | 支持 | 支持 | 无 |
window.resized | 支持 | 支持 | 无 |
webview.reloaded | 支持 | 支持 | 无 |
| 方法 | 参数 | 返回 |
|---|---|---|
KSM.events.on | event: string、listener: (payload) => void | 取消监听的函数 |
KSM.subscribe | event: string | Promise<void> |
KSM.unsubscribe | event: string | Promise<void> |
event.subscribe | { event } | { subscribed: true } |
event.unsubscribe | { event } | { unsubscribed: true } |
window.resized 载荷为：
interface KSMWindowResizedPayload {
width: number;
height: number;
}尺寸单位是物理内容区像素，不是 CSS 像素、逻辑外框尺寸或 DPI 缩放后的前端坐标。
KSM.events.on 在第一个监听器注册时自动发送 event.subscribe，最后一个监听器移除时自动
退订。重复订阅同一事件是幂等的。
webview.reloaded 是系统事件，不需要订阅。前端收到后会丢弃旧请求、清空能力缓存、重新查询
能力，并恢复 window.resized 等已跟踪订阅。业务代码不需要手工监听该事件来恢复桥接。
import { KSM } from '@kasumi/bridge';
const off = KSM.events.on<{ width: number; height: number }>(
'window.resized',
({ width, height }) => {
console.info(`content area: ${width} x ${height} physical px`);
}
);
// 页面卸载时解除监听，最后一个监听器会触发自动退订。
window.addEventListener('pagehide', off, { once: true });| 情况 | 结果 |
|---|---|
| 未初始化桥接 | 普通 Error |
| 未注册事件名 | 前端 TypeError；宿主侧返回 INVALID_ARGS |
| 订阅请求超时 | name === "TIMEOUT"，监听器会回滚 |
| WebView 重建 | 旧监听器保留，宿主订阅由前端自动恢复 |
| 当前窗口已销毁 | 事件不再投递，迟到事件被忽略 |
Windows 在 WM_SIZE 后发送 window.resized；Android 在 WebView 布局尺寸变化后发送。
两端都使用物理内容区尺寸。webview.reloaded 在 Windows WebView2 完成加载后发送，在
Android onPageFinished 后发送。
protocol/commands.json 的 events 段。KSM.events.on 的监听器已注册，且没有被提前解除。event.subscribe 成功响应。
评论