code-style

name	code-style
description	工程代码编写风格指引（不含简单的格式化风格）

Pixeval 代码风格

• 在重构代码时，不要被既有模式束缚住，直接重构为更合理、更高效的实现。
• 修改代码时，不要作打补丁式的临时修改，并且不要留下兼容代码或过渡方案，避免新旧逻辑混杂。
• 在关键处留下注释以表达意图。
• 优先复用现有包和辅助项目、工具类，避免重复造轮子，优先复用 Pixeval.Utilities 或本项目里已经有的辅助函数和扩展，例如 SelectNotNull、PickMax/PickClosest、FileHelper、MakoHelper 和缓存辅助方法。
• 保持代码可 AOT 编译，避免使用反射、动态代码，但是若可以用 [DynamicallyAccessedMembers] 避免反射失败则可以使用。
• 对于相近功能的模型，通过继承、接口、组合等方式复用代码，避免重复代码。
• 可观测属性优先使用 CommunityToolkit 的 [ObservableProperty] 生成器，并附在部分属性上而不是字段上来生成。
• 对于难以处理的异常，可以使用 App.AppViewModel.AppServiceProvider.GetRequiredService<FileLogger>() 记录日志，但若频繁抛出的异常（如 OperationCanceledException、TaskCanceledException等）则不记录。

文件夹结构

• AppManagement：应用状态和生命周期管理。
• Controls：模板控件或控件样式，模板控件继承 TemplatedControl，成对的文件命名也使用 .axaml 和 .axaml.cs；资源字典要在 Themes/Controls.axaml 里引用。
• Utilities：辅助函数和扩展方法。
• Views：普通的用户控件，包括页面等。
• ViewModels：视图模型。
• Models：数据模型。
• i18n：国际化字符串资源。

其他

Avalonia XAML

• 打开浏览器、复制文本使用 AvaloniaHelper 里封装好的静态属性，参数通过 Tag 属性指定。
• 通过现有 {I18N ...} 标记扩展指定本地化字符串。
• 复用主题资源，例如 ControlCornerRadius、TextFillColorSecondaryBrush、SystemAccentColor 等。不要在资源字典外硬编码颜色。
• 对来自 URL 或可缓存源的图片加载，优先使用已有附加属性，例如 controls:Source.Cache，而不是直接设置 Image.Source。
• 优先复用现有的 Views.Converters、Views.Markup、Utilities 里已有的转换器和标记扩展，不要临时在 code-behind 里手写格式化。

国际化字符串管理

• 主项目 UI 中禁止出现硬编码的字符串（除非不需要翻译的名字、专有名词），所有用户可见的字符串都必须通过资源管理。
• 字符串资源在 i18n 文件夹里以语言划分，包含 JSON 文件和 Markdown 文件两种形式。
• 编辑完字符串资源后，运行 i18n/Language.tt 来生成对应的 Language.cs，不要手动编辑这个文件。
• C# 文件中，使用 I18NManager.GetResource(XXXResources.XXX) 来获取字符串。禁止直接使用常量字符串： I18NManager.GetResource("XXXResources.XXX")。
• XAML 文件中，使用 {I18N {x:Static xxx:XXXResources.XXX}} 标记扩展来获取字符串。禁止直接使用常量字符串： {I18N XXXResources.XXX}。
• 对于自定义枚举，若要给每个枚举值指定一个对应的字符串资源（来给ComboBox等控件使用），则遵循以下步骤：
  • 先在 i18n/xx-XX/Enum.json 中定义枚举值对应的字符串资源，并生成 Language.cs。
  • 若是项目内定义的枚举，在枚举上提供 [LocalizationMetadata]，并在每个枚举值上提供 [LocalizedResource(EnumResources.XXX)] 来指定资源键，也可以通过 [LocalizedResource(Resource = "XXX")] 直接指定本地化字符串的值，在使用不需要翻译的专有英文名词时会用到（如 "http"）。
  • 若是外部库的枚举，则在 Models/Settings/LocalSettingsEntryHelper.cs 的静态构造函数里指定映射，参考已有示例即可。

添加设置项

• 设置页应优先使用现有的设置生成器，而不是直接手写。大致流程是：
  • 先在 AppManagement/AppSettings.cs 中添加一个新的可读可写属性，若有必要可指定默认值。
  • 在 i18n/xx-XX/AppSettings.json 中添加这个设置项的名称和描述资源，并生成 Language.cs。
  • 给这个属性添加一个 [SettingsEntry]，指定设置图标（Icon）、标题（Header）资源和描述（Description）资源，还可以指定占位符（Placeholder）资源。
  • 在 ViewModels/SettingsPageViewModel.cs 的 LocalGroups 属性中选择合适的设置组，注册设置项；若有必要可以指定 ValueChanged 回调或更多复杂的逻辑。
  • 若要实现特殊的设置项控件，需要在 Views/Settings 下实现一个 XXXSettingsCard 或 XXXSettingsExpander，继承于 IEntryControl<XXXSettingsEntry>；并在 Models/Settings/LocalSettingsEntryHelper.cs 静态构造函数里注册设置项对应的控件类型。
  • 如果要实现出了基元和数组类型外的设置项，需要在 Models\Settings\Entries 下实现一个 XXXSettingsEntry 设置类，再注册对应的设置控件。

完成前

• 对当前改动的文件，运行最小且相关的格式化 / 构建 / 测试命令。