Встроенное внедрение

Обзор примера

Как правило, приложение многоплатформенного пользовательского интерфейса приложений .NET (.NET MAUI) включает страницы, содержащие макеты, например макеты и макеты, содержащие представления, напримерGridButton. Страницы, макеты и представления являются производными от Element. Встроенное внедрение позволяет использовать любые элементы управления MAUI .NET, производные от Element использования в .NET для Android, .NET для iOS, .NET для Mac Catalyst и собственных приложений WinUI.

Процесс использования элемента управления MAUI .NET в собственном приложении выглядит следующим образом:

1. Создайте единый проект .NET MAUI, содержащий пользовательский интерфейс .NET MAUI и все зависимости. Дополнительные сведения см. в статье "Создание единого проекта .NET MAUI".
2. Создайте собственное приложение и включите в ней поддержку .NET MAUI. Дополнительные сведения см. в разделе "Включение поддержки MAUI для .NET".
3. Инициализация .NET MAUI в проекте собственного приложения. Дополнительные сведения см. в разделе Инициализация MAUI .NET.
4. Создайте пользовательский интерфейс .NET MAUI и преобразуйте его в соответствующий ToPlatformEmbedding собственный тип с помощью метода расширения. Дополнительные сведения см. в разделе "Использование элементов управления MAUI .NET".

Примечание.

При использовании встроенного внедрения подсистема привязки данных .NET MAUI по-прежнему работает. Однако навигация по страницам должна выполняться с помощью собственного API навигации.

Создание единого проекта .NET MAUI

Перед созданием собственного приложения, использующее элементы управления MAUI .NET, необходимо добавить проект приложения .NET MAUI в то же решение, что и проект библиотеки классов .NET MAUI, созданный ранее. Проект приложения .NET MAUI будет хранить пользовательский интерфейс, который вы планируете повторно использовать в собственном внедренном приложении. После добавления нового проекта приложения MAUI .NET в решение выполните следующие действия:

1. Удалите папку "Свойства" из проекта.

2. Удалите папку Platform из проекта.

3. Удалите папку Resources/AppIcon из проекта.

4. Удалите папку Resources/raw из проекта.

5. Удалите папку Resources/Splash из проекта.

6. AppShell Удалите класс из проекта.

7. Убедитесь, App что класс не задает MainPage свойство или переопределяет CreateWindow метод:

   public partial class App : Application
   {
       public App()
       {
           InitializeComponent();
       }
   }
   

8. MainPage Удалите класс из проекта.

9. Измените файл проекта таким образом, чтобы $(TargetFramework) свойство сборки было задано net9.0, и $(OutputType) свойство сборки удаляется:

   <PropertyGroup>
     <TargetFramework>net9.0</TargetFramework>
   
     <RootNamespace>MyMauiApp</RootNamespace>
     <UseMaui>true</UseMaui>
     <SingleProject>true</SingleProject>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
   
     ...
   </PropertyGroup>
   

   Внимание

   Убедитесь, что свойство сборки задано $(TargetFramework) , а не свойство сборки$(TargetFrameworks) .

10. MauiProgram В классе измените CreateMauiApp метод, чтобы принять универсальный TApp аргумент, и примите необязательный Action<MauiAppBuilder> аргумент, который вызывается перед возвратом метода. Кроме того, измените вызов на UseMauiApp<App> UseMauiEmbeddedApp<TApp>:

    public static class MauiProgram
    {
        // Create a MauiApp using the specified application.
        public static MauiApp CreateMauiApp<TApp>(Action<MauiAppBuilder>? additional = null) where TApp : App
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiEmbeddedApp<TApp>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                });
    
            #if DEBUG
                builder.Logging.AddDebug();
            #endif
    
            additional?.Invoke(builder);
    
            return builder.Build();
        }
    }
    

