05-frontend-api

前端命名空间（window.auroraview）

• 全局唯一入口：window.auroraview
• 核心能力：
  • auroraview.call(method: string, params?: any): Promise<any>
    • method 为字符串命名空间，如："api.export_scene"、"tool.apply"
    • params 支持：对象（当作 kwargs）、数组（当作位置参数）、单值（单一位置参数）
    • 正常返回：Promise resolve 为 Python 返回的 JSON 兼容值
    • 异常：Promise reject，错误对象包含 name / message / 可选 code / data
  • auroraview.on(event: string, handler: (payload: any) => void): () => void
    • 订阅后端推送事件，返回取消订阅函数
  • auroraview.off(event: string, handler: (payload: any) => void): void
• pywebview 风格语法糖：auroraview.api
  • 通过 JS Proxy 映射：auroraview.api.foo(...args) → auroraview.call("api.foo", args)
  • 主要服务于 PyWebView 用户迁移场景
• 预留字段：
  • auroraview.platform?: string （如 "standalone"、"maya2025-pyside6"）
  • auroraview.token?: string （CSRF/session token，对齐 pywebview）
• Ready 事件：
  • 注入完成后触发 window 级事件 "auroraviewready"
  • 前端可在该事件中安全使用 auroraview.call/on/api

auroraview.call 请求/响应协议（目标结构）

• JS → 后端（Rust/Python）消息：

  • type: "call"
  • id: string 唯一ID（例如自增序号 + 时间戳），用于在回包中对应 Promise
  • method: string 方法名（如 "api.echo"、"tool.apply"）
  • params: any 参数（对象/数组/单值，遵循上文的调用规则）

• 后端 → JS 回包消息：

  • type: "call_result"
  • id: string 必须与请求中 id 完全一致
  • ok: bool 调用是否成功
  • 成功时：result: any 为返回值（JSON 兼容类型）
  • 失败时：error: { name: string; message: string; code?: string | int; data?: any }

• JS 侧 Promise 语义：

  • 发起调用时，JS 为 id 建立一个 pending Promise
  • 收到 call_result：
    • ok == true → resolve(result)
    • ok == false → reject(error)
  • 如果超时或底层报错，可在 JS 层构造 error 并 reject