Dostosowywanie kontrolek za pomocą programów obsługi

Przeglądanie przykładu

Obsługiwacze można dostosować, aby zwiększyć wygląd i zachowanie kontroli międzyplatformowej, wykraczając poza dostosowania możliwe za pośrednictwem interfejsu API kontrolki. To dostosowanie, które modyfikuje widoki natywne dla kontrolki międzyplatformowej, jest osiągane przez zmodyfikowanie mapera dla programu obsługi przy użyciu jednej z następujących metod:

• PrependToMapping, który modyfikuje maper programu obsługi przed zastosowaniem mapowań kontrolek .NET MAUI.
• ModifyMapping, który modyfikuje istniejące mapowanie.
• AppendToMapping, który modyfikuje maper programu obsługi po zastosowaniu mapowań kontrolek .NET MAUI.

Każda z tych metod ma identyczny podpis, który wymaga dwóch argumentów:

• Klucz oparty na string. Podczas modyfikowania jednego z mapowań dostarczonych przez program .NET MAUI należy określić klucz używany przez program .NET MAUI. Wartości kluczy używane przez mapowania kontrolek MAUI platformy .NET są oparte na nazwach interfejsów i właściwości, na przykład nameof(IEntry.IsPassword). Interfejsy, które abstrahują każdą kontrolkę międzyplatformową, można znaleźć w repozytorium dotnet/maui. Jest to format klucza, który powinien być używany, jeśli chcesz, aby dostosowanie programu obsługi było uruchamiane za każdym razem, gdy zmienia się właściwość. W przeciwnym razie klucz może być dowolną wartością, która nie musi odpowiadać nazwie właściwości uwidocznionej przez typ. Można na przykład określić MyCustomization jako klucz, a każda modyfikacja widoku natywnego może być wykonywana jako dostosowanie. Jednak konsekwencją tego formatu klucza jest to, że dostosowanie programu obsługi zostanie uruchomione tylko wtedy, gdy maper programu obsługi zostanie po raz pierwszy zmodyfikowany.
• Element Action reprezentujący metodę, która wykonuje dostosowywanie programu obsługi. Parametr Action określa dwa argumenty:
  • handler argument, który zapewnia instancję dostosowywanego handlera.
  • view Argument, który udostępnia wystąpienie kontrolki międzyplatformowej, którą implementuje program obsługi.

Każda klasa obsługi udostępnia widok natywny dla kontrolki międzyplatformowej za pośrednictwem swojej właściwości PlatformView. Dostęp do tej właściwości można uzyskać, aby ustawić właściwości widoku natywnego, wywołać metody widoku natywnego i zasubskrybować zdarzenia widoku natywnego. Ponadto kontrolka międzyplatformowa zaimplementowana przez program obsługi jest widoczna za pośrednictwem jej właściwości VirtualView.

Programy obsługi można dostosować na platformę przy użyciu kompilacji warunkowej w kodzie wielokierunkowym opartym na platformie. Alternatywnie można użyć klas częściowych do organizowania kodu w foldery i pliki specyficzne dla platformy. Aby uzyskać więcej informacji na temat kompilacji warunkowej, zobacz Kompilacja warunkowa.

Dostosowywanie kontrolki

Widok MAUI Entry platformy .NET to jednowierszowa kontrolka wprowadzania tekstu, która implementuje IEntry interfejs. Widok Entry odwzorowuje się w następujące natywne widoki dla każdej platformy przez EntryHandler.

Na poniższych diagramach pokazano, jak Entry widok jest mapowany na widoki natywne za pośrednictwem elementu EntryHandler:

Maper Entry właściwości w EntryHandler klasie mapuje właściwości kontrolek międzyplatformowych na interfejs API widoku natywnego. Gwarantuje to, że po ustawieniu właściwości na Entryobiekcie podstawowy widok macierzysty jest aktualizowany zgodnie z potrzebami.

Mapowanie właściwości można zmodyfikować w celu dostosowania Entry na wszystkich platformach.

namespace CustomizeHandlersDemo.Views;

public partial class CustomizeEntryPage : ContentPage
{
    public CustomizeEntryPage()
    {
        InitializeComponent();
        ModifyEntry();
    }

