designing-avalonia-customcontrol-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

6.5 Writing AXAML Code

6.5 编写AXAML代码

When generating AXAML code, use CustomControl with ControlTheme for Stand-Alone Control Style
Purpose: Theme separation and minimizing style dependencies

生成AXAML代码时，使用带ControlTheme的CustomControl来实现独立控件样式
目的：主题分离并最小化样式依赖

6.5.1 AvaloniaUI Custom Control Library Project Structure

6.5.1 AvaloniaUI自定义控件库项目结构

Recommended Project Structure:

YourAvaloniaSolution
├── YourCustomControlProject1/
│    ├── Properties/
│    │   ├── AssemblyInfo.cs            ← AssemblyInfo.cs definition
│    ├── Themes/
│    │   ├── Generic.axaml            ← ControlTheme definition
│    │   ├── CustomButton1.axaml       ← Individual control theme
│    │   └── CustomTextBox1.axaml      ← Individual control theme
│    ├── CustomButton1.cs
│    └── CustomTextBox1.cs
└── YourCustomControlProject2/
    ├── Properties/
    │   ├── AssemblyInfo.cs            ← AssemblyInfo.cs definition
    ├── Themes/
    │   ├── Generic.axaml            ← ControlTheme definition
    │   ├── CustomButton2.axaml       ← Individual control theme
    │   └── CustomTextBox2.axaml      ← Individual control theme
    ├── CustomButton2.cs
    └── CustomTextBox2.cs

推荐项目结构：

YourAvaloniaSolution
├── YourCustomControlProject1/
│    ├── Properties/
│    │   ├── AssemblyInfo.cs            ← AssemblyInfo.cs 定义
│    ├── Themes/
│    │   ├── Generic.axaml            ← ControlTheme 定义
│    │   ├── CustomButton1.axaml       ← 独立控件主题
│    │   └── CustomTextBox1.axaml      ← 独立控件主题
│    ├── CustomButton1.cs
│    └── CustomTextBox1.cs
└── YourCustomControlProject2/
    ├── Properties/
    │   ├── AssemblyInfo.cs            ← AssemblyInfo.cs 定义
    ├── Themes/
    │   ├── Generic.axaml            ← ControlTheme 定义
    │   ├── CustomButton2.axaml       ← 独立控件主题
    │   └── CustomTextBox2.axaml      ← 独立控件主题
    ├── CustomButton2.cs
    └── CustomTextBox2.cs

6.6 ⚠️ Distinguishing ResourceInclude vs MergeResourceInclude

6.6 ⚠️ 区分ResourceInclude与MergeResourceInclude

ResourceInclude: Used in regular ResourceDictionary files (Generic.axaml, Styles, etc.)
MergeResourceInclude: Used only in Application.Resources (App.axaml)

Advantages:

Complete separation of theme and logic based on ControlTheme
Flexible style variations through CSS Classes
State management via Pseudo Classes (:pointerover, :pressed, etc.)
Theme modularization through ResourceInclude
Work can be split by file for team collaboration

ResourceInclude：用于常规ResourceDictionary文件（Generic.axaml、Styles等）
MergeResourceInclude：仅用于Application.Resources（App.axaml）

优势：

基于ControlTheme实现主题与逻辑的完全分离
通过CSS类实现灵活的样式变体
通过伪类（:pointerover、:pressed等）管理状态
通过ResourceInclude实现主题模块化
可按文件拆分工作以实现团队协作

6.5.2 Key Differences Between WPF and AvaloniaUI

6.5.2 WPF与AvaloniaUI的关键差异

Item	WPF	AvaloniaUI
File Extension	.xaml	.axaml
Style Definition	Style + ControlTemplate	ControlTheme
State Management	Trigger, DataTrigger	Pseudo Classes, Style Selector
CSS Support	❌	✅ (Classes attribute)
Resource Merging	MergedDictionaries + ResourceDictionary	MergedDictionaries + ResourceInclude
Dependency Props	DependencyProperty	StyledProperty, DirectProperty

项目	WPF	AvaloniaUI
文件扩展名	.xaml	.axaml
样式定义方式	Style + ControlTemplate	ControlTheme
状态管理方式	Trigger、DataTrigger	伪类、样式选择器
CSS支持	❌	✅（Classes属性）
资源合并方式	MergedDictionaries + ResourceDictionary	MergedDictionaries + ResourceInclude
依赖属性	DependencyProperty	StyledProperty、DirectProperty