NavigationFrame.Avalonia 1.7.0

NavigationFrame.Avalonia

A flexible and easy-to-use navigation framework for Avalonia applications, inspired by Blazor's layout system and modern navigation patterns.

Features

• Page Navigation: Navigate between pages with parameter passing.
• Layout System: Define layouts (e.g., MainLayout, AuthLayout) and apply them to pages using attributes.
• Navigation Stack: Built-in forward and back history stacks.
• Async Lifecycle: OnNavigatingTo, OnNavigatedTo, OnNavigatingAway, OnNavigatedAway lifecycle methods for ViewModels.
• Transitions: Support for custom page transitions (Slide, CrossFade, OverlaySlide).
• DI Support: Designed to work with Dependency Injection (using IViewFactory).

Getting Started

1. Installation

Add the NavigationFrame.Avalonia project to your solution and reference it.

2. Setup Services

Register the navigation services in your DI container (e.g., Microsoft.Extensions.DependencyInjection):

// Register the NavigationService
services.AddSingleton<INavigationService, DefaultNavigationService>();

// Register your ViewFactory (implement IViewFactory)
services.AddSingleton<IViewFactory, MyViewFactory>();

3. Implement IViewFactory

You need to implement IViewFactory to tell the framework how to resolve views (Controls) from navigation keys (strings/Types/viewmodel instance/any thing you like).

public class MyViewFactory : IViewFactory
{
    private readonly IServiceProvider _services;

    public MyViewFactory(IServiceProvider services)
    {
        _services = services;
    }

    public Control ResolveView(object key)
    {
        // Resolve view based on key (string or Type)
        // Ensure DataContext is set!
        if (key is Type type)
        {
             var view = (Control)Activator.CreateInstance(type)!;
             view.DataContext = _services.GetService(GetViewModelTypeFor(type));
             return view;
        }
        // ... handle string keys
        return new TextBlock { Text = "Not Found" };
    }
}

4. Add LayoutAwareFrame to your MainView

In your main window or view (e.g., MainView.axaml):

<UserControl xmlns:frame="using:NavigationFrame.Avalonia" ...>
    <frame:LayoutAwareFrame Name="FrameView"
                            NavigationService="{Binding NavigationService}"
                            ViewFactory="{Binding ViewFactory}" />
</UserControl>

Ensure your MainViewModel provides the NavigationService and ViewFactory.

5. Create Pages and ViewModels

Create your views (UserControls) and ViewModels. Optionally implement IPageContext in your ViewModel to handle navigation events.

public partial class HomeViewModel : ViewModelBase, IPageContext
{
    // you can cache this reference if you don't inject INavigationService to your PageViewModel, the instance exposes an INavigator
    public void OnInit(WeakReference<IPageHost> host) { }

    /// <summary>
    /// Called when the page is about to be navigated to. This is the best place to load data but don't 
    /// perform any UI operations in this method like setting data to an <see cref="ObservableCollection{T}"/>, cache the data in some fields and use them in <see cref="OnNavigatedTo"/>.
    /// </summary>
    /// <param name="args">The navigation arguments.</param>
    /// <returns>A task that completes when the initialization is done.</returns>
    public async Task OnNavigatingTo(NavigationArgs args)
    {
        // You are ready on a background thread
        if (args.Parameter is string userId)
        {
           _user = await LoadUserAsync(userId);
        }
    }

    public Task OnNavigatedTo(NavigationArgs args) => Task.CompletedTask;
    public Task<bool> OnNavigatingAway(NavigationArgs args) => Task.FromResult(false); // return true to cancel
    public Task OnNavigatedAway(NavigationArgs args) => Task.CompletedTask;
    public void OnPageReleased() { }
}

6. Navigation

Inject INavigationService into your ViewModels and use it to navigate.

public class MyViewModel
{
    private readonly INavigationService _navigationService;

    public MyViewModel(INavigationService navigationService)
    {
        _navigationService = navigationService;
    }

    public async Task GoToDetails()
    {
        await _navigationService.NavigateAsync(typeof(DetailsView), "some-parameter");
    }
}

Layouts

Layouts allow you to wrap your pages with a common UI structure. To use a layout, create a Layout View (e.g., MainLayout) that implements ILayoutControl and returns a LayoutBody. The LayoutBody is a placeholder where the page content will be placed.

public partial class MainLayout : UserControl, ILayoutControl
{
    public LayoutBody GetBodyHolder()
    {
        // Return the container where the page content should be placed
        return this.FindControl<LayoutBody>("Body"); 
    }
    
    // ...
}

Then apply the LayoutAttribute to your pages:

[Layout(typeof(MainLayout))]
public partial class HomePage : UserControl
{
    // ...
}

Transitions

You can specify transitions when navigating:

await _navigationService.NavigateAsync(
    NavigationOptions.SlideFromRight(typeof(DetailsView))
);