    void ModifyEntry()
    {
        Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("MyCustomization", (handler, view) =>
        {
#if ANDROID
            handler.PlatformView.SetSelectAllOnFocus(true);
#elif IOS || MACCATALYST
            handler.PlatformView.EditingDidBegin += (s, e) =>
            {
                handler.PlatformView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
            };
#elif WINDOWS
            handler.PlatformView.GotFocus += (s, e) =>
            {
                handler.PlatformView.SelectAll();
            };
#endif
        });
    }
}

W tym przykładzie Entry dostosowanie odbywa się w klasie strony. W związku z tym wszystkie Entry elementy sterujące w systemach Android, iOS i Windows zostaną dostosowane po utworzeniu wystąpienia tego CustomizeEntryPage. pl-PL: Dostosowywanie jest wykonywane przez uzyskanie dostępu do właściwości PlatformView, która umożliwia dostęp do widoku natywnego mapowania na kontrolkę międzyplatformową dla każdej platformy. Następnie kod natywny dostosowuje procedurę obsługi, zaznaczając cały tekst w Entry w momencie, gdy zyskuje fokus.

Aby uzyskać więcej informacji na temat maperów, zobacz Mappers.

Dostosowywanie określonego wystąpienia kontrolki

Procedury obsługi są globalne, a dostosowywanie procedury obsługi na rzecz kontrolki spowoduje dostosowanie w aplikacji wszystkich kontrolek tego samego typu. Jednak procedury obsługi dla określonych wystąpień kontrolek można dostosować poprzez tworzenie podklasy kontrolki, a następnie zmodyfikować procedurę obsługi dla podstawowego typu kontrolki tylko gdy kontrolka jest typem podklasy. Aby na przykład dostosować określoną Entry kontrolkę na stronie zawierającej wiele Entry kontrolek, należy najpierw utworzyć podklasę dla kontrolki Entry :

namespace CustomizeHandlersDemo.Controls
{
    internal class MyEntry : Entry
    {
    }
}

Następnie można dostosować element za pomocą mapatora właściwości EntryHandler, aby wykonać żądaną modyfikację tylko dla wystąpień MyEntry.

Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("MyCustomization", (handler, view) =>
{
    if (view is MyEntry)
    {
#if ANDROID
        handler.PlatformView.SetSelectAllOnFocus(true);
#elif IOS || MACCATALYST
        handler.PlatformView.EditingDidBegin += (s, e) =>
        {
            handler.PlatformView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
        };
#elif WINDOWS
        handler.PlatformView.GotFocus += (s, e) =>
        {
            handler.PlatformView.SelectAll();
        };
#endif
    }
});

Jeśli dostosowanie programu obsługi zostanie wykonane w twojej klasie App, wszystkie wystąpienia MyEntry w aplikacji zostaną dostosowane zgodnie z dokonanymi zmianami w programie obsługi.

Dostosowanie kontrolki przy użyciu cyklu życia kontrolera

Wszystkie kontrolki oparte na obsługiwaniu .NET MAUI obsługują zdarzenia HandlerChanging i HandlerChanged. Zdarzenie HandlerChanged jest zgłaszane, gdy widok natywny, który implementuje kontrolkę międzyplatformową, jest dostępny i inicjowany. Zdarzenie HandlerChanging jest zgłaszane, gdy obsługujący kontrolkę ma zostać usunięty z kontrolki wieloplatformowej. Aby uzyskać więcej informacji na temat zdarzeń cyklu życia programu obsługi, zobacz Cykl życia programu obsługi.

Cykl życia programu obsługi może służyć do dostosowywania programu obsługi. Aby na przykład zasubskrybować i anulować subskrypcję zdarzeń widoku natywnego, należy zarejestrować obsługujące programy zdarzeń dla zdarzeń HandlerChanged i HandlerChanging na dostosowywanej kontrolce międzyplatformowej.

<Entry HandlerChanged="OnEntryHandlerChanged"
       HandlerChanging="OnEntryHandlerChanging" />

Programy obsługi można dostosować na platformę przy użyciu kompilacji warunkowej lub za pomocą klas częściowych do organizowania kodu w foldery i pliki specyficzne dla platformy. Każde podejście zostanie omówione po kolei, poprzez dostosowanie elementu Entry, tak aby cały jego tekst był wybierany wtedy, gdy zostanie skupiony.

Kompilacja warunkowa

Plik zaplecza zawierający programy obsługi zdarzeń dla zdarzeń HandlerChanged i HandlerChanging jest pokazany w poniższym przykładzie, który wykorzystuje kompilację warunkową.

#if ANDROID
using AndroidX.AppCompat.Widget;
#elif IOS || MACCATALYST
using UIKit;
#elif WINDOWS
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml;
#endif