11. MauiProgram В классе добавьте перегрузкуCreateMauiApp, которая принимает необязательный Action<MauiAppBuilder> аргумент:

    public static class MauiProgram
    {
        ...
    
        // Create a MauiApp using the default application.
        public static MauiApp CreateMauiApp(Action<MauiAppBuilder>? additional = null) =>
            CreateMauiApp<App>(additional);
    }
    

Затем необходимо добавить необходимый пользовательский интерфейс .NET MAUI в проект, включая все зависимости и ресурсы, и убедиться, что проект выполняет сборку правильно.

Включение поддержки .NET MAUI

Чтобы использовать элементы управления .NET MAUI, производные от Element .NET для Android, .NET для iOS, .NET для Mac Catalyst или приложения WinUI, необходимо добавить собственный проект приложения в то же решение, что и проект библиотеки классов .NET MAUI, созданный ранее. Затем необходимо включить поддержку .NET MAUI в файле проекта собственного приложения, задав $(UseMaui) свойства true сборки $(MauiEnablePlatformUsings) в первом <PropertyGroup> узле в файле проекта:

<PropertyGroup>
    ...
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>

    <UseMaui>true</UseMaui>
    <MauiEnablePlatformUsings>true</MauiEnablePlatformUsings>  
</PropertyGroup>

Для приложений .NET для Mac Catalyst также необходимо задать $(SupportedOSPlatformVersion) для свойства сборки не менее 15.0:

<PropertyGroup>
    ...
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>

    <SupportedOSPlatformVersion>15.0</SupportedOSPlatformVersion>
    <UseMaui>true</UseMaui>
    <MauiEnablePlatformUsings>true</MauiEnablePlatformUsings>  
</PropertyGroup>

Для приложений WinUI также необходимо задать для свойства falseсборки $(EnableDefaultXamlItems) значение :

<PropertyGroup>
    ...
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>

    <UseMaui>true</UseMaui>
    <MauiEnablePlatformUsings>true</MauiEnablePlatformUsings>    
    <EnableDefaultXamlItems>false</EnableDefaultXamlItems>
</PropertyGroup>

Это приведет к остановке получения ошибок сборки о том, что InitializeComponent метод уже определен.

Затем добавьте $(PackageReference) элементы сборки Microsoft.Maui.Controls в файл проекта для пакета NuGet:

<ItemGroup>
    <PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
</ItemGroup>

Инициализация .NET MAUI

.NET MAUI необходимо инициализировать, прежде чем проект собственного приложения может создать элемент управления .NET MAUI. Выбор времени инициализации в первую очередь зависит от того, когда он наиболее удобно в потоке приложений, он может выполняться при запуске или непосредственно перед созданием элемента управления MAUI .NET. Описанный здесь подход заключается в инициализации .NET MAUI при создании начального пользовательского интерфейса приложения.

Внедрение может выполняться в контексте приложения или контексте окна, но для максимальной совместимости .NET MAUI она должна выполняться в контексте окна.

Контекст приложения

Встроенная внедрение может выполняться в контексте приложения, где собственное приложение не имеет знаний о окне. При таком подходе для инициализации внедрения машинного внедрения требуется:

• Создание объекта MauiApp.
• MauiContext Создайте объект из MauiApp объекта. Объект MauiContext будет использоваться для получения собственного представления из представления .NET MAUI.

В следующем примере показан такой подход:

var mauiApp = MauiProgram.CreateMauiApp();
var context = new MauiContext(mauiApp.Services); // Activity also needs passing on Android

Затем можно создать и преобразовать представление .NET MAUI в собственное представление с ToPlatformEmbedded помощью метода расширения, для которого требуется MauiContext объект в качестве аргумента.

Этот подход подходит для сценариев, когда машинное приложение должно внедрить простой пользовательский интерфейс .NET MAUI, но не требует доступа ко всем функциям MAUI .NET. Недостатком этого подхода является то, что средства, такие как горячая перезагрузка, и некоторые функции .NET MAUI не будут работать.

Совет

