mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-24 02:14:26 +08:00
feat.新增了插件开发文档
This commit is contained in:
lincube
353
docs/Plugins develop/02-核心概念与原理/03-设置系统集成.md
Normal file
353
docs/Plugins develop/02-核心概念与原理/03-设置系统集成.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# 03-设置系统集成
|
||||
|
||||
设置系统允许插件在阑山桌面的设置窗口中添加自己的配置页面，让用户可以自定义插件行为。
|
||||
|
||||
---
|
||||
|
||||
## 🎯 设置系统概述
|
||||
|
||||
阑山桌面提供两种设置页面模式：
|
||||
|
||||
| 模式 | 适用场景 | 复杂度 | 灵活性 |
|
||||
|-----|---------|--------|--------|
|
||||
| **声明式设置** | 简单的键值配置 | 低 | 中 |
|
||||
| **自定义设置页** | 复杂交互、自定义控件 | 中 | 高 |
|
||||
|
||||
---
|
||||
|
||||
## 📝 声明式设置
|
||||
|
||||
通过链式 API 声明配置项，宿主自动生成设置页面。
|
||||
|
||||
### 基本用法
|
||||
|
||||
```csharp
|
||||
public override void Initialize(HostBuilderContext context, IServiceCollection services)
|
||||
{
|
||||
services.AddPluginSettingsSection(
|
||||
sectionId: "myplugin-settings", // 设置节唯一标识
|
||||
displayName: "我的插件设置", // 显示名称
|
||||
configure: section => // 配置设置项
|
||||
{
|
||||
section
|
||||
.AddToggle("enabled", "启用插件", defaultValue: true)
|
||||
.AddText("api_key", "API密钥", defaultValue: "")
|
||||
.AddNumber("interval", "刷新间隔(秒)", defaultValue: 60, minimum: 10, maximum: 3600)
|
||||
.AddSelect("theme", "主题", new[]
|
||||
{
|
||||
new SettingsOptionChoice("light", "浅色"),
|
||||
new SettingsOptionChoice("dark", "深色"),
|
||||
new SettingsOptionChoice("auto", "跟随系统")
|
||||
}, defaultValue: "auto");
|
||||
},
|
||||
iconKey: "Settings"); // 图标
|
||||
}
|
||||
```
|
||||
|
||||
### 支持的设置类型
|
||||
|
||||
| 方法 | 类型 | 用途 | 示例 |
|
||||
|-----|------|------|------|
|
||||
| `AddToggle` | 布尔 | 开关选项 | 启用/禁用 |
|
||||
| `AddText` | 字符串 | 文本输入 | API密钥、用户名 |
|
||||
| `AddNumber` | 数值 | 数字输入 | 刷新间隔、数量 |
|
||||
| `AddSelect` | 枚举 | 下拉选择 | 主题、语言 |
|
||||
| `AddPath` | 路径 | 文件/文件夹选择 | 保存路径 |
|
||||
| `AddList` | 列表 | 字符串列表 | 服务器地址列表 |
|
||||
|
||||
### 各类型详解
|
||||
|
||||
#### Toggle（开关）
|
||||
|
||||
```csharp
|
||||
.AddToggle(
|
||||
key: "auto_update", // 设置键
|
||||
displayName: "自动更新", // 显示名称
|
||||
defaultValue: true, // 默认值
|
||||
description: "启动时检查更新" // 可选描述
|
||||
)
|
||||
```
|
||||
|
||||
#### Text（文本）
|
||||
|
||||
```csharp
|
||||
.AddText(
|
||||
key: "api_key",
|
||||
displayName: "API密钥",
|
||||
defaultValue: "",
|
||||
placeholder: "请输入API密钥", // 占位符
|
||||
isPassword: true // 密码输入（掩码显示）
|
||||
)
|
||||
```
|
||||
|
||||
#### Number（数值）
|
||||
|
||||
```csharp
|
||||
.AddNumber(
|
||||
key: "refresh_interval",
|
||||
displayName: "刷新间隔",
|
||||
defaultValue: 60,
|
||||
minimum: 10, // 最小值
|
||||
maximum: 3600, // 最大值
|
||||
increment: 10 // 步进值
|
||||
)
|
||||
```
|
||||
|
||||
#### Select（选择）
|
||||
|
||||
```csharp
|
||||
.AddSelect(
|
||||
key: "display_mode",
|
||||
displayName: "显示模式",
|
||||
choices: new[]
|
||||
{
|
||||
new SettingsOptionChoice("compact", "紧凑"),
|
||||
new SettingsOptionChoice("normal", "标准"),
|
||||
new SettingsOptionChoice("detailed", "详细")
|
||||
},
|
||||
defaultValue: "normal"
|
||||
)
|
||||
```
|
||||
|
||||
#### Path（路径）
|
||||
|
||||
```csharp
|
||||
.AddPath(
|
||||
key: "save_location",
|
||||
displayName: "保存位置",
|
||||
defaultValue: "",
|
||||
pathType: SettingsPathType.Folder, // Folder 或 File
|
||||
dialogTitle: "选择保存文件夹"
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 自定义设置页
|
||||
|
||||
当声明式设置无法满足需求时，可以创建自定义设置页面。
|
||||
|
||||
### 步骤 1：创建设置页类
|
||||
|
||||
```csharp
|
||||
using LanMountainDesktop.PluginSdk;
|
||||
using FluentAvalonia.UI.Controls;
|
||||
|
||||
namespace MyPlugin;
|
||||
|
||||
public class MySettingsPage : SettingsPageBase
|
||||
{
|
||||
private readonly IPluginSettingsService _settingsService;
|
||||
|
||||
public MySettingsPage(IPluginSettingsService settingsService)
|
||||
{
|
||||
_settingsService = settingsService;
|
||||
InitializeComponent();
|
||||
}
|
||||
|
||||
private void InitializeComponent()
|
||||
{
|
||||
// 创建页面内容
|
||||
var panel = new StackPanel { Spacing = 16 };
|
||||
|
||||
// 添加自定义控件
|
||||
var expander = new SettingsExpander
|
||||
{
|
||||
Header = "高级设置",
|
||||
Description = "配置插件的高级选项"
|
||||
};
|
||||
|
||||
var toggle = new ToggleSwitch
|
||||
{
|
||||
Content = "启用实验性功能"
|
||||
};
|
||||
|
||||
expander.Items.Add(toggle);
|
||||
panel.Children.Add(expander);
|
||||
|
||||
// 添加颜色选择器示例
|
||||
var colorPicker = new ColorPicker
|
||||
{
|
||||
Header = "主题颜色"
|
||||
};
|
||||
panel.Children.Add(colorPicker);
|
||||
|
||||
Content = panel;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 步骤 2：注册自定义设置页
|
||||
|
||||
```csharp
|
||||
public override void Initialize(HostBuilderContext context, IServiceCollection services)
|
||||
{
|
||||
services.AddPluginSettingsSection<MySettingsPage>(
|
||||
sectionId: "myplugin-advanced",
|
||||
displayName: "高级设置",
|
||||
iconKey: "Settings");
|
||||
}
|
||||
```
|
||||
|
||||
### 混合模式
|
||||
|
||||
可以同时使用声明式设置和自定义视图：
|
||||
|
||||
```csharp
|
||||
services.AddPluginSettingsSection(
|
||||
sectionId: "myplugin-settings",
|
||||
displayName: "插件设置",
|
||||
configure: section => section
|
||||
.SetCustomView<MyCustomSettingsPage>() // 设置自定义视图
|
||||
.AddToggle("enabled", "启用") // 同时声明设置项
|
||||
.AddText("api_key", "API密钥"),
|
||||
iconKey: "Settings");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💾 读取和保存设置
|
||||
|
||||
### 在服务中读取设置
|
||||
|
||||
```csharp
|
||||
public class WeatherService
|
||||
{
|
||||
private readonly IPluginSettingsService _settings;
|
||||
|
||||
public WeatherService(IPluginSettingsService settings)
|
||||
{
|
||||
_settings = settings;
|
||||
|
||||
// 读取设置
|
||||
var apiKey = _settings.GetValue<string>("api_key", "");
|
||||
var autoRefresh = _settings.GetValue<bool>("auto_update", true);
|
||||
var interval = _settings.GetValue<int>("refresh_interval", 60);
|
||||
|
||||
// 监听设置变化
|
||||
_settings.SettingsChanged += (sender, e) =>
|
||||
{
|
||||
if (e.Key == "refresh_interval")
|
||||
{
|
||||
UpdateTimerInterval(e.NewValue);
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 在组件中读取设置
|
||||
|
||||
```csharp
|
||||
public class WeatherWidget : Border
|
||||
{
|
||||
public WeatherWidget(PluginDesktopComponentContext context)
|
||||
{
|
||||
// 通过 context 获取设置
|
||||
var settings = context.Settings;
|
||||
|
||||
var city = settings.GetValue<string>("city", "北京");
|
||||
var unit = settings.GetValue<string>("temperature_unit", "celsius");
|
||||
|
||||
// 监听设置变化
|
||||
context.Settings.SettingsChanged += (_, e) =>
|
||||
{
|
||||
if (e.Key == "city")
|
||||
{
|
||||
RefreshWeather(e.NewValue);
|
||||
}
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 保存设置
|
||||
|
||||
```csharp
|
||||
// 在设置页面中保存
|
||||
private void SaveButton_Click(object? sender, RoutedEventArgs e)
|
||||
{
|
||||
_settingsService.SetValue("api_key", ApiKeyTextBox.Text);
|
||||
_settingsService.SetValue("auto_update", AutoUpdateToggle.IsChecked ?? false);
|
||||
|
||||
// 设置会自动持久化，无需手动保存文件
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔔 设置变更通知
|
||||
|
||||
### 订阅变更事件
|
||||
|
||||
```csharp
|
||||
public class MyService
|
||||
{
|
||||
public MyService(IPluginSettingsService settings)
|
||||
{
|
||||
settings.SettingsChanged += OnSettingsChanged;
|
||||
}
|
||||
|
||||
private void OnSettingsChanged(object? sender, SettingsChangedEvent e)
|
||||
{
|
||||
Console.WriteLine($"设置变更: {e.Key}");
|
||||
Console.WriteLine($"旧值: {e.OldValue}");
|
||||
Console.WriteLine($"新值: {e.NewValue}");
|
||||
|
||||
// 根据变更的键执行相应操作
|
||||
switch (e.Key)
|
||||
{
|
||||
case "refresh_interval":
|
||||
UpdateRefreshTimer((int)e.NewValue);
|
||||
break;
|
||||
case "theme":
|
||||
ApplyTheme((string)e.NewValue);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### 问题 1：设置不保存
|
||||
|
||||
**排查：**
|
||||
1. 确认 `sectionId` 唯一且合法
|
||||
2. 检查设置键名是否正确
|
||||
3. 查看日志是否有权限错误
|
||||
|
||||
### 问题 2：设置页面不显示
|
||||
|
||||
**排查：**
|
||||
1. 确认已调用 `AddPluginSettingsSection`
|
||||
2. 检查 `sectionId` 是否唯一
|
||||
3. 确认设置页类是 `public`
|
||||
|
||||
### 问题 3：设置变更通知不触发
|
||||
|
||||
**原因：** 可能订阅的是不同实例
|
||||
|
||||
**解决：** 确保使用注入的 `IPluginSettingsService`
|
||||
|
||||
---
|
||||
|
||||
## 📚 参考资源
|
||||
|
||||
- [IPluginSettingsService 源码](../../LanMountainDesktop.PluginSdk/IPluginSettingsService.cs)
|
||||
- [SettingsPageBase 源码](../../LanMountainDesktop.PluginSdk/SettingsPageBase.cs)
|
||||
- [04-开发设置页面](../04-实战案例/04-开发设置页面.md)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
学习外观系统：
|
||||
|
||||
👉 **[04-外观与主题系统](04-外观与主题系统.md)** - 适配宿主主题
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026年4月*
|
||||
Reference in New Issue
Block a user