namespace CustomizeHandlersDemo.Views;

public partial class CustomizeEntryHandlerLifecyclePage : ContentPage
{
    public CustomizeEntryHandlerLifecyclePage()
    {
        InitializeComponent();
    }

    void OnEntryHandlerChanged(object sender, EventArgs e)
    {
        Entry entry = sender as Entry;
#if ANDROID
        (entry.Handler.PlatformView as AppCompatEditText).SetSelectAllOnFocus(true);
#elif IOS || MACCATALYST
        (entry.Handler.PlatformView as UITextField).EditingDidBegin += OnEditingDidBegin;
#elif WINDOWS
        (entry.Handler.PlatformView as TextBox).GotFocus += OnGotFocus;
#endif
    }

    void OnEntryHandlerChanging(object sender, HandlerChangingEventArgs e)
    {
        if (e.OldHandler != null)
        {
#if IOS || MACCATALYST
            (e.OldHandler.PlatformView as UITextField).EditingDidBegin -= OnEditingDidBegin;
#elif WINDOWS
            (e.OldHandler.PlatformView as TextBox).GotFocus -= OnGotFocus;
#endif
        }
    }

#if IOS || MACCATALYST
    void OnEditingDidBegin(object sender, EventArgs e)
    {
        var nativeView = sender as UITextField;
        nativeView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
    }
#elif WINDOWS
    void OnGotFocus(object sender, RoutedEventArgs e)
    {
        var nativeView = sender as TextBox;
        nativeView.SelectAll();
    }
#endif
}

#if ANDROID
using Microsoft.Maui.Platform;
#elif IOS || MACCATALYST
using UIKit;
#elif WINDOWS
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml;
#endif

namespace CustomizeHandlersDemo.Views;

public partial class CustomizeEntryHandlerLifecyclePage : ContentPage
{
    public CustomizeEntryHandlerLifecyclePage()
    {
        InitializeComponent();
    }

    void OnEntryHandlerChanged(object sender, EventArgs e)
    {
        Entry entry = sender as Entry;
#if ANDROID
        (entry.Handler.PlatformView as MauiAppCompatEditText).SetSelectAllOnFocus(true);
#elif IOS || MACCATALYST
        (entry.Handler.PlatformView as UITextField).EditingDidBegin += OnEditingDidBegin;
#elif WINDOWS
        (entry.Handler.PlatformView as TextBox).GotFocus += OnGotFocus;
#endif
    }

    void OnEntryHandlerChanging(object sender, HandlerChangingEventArgs e)
    {
        if (e.OldHandler != null)
        {
#if IOS || MACCATALYST
            (e.OldHandler.PlatformView as UITextField).EditingDidBegin -= OnEditingDidBegin;
#elif WINDOWS
            (e.OldHandler.PlatformView as TextBox).GotFocus -= OnGotFocus;
#endif
        }
    }

#if IOS || MACCATALYST
    void OnEditingDidBegin(object sender, EventArgs e)
    {
        var nativeView = sender as UITextField;
        nativeView.PerformSelector(new ObjCRuntime.Selector("selectAll"), null, 0.0f);
    }
#elif WINDOWS
    void OnGotFocus(object sender, RoutedEventArgs e)
    {
        var nativeView = sender as TextBox;
        nativeView.SelectAll();
    }
#endif
}

Zdarzenie HandlerChanged jest wywoływane po utworzeniu i zainicjowaniu widoku natywnego, który implementuje kontrolkę międzyplatformową. W związku z tym program obsługi zdarzeń to miejsce, w którym powinny być wykonywane subskrypcje zdarzeń natywnych. Wymaga to rzutowania właściwości PlatformView obsługiwacza na typ lub typ bazowy widoku natywnego, aby można było uzyskać dostęp do zdarzeń natywnych. W tym przykładzie w systemach iOS, Mac Catalyst i Windows zdarzenie OnEntryHandlerChanged subskrybuje zdarzenia widoku natywnego, które są zgłaszane, gdy widoki natywne implementujące Entry zyskują fokus.

Procedury obsługi zdarzeń OnEditingDidBegin oraz OnGotFocus uzyskują dostęp do widoku natywnego dla Entry na swoich odpowiednich platformach i wybierają cały tekst, który znajduje się w obiekcie Entry.