MauiApp Создание объекта при каждом внедрении представления MAUI .NET в собственном представлении не рекомендуется. Это может быть проблематично, если внедренные представления обращаются к свойству Application.Current . Вместо этого MauiApp объект можно создать как общий статический экземпляр:

public static class MyEmbeddedMauiApp
{
    static MauiApp? _shared;
    public static MauiApp Shared => _shared ??= MauiProgram.CreateMauiApp();
}

С помощью этого подхода можно создать экземпляр MauiApp объекта в начале жизненного цикла приложения, чтобы избежать небольшой задержки при первом внедрении представления MAUI .NET в приложение.

В Android фрагмент представляет часть пользовательского интерфейса в действии. В следующем примере кода показано, как инициализировать MAUI .NET в фрагменте:

using Android.Runtime;
using Android.Views;
using AndroidX.Navigation.Fragment;
using Microsoft.Maui.Controls.Embedding;
using Fragment = AndroidX.Fragment.App.Fragment;
using View = Android.Views.View;

namespace MyNativeEmbeddedApp.Droid;

[Register("com.companyname.nativeembeddingdemo." + nameof(FirstFragment))]
public class FirstFragment : Fragment
{
    public override View? OnCreateView(LayoutInflater inflater, ViewGroup? container, Bundle? savedInstanceState) =>
        inflater.Inflate(Resource.Layout.fragment_first, container, false);

    public override void OnViewCreated(View view, Bundle? savedInstanceState)
    {
        base.OnViewCreated(view, savedInstanceState);

        // Ensure .NET MAUI app is built before creating .NET MAUI views
        var mauiApp = MyEmbeddedMauiApp.Shared;

        // Create .NET MAUI context
        var context = new MauiContext(mauiApp.Services, Activity);

        ...
    }
}

В iOS и Mac Catalyst AppDelegate класс должен быть изменен для возврата true для FinishedLaunching переопределения:

namespace MyNativeEmbeddedApp.iOS;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override UIWindow? Window { get; set; }

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions) => true;
}

Затем WillConnect необходимо изменить метод в SceneDelegate классе, чтобы создать основной контроллер представления и задать его в качестве представления UINavigationController:

namespace MyNativeEmbeddedApp.iOS;

[Register("SceneDelegate")]
public class SceneDelegate : UIResponder, IUIWindowSceneDelegate
{
    [Export("window")]
    public UIWindow? Window { get; set; }

    [Export("scene:willConnectToSession:options:")]
    public void WillConnect(UIScene scene, UISceneSession session, UISceneConnectionOptions connectionOptions)
    {
        if (scene is not UIWindowScene windowScene)
            return;

        Window = new UIWindow(windowScene);

        var mainVC = new MainViewController();
        var navigationController = new UINavigationController(mainVC);
        navigationController.NavigationBar.PrefersLargeTitles = true;

        Window.RootViewController = navigationController;
        Window.MakeKeyAndVisible();
    }

    ...
}

Затем в редакторе XML откройте файл Info.plist и добавьте следующий XML-код в конец файла:

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneConfigurationName</key>
        <string>Default Configuration</string>
        <key>UISceneDelegateClassName</key>
        <string>SceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

Затем .NET MAUI можно инициализировать в методе в контроллере основного ViewDidLoad представления:

using Microsoft.Maui.Controls.Embedding;

namespace MyNativeEmbeddedApp.iOS;

public class MainViewController : UIViewController
{
    public override void ViewDidLoad()
    {
        base.ViewDidLoad();

        // Ensure .NET MAUI app is built before creating .NET MAUI views
        var mauiApp = MyEmbeddedMauiApp.Shared;

        // Create .NET MAUI context
        var context = new MauiContext(mauiApp.Services);

        ...
    }
}

В MainWindow Windows класс обычно является местом для выполнения задач запуска приложения, связанных с пользовательским интерфейсом:

using Microsoft.Maui.Controls.Embedding;
using Microsoft.UI.Xaml;

