设置系统实现总结

May 31, 2025 · View on GitHub

概述

成功实现了完整的泛型设置管理系统，参考 Microsoft TemplateStudio 的 WinUI 项目模板设计。系统采用分层架构，Core 项目提供跨平台接口和默认实现，WinUI 项目提供 Windows 平台特有的实现。

已完成的功能

1. 核心接口和模型 (XiaoZhi.Core)

ISettingsService 泛型接口

  • Task<T> LoadSettingsAsync() - 异步加载设置
  • Task SaveSettingsAsync(T settings) - 异步保存设置
  • Task<bool> ExportSettingsAsync(string filePath, T settings) - 导出设置到文件
  • Task<T?> ImportSettingsAsync(string filePath) - 从文件导入设置
  • Task ResetToDefaultAsync() - 重置为默认设置
  • T GetCurrentSettings() - 获取当前设置（同步方法）
  • event EventHandler<T>? SettingsChanged - 设置变化事件

AppSettings 模型类

包含所有应用设置属性：

  • 唤醒词设置: WakeWordEnabled, WakeWords
  • 设备设置: DeviceId
  • 服务器设置: WsAddress, WsToken
  • 音频设置: DefaultVolume, AutoAdjustVolume, AudioInputDevice, AudioOutputDevice
  • 应用设置: AutoStart, MinimizeToTray, EnableLogging
  • 高级设置: ConnectionTimeout, AudioSampleRate, AudioChannels

包含验证逻辑和默认值设置。

2. 跨平台默认实现 (XiaoZhi.Core)

FileBasedSettingsService

  • 基于文件系统的跨平台实现
  • 使用 JSON 序列化/反序列化
  • 支持自定义配置文件路径
  • 包含完整的错误处理和日志记录

3. Windows 平台特有实现 (XiaoZhi.WinUI)

WindowsSettingsService

  • 使用 Windows ApplicationData 进行本地存储
  • 集成 Windows 文件选择器用于导入/导出
  • 支持 WinUI 平台特有的文件操作
  • 完整的异常处理和日志记录

4. 依赖注入配置

App.xaml.cs 配置

services.AddSingleton<ISettingsService<AppSettings>, WindowsSettingsService<AppSettings>>();

5. UI 集成 (SettingsPage)

完整的设置页面功能

  • 加载设置: 从设置服务加载配置并更新UI
  • 保存设置: 收集UI输入并通过设置服务保存
  • 导出设置: 使用 Windows 文件选择器导出JSON配置文件
  • 导入设置: 从JSON文件导入配置并更新UI
  • 重置设置: 恢复所有设置为默认值
  • 实时同步: UI控件变化时实时保存到本地设置

错误处理和用户反馈

  • 完整的异常处理机制
  • 用户友好的错误对话框
  • 操作成功确认提示

技术特点

1. 泛型设计

  • 使用泛型接口支持任意设置类型
  • 类型安全的设置操作
  • 可扩展到其他设置类型

2. 平台适配

  • Core 项目提供跨平台默认实现
  • WinUI 项目提供 Windows 优化实现
  • 遵循 .NET 平台最佳实践

3. JSON 序列化

  • 人类可读的配置文件格式
  • 支持注释和格式化
  • 版本兼容性友好

4. 事件驱动

  • 设置变化事件通知
  • 支持响应式UI更新
  • 解耦的组件通信

项目状态

✅ 已完成

  1. 核心接口和模型定义
  2. 跨平台默认实现
  3. Windows 平台特有实现
  4. 依赖注入配置
  5. SettingsPage UI 集成
  6. 错误处理和日志记录
  7. 项目编译成功

🧪 需要测试

  1. 设置加载功能 - 验证应用启动时正确加载设置
  2. 设置保存功能 - 验证UI变化后设置正确保存
  3. 导出功能 - 测试JSON文件导出和文件选择器
  4. 导入功能 - 测试从JSON文件导入设置
  5. 重置功能 - 验证重置到默认值功能
  6. 错误处理 - 测试各种错误场景的处理
  7. UI同步 - 验证设置与UI控件的双向绑定

📝 已知问题

  1. IDE 类型解析 - VS Code 编辑器显示跨项目类型引用错误，但编译成功
  2. 未使用字段警告 - HomePage 中有未使用的字段警告（与设置系统无关）

使用方法

1. 注入设置服务

private readonly ISettingsService<AppSettings>? _settingsService;

public SettingsPage()
{
    _settingsService = App.GetService<ISettingsService<AppSettings>>();
}

2. 加载设置

var settings = await _settingsService.LoadSettingsAsync();

3. 保存设置

await _settingsService.SaveSettingsAsync(settings);

4. 导出设置

var success = await _settingsService.ExportSettingsAsync(filePath, settings);

5. 导入设置

var importedSettings = await _settingsService.ImportSettingsAsync(filePath);

6. 重置设置

await _settingsService.ResetToDefaultAsync();

架构优势

  1. 模块化设计 - 核心逻辑与平台实现分离
  2. 可测试性 - 接口驱动设计便于单元测试
  3. 可扩展性 - 泛型设计支持多种设置类型
  4. 平台优化 - 每个平台使用最适合的存储机制
  5. 类型安全 - 编译时类型检查避免运行时错误

下一步计划

  1. 端到端测试 - 全面测试所有设置功能
  2. 性能优化 - 优化大型设置文件的处理
  3. 本地化支持 - 添加多语言错误消息
  4. 单元测试 - 为所有组件添加单元测试
  5. 文档完善 - 添加开发者文档和使用示例