LanMountainDesktop/LanMontainDesktop/.trae/specs/remove-video-wallpaper-feature/design.md

移除视频壁纸功能 - 技术设计文档

1. 概述

1.1 设计目标

本设计文档描述如何从 LanMountainDesktop 项目中完全移除视频壁纸功能，包括：

• 移除 LibVLC 相关依赖
• 清理主窗口中的视频壁纸代码
• 简化壁纸设置页面
• 清理本地化资源

1.2 技术约束

• 保持现有图片壁纸和纯色壁纸功能完整
• 确保应用构建和运行正常
• 不引入新的外部依赖

---

2. 架构变更

2.1 变更概览图

┌─────────────────────────────────────────────────────────────────┐
│                        变更前架构                                │
├─────────────────────────────────────────────────────────────────┤
│  MainWindow                                                      │
│  ├── DesktopWallpaperLayer (背景层)                              │
│  │   ├── DesktopWallpaperImageLayer (图片层)                     │
│  │   ├── DesktopVideoWallpaperImage (视频海报层)                  │
│  │   └── DesktopVideoWallpaperView (VLC视频播放层)               │
│  ├── _libVlc, _videoWallpaperPlayer, _videoWallpaperMedia        │
│  └── StartVideoWallpaper(), StopVideoWallpaper()                 │
│                                                                  │
│  WallpaperSettingsPage                                           │
│  ├── 类型选择: Image | Video | SolidColor                        │
│  └── 视频预览区域                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                        变更后架构                                │
├─────────────────────────────────────────────────────────────────┤
│  MainWindow                                                      │
│  ├── DesktopWallpaperLayer (背景层)                              │
│  │   └── DesktopWallpaperImageLayer (图片层)                     │
│  └── (移除所有视频相关字段和方法)                                  │
│                                                                  │
│  WallpaperSettingsPage                                           │
│  ├── 类型选择: Image | SolidColor                                │
│  └── (移除视频预览区域)                                           │
└─────────────────────────────────────────────────────────────────┘

2.2 组件变更清单

组件	变更类型	说明
LanMountainDesktop.csproj	修改	移除 LibVLC 包引用
MainWindow.axaml	修改	移除视频控件和命名空间
MainWindow.axaml.cs	修改	移除视频相关字段和清理代码
MainWindow.SettingsHardCut.Stubs.cs	修改	移除视频壁纸方法
AppearanceThemeService.cs	修改	移除视频种子提取器
WallpaperSettingsPage.axaml	修改	移除视频类型UI
WallpaperSettingsPageViewModel.cs	修改	移除视频相关属性
SettingsContracts.cs	修改	移除 Video 枚举值
SettingsDomainServices.cs	修改	移除视频扩展名检测
zh-CN.json	修改	移除视频相关本地化文本

---

3. 详细设计

3.1 项目依赖变更 (LanMountainDesktop.csproj)

3.1.1 移除的包引用

<!-- 移除以下包引用 -->
<PackageReference Include="LibVLCSharp.Avalonia" Version="3.9.5" />
<PackageReference Include="VideoLAN.LibVLC.Windows" Version="3.0.23" Condition="..." />
<PackageReference Include="VideoLAN.LibVLC.Mac" Version="3.1.3.1" Condition="..." />

3.1.2 变更影响

• 减少约 100MB+ 的依赖包大小
• 简化构建和发布流程
• 移除平台特定的原生库依赖

---

3.2 主窗口 XAML 变更 (MainWindow.axaml)

3.2.1 移除命名空间声明

<!-- 移除此行 -->
xmlns:vlc="clr-namespace:LibVLCSharp.Avalonia;assembly=LibVLCSharp.Avalonia"

3.2.2 移除视频壁纸控件

移除以下控件（约第126-137行）：

<!-- 移除 DesktopVideoWallpaperImage -->
<Image x:Name="DesktopVideoWallpaperImage"
       IsVisible="False"
       IsHitTestVisible="False"
       Stretch="UniformToFill"
       HorizontalAlignment="Stretch"
       VerticalAlignment="Stretch" />