namespace MyNativeEmbeddedApp.WinUI;

public sealed partial class MainWindow : Microsoft.UI.Xaml.Window
{
    public MainWindow()
    {
        this.InitializeComponent();
    }

    private async void OnRootLayoutLoaded(object? sender, RoutedEventArgs e)
    {
        await Task.Yield();

        // Ensure .NET MAUI app is built before creating .NET MAUI views
        var mauiApp = MyEmbeddedMauiApp.Shared;

        // Create .NET MAUI context
        var context = new MauiContext(mauiApp.Services);

        ...
    }
}

В этом примере MauiApp объект создается как общий статический экземпляр. При создании этого объекта вызывается, MauiProgram.CreateMauiApp который в свою очередь вызывает UseMauiEmbedding метод расширения для MauiAppBuilder объекта. Таким образом, проект собственного приложения должен содержать ссылку на созданный проект библиотеки классов .NET MAUI, содержащий MauiProgram класс и пользовательский интерфейс .NET MAUI. Затем MauiContext объект создается из MauiApp объекта, который находится в MauiApp области объекта. Объект MauiContext будет использоваться при преобразовании элементов управления MAUI .NET в собственные типы.

Контекст окна

Встроенная внедрение может выполняться в контексте окна, где собственное приложение имеет знания о окне. В некоторых сценариях представления .NET MAUI требуют правильного доступа к окну. Например, адаптивные триггеры требуют доступа к окну представления и если нет окна, они не работают.

При таком подходе для инициализации внедрения машинного внедрения требуется:

• Создание объекта MauiApp.
• MauiContext Создайте объект с CreateEmbeddedWindowContext помощью метода. Объект MauiContext будет использоваться для получения собственного представления из представления .NET MAUI.

Метод CreateEmbeddedWindowContext создает контекст окна, связанный с собственным окном с окном .NET MAUI:

var mauiApp = MauiProgram.CreateMauiApp();
var context = mauiApp.CreateEmbeddedWindowContext(this);

Затем можно создать и преобразовать представление .NET MAUI в собственное представление с ToPlatformEmbedded помощью метода расширения, для которого требуется MauiContext объект в качестве аргумента.

Примечание.

Метод ToPlatformEmbedded расширения имеет перегрузку, которая добавляет представление MAUI .NET в внедренное окно.

Преимущество этого подхода заключается в том, что для каждого собственного окна существует одно окно .NET MAUI, связанные с окном API-интерфейсы, связанные с окном, будут работать правильно, и средства, такие как горячая перезагрузка работает правильно.

Совет

MauiApp Создание объекта при каждом внедрении представления MAUI .NET в собственном представлении не рекомендуется. Это может быть проблематично, если внедренные представления обращаются к свойству Application.Current . Вместо этого MauiApp объект можно создать как общий статический экземпляр:

public static class MyEmbeddedMauiApp
{
    static MauiApp? _shared;
    public static MauiApp Shared => _shared ??= MauiProgram.CreateMauiApp();
}

С помощью этого подхода можно создать экземпляр MauiApp объекта в начале жизненного цикла приложения, чтобы избежать небольшой задержки при первом внедрении представления MAUI .NET в приложение.

В Android фрагмент представляет часть пользовательского интерфейса в действии. В следующем примере кода показано, как инициализировать MAUI .NET в фрагменте:

using Android.Runtime;
using Android.Views;
using AndroidX.Navigation.Fragment;
using Microsoft.Maui.Controls.Embedding;
using Fragment = AndroidX.Fragment.App.Fragment;
using View = Android.Views.View;

namespace MyNativeEmbeddedApp.Droid;

[Register("com.companyname.nativeembeddingdemo." + nameof(FirstFragment))]
public class FirstFragment : Fragment
{
    Activity? _window;
    IMauiContext? _windowContext;

    public IMauiContext WindowContext =>
        _windowContext ??= MyEmbeddedMauiApp.Shared.CreateEmbeddedWindowContext(_window ?? throw new InvalidOperationException());

