LanMountainDesktop/docs/archive/Plugins develop/03-API实践指南/02-组件注册与配置.md

02-组件注册与配置

AddPluginDesktopComponent 是注册桌面组件的核心 API。本文详细讲解其用法和配置选项。

---

🎯 API 概览

public static IServiceCollection AddPluginDesktopComponent<TComponent>(
    this IServiceCollection services,
    PluginDesktopComponentOptions options)
    where TComponent : class, IControl

---

📋 基本用法

public override void Initialize(HostBuilderContext context, IServiceCollection services)
{
    services.AddPluginDesktopComponent<MyWidget>(
        new PluginDesktopComponentOptions
        {
            ComponentId = "MyPlugin.MyWidget",
            DisplayName = "我的组件",
            IconKey = "Home",
            Category = "工具",
            MinWidthCells = 4,
            MinHeightCells = 3
        });
}

---

🔧 PluginDesktopComponentOptions

完整属性列表

属性	类型	必需	说明
ComponentId	string	✅	唯一标识符
DisplayName	string	✅	显示名称
IconKey	string	✅	图标键名
Category	string	✅	分类
MinWidthCells	int	✅	最小宽度（格）
MinHeightCells	int	✅	最小高度（格）
CornerRadiusPreset	PluginCornerRadiusPreset	❌	圆角预设
ResizeMode	PluginDesktopComponentResizeMode	❌	调整大小模式

ComponentId

ComponentId = "MyPlugin.WeatherWidget"

• 必须唯一
• 建议使用 插件ID.组件名 格式
• 一经发布不可更改

DisplayName

DisplayName = "天气"

• 显示在组件库中
• 支持本地化（通过资源文件）

IconKey

IconKey = "Weather"

使用 Fluent UI System Icons 的图标名。

Category

Category = "工具"

常用分类：

• 工具 - 实用工具
• 信息 - 信息展示
• 娱乐 - 娱乐相关
• 系统 - 系统监控

MinWidthCells / MinHeightCells

MinWidthCells = 4,   // 4格宽，约240像素
MinHeightCells = 3   // 3格高，约180像素

---

🎨 圆角配置

services.AddPluginDesktopComponent<MyWidget>(
    new PluginDesktopComponentOptions
    {
        ComponentId = "MyPlugin.Widget",
        DisplayName = "我的组件",
        IconKey = "Home",
        Category = "工具",
        MinWidthCells = 4,
        MinHeightCells = 3,
        CornerRadiusPreset = PluginCornerRadiusPreset.Component
    });

---

📐 调整大小模式

services.AddPluginDesktopComponent<MyWidget>(
    new PluginDesktopComponentOptions
    {
        // ...
        ResizeMode = PluginDesktopComponentResizeMode.Free
    });

模式	说明
Free	自由调整大小
Fixed	固定大小
AspectRatio	保持宽高比

---

🧩 完整示例

public override void Initialize(HostBuilderContext context, IServiceCollection services)
{
    // 天气组件
    services.AddPluginDesktopComponent<WeatherWidget>(
        new PluginDesktopComponentOptions
        {
            ComponentId = "WeatherPlugin.Widget",
            DisplayName = "天气",
            IconKey = "Weather",
            Category = "信息",
            MinWidthCells = 4,
            MinHeightCells = 3,
            CornerRadiusPreset = PluginCornerRadiusPreset.Component,
            ResizeMode = PluginDesktopComponentResizeMode.Free
        });
    
    // 时钟组件
    services.AddPluginDesktopComponent<ClockWidget>(
        new PluginDesktopComponentOptions
        {
            ComponentId = "ClockPlugin.Widget",
            DisplayName = "时钟",
            IconKey = "Clock",
            Category = "工具",
            MinWidthCells = 4,
            MinHeightCells = 4,
            CornerRadiusPreset = PluginCornerRadiusPreset.Component,
            ResizeMode = PluginDesktopComponentResizeMode.AspectRatio
        });
}

---

📚 参考资源

• PluginDesktopComponentOptions 源码
• 02-桌面组件系统

---

最后更新：2026年4月