07-event-system

事件分发机制（Python → JavaScript）

关键设计决策（2025-01）：统一使用 window.auroraview.trigger() 进行事件分发

• Rust 层实现：

  • 所有 WebViewMessage::EmitEvent 处理统一使用 window.auroraview.trigger(event, data)
  • 替代原有的 window.dispatchEvent(new CustomEvent(...))
  • 涉及文件：
    • src/webview/backend/native.rs
    • src/webview/event_loop.rs（两处）
    • src/webview/webview_inner.rs
    • src/webview/backend/mod.rs
    • src/webview/backend/custom.rs

• 标准模式：

  (function() {
      if (window.auroraview && window.auroraview.trigger) {
          window.auroraview.trigger('event_name', data);
      } else {
          console.error('[AuroraView] Event bridge not ready, cannot emit event: event_name');
      }
  })();
  

• 前端接收：

  • 使用 window.auroraview.on(event, handler) 订阅事件
  • 与 Rust 层的 trigger() 完全匹配
  • 形成完整的事件流：Python emit() → Rust trigger() → JS on()

• 架构优势：

  • API 一致性：统一使用 AuroraView 事件系统，不混用浏览器原生 API
  • 错误处理：事件桥接未就绪时有明确错误提示
  • 可维护性：所有事件分发逻辑集中在 window.auroraview 命名空间

最小端到端示例（当前实现）

注意：当前实现中，auroraview.call() 在桥接层还是 fire-and-forget，Promise 会立即 resolve 为 undefined； 最推荐的模式是：前端通过 auroraview.api.* 触发 Python 逻辑，Python 再通过 emit 向前端推事件。

• 前端（JS）：

  // 等待 bridge 就绪
  window.addEventListener('auroraviewready', () => {
    // 订阅来自 Python 的 echo 结果
    auroraview.on('echo_result', (payload) => {
      console.log('[AuroraView] echo_result from Python:', payload);
    });
  
    // 通过 api 调用 Python 方法（fire-and-forget）
    auroraview.api.echo({ message: 'hello from JS' });
  });
  

• Python（概念示例，基于 AuroraView 基类）：

  from auroraview import AuroraView
  
  class MyTool(AuroraView):
      def __init__(self, **kwargs):
          super().__init__(api=self, **kwargs)
  
      # JS 侧调用：auroraview.api.echo({ message: "..." })
      def echo(self, message: str) -> None:
          # 当前实现：通过事件把结果推回前端
          self.emit("echo_result", {"message": message})
  

后续在 call 的 request/response 协议补全后，可以把 echo 设计为真正返回值的函数， 前端直接使用 await auroraview.api.echo("hello") 获取结果。