06-python-api

Python 抽象：AuroraView 基类

• 导入约定：from auroraview import AuroraView
• 构造参数（简化版）：
  • parent: Any | None = None
    • None → Standalone 模式（Rust Shell / WebView 壳）
    • Qt 对象 → DCC 模式（PySide 宿主，作为 parent dock/panel）
  • url: str | None = None / html: str | None = None
  • title: str = "AuroraView"
  • width: int = 800, height: int = 600
  • fullscreen: bool = False
  • debug: bool = False
  • api: Any | None = None → 暴露到 auroraview.api.*
• 生命周期钩子（可覆写）：
  • def on_show(self) -> None: ...
  • def on_hide(self) -> None: ...
  • def on_close(self) -> None: ...
  • def on_ready(self) -> None: ... （WebView & JS bridge 就绪）
• 事件推送：
  • self.emit(event_name: str, payload: Any) -> None
    • Python → JS：触发前端 auroraview.on(event_name, handler)

JS → Python 映射机制

1. auroraview.api.* 风格

   • Python 在构造 AuroraView 时传入 api 对象，例如 api=self
   • 规则：auroraview.api.export_scene(*args) → Python api.export_scene(*args)
   • 实现：
     • JS：auroraview.api.foo(...args) → auroraview.call("api.foo", args)
     • Python：解析 method 前缀 "api."，以 getattr(api, name) 查找方法
     • params 为 list → 调用 func(*params)；为 dict → 调用 func(**params)

2. 通用 auroraview.call(method, params)

   • AuroraView 提供注册接口：bind_call(method: str, func: Callable)
   • 使用示例：
     • JS：auroraview.call("tool.apply", {"strength": 0.8})
     • Python：
       • self.bind_call("tool.apply", self.apply_tool)
       • def apply_tool(self, strength: float, mode: str = "preview"): ...
   • 调用规则：
     • params 是 dict → func(**params)
     • params 是 list → func(*params)
     • 其它 → 单一位置参数

Standalone / DCC 双模式

• Standalone：
  • 不依赖 Qt/PySide，仅使用 Rust 壳 + WebView（现有 wry/tao，可逐步演进到 Win32 + WebView2）
  • parent=None，AuroraView 负责创建顶层窗口并托管事件循环
• DCC：
  • 仅在 Python 层使用 Qt/PySide 作为宿主壳（通过 parent 注入）
  • Rust/Python core 不直接依赖 Qt；Qt 逻辑集中在 auroraview.dcc.qt_shell 类模块
  • 通过 parent 将 WebView 子窗口嵌入 DCC 主窗口（Dock/Pane），保持原生体验