Zdarzenie HandlerChanging jest wywoływane przed usunięciem istniejącej procedury obsługi z kontroli międzyplatformowej i przed utworzeniem nowej procedury obsługi dla kontroli międzyplatformowej. W związku z tym jego program obsługi zdarzeń to miejsce, w którym należy usunąć subskrypcje zdarzeń natywnych, a inne oczyszczanie powinno zostać wykonane. Obiekt HandlerChangingEventArgs , który towarzyszy temu zdarzeniu, ma OldHandler właściwości i NewHandler , które zostaną ustawione odpowiednio na stare i nowe procedury obsługi. W tym przykładzie OnEntryHandlerChanging zdarzenie usuwa subskrypcję zdarzeń natywnego widoku w systemach iOS, Mac Catalyst i Windows.

Klasy częściowe

Zamiast korzystać z kompilacji warunkowej, można również używać klas częściowych do organizowania kodu dostosowywania kontrolek w folderach i plikach specyficznych dla platformy. Dzięki temu podejściu kod dostosowywania jest podzielony na częściową klasę międzyplatformową oraz częściową klasę specyficzną dla platformy.

• Klasa częściowa międzyplatformowa zwykle definiuje członków, ale ich nie implementuje i jest przeznaczona na wszystkie platformy. Ta klasa nie powinna być umieszczana w żadnym folderze podrzędnym Platformy projektu, ponieważ uczyniłoby to klasą specyficzną dla platformy.
• Klasa częściowa specyficzna dla platformy zwykle implementuje składowe zdefiniowane w klasie częściowej międzyplatformowej i jest tworzona dla jednej platformy. Ta klasa powinna zostać umieszczona w folderze podrzędnym folderu Platformy dla wybranej platformy.

W poniższym przykładzie przedstawiono międzyplatformową klasę częściową:

namespace CustomizeHandlersDemo.Views;

public partial class CustomizeEntryPartialMethodsPage : ContentPage
{
    public CustomizeEntryPartialMethodsPage()
    {
        InitializeComponent();
    }

    partial void ChangedHandler(object sender, EventArgs e);
    partial void ChangingHandler(object sender, HandlerChangingEventArgs e);

    void OnEntryHandlerChanged(object sender, EventArgs e) => ChangedHandler(sender, e);
    void OnEntryHandlerChanging(object sender, HandlerChangingEventArgs e) => ChangingHandler(sender, e);
}

W tym przykładzie dwie procedury obsługi zdarzeń wywołują metody częściowe o nazwie ChangedHandler i ChangingHandler, których podpisy są zdefiniowane w klasie częściowej wieloplatformowej. Implementacje metody częściowej są następnie definiowane w klasach częściowych specyficznych dla platformy, które powinny zostać umieszczone w odpowiednich folderach podrzędnych Platformy , aby upewnić się, że system kompilacji próbuje skompilować kod natywny tylko podczas kompilowania dla określonej platformy. Na przykład poniższy kod przedstawia klasę CustomizeEntryPartialMethodsPage w folderze Platformy> systemuWindows projektu:

using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;

namespace CustomizeHandlersDemo.Views
{
    public partial class CustomizeEntryPartialMethodsPage : ContentPage
    {
        partial void ChangedHandler(object sender, EventArgs e)
        {
            Entry entry = sender as Entry;
            (entry.Handler.PlatformView as TextBox).GotFocus += OnGotFocus;
        }

        partial void ChangingHandler(object sender, HandlerChangingEventArgs e)
        {
            if (e.OldHandler != null)
            {
                (e.OldHandler.PlatformView as TextBox).GotFocus -= OnGotFocus;
            }
        }

        void OnGotFocus(object sender, RoutedEventArgs e)
        {
            var nativeView = sender as TextBox;
            nativeView.SelectAll();
        }
    }
}

Zaletą tego podejścia jest to, że kompilacja warunkowa nie jest wymagana i że metody częściowe nie muszą być implementowane na każdej platformie. Jeśli implementacja nie jest udostępniana na platformie, metoda i wszystkie wywołania metody zostaną usunięte w czasie kompilacji. Aby uzyskać informacje na temat metod częściowych, zobacz Metody częściowe.

Aby uzyskać informacje o organizacji folderu Platformy w projekcie .NET MAUI, zobacz Częściowe klasy i metody. Aby uzyskać informacje o sposobie konfigurowania wielotargetowania, aby uniknąć umieszczania kodu platformy w podfolderach folderu Platformy, zobacz Konfigurowanie wielotargetowania.