<!-- 移除 DesktopVideoWallpaperView -->
<vlc:VideoView x:Name="DesktopVideoWallpaperView"
               IsVisible="False"
               IsHitTestVisible="False"
               HorizontalAlignment="Stretch"
               VerticalAlignment="Stretch" />

---

3.3 主窗口代码变更 (MainWindow.axaml.cs)

3.3.1 移除 using 声明

// 移除以下 using（如果存在）
using LibVLCSharp.Shared;
using LibVLCSharp.Avalonia;

3.3.2 移除静态字段

// 移除以下字段（约第68-71行）
private static readonly HashSet<string> SupportedVideoExtensions = new(StringComparer.OrdinalIgnoreCase)
{
    ".mp4", ".mkv", ".webm", ".avi", ".mov", ".m4v"
};

3.3.3 移除实例字段

// 移除以下字段（约第123-146行）
private Bitmap? _videoWallpaperPosterBitmap;
private string? _videoWallpaperPosterPath;
private string? _wallpaperVideoPath;
private LibVLC? _libVlc;
private MediaPlayer? _videoWallpaperPlayer;
private Media? _videoWallpaperMedia;
private readonly object _desktopVideoFrameSync = new();
private MediaPlayer.LibVLCVideoLockCb? _desktopVideoLockCallback;
private MediaPlayer.LibVLCVideoUnlockCb? _desktopVideoUnlockCallback;
private MediaPlayer.LibVLCVideoDisplayCb? _desktopVideoDisplayCallback;
private DispatcherTimer? _desktopVideoFrameRefreshTimer;
private IntPtr _desktopVideoFrameBufferPtr;
private byte[]? _desktopVideoStagingBuffer;
private WriteableBitmap? _desktopVideoBitmap;
private int _desktopVideoFrameWidth;
private int _desktopVideoFrameHeight;
private int _desktopVideoFramePitch;
private int _desktopVideoFrameBufferSize;
private int _desktopVideoFrameDirtyFlag;

3.3.4 修改 OnClosed 方法

移除视频相关清理代码（约第336-350行）：

// 移除以下代码行
StopVideoWallpaper();
_videoWallpaperMedia?.Dispose();
_videoWallpaperMedia = null;
_videoWallpaperPlayer?.Dispose();
_videoWallpaperPlayer = null;
_desktopVideoFrameRefreshTimer?.Stop();
_desktopVideoFrameRefreshTimer = null;
_videoWallpaperPosterBitmap?.Dispose();
_videoWallpaperPosterBitmap = null;
_videoWallpaperPosterPath = null;
_libVlc?.Dispose();
_libVlc = null;

---

3.4 主窗口 Stub 方法变更 (MainWindow.SettingsHardCut.Stubs.cs)

3.4.1 移除 using 声明

// 移除以下 using（第19-20行）
using LibVLCSharp.Shared;
using LibVLCSharp.Avalonia;

3.4.2 移除方法

移除以下完整方法：

方法名	行号范围	说明
StartVideoWallpaper	337-383	启动视频壁纸播放
StopVideoWallpaper	385-395	停止视频壁纸播放
TryCaptureVideoWallpaperPosterFrame	666-751	捕获视频海报帧
ApplyVideoWallpaperPosterVisibility	647-664	控制视频海报可见性

3.4.3 修改 UpdateWallpaperDisplay 方法

简化为仅处理图片壁纸：

private void UpdateWallpaperDisplay()
{
    // 移除视频分支，仅保留图片处理
    StopVideoWallpaper();  // 移除此调用
    ApplyWallpaperBrush();
}

修改后：

private void UpdateWallpaperDisplay()
{
    ApplyWallpaperBrush();
}

3.4.4 修改 ApplyWallpaperBrush 方法

移除所有 ApplyVideoWallpaperPosterVisibility 调用：

// 移除以下调用
ApplyVideoWallpaperPosterVisibility(showPoster: false);
ApplyVideoWallpaperPosterVisibility(showPoster: _videoWallpaperPosterBitmap is not null);

3.4.5 修改 SetWallpaperState 方法

移除视频类型处理分支（约第238-247行）：

