main

Author: sharpchen

docs/components/Copyright.vue

@@ -5,9 +5,6 @@
         <br />
         Powered by
         <a class="bold" target="_blank" href="//vitepress.vuejs.org/">VitePress - {{ vitepressVersion }}</a>
-        <!-- <br />
-        Markdown Themed by
-        <a class="bold" target="_blank" href="https://github.com/fisheva/Eva-Theme">Eva-Theme@fisheva</a> -->
     </div>
 </template>
 

docs/document/Skill/Avalonia/docs/1. Fundamentals/2. XAML Essentials.md

@@ -1,50 +1,145 @@
 # XAML Essentials
 
-## Importing a namespace
+Each tag in XAML file is of `AvaloniaObject`, it can be of `Control` or something else but inherits from `AvaloniaObject`.
 
-The semantic of `xmlns:x` basically means importing a namespace as an alias named `x`.
-Then we can use `:` to access the members of the namespace.
-`x:Class` binds the code behind(`.axaml.cs`) the AXAML(not the ViewModel!).
+::: code-group
 
-```xml
+```xml [App.axaml]
+<!-- Application is AvaloniaObject but not a Control --> <!-- [!code highlight] -->
 <Application xmlns="https://github.com/avaloniaui"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
-             x:Class="AvaloniaApplication.App"
-             xmlns:local="using:AvaloniaApplication"
+             x:Class="MyApp.App"
+             xmlns:local="using:MyApp"
              RequestedThemeVariant="Default">
-             <!-- "Default" ThemeVariant follows system theme variant. "Dark" or "Light" are other available options. -->
+    <Application.DataTemplates>
+        <local:ViewLocator/>
+    </Application.DataTemplates>
+    <Application.Styles>
+        <FluentTheme />
+    </Application.Styles>
 </Application>
 ```
+:::
+
+## XAML Namespace
 
-## Spreading Namespace
+XAML namespace was a feature inherited from xml, it allows to import namespaces at any level of element, and all of its child elements within the scope can access the namespace.
+A namespace follows syntax of `xmlns[:<alias>]`, where `<alias>` is available as identifier in scope, either **as attribute name or a interpolated uri using another namespace alias.**
 
-The default namespace is imported without name, which mean its members are imported globally in this AXAML file, can be accessed them without any prefix.
-Generally the default is avalonia namespace which contains built-in components like `Button`, `TextBlock`.
+> [!NOTE]
+> Namespace is **not order-sensitive**, they're structural.
 
 ```xml
-<Application xmlns="https://github.com/avaloniaui" <!-- [!code highlight] -->
-             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
-             x:Class="AvaloniaApplication.App"
-             xmlns:local="using:AvaloniaApplication"
-             RequestedThemeVariant="Default">
-             <!-- "Default" ThemeVariant follows system theme variant. "Dark" or "Light" are other available options. -->
-</Application>
+<MyElement xmlns:vm="using:MyApp.ViewModels"
+    x:DataType="vm:MainWindowViewModel"> <!-- use vm alias in another namespace --> <!-- [!code highlight] -->
+    <BarElement xmlns:BarElement="MyElement.BarElement" /> <!-- namespace can be imported in any level --> <!-- [!code highlight] -->
+</MyElement>
 ```
 
-## Import from Project Namespace
+### Default Namespace
 
-`using:<namespace>` imports the namespace from **specific project** with the alias name `local`
+Default namespace is a shorthand without alias name that emits members into current scope.
+The default namespace in xaml files is particularly a url, but compiler is not going to read any content of it, instead it's simply a unique identifier used as a key to a specific internal mapping.
 
 ```xml
