QML 界面插槽与 HostContext

在 mod.json 的 ui_extensions 里把插槽名映射到包内 .qml 文件，即可替换对应视觉区域，无需改主程序。

插槽清单、互斥与级联回退、背景插槽准则、window_backdrop、settings_view 注入 都已在知识卡片里各自成页，本页不再重复：

主题	卡片
槽位清单 / 互斥 / 级联回退 / 决议优先级 / 背景插槽准则	UI 插槽
窗口材质 window_backdrop	theme
settings_view 注入属性与保存示例	自定义设置页
QML 通用写法 / 配置热响应 / 视觉规范	UI 扩展（QML）

本页只讲卡片里没有的部分：hostContext 子系统、按插槽的额外注入属性、实战示例。

---

1. HostContext（悬浮窗类插槽）

宿主向组件根对象注入 property var hostContext：

import QtQuick 2.15

Item {
    id: root
    property var hostContext: null

    readonly property color textColor:
        hostContext ? hostContext.style.textColor : "#ffffff"
    readonly property string translation:
        hostContext ? hostContext.subtitle.currTranslation : ""
    readonly property bool hovered:
        hostContext ? hostContext.window.hovered : false

    function callPython() {
        if (!hostContext) return
        hostContext.invoke("my.plugin.id", "ping", { "n": 1 })
    }

    Rectangle {
        anchors.fill: parent
        color: hostContext ? hostContext.style.bgColor : "#00000000"
        opacity: hostContext ? hostContext.style.bgOpacity : 1.0

        Text {
            anchors.centerIn: parent
            text: translation
            color: textColor
            font.pixelSize: hostContext ? hostContext.style.fontSize : 24
            font.family: hostContext ? hostContext.style.fontFamily : "sans-serif"
        }
    }
}

子系统

style
textColor · bgColor · fontOpacity · bgOpacity · fontSize · fontFamily · themeId · primary · primaryHover · primaryGlow · radiusLarge

subtitle
currSource · currTranslation · hasRealSubtitle · prevSource · prevTranslation · hasPrev · isTyping · isSourceActive · isTranslationActive

audio
isMicMuted · audioDuckingEnabled · playbackDevice

window
hovered · dragging · width · height · setBackdrop(type) · setClickThrough(bool)

RPC
hostContext.invoke(pluginId, action, params) → Python handle_action → action_<action>(**params)

---

2. 额外注入属性（按插槽）

插槽	额外属性 / 信号
overlay_background 等	hovered, appState
caption_view	appState, bridge
alert_capsule	alertType, alertCategory, showCapsule；信号 closeRequested, gotoSettingsRequested, switchLocalRequested
style_bar_actions	hostContext
窗口底板类	window, appState, 可用 customRadius

多窗口底板可声明：

property bool enforceCustomRadius: true
property real customRadius: 16
property real customOpacity: 0.85

3. 实战：替换音量条

mod.json 片段：

{
  "type": "theme",
  "ui_extensions": { "audio_level": "CustomWaveform.qml" }
}

import QtQuick 2.15

Item {
    id: root
    anchors.fill: parent
    property real level: 0.0
    property var hostContext: null

    // 若宿主未提供电平信号，可自行用 Connections 接 bridge（视版本）
    Row {
        anchors.bottom: parent.bottom
        anchors.right: parent.right
        anchors.margins: 8
        spacing: 2
        opacity: root.level > 0.01 ? 0.95 : 0.0

        Repeater {
            model: 5
            Rectangle {
                width: 2
                height: Math.max(2, Math.min(10, root.level * 10))
                color: "#00f0ff"
            }
        }
    }
}

完整可运行参考：extensions/example_custom_waveform_ui/、example_theme_cyberpunk/。

---

4. QML 编写要点

1. 组件根上保留 anchors.fill: parent，避免撑破宿主布局。
2. 所有 hostContext 访问做空判断，便于预览。
3. 不要依赖未在本文出现的全局对象名。

主题自动适配（ThemeTokens / PluggableWindowBackground）与「矢量 SVG 图标」红线见 UI 扩展（QML） 与 运行环境与安全红线。