// 移除以下代码块
var requestedTypeIsVideo = string.Equals(_wallpaperType, "Video", StringComparison.OrdinalIgnoreCase);
if (SupportedVideoExtensions.Contains(extension) || requestedTypeIsVideo)
{
    _wallpaperMediaType = WallpaperMediaType.Video;
    _wallpaperVideoPath = _wallpaperPath;
    _wallpaperDisplayState = File.Exists(_wallpaperPath)
        ? WallpaperDisplayState.CurrentValidWallpaper
        : WallpaperDisplayState.TemporarilyUnavailable;
    return;
}

---

3.5 外观主题服务变更 (AppearanceThemeService.cs)

3.5.1 移除接口和类

移除以下代码（约第92-184行）：

// 移除接口
internal interface IVideoWallpaperSeedExtractor
{
    IReadOnlyList<Color> ExtractSeedCandidates(string videoPath, MonetColorService monetColorService);
}

// 移除实现类
internal sealed class LibVlcVideoWallpaperSeedExtractor : IVideoWallpaperSeedExtractor
{
    // ... 整个类实现
}

---

3.6 壁纸设置页面 XAML 变更 (WallpaperSettingsPage.axaml)

3.6.1 移除视频预览区域

移除以下代码（约第29-44行）：

<Border Background="#FFF6F7F9"
        IsVisible="{Binding IsVideo}">
    <StackPanel HorizontalAlignment="Center"
                VerticalAlignment="Center"
                Spacing="12">
        <fi:FluentIcon Icon="Video"
                       Width="72"
                       Height="72"
                       Foreground="{DynamicResource AdaptiveTextSecondaryBrush}" />
        <TextBlock Text="{Binding VideoModeHintText}"
                   Width="300"
                   TextAlignment="Center"
                   TextWrapping="Wrap"
                   Foreground="{DynamicResource AdaptiveTextSecondaryBrush}" />
    </StackPanel>
</Border>

3.6.2 移除视频模式提示文本

移除以下代码（约第150-154行）：

<TextBlock Margin="0,8,0,0"
           IsVisible="{Binding IsVideo}"
           Foreground="{DynamicResource AdaptiveTextSecondaryBrush}"
           Text="{Binding VideoModeHintText}"
           TextWrapping="Wrap" />

3.6.3 修改填充方式设置可见性绑定

<!-- 修改前 -->
IsVisible="{Binding IsImageOrVideo}"

<!-- 修改后 -->
IsVisible="{Binding IsImage}"

---

3.7 壁纸设置 ViewModel 变更 (WallpaperSettingsPageViewModel.cs)

3.7.1 移除属性

// 移除以下属性
[ObservableProperty]
private bool _isImageOrVideo;

[ObservableProperty]
private bool _isVideo;

[ObservableProperty]
private string _videoModeHintText = string.Empty;

3.7.2 修改 CreateWallpaperTypes 方法

// 修改前
private IReadOnlyList<SelectionOption> CreateWallpaperTypes()
{
    return
    [
        new SelectionOption("Image", L("settings.wallpaper.type.image", "Image")),
        new SelectionOption("Video", L("settings.wallpaper.type.video", "Video")),
        new SelectionOption("SolidColor", L("settings.wallpaper.type.solid_color", "Solid Color"))
    ];
}

// 修改后
private IReadOnlyList<SelectionOption> CreateWallpaperTypes()
{
    return
    [
        new SelectionOption("Image", L("settings.wallpaper.type.image", "Image")),
        new SelectionOption("SolidColor", L("settings.wallpaper.type.solid_color", "Solid Color"))
    ];
}

3.7.3 修改 UpdateVisibility 方法

移除 IsVideo 和 IsImageOrVideo 的赋值：

// 移除以下行
IsVideo = SelectedWallpaperType?.Value == "Video";
IsImageOrVideo = SelectedWallpaperType?.Value is "Image" or "Video";

3.7.4 修改 RefreshLocalizedText 方法

// 移除以下行
VideoModeHintText = L("settings.wallpaper.video_mode", "Video wallpaper uses automatic fill mode.");

---

3.8 设置契约变更 (SettingsContracts.cs)

3.8.1 修改 WallpaperMediaType 枚举

// 修改前
public enum WallpaperMediaType
{
    None,
    Image,
    Video
}

