NavigationFrame.Avalonia 1.5.1

NavigationFrame.Avalonia

A flexible and powerful navigation framework for Avalonia UI that supports Layouts (similar to Blazor/ASP.NET Core), built-in Transitions, and MVVM-friendly lifecycle events.

Features

• Layout Support: Define common layouts (e.g., Master-Detail, Sidebar) and wrap your pages automatically.
• Navigation History: Built-in support for Back and Forward navigation stacks.
• Caching: Configurable page caching to preserve state.
• Transitions: A wide variety of built-in animations (Slide, DrillIn, Entrance, Zoom).
• MVVM Friendly: Lifecycle interfaces for both Views (IPageControl) and ViewModels (IPageContext).
• Async Navigation: Fully asynchronous navigation pipeline.

Getting Started

1. Add Resources

You must add the framework's resources to your App.axaml to ensure controls render correctly.

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

2. Implement IViewFactory

You need to tell the framework how to resolve your Views (Controls).

using NavigationFrame.Avalonia;
using Avalonia.Controls;

public class ViewFactory : IViewFactory
{
    public Control ResolveView(object key)
    {
        if (key is Type type)
        {
            var control = (Control)Activator.CreateInstance(type)!;
            control.DataContext = CreateViewModelForView(type);
            return control;
        }
        
        // Handle other key types or dependency injection here
        throw new ArgumentException($"Cannot resolve view for key {key}");
    }

    private object CreateViewModelForView(Type viewType)
    {
        // Use your DI container or create instance manually
        throw new NotImplementedException();
    }
}

3. Setup LayoutAwareFrame

Add the LayoutAwareFrame to your main window or view.

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

In your code-behind (or setup logic), initialize the dependencies:

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
        
        // 1. Setup Navigation Service
        var navService = new DefaultNavigationService();
        
        // 2. Setup View Factory
        var viewFactory = new ViewFactory(); // Your implementation
        
        // 3. Configure Frame, binding supported
        AppFrame.NavigationService = navService;
        AppFrame.ViewFactory = viewFactory;
        
        // 4. Navigate to Home
        AppFrame.NavigateAsync(typeof(HomePage));
    }
}

Usage

Navigation

Inject INavigationService into your ViewModels or access it from the Frame.

// Simple navigation
await _navService.NavigateAsync(typeof(DetailsPage));

// Navigation with Parameter
await _navService.NavigateAsync(typeof(DetailsPage), "MyParameter");

// Navigation with Transition
await _navService.NavigateAsync(typeof(DetailsPage), null, Transition.SlideFromRight);

// Go Back
await _navService.GoBackAsync();

Lifecycle Events

For ViewModels (IPageContext)

Implement IPageContext in your ViewModel to handle navigation events.

public class MyPageViewModel : IPageContext
{
    // Injected automatically
    // make sure you set the ViewModel as DataContext when ResolveView is called.
    public INavigationService NavigationService { get; set; } 

    // Load data here (already in background thread)
    public async Task OnNavigatingTo(PageNavigationArgs args)
    {
        if (args.Parameter is string id)
        {
             await LoadDataAsync(id);
        }
    }

    public Task<bool> OnNavigatingAway(PageNavigationArgs args)
    {
        // Return true to cancel navigation (e.g., unsaved changes)
        return Task.FromResult(false); 
    }
    
    public Task OnNavigatedAway(PageNavigationArgs args)
    {
        // Indicates that the page is no longer visible, useful to stop some background tasks.
        return Task.CompletedTask;
    }
    
    public void OnPageReleased()
    {
        // Final cleanup when removed from cache/stack
    }
}

For Views (IPageControl)

Implement IPageControl in your UserControl code-behind if you need UI-specific lifecycle events.

Layouts

Layouts allow you to define a common shell (like a header or sidebar) for multiple pages.

1. Create a Layout Control: Implement ILayoutControl.

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

    public void OnBodyChanged(Control currentBody)
    {
        // Optional: React to body change
    }
}

2. Assign Layout to Page:

   Option A: Attribute

   [LayoutContext(typeof(MainLayout))]
   public class HomePageViewModel : IPageContext { ... }
   

   Option B: Implement Interface

   public class HomePageViewModel : IPageContext 
   {
       public Type? GetLayoutContextType() => typeof(MainLayout);
       // ...
   }
   

Key Components

• LayoutAwareFrame: The core control handling navigation, history, and layouts.
• INavigationService: The interface used to request navigation.
• IViewFactory: The bridge between navigation keys (Types) and actual UI Controls.
• IPageContext: ViewModel interface for navigation lifecycle.
• ILayoutControl: Interface for creating Layout shells.

Contact

For questions or support, please reach out to richardplus@foxmail.com