NavigationFrame.Avalonia 1.4.0

NavigationFrame.Avalonia

A flexible and layout-aware navigation framework for Avalonia UI, inspired by Blazor's layout system. It supports transition animations, navigation history, and MVVM patterns.

Features

• Layout Support: Define shared layouts (like Master/Detail, Shells) that wrap your pages.
• MVVM Ready: IPageContext and ILayoutContext interfaces for ViewModel integration.
• Navigation Stack: Built-in Forward/Back navigation history.
• Transitions: Built-in transition animations (Slide, DrillIn, Entrance, Suppress) and support for custom transitions.
• Navigation Awareness: Events for OnNavigatedTo, OnNavigatingAway (cancellable), and OnNavigatedAway.

Installation

Install the NuGet package:

dotnet add package NavigationFrame.Avalonia

Getting Started

1. Add Resources

In your App.axaml, add the required resources to Application.Resources:

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceInclude Source="avares://NavigationFrame.Avalonia/Styling/Resources.axaml" />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

2. Define a Layout (Optional)

Create a layout control by implementing ILayoutControl. This control acts as a wrapper for your pages.

View (MainLayout.axaml):

<UserControl xmlns="https://github.com/avaloniaui"
             x:Class="MyApp.Views.MainLayout">
    <DockPanel>
        <TextBlock Text="My App Header" DockPanel.Dock="Top"/>
        
        <ContentPresenter x:Name="BodyHolder" DockPanel.Dock="Bottom"/>
    </DockPanel>
</UserControl>

Code-behind (MainLayout.axaml.cs):

using Avalonia.Controls;
using NavigationFrame.Avalonia;

public partial class MainLayout : UserControl, ILayoutControl
{
    public MainLayout()
    {
        InitializeComponent();
    }

    public Control GetBodyHolder()
    {
        return this.FindControl<ContentPresenter>("BodyHolder")!;
    }

    public void OnBodyChanged(Control currentBody)
    {
        // Optional: React when the page changes
    }
}

ViewModel (MainLayoutViewModel.cs):

using NavigationFrame.Avalonia;

public class MainLayoutViewModel : ILayoutContext
{
    public INavigationService? NavigationService { get; set; }

    public void OnBodyChanged(IPageContext pageContext)
    {
        // Update title or other properties based on the current page
        Console.WriteLine($"Switched to page: {pageContext.Title}");
    }
}

3. Define a Page

Create a page and optionally link it to a layout.

View (HomePage.axaml):

<UserControl xmlns="https://github.com/avaloniaui"
             x:Class="MyApp.Views.HomePage">
    <StackPanel>
        <TextBlock Text="Welcome to Home Page!" />
        <Button Content="Go to Settings" Command="{Binding GoSettingsCommand}" />
    </StackPanel>
</UserControl>

ViewModel (HomePageViewModel.cs):

using CommunityToolkit.Mvvm.Input; // Example
using NavigationFrame.Avalonia;

// Link this page to MainLayoutViewModel
[LayoutContext(typeof(MainLayoutViewModel))] 
public partial class HomePageViewModel : IPageContext
{
    public INavigationService? NavigationService { get; set; }
    public string Title => "Home";

    [RelayCommand]
    private async Task GoSettings()
    {
        // Navigate to SettingsPageViewModel
        await NavigationService!.NavigateAsync(typeof(SettingsPageViewModel));
    }
}

4. Setup ViewFactory

You need an IViewFactory to resolve Views from ViewModels (or keys).

using Avalonia.Controls;
using NavigationFrame.Avalonia;

public class ViewFactory : IViewFactory
{
    public Control ResolveView(object obj)
    {
        // Simple example: mapping Types to Views
     
        if (obj is Type type)
        {
            if (type == typeof(HomePageViewModel)) return new HomePage();
            if (type == typeof(MainLayoutViewModel)) return new MainLayout();
            // ...
        }
        
        return new TextBlock { Text = "View Not Found" };
    }
}

5. Setup LayoutAwareFrame

In your main window or view, place the LayoutAwareFrame.

<Window xmlns:nav="using:NavigationFrame.Avalonia">
    <nav:LayoutAwareFrame x:Name="NavFrame" />
</Window>

Code-behind (MainWindow.axaml.cs):

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
        
        var frame = this.FindControl<LayoutAwareFrame>("NavFrame");
        frame.ViewFactory = new ViewFactory(); // Set your factory
        
        // Navigate to the initial page
        frame.NavigateAsync(typeof(HomePageViewModel));
    }
}

Navigation

• Navigate: NavigateAsync(object key, object? parameter = null)
• Go Back: GoBackAsync()
• Go Forward: GoForwardAsync()

Transitions

You can specify transitions during navigation:

await NavigationService.NavigateAsync(
    typeof(DetailsViewModel), 
    transition: Transition.DrillIn
);

Available transitions:

• SlideFromRight (Default)
• SlideFromLeft
• SlideFromTop
• SlideFromBottom
• DrillIn
• Entrance
• Suppress (No animation)

Lifecycle Events

Implement IPageContext in your ViewModel to handle lifecycle events:

• OnNavigatedTo(NavigationEventArgs e)
• OnNavigatingAway(NavigatingCancelEventArgs e): Can cancel navigation.
• OnNavigatedAway(NavigationEventArgs e)
• OnPageReleased(): Called when page is removed from history stack.