    public override View? OnCreateView(LayoutInflater inflater, ViewGroup? container, Bundle? savedInstanceState) =>
        inflater.Inflate(Resource.Layout.fragment_first, container, false);

    public override void OnViewCreated(View view, Bundle? savedInstanceState)
    {
        base.OnViewCreated(view, savedInstanceState);

        _window ??= Activity;

        // Create MAUI embedded window context
        var context = WindowContext;

        ...
    }
}

В iOS и Mac Catalyst AppDelegate класс должен быть изменен для возврата true для FinishedLaunching переопределения:

namespace MyNativeEmbeddedApp.iOS;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override UIWindow? Window { get; set; }

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions) => true;
}

Затем WillConnect необходимо изменить метод в SceneDelegate классе, чтобы создать основной контроллер представления и задать его в качестве представления UINavigationController:

namespace MyNativeEmbeddedApp.iOS;

[Register("SceneDelegate")]
public class SceneDelegate : UIResponder, IUIWindowSceneDelegate
{
    [Export("window")]
    public UIWindow? Window { get; set; }

    [Export("scene:willConnectToSession:options:")]
    public void WillConnect(UIScene scene, UISceneSession session, UISceneConnectionOptions connectionOptions)
    {
        if (scene is not UIWindowScene windowScene)
            return;

        Window = new UIWindow(windowScene);

        var mainVC = new MainViewController();
        var navigationController = new UINavigationController(mainVC);
        navigationController.NavigationBar.PrefersLargeTitles = true;

        Window.RootViewController = navigationController;
        Window.MakeKeyAndVisible();
    }

    ...
}

Затем в редакторе XML откройте файл Info.plist и добавьте следующий XML-код в конец файла:

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneConfigurationName</key>
        <string>Default Configuration</string>
        <key>UISceneDelegateClassName</key>
        <string>SceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

Затем .NET MAUI можно инициализировать в методе в контроллере основного ViewDidLoad представления:

using Microsoft.Maui.Controls.Embedding;

namespace MyNativeEmbeddedApp.iOS;

public class MainViewController : UIViewController
{
    UIKit.UIWindow? _window;
    IMauiContext? _windowContext;

    public IMauiContext WindowContext =>
        _windowContext ??= MyEmbeddedMauiApp.Shared.CreateEmbeddedWindowContext(_window ?? throw new InvalidOperationException());

    public override void ViewDidLoad()
    {
        base.ViewDidLoad();

        _window ??= ParentViewController!.View!.Window;

        // Create MAUI embedded window context
        var context = WindowContext;

        ...
    }
}

В MainWindow Windows класс обычно является местом для выполнения задач запуска приложения, связанных с пользовательским интерфейсом:

using Microsoft.Maui.Controls.Embedding;
using Microsoft.UI.Xaml;

namespace MyNativeEmbeddedApp.WinUI;

public sealed partial class MainWindow : Microsoft.UI.Xaml.Window
{
    Microsoft.UI.Xaml.Window? _window;
    IMauiContext? _windowContext;

    public IMauiContext WindowContext =>
        _windowContext ??= MyEmbeddedMauiApp.Shared.CreateEmbeddedWindowContext(_window ?? throw new InvalidOperationException());

    public MainWindow()
    {
        this.InitializeComponent();
        _window ??= this;
    }

    private async void OnRootLayoutLoaded(object? sender, RoutedEventArgs e)
    {
        await Task.Yield();

        // Create MAUI embedded window context
        var context = WindowContext;

        ...
    }
}

В этом примере MauiApp объект создается как общий статический экземпляр. При создании этого объекта вызывается, MauiProgram.CreateMauiApp который в свою очередь вызывает UseMauiEmbedding метод расширения для MauiAppBuilder объекта. Таким образом, проект собственного приложения должен содержать ссылку на созданный проект библиотеки классов .NET MAUI, содержащий MauiProgram класс и пользовательский интерфейс .NET MAUI. MauiContext Затем объект создается с CreateEmbeddedWindowContext помощью метода, область действия в окне. Объект MauiContext будет использоваться при преобразовании элементов управления MAUI .NET в собственные типы.

