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

# 02-组件注册与配置

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

---

## 🎯 API 概览

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

---

## 📋 基本用法

```csharp
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

```csharp
ComponentId = "MyPlugin.WeatherWidget"
```

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

### DisplayName

```csharp
DisplayName = "天气"
```

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

### IconKey

```csharp
IconKey = "Weather"
```

使用 [Fluent UI System Icons](https://github.com/microsoft/fluentui-system-icons) 的图标名。

### Category

```csharp
Category = "工具"
```

常用分类：
- `工具` - 实用工具
- `信息` - 信息展示
- `娱乐` - 娱乐相关
- `系统` - 系统监控

### MinWidthCells / MinHeightCells

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

---

## 🎨 圆角配置

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

---

## 📐 调整大小模式

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

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

---

## 🧩 完整示例

```csharp
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 源码](../../LanMountainDesktop.PluginSdk/PluginDesktopComponentOptions.cs)
- [02-桌面组件系统](../02-核心概念与原理/02-桌面组件系统.md)

---

*最后更新：2026年4月*