-<Application xmlns="https://github.com/avaloniaui"
-             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
-             x:Class="AvaloniaApplication.App"
-             xmlns:local="using:AvaloniaApplication" <!-- [!code highlight] -->
-             RequestedThemeVariant="Default">
-             <!-- "Default" ThemeVariant follows system theme variant. "Dark" or "Light" are other available options. -->
+<Foo xmlns="https://github.com/avaloniaui" />
+```
 
-    <Application.DataTemplates>
-        <local:ViewLocator/> <!-- use `local` here to access types from it --> <!-- [!code highlight] -->
-    </Application.DataTemplates>
-</Application>
+### Conventional Namespaces
+
+- `xmlns:x`: a namespace of common XAML directives, see [XAML Directives](#xaml-directives)
+    ```xml
+    <Foo xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" />
+    ```
+- `xmlns:d`
+- `xmlns:vm`
+- `xmlns:mc`
+
+## XAML Directives
+
+`xmlns:x` contains common directives of XAML elements to bind special context for the xaml file, such its code-behind class and view model.
+Each child element within the scope can access it.
+
+- `x:Class`: the class of control presented as xaml element.
+- `x:DataType`: the `DataContext`(aka ViewModel in MVVM) for current control.
+- `x:Name`: name of the instance of control within the code-behind class.
+    - XAML compiler would generate an instance by that name for your code-behind class.
+    - avalonia has a `StyledElement.Name` property available, which is an equivalence of `x:Name`
+- `x:Static`: accessor for **static members in assembly**
+```xml
+ <Window.Resources>
+     <SolidColorBrush Color="{x:Static Colors.Aqua}"></SolidColorBrush> <!-- [!code highlight] -->
+ </Window.Resources>
+```
+- `x:Key`: similar to `x:Name` but for static identifier in resource dictionary
+
+::: code-group
+```xml [XAML]
+<Window xmlns="https://github.com/avaloniaui"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" <!-- [!code highlight] -->
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    xmlns:vm="using:MyApp.ViewModels"
+    mc:Ignorable="d" d:DesignWidth="800" d:DesignHeight="450"
+    x:Class="MyApp.Views.MainWindow" <!-- [!code highlight] -->
+    x:DataType="vm:MainWindowViewModel" <!-- [!code highlight] -->
+    Title="MyApp">
+
+    <StackPanel>
+        <TextBlock x:Name="MyTextBlock" /> <!-- [!code highlight] -->
+        <TextBlock Name="MyAnotherTextBlock" /> <!-- this is equivalent way to declare the field --> <!-- [!code highlight] -->
+    </StackPanel>
+</Window>
+```
+```cs [code-behind]
+using Avalonia.Controls;
+
+namespace MyApp.Views;
+public partial class MainWindow : Window {
+    public MainWindow() {
+        InitializeComponent();
+        // access the control instance declared in XAML
+        this.MyTextBlock.Text = nameof(MyTextBlock); // [!code highlight]
+        this.MyAnotherTextBlock.Text = nameof(MyAnotherTextBlock); // [!code highlight]
+    }
+}
 ```
+:::
+
+## Property Syntax
+
+A property can be assigned by **attribute syntax** or a nesting element(when the property is a structural element)
+
+```xml
+<MyWindow FooProperty="FooProperty"></MyWindow>
+<!-- equivalent to -->
+<MyWindow>
+    <MyWindow.FooProperty>FooProperty</MyWindow.FooProperty>
+</MyWindow>
+```
+
+## Implicit Bindings
+
+- `ContentControl.Content`: xaml compiler would recognize the first(and only allow one) element as the value of `Content`.
+- `ItemsControl.Items`
+
+> [!NOTE]
+> `ContentControl.Content` and `ItemsControl.Items` are all marked by `[Avalonia.Metadata.ContentAttribute]`
+>```cs
+>public class ContentControl
+>    : TemplatedControl,
+>      IContentControl,
+>      IContentPresenterHost {
+>    /** ... **/
+>    public static readonly StyledProperty<object?> ContentProperty =
+>        AvaloniaProperty.Register<ContentControl, object?>(nameof(Content));
+>
+>    [Content] // [!code highlight]
+>    [DependsOn(nameof(ContentTemplate))]
+>    public object? Content {
+>        get => GetValue(ContentProperty); // ContentProperty is of type AvaloniaProperty // [!code highlight]
+>        set => SetValue(ContentProperty, value);
+>    }
+>    /** ... **/
+>}
+>```