插件浮窗（Plugin Window SPI）

第三方可创建多开、可定位、置顶、可穿透、可防录屏的 QML 浮窗，无需宿主改源码。 适用：OCR 贴译覆盖层、独立助手窗、工具 HUD、悬浮提示板。

功能型常驻窗用本页 API；主题/装饰类的插槽替换见 UI 插槽。

---

创建

host.create_plugin_window(
    plugin_id: str,
    qml_path: str,                    # 插件包内相对路径，或 file:// URL
    *,
    window_id: str = "",              # 省略则自动生成；同 ID 重建会先关旧窗
    title: str = "",
    x: int | None = None,
    y: int | None = None,
    width: int = 480,
    height: int = 320,
    always_on_top: bool = True,
    frameless: bool = False,
    click_through: bool = False,
    exclude_from_capture: bool = False,
    context: dict | None = None,      # 注入根对象的额外属性
) -> str                              # window_id；失败返回 ""

控制

host.show_plugin_window(window_id: str, visible: bool = True) -> bool
host.close_plugin_window(window_id: str) -> bool
host.close_plugin_windows(plugin_id: str | None = None) -> bool
host.move_plugin_window(window_id: str, x: int, y: int) -> bool
host.resize_plugin_window(window_id: str, width: int, height: int) -> bool
host.set_plugin_window_flags(
    window_id: str,
    *,
    always_on_top: bool | None = None,
    click_through: bool | None = None,
    exclude_from_capture: bool | None = None,
) -> bool
host.list_plugin_windows(plugin_id: str = "") -> list[dict]
host.get_plugin_window(window_id: str) -> dict

---

QML 约定

• 根元素可以是：
  • Window —— 完全自控（自己调 visible / 位置 / 旗标）；
  • Item —— 宿主自动包一层 PluginWindowShell（推荐，省事且风格统一）。
• 宿主注入：pluginId、windowId、bridge，以及 context 里的键。
• 无边框窗自行处理拖拽。
• click_through / exclude_from_capture 走宿主平台能力（后者即 SetWindowDisplayAffinity，见 朗读与提示）。
• 插件 shutdown() 时应 close_plugin_windows(self.id)；窗口被销毁会自动出注册表。

---

最小示例

# 定位覆盖窗（例如 OCR 贴译）
wid = self.host.create_plugin_window(
    self.id, "Overlay.qml",
    title="OCR",
    x=100, y=80, width=420, height=120,
    always_on_top=True, frameless=True,
    click_through=True,
    exclude_from_capture=True,
    context={"scale": 1.0},
)
if wid:
    self.host.move_plugin_window(wid, 100, 80)

// Overlay.qml（根为 Item，宿主自动包壳）
import QtQuick 2.15

Item {
    property string pluginId: ""
    property string windowId: ""
    property var bridge: null
    property real scale: 1.0     // ← context 注入

    Text { text: "识别结果…"; color: "white" }
}

---

与 UI 插槽的区别

	插件浮窗	UI 插槽
数量	多开	通常是单例（同级互斥）
位置	运行时任意定位/改尺寸	由宿主布局决定
典型用途	工具 HUD、独立助手、覆盖层	换底板/音柱/字幕视图
声明	代码调用	mod.json 的 ui_extensions

---

相关

• UI 插槽
• 朗读与提示 — 防录屏
• 文件选择与长任务
• tool 工具