MiguDelay 架构 05：QML、UiContext 与 ViewModel

系列导航：系列总览 · 上一篇：MiguDelay 架构 04：配置持久化与任务工作区 · 下一篇：MiguDelay 架构 06：MQTT 与协议入口

扫描基线

• 项目：MiguDelay（DDLive）
• 分支：refactor/video-frame-provider
• HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908
• 工作树：clean
• 扫描日期：2026-08-04
• 说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. QML 页面结构

App.qml 使用 FluentUI Router：

• / → windows/main.qml
• /HorizontalWindow → 横屏操作窗口
• /VerticalWindow → 竖屏操作窗口
• /Message → 消息页面

启动时调用 AppConfig.openPreviewOnStartup(true)。

2. PlaybackUiContext

QML 通过单一 playback 属性访问：

playback.task
playback.output
playback.aux
playback.monitor
playback.masterBackup
playback.preview
playback.errors

页面销毁不会决定后台任务是否继续。

3. ViewModel 合同

1. typed snapshot → Q_PROPERTY
2. QML 操作 → typed command
3. authoritative signal → 展示更新

sequenceDiagram
    participant QML as QML Control
    participant VM as ViewModel
    participant S as Domain Service
    participant M as QML Property

    QML->>VM: invoke command
    VM->>S: typed command
    alt accepted
        S->>S: commit authoritative state
        S-->>VM: stateChanged snapshot
        VM->>M: update property
    else rejected
        S-->>VM: stable error
        VM-->>QML: one warning
    end

ViewModel 不应先乐观改本地 mode、phase 或 playlist。

4. Preview Surface

PreviewSurfaceBinding.qml 将 YuvVideoItem、channel 和 Registry 绑定。页面销毁时 detach，Registry 使用 QPointer 防悬空。

5. Aux 与设置页

Aux 页面包含文件列表、文件预览、normal/emergency 播单、Live Preview 和标记栏。所有结构修改通过 AuxPlaybackViewModel 进入 Service/Store。

设置页仍直接编辑 AppConfig，保存或检测可能触发 StreamReconfiguration Binding，但 QML 不执行重配置。

6. 最新 HEAD UI 变化

d28ec061 修复 Aux_MarkBar.qml 中磁盘饼图因高频 Aux 状态刷新而重复初始化动画的问题，并增加静态校验测试。该变化不修改 Aux 领域状态。

7. 源码证据

• src/qml/App.qml
• src/qml/windows/*.qml
• src/qml/pages/**/*.qml
• src/qml/components/PreviewSurfaceBinding.qml
• src/code/data/playback/playbackuicontext.*
• src/code/data/playback/*viewmodel.*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 04：配置持久化与任务工作区 · 下一篇：MiguDelay 架构 06：MQTT 与协议入口