Использование элементов управления MAUI .NET

После инициализации .NET MAUI в собственном приложении вы можете добавить пользовательский интерфейс .NET MAUI в макет собственного приложения. Это можно сделать, создав экземпляр пользовательского интерфейса и преобразовав его в соответствующий собственный тип с ToPlatformEmbedded помощью метода расширения.

В ToPlatformEmbedded Android метод расширения преобразует элемент управления MAUI .NET в объект Android View :

var mauiView = new MyMauiContent();
Android.Views.View nativeView = mauiView.ToPlatformEmbedded(context);

В этом примере производный ContentViewобъект преобразуется в объект Android View .

Примечание.

Метод ToPlatformEmbedded расширения находится в Microsoft.Maui.Controls.Embedding пространстве имен. Поэтому проект собственного приложения должен содержать инструкцию using для этого пространства имен.

Затем View объект можно добавить в макет в собственном приложении:

rootLayout.AddView(nativeView, new LinearLayout.LayoutParams(MatchParent, WrapContent));

В iOS и Mac Catalyst ToPlatformEmbedded метод расширения преобразует элемент управления MAUI .NET в UIView объект:

var mauiView = new MyMauiContent();
UIView nativeView = mauiView.ToPlatformEmbedded(context);

В этом примере производный ContentViewобъект преобразуется в UIView объект.

Примечание.

Метод ToPlatformEmbedded расширения находится в Microsoft.Maui.Controls.Embedding пространстве имен. Поэтому проект собственного приложения должен содержать инструкцию using для этого пространства имен.

Затем UIView объект можно добавить в представление в контроллере представления:

stackView.AddArrangedSubView(new ContainerView(nativeView));

ContainerView — это пользовательский тип, который упаковывает представление MAUI .NET, чтобы обеспечить правильность его размера. Это достигается путем перенаправления IntrinsicContentSize в представление SizeThatFits.NET MAUI:

class ContainerView : UIView
{
    public ContainerView(UIView view)
    {
        AddSubview(view);
    }

    public override CGSize IntrinsicContentSize =>
        SizeThatFits(new CGSize(nfloat.MaxValue, nfloat.MaxValue));

    public override CGSize SizeThatFits(CGSize size) =>
        Subviews?.FirstOrDefault()?.SizeThatFits(size) ?? CGSize.Empty;

    public override void LayoutSubviews()
    {
        if (Subviews?.FirstOrDefault() is { } view)
            view.Frame = Bounds;
    }

    public override void SetNeedsLayout()
    {
        base.SetNeedsLayout();
          InvalidateIntrinsicContentSize();
    }
}

Кроме того, ToUIViewController метод расширения в .NET MAUI можно использовать для преобразования страницы UIViewControllerMAUI .NET в :

MyMauiPage myMauiPage = new MyMauiPage();
UIViewController myPageController = myMauiPage.ToUIViewController(context);

В этом примере производный ContentPageобъект преобразуется в объект UIViewController.

В ToPlatformEmbedded Windows метод расширения преобразует элемент управления MAUI .NET в FrameworkElement объект:

var mauiView = new MyMauiContent();
FrameworkElement nativeView = myMauiPage.ToPlatformEmbedded(context);

В этом примере производный ContentViewобъект преобразуется в FrameworkElement объект. Затем FrameworkElement объект можно задать как содержимое страницы WinUI.

Примечание.

Метод ToPlatformEmbedded расширения находится в Microsoft.Maui.Controls.Embedding пространстве имен. Поэтому проект собственного приложения должен содержать инструкцию using для этого пространства имен.

Затем FrameworkElement объект можно добавить в макет в собственном приложении:

stackPanel.Children.Add(nativeView);