LanMountainDesktop/docs/archive/Plugins develop/02-核心概念与原理/03-设置系统集成.md

03-设置系统集成

设置系统允许插件在阑山桌面的设置窗口中添加自己的配置页面，让用户可以自定义插件行为。

---

🎯 设置系统概述

阑山桌面提供两种设置页面模式：

模式	适用场景	复杂度	灵活性
声明式设置	简单的键值配置	低	中
自定义设置页	复杂交互、自定义控件	中	高

---

📝 声明式设置

通过链式 API 声明配置项，宿主自动生成设置页面。

基本用法

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（开关）

.AddToggle(
    key: "auto_update",           // 设置键
    displayName: "自动更新",      // 显示名称
    defaultValue: true,           // 默认值
    description: "启动时检查更新"   // 可选描述
)

Text（文本）

.AddText(
    key: "api_key",
    displayName: "API密钥",
    defaultValue: "",
    placeholder: "请输入API密钥",   // 占位符
    isPassword: true               // 密码输入（掩码显示）
)

Number（数值）

.AddNumber(
    key: "refresh_interval",
    displayName: "刷新间隔",
    defaultValue: 60,
    minimum: 10,                  // 最小值
    maximum: 3600,                // 最大值
    increment: 10                 // 步进值
)

Select（选择）

.AddSelect(
    key: "display_mode",
    displayName: "显示模式",
    choices: new[]
    {
        new SettingsOptionChoice("compact", "紧凑"),
        new SettingsOptionChoice("normal", "标准"),
        new SettingsOptionChoice("detailed", "详细")
    },
    defaultValue: "normal"
)

Path（路径）

.AddPath(
    key: "save_location",
    displayName: "保存位置",
    defaultValue: "",
    pathType: SettingsPathType.Folder,  // Folder 或 File
    dialogTitle: "选择保存文件夹"
)

---

🎨 自定义设置页

当声明式设置无法满足需求时，可以创建自定义设置页面。

步骤 1：创建设置页类

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：注册自定义设置页

public override void Initialize(HostBuilderContext context, IServiceCollection services)
{
    services.AddPluginSettingsSection<MySettingsPage>(
        sectionId: "myplugin-advanced",
        displayName: "高级设置",
        iconKey: "Settings");
}

混合模式

可以同时使用声明式设置和自定义视图：

services.AddPluginSettingsSection(
    sectionId: "myplugin-settings",
    displayName: "插件设置",
    configure: section => section
        .SetCustomView<MyCustomSettingsPage>()  // 设置自定义视图
        .AddToggle("enabled", "启用")            // 同时声明设置项
        .AddText("api_key", "API密钥"),
    iconKey: "Settings");

---

💾 读取和保存设置

在服务中读取设置

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);
            }
        };
    }
}

在组件中读取设置

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);
            }
        };
    }
}

保存设置

// 在设置页面中保存
private void SaveButton_Click(object? sender, RoutedEventArgs e)
{
    _settingsService.SetValue("api_key", ApiKeyTextBox.Text);
    _settingsService.SetValue("auto_update", AutoUpdateToggle.IsChecked ?? false);
    
    // 设置会自动持久化，无需手动保存文件
}

---

🔔 设置变更通知

订阅变更事件

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 源码
• SettingsPageBase 源码
• 04-开发设置页面

---

🎯 下一步

学习外观系统：

👉 04-外观与主题系统 - 适配宿主主题

---

最后更新：2026年4月