Desktop Frames Plus 插件引擎开发指南:从零实现 IFramePlugin 打造自定义桌面插件
Desktop Frames Plus 插件引擎开发指南:从零实现 IFramePlugin 打造自定义桌面插件
Desktop Frames Plus 是一款开源的 Windows 桌面图标管理工具,它在桌面上创建虚拟"边框"(Frame),帮你把杂乱的图标收纳成整齐的区块。更强大的是,它内置了一套插件引擎:VU 表、系统性能监控、迷你计算器等 7 个官方插件都实现了同一个接口 IFramePlugin。本文是一份从零开始的 Desktop Frames Plus 插件开发教程,带你亲手实现一个自定义桌面插件,理解"插件如何被注册、加载、调度和回收"的完整链路。
先认识插件目录:7 个内置插件长什么样
所有插件代码集中在 Code/Desktop Frames/Plugins/ 目录,每个文件就是一个独立插件:
| 插件类 | 插件 ID | 功能 |
|---|---|---|
PictureSlideshowPlugin |
PictureSlideshow |
桌面照片轮播 |
VUMeterPlugin |
AnalogVUMeter |
模拟 VU 表(音频电平) |
SystemIpPlugin |
IPInfo |
显示本机 IP 信息 |
SystemPerformancePlugin |
SystemPerformancePlugin |
CPU / 内存性能监控 |
SystemQueueSaturationPlugin |
SystemQueueSaturation |
磁盘队列饱和度 |
CalculatorPlugin |
MinimalCalculator |
迷你计算器(支持全局键盘) |
CustomTerminalPlugin |
CustomTerminal |
桌面迷你终端 |
所有插件共享同一个契约文件 IFramePlugin.cs,这正是我们要实现的核心接口。
接口解剖:IFramePlugin 的 8 个成员
打开 IFramePlugin.cs,接口非常精简,分为"身份描述"和"生命周期"两组:
public interface IFramePlugin
{
string PluginId { get; } // 插件唯一标识,如 "MinimalCalculator"
string DisplayName { get; } // 菜单中显示的插件名
int DevelopmentState { get; } // 1=成熟 2=实验 3=开发中
FrameworkElement CreateVisualElement(); // ① 创建 WPF 视图
void Initialize(FrameworkElement visual,
Dictionary<string, object> settings); // ② 用保存的配置初始化
void Pause(); // ③ 暂停(收起/失焦时)
void Resume(); // ④ 恢复
void Cleanup(); // ⑤ 销毁前清理资源
void ShowSettingsWindow(Window ownerWindow, dynamic frameData); // ⑥ 自绘设置窗口
}
一句话概括:插件自己画界面、自己管资源、自己开设置窗口,宿主(Desktop Frames Plus)只负责创建窗口和调度。这种"解耦式设置接口"(源码注释称为 Decoupled Settings Interface)意味着每个插件可以拥有风格完全独立的设置对话框。
生命周期详解:一个插件帧的诞生与销毁
以 FrameManager.cs 中 ItemsType == "Plugin" 的处理分支为例,宿主创建插件帧时的调用顺序是:
CreatePluginInstance(pluginId)— 从 PluginManager.cs 的工厂字典中取出工厂函数,new出一个全新的隔离实例(每个插件帧独立一个实例,互不共享状态);CreateVisualElement()— 插件返回 WPF 根元素,宿主把它注入到帧窗口中;Initialize(visual, settings)— 宿主从帧数据里解析出PluginSettings字典传入,插件据此恢复上次的配置;- 若该帧处于"收起"(Rollup)状态,立即调用
Pause(); - 展开时调用
Resume(),删除帧时调用Cleanup()。
💡 实例化失败时的兜底:如果
CreatePluginInstance返回null,宿主会显示红色提示 "Plugin 'xxx' missing or failed to load.",而不会让整个程序崩溃——这是插件容错设计。
从零实现:打造你的第一个自定义插件
假设我们要做一个"桌面时钟插件"。下面按 5 步完成,每步代码都很短,建议配合 VUMeterPlugin.cs(结构最清晰的参考实现)对照阅读。
第 1 步:在 Plugins 目录新建类文件
在 Code/Desktop Frames/Plugins/ 下新建 ClockPlugin.cs,命名空间固定为 Desktop_Frames.Plugins:
public class ClockPlugin : IFramePlugin
{
public string PluginId => "WallClock";
public string DisplayName => "Wall Clock";
public int DevelopmentState => 2; // 实验阶段
private DispatcherTimer _timer;
private TextBlock _clockText;
}
第 2 步:CreateVisualElement 构建 WPF 视图
关键技巧:用 Viewbox 作为根容器并设置 Stretch.Uniform,插件内容会随帧窗口自动等比缩放——这是 VU 表、性能监控等插件的共同做法:
public FrameworkElement CreateVisualElement()
{
_clockText = new TextBlock
{
Text = "00:00:00",
FontSize = 48,
Foreground = Brushes.White,
HorizontalAlignment = HorizontalAlignment.Center,
VerticalAlignment = VerticalAlignment.Center
};
_rootViewbox = new Viewbox { Child = _clockText, Margin = new Thickness(8) };
return _rootViewbox;
}
第 3 步:Initialize 读取配置并启动计时器
settings 是宿主传入的 Dictionary<string, object>,对应帧数据 JSON 中的 PluginSettings 节点。读取时记得做键存在检查 + 安全解析,参考 VUMeterPlugin.cs 的 ApplySettingsData:
public void Initialize(FrameworkElement visual, Dictionary<string, object> settings)
{
if (settings != null && settings.ContainsKey("ShowSeconds"))
_showSeconds = bool.Parse(settings["ShowSeconds"].ToString());
_timer = new DispatcherTimer { Interval = TimeSpan.FromSeconds(1) };
_timer.Tick += (s, e) => _clockText.Text = DateTime.Now
.ToString(_showSeconds ? "HH:mm:ss" : "HH:mm");
_timer.Start();
}
第 4 步:Pause / Resume / Cleanup 管好资源
DispatcherTimer、事件订阅、COM 对象(如 VU 表用到的 WASAPI 音频接口)都必须成对管理。最小实现:
public void Pause() => _timer?.Stop();
public void Resume() => _timer?.Start();
public void Cleanup()
{
_timer?.Stop();
_timer = null; // 防止事件回调触碰已销毁的视图
}
CalculatorPlugin 是一个反面教材式的深度案例:它用 Windows 低级键盘钩子(SetWindowsHookEx),在 CalculatorPlugin.cs 中展示了 Pause() 卸载钩子、Cleanup() 卸载钩子并保存状态的双保险写法。
第 5 步:ShowSettingsWindow 自绘设置窗口
这是接口中最"自由"的成员:宿主只把当前窗口(用于居中)和帧数据传进来,插件自己画一个无边框小窗口。三个内置插件的通用套路(见 VUMeterPlugin.cs):
- 用
WindowStyle.None+ 顶部Border做可拖拽标题栏; - 用
Utility.GetColorFromName(SettingsManager.SelectedColor)取用户主题色做点缀; - 点击"保存"时,把新配置写回帧数据:
if (frameData is Newtonsoft.Json.Linq.JObject jFrame)
jFrame["PluginSettings"] = JObject.FromObject(newSettings);
try { FrameDataManager.SaveFrameData(); } catch { }
写回 PluginSettings 后再调用 FrameDataManager.SaveFrameData() 持久化,下次加载帧时配置就会自动恢复到 Initialize 的 settings 字典里,形成闭环。
注册插件:让 PluginManager 认识你的新类
打开 PluginManager.cs 的 Initialize(),所有内置插件都在这里登记。仿照现有写法加一行即可:
RegisterPlugin("WallClock", "Wall Clock", () => new ClockPlugin());
RegisterPlugin 内部做三件事:
- 把工厂委托(
() => new ...)存入_pluginFactories,保证每次CreatePluginInstance都拿到全新实例; - 把
displayName存入_pluginNames,供右键菜单"新建插件帧"下拉项显示; - 立即试实例化一次,读取
DevelopmentState存入_pluginStates——失败则回退为 3(最不稳定),保证注册流程永不中断。
DevelopmentState 与菜单可见性:插件分级机制
插件不是注册了就一定能被用户看到。SettingsManager.cs 中有一个全局开关 PluginAvailabilityLevel(默认 1):
| 级别含义 | 效果 |
|---|---|
0 |
右键菜单中"添加插件"入口整体隐藏(见 FrameManager.cs) |
1 |
只显示 DevelopmentState <= 1 的成熟插件 |
2 |
追加显示实验性插件 |
3 |
追加显示开发中的插件 |
GetAvailablePlugins() 按 pluginLevel <= userAllowedLevel 过滤,所以把新插件标记为 3(In Development)是向自己"灰度发布"的安全做法。
避坑清单:从 7 个内置插件总结的 6 条经验
- 一个帧一个实例:绝不要用静态字段存运行状态,
CreatePluginInstance会按帧多次调用工厂; - 视图用 Viewbox 包裹:帧窗口尺寸由用户随意拖动,
Stretch.Uniform是最稳的适配方案; - 所有外部数据都要"防御式解析":
settings里任何值都可能是字符串或 null,参考double.TryParse+ 范围钳制的写法; - 定时器必须成对 Start/Stop:
Pause停表、Cleanup解绑事件并置空引用; - COM 与钩子资源显式释放:
Marshal.ReleaseComObject、UnhookWindowsHookEx一个都不能少; - 设置窗口保存后重建视图:先
BuildLayout()/刷新 UI,再win.Close(),用户才能即时看到效果。
常用文件速查
| 文件 | 作用 |
|---|---|
| IFramePlugin.cs | 插件契约接口(8 个成员) |
| PluginManager.cs | 插件注册表与实例工厂 |
| VUMeterPlugin.cs | 结构最完整的参考实现 |
| CalculatorPlugin.cs | 键盘钩子 + 状态持久化案例 |
| FrameManager.cs | 插件帧创建/初始化调度 |
| SettingsManager.cs | 插件可见性级别 PluginAvailabilityLevel |
| Desktop Frames.csproj | 工程文件,编译入口 |
至此,你已经掌握了 Desktop Frames Plus 插件引擎的完整开发路径:实现接口 → 注册工厂 → 分级发布 → 自绘设置 → 资源闭环。动手写一个"桌面时钟"或"CPU 温度探针",就是进入这套插件生态的最佳第一步 🚀