// 修改后
public enum WallpaperMediaType
{
    None,
    Image
}

---

3.9 设置域服务变更 (SettingsDomainServices.cs)

3.9.1 移除视频扩展名集合

// 移除以下字段（约第150-153行）
private static readonly HashSet<string> VideoExtensions = new(StringComparer.OrdinalIgnoreCase)
{
    ".mp4", ".mkv", ".webm", ".avi", ".mov", ".m4v"
};

3.9.2 修改 DetectMediaType 方法

// 修改前
public WallpaperMediaType DetectMediaType(string? path)
{
    if (string.IsNullOrWhiteSpace(path))
    {
        return WallpaperMediaType.None;
    }

    var extension = Path.GetExtension(path.Trim());
    if (string.IsNullOrWhiteSpace(extension))
    {
        return WallpaperMediaType.None;
    }

    if (ImageExtensions.Contains(extension))
    {
        return WallpaperMediaType.Image;
    }

    if (VideoExtensions.Contains(extension))
    {
        return WallpaperMediaType.Video;
    }

    return WallpaperMediaType.None;
}

// 修改后
public WallpaperMediaType DetectMediaType(string? path)
{
    if (string.IsNullOrWhiteSpace(path))
    {
        return WallpaperMediaType.None;
    }

    var extension = Path.GetExtension(path.Trim());
    if (string.IsNullOrWhiteSpace(extension))
    {
        return WallpaperMediaType.None;
    }

    if (ImageExtensions.Contains(extension))
    {
        return WallpaperMediaType.Image;
    }

    return WallpaperMediaType.None;
}

---

3.10 本地化文件变更 (zh-CN.json)

3.10.1 移除的本地化键

// 移除以下键值对
"settings.wallpaper.type.video": "视频",
"settings.wallpaper.video_applied": "视频壁纸已应用。",
"settings.wallpaper.video_mode": "视频壁纸使用自动填充模式。",
"settings.wallpaper.video_restored": "已恢复保存的视频壁纸。",
"settings.wallpaper.video_not_found": "未找到视频壁纸文件。",
"settings.wallpaper.video_player_unavailable": "视频播放器不可用。",
"settings.wallpaper.video_play_failed_format": "播放视频壁纸失败：{0}"

3.10.2 修改描述文本

// 修改前
"settings.wallpaper.description": "选择图片或视频后可立即设为应用窗口壁纸。",

// 修改后
"settings.wallpaper.description": "选择图片后可立即设为应用窗口壁纸。",

---

4. 数据模型变更

4.1 WallpaperMediaType 枚举简化

变更前: None | Image | Video
变更后: None | Image

4.2 设置存储兼容性

现有用户设置中如果包含 Type: "Video" 的壁纸配置：

• 应用将无法识别该类型
• 将回退到纯色背景
• 用户需要重新选择图片壁纸

---

5. 风险评估

5.1 潜在风险

风险	影响	缓解措施
现有视频壁纸用户设置失效	中	应用会自动回退到纯色背景
遗漏的视频相关代码引用	低	编译器会报告未定义类型错误
本地化键遗漏	低	运行时会显示键名而非翻译文本

5.2 回滚策略

如需回滚，可通过 Git 恢复以下文件：

• LanMountainDesktop.csproj
• MainWindow.axaml / .axaml.cs
• MainWindow.SettingsHardCut.Stubs.cs
• AppearanceThemeService.cs
• WallpaperSettingsPage.axaml
• WallpaperSettingsPageViewModel.cs
• SettingsContracts.cs
• SettingsDomainServices.cs
• zh-CN.json

---

6. 验证清单

6.1 编译验证

• 项目编译无错误
• 无 LibVLC 相关类型引用警告
• 无未使用变量警告

6.2 功能验证

• 应用正常启动
• 图片壁纸正常显示
• 纯色壁纸正常显示
• 壁纸设置页面正常打开
• 类型选择器仅显示"图片"和"纯色"
• 壁纸导入功能正常工作

6.3 清理验证

• 无 LibVLC 相关 DLL 在输出目录
• 无视频相关本地化文本残留
• 无视频相关 UI 控件残留