feat.新增了插件开发文档

2026-06-24 02:14:26 +08:00 · 2026-04-13 19:54:37 +08:00
parent ce5acf5bd7
commit 1b22e9df4a
23 changed files with 4770 additions and 1 deletions
--- a/develop/03-API实践指南/02-组件注册与配置.md
+++ b/develop/03-API实践指南/02-组件注册与配置.md
@@ -0,0 +1,182 @@
+# 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月*