NavigationFrame.Avalonia 1.6.0

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)!;
            // Ensure DataContext is set!
            control.DataContext = CreateViewModelForView(type);
            return control;
        }
        
        // Handle other key types (e.g., strings) 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
        // e.g. return _serviceProvider.GetService(ViewModelTypeMap[viewType]);
        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
        navService.SetNavigator(AppFrame); // Link service to frame
        AppFrame.ViewFactory = viewFactory;
        
        // 4. Navigate to Home
        navService.NavigateAsync(new NavigationOptions(typeof(HomePage)));
    }
}

Usage

Navigation

Inject INavigator into your ViewModels.

// Simple navigation
await _navigator.NavigateAsync(new NavigationOptions(typeof(DetailsPage)));

// Navigation with Parameter
await _navigator.NavigateAsync(new NavigationOptions(typeof(DetailsPage), "MyParameter"));

// Navigation with Transition
await _navigator.NavigateAsync(new NavigationOptions(typeof(DetailsPage))
{
    TransitionInfo = new SlideTransitionInfo { Effect = SlideTransitionEffect.FromRight }
});

// Or use predefined helpers
await _navigator.NavigateAsync(NavigationOptions.SlideIn());

// Go Back
await _navigator.GoBackAsync();

Lifecycle Events

For ViewModels (IPageContext)

Implement IPageContext in your ViewModel to handle navigation events.

public class MyPageViewModel : IPageContext
{
    private WeakReference<IPageHost>? _host;

    // Accessed via property
    public INavigator NavigationService => _host?.TryGetTarget(out var host) == true ? host.Navigator : throw new Exception("Host released"); 

    public void OnInit(WeakReference<IPageHost> host)
    {
        _host = host;
    }
    
    public string Title => "My Page";

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

    public Task<bool> OnNavigatingAway(NavigationArgs args)
    {
        // Return true to cancel navigation (e.g., unsaved changes)
        return Task.FromResult(false); 
    }
    
    public Task OnNavigatedAway(NavigationArgs args)
    {
        // Indicates that the page is no longer visible.
        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:

   Use the [Layout] attribute on your View (UserControl) class.

   [Layout(typeof(MainLayout))]
   public partial class HomePage : UserControl
   {
       public HomePage()
       {
           InitializeComponent();
       }
   }
   

Key Components

• LayoutAwareFrame: The core control handling navigation, history, and layouts.
• INavigator: 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