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 设置类，再注册对应的设置控件。 完成前 对当前改动的文件，运行最小且相关的格式化 / 构建 / 测试命令。