Bridge Hooks API

概述

Bridge Hooks 提供了插件渲染进程与 CoreBox 主进程之间的事件订阅机制。系统自动处理事件缓存与回放，确保插件不会错过初始化时的早期事件。

介绍

适合需要感知输入、剪贴板等 CoreBox 行为的插件，使用独立 hooks 免去手动注册 Channel。

核心 Hooks

onCoreBoxInputChange

监听 CoreBox 输入框变化。

import { onCoreBoxInputChange } from '@talex-touch/utils/plugin/sdk/hooks'

onCoreBoxInputChange(({ data, meta }) => {
  console.log('输入内容:', data.query.text)
  console.log('剪贴板输入:', data.query.inputs)
  console.log('是否来自缓存:', meta.fromCache)
  console.log('事件时间戳:', meta.timestamp)
})

Payload 类型:

interface BridgeEventPayload<CoreBoxInputData> {
  data: {
    query: {
      text: string
      inputs: Array<{ type: string; content: string }>
    }
  }
  meta: {
    timestamp: number
    fromCache: boolean
  }
}

onCoreBoxClipboardChange

监听剪贴板内容变化。

import { onCoreBoxClipboardChange } from '@talex-touch/utils/plugin/sdk/hooks'

onCoreBoxClipboardChange(({ data, meta }) => {
  console.log('剪贴板项:', data.item)
  console.log('是否来自缓存:', meta.fromCache)
})

onCoreBoxKeyEvent

已由 hard-cut 退役。旧 core-box:key-event 通道没有生产发送端，调用 onCoreBoxKeyEvent() 会抛出 plugin_bridge_key_event_removed。键盘交互应在插件 UI 组件内处理，或在附加型 widget 宿主提供 hostKeyEvent props 时使用该 prop。

自动事件缓存

问题背景

当插件 UIView 挂载到 CoreBox 时，主进程会在 dom-ready 后立即发送初始 query。但此时插件 JS 可能还未执行到 hook 注册代码，导致事件丢失。

解决方案

SDK 自动实现事件缓存机制：

自动缓存 - 模块加载时即开始监听并缓存事件
自动回放 - 调用 onCoreBoxInputChange 等 hook 时，自动回放缓存的事件
自动清理 - 回放后自动清除缓存

时序图:
────────────────────────────────────────────────────────►

主进程:
    [dom-ready] ──► 发送 input-change 事件

插件渲染进程:
    [模块加载] ──► 自动缓存事件
                            │
    [JS 执行] ──► onCoreBoxInputChange(handler)
                            │
                            └─► 回放缓存的事件给 handler

控制 API

clearBridgeEventCache

手动清除事件缓存（通常不需要调用）。

import { clearBridgeEventCache } from '@talex-touch/utils/plugin/sdk/hooks'

// 清除特定事件类型的缓存
clearBridgeEventCache('core-box:input-change')

// 清除所有缓存
clearBridgeEventCache()

使用场景:

插件需要忽略旧的初始查询
插件重新初始化时清理状态

技术原理

Hook 模块在加载阶段就订阅主进程事件并缓存。
注册 hook 时按时间顺序回放缓存，并附带 meta.fromCache。

最佳实践

尽早注册 hook - 虽然有缓存机制，但仍建议在插件入口尽早注册
处理空值 - 始终检查 query.text 和 query.inputs 是否存在
避免重复注册 - hook 不会自动去重，多次调用会触发多次回调

// ✅ 推荐：在顶层注册
onCoreBoxInputChange(({ data, meta }) => {
  const { query } = data
  if (!query.text && (!query.inputs || query.inputs.length === 0)) {
    return // 空查询
  }
  // 可以根据 meta.fromCache 判断是否为初始化时的缓存事件
  handleSearch(query)
})

// ❌ 避免：在异步回调中注册
setTimeout(() => {
  onCoreBoxInputChange(handler) // 可能错过缓存回放窗口
}, 1000)