İşleyicilerle denetimleri özelleştirme

Örneğe göz atın

İşleyiciler, bir platformlar arası denetimin görünümünü ve davranışını denetimin API'sinde mümkün olan özelleştirmenin ötesinde artıracak şekilde özelleştirilebilir. Platformlar arası denetimin yerel görünümlerini değiştiren bu özelleştirme, aşağıdaki yöntemlerden biriyle bir işleyici için eşleyici değiştirilerek elde edilir:

• PrependToMapping, .NET MAUI denetim eşlemeleri uygulanmadan önce işleyici için eşleyiciyi değiştirir.
• ModifyMapping, var olan eşlemeyi değiştirir.
• AppendToMapping, .NET MAUI denetim eşlemeleri uygulandıktan sonra işleyici için eşleyiciyi değiştirir.

Bu yöntemlerin her biri, iki bağımsız değişken gerektiren aynı imzaya sahiptir:

• stringTabanlı anahtar. .NET MAUI tarafından sağlanan eşlemelerden biri değiştirilirken, .NET MAUI tarafından kullanılan anahtar belirtilmelidir. .NET MAUI denetim eşlemeleri tarafından kullanılan anahtar değerleri, örneğin nameof(IEntry.IsPassword)arabirim ve özellik adlarını temel alır. Her platformlar arası denetimi soyutlayan arabirimler ve özellikleri burada bulunabilir. Bu, işleyici özelleştirmenizin bir özellik her değiştiğinde çalışmasını istiyorsanız kullanılması gereken anahtar biçimidir. Aksi takdirde anahtar, bir tür tarafından sunulan bir özelliğin adına karşılık gelen rastgele bir değer olabilir. Örneğin, MyCustomization herhangi bir yerel görünüm değişikliği özelleştirme olarak gerçekleştirilerek bir anahtar olarak belirtilebilir. Ancak, bu anahtar biçiminin bir sonucu, işleyici özelleştirmenizin yalnızca işleyici için eşleyici ilk kez değiştirildiğinde çalıştırılmasıdır.
• Action İşleyici özelleştirmesini gerçekleştiren yöntemi temsil eden bir. Action iki bağımsız değişken belirtir:
  • handler Özelleştirilen işleyicinin bir örneğini sağlayan bağımsız değişken.
  • view İşleyicinin uyguladığı platformlar arası denetimin bir örneğini sağlayan bağımsız değişken.

Önemli

İşleyici özelleştirmeleri geneldir ve belirli bir denetim örneği kapsamında değildir. İşleyici özelleştirmenin uygulamanızın herhangi bir yerinde gerçekleşmesine izin verilir. bir işleyici özelleştirildikten sonra, uygulamanızın her yerinde bu türdeki tüm denetimleri etkiler.

Her işleyici sınıfı, özelliği aracılığıyla PlatformView platformlar arası denetim için yerel görünümü kullanıma sunar. Bu özelliğe yerel görünüm özelliklerini ayarlamak, yerel görünüm yöntemlerini çağırmak ve yerel görünüm olaylarına abone olmak için erişilebilir. Ayrıca, işleyici tarafından uygulanan platformlar arası denetim özelliği VirtualView aracılığıyla kullanıma sunulur.

İşleyiciler, platforma dayalı çok hedefli koda koşullu derleme kullanılarak platform başına özelleştirilebilir. Alternatif olarak, kodunuzu platforma özgü klasörler ve dosyalar halinde düzenlemek için kısmi sınıfları kullanabilirsiniz. Koşullu derleme hakkında daha fazla bilgi için bkz . Koşullu derleme.

Denetimi özelleştirme

.NET MAUI Entry görünümü, arabirimi uygulayan IEntry tek satırlı bir metin girişi denetimidir. görünümü EntryHandler her platform için aşağıdaki yerel görünümlere eşler Entry :

• iOS/Mac Katalizör: UITextField
• Android: AppCompatEditText
• Windows: TextBox

Aşağıdaki diyagramlarda, aracılığıyla görünümün Entry yerel görünümleriyle EntryHandlernasıl eşlendiği gösterilmektedir:

Entry sınıfında özellik eşleyicisiEntryHandler, platformlar arası denetim özelliklerini yerel görünüm API'sine eşler. Bu, bir özelliği üzerinde Entryayarlandığında temel alınan yerel görünümün gerektiği gibi güncelleştirilmesini sağlar.

Özellik eşleyicisi, her platformda özelleştirilecek Entry şekilde değiştirilebilir:

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
        });
    }
}

Bu örnekte, Entry özelleştirme bir sayfa sınıfında gerçekleşir. Bu nedenle, Android, iOS ve Windows üzerindeki tüm Entry denetimler, örneğini CustomizeEntryPage oluşturduktan sonra özelleştirilecektir. Özelleştirme, her platformdaki platformlar arası denetime eşlenen yerel görünüme erişim sağlayan işleyiciler PlatformView özelliğine erişilerek gerçekleştirilir. Daha sonra yerel kod, odak kazandığında içindeki metnin tümünü seçerek işleyiciyi Entry özelleştirir.

Eşleyiciler hakkında daha fazla bilgi için bkz . Eşleyiciler.

Belirli bir denetim örneğini özelleştirme

İşleyiciler geneldir ve bir denetim için işleyiciyi özelleştirmek, uygulamanızda aynı türdeki tüm denetimlerin özelleştirilmesine neden olur. Ancak, belirli denetim örneklerinin işleyicileri denetimin alt sınıfına eklenerek ve ardından yalnızca denetim alt sınıf türünde olduğunda temel denetim türü için işleyici değiştirilerek özelleştirilebilir. Örneğin, birden çok Entry denetim içeren bir sayfadaki belirli Entry bir denetimi özelleştirmek için önce denetimi alt sınıfa eklemelisinizEntry:

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

Ardından, yalnızca örneklerde istenen değişikliği MyEntry gerçekleştirmek için özelliğini eşleyicisi aracılığıyla özelleştirebilirsinizEntryHandler:

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
    }
});

İşleyici özelleştirmesi sınıfınızda App gerçekleştiriliyorsa, uygulamadaki tüm MyEntry örnekler işleyici değişikliğine göre özelleştirilir.

İşleyici yaşam döngüsünü kullanarak denetimi özelleştirme

Tüm işleyici tabanlı .NET MAUI denetimleri destek HandlerChanging ve HandlerChanged olayları içerir. Olay HandlerChanged , platformlar arası denetimi uygulayan yerel görünüm kullanılabilir ve başlatıldığında oluşturulur. Olay HandlerChanging , denetimin işleyicisi platformlar arası denetimden kaldırılacakken oluşturulur. İşleyici yaşam döngüsü olayları hakkında daha fazla bilgi için bkz . İşleyici yaşam döngüsü.

İşleyici yaşam döngüsü, işleyici özelleştirmesi gerçekleştirmek için kullanılabilir. Örneğin, yerel görünüm olaylarına abone olmak ve bu olayların aboneliğini kaldırmak için, özelleştirilen platformlar arası denetimdeki ve HandlerChanging olayları için HandlerChanged olay işleyicilerini kaydetmeniz gerekir:

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

İşleyiciler, koşullu derleme kullanılarak veya kodunuzu platforma özgü klasörler ve dosyalar halinde düzenlemek için kısmi sınıflar kullanılarak platform başına özelleştirilebilir. Her yaklaşım sırayla ele alınacaktır, böylece odak kazandığında metnin tümü seçilecek şekilde özelleştirilecektir Entry .

Koşullu derleme

ve HandlerChanging olayları için HandlerChanged olay işleyicilerini içeren arka planda kod dosyası, koşullu derleme kullanan aşağıdaki örnekte gösterilmiştir:

#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
}

Olay HandlerChanged , platformlar arası denetimi uygulayan yerel görünüm oluşturulduktan ve başlatıldıktan sonra oluşturulur. Bu nedenle, olay işleyicisi yerel olay aboneliklerinin gerçekleştirilmesi gereken yerdir. Bu, yerel olaylara PlatformView erişebilmek için işleyicinin özelliğini yerel görünümün türüne veya temel türüne atamayı gerektirir. Bu örnekte, iOS, Mac Catalyst ve Windows'da olay, OnEntryHandlerChanged kazanç odağını uygulayan yerel görünümler olduğunda tetiklenen yerel görünüm olaylarına Entry abone olur.

OnEditingDidBegin ve OnGotFocus olay işleyicileri ilgili platformlarında için yerel görünüme Entry erişip içindeki tüm metinleri Entryseçer.

Olay HandlerChanging , mevcut işleyici platformlar arası denetimden kaldırılmadan önce ve platformlar arası denetim için yeni işleyici oluşturulmadan önce oluşturulur. Bu nedenle, olay işleyicisi yerel olay aboneliklerinin kaldırılması ve diğer temizlemenin gerçekleştirilmesi gereken yerdir. HandlerChangingEventArgs Bu olaya eşlik eden nesne, sırasıyla eski ve NewHandler yeni işleyicilere ayarlanacak olan ve özelliklerine sahiptirOldHandler. Bu örnekte olay, iOS, OnEntryHandlerChanging Mac Catalyst ve Windows'taki yerel görünüm olaylarının aboneliğini kaldırır.

Kısmi sınıflar

Koşullu derleme kullanmak yerine, denetim özelleştirme kodunuzu platforma özgü klasörler ve dosyalar halinde düzenlemek için kısmi sınıflar kullanmak da mümkündür. Bu yaklaşımla özelleştirme kodunuz platformlar arası bir kısmi sınıfa ve platforma özgü kısmi sınıfa ayrılır:

• Platformlar arası kısmi sınıf genellikle üyeleri tanımlar, ancak uygulamaz ve tüm platformlar için oluşturulur. Bu sınıf, projenizin Platformlar alt klasörlerinden herhangi birine yerleştirilmemelidir, çünkü bunu yapmak onu platforma özgü bir sınıf haline getirir.
• Platforma özgü kısmi sınıf genellikle platformlar arası kısmi sınıfta tanımlanan üyeleri uygular ve tek bir platform için oluşturulur. Bu sınıf, seçtiğiniz platform için Platformlar klasörünün alt klasörüne yerleştirilmelidir.

Aşağıdaki örnekte platformlar arası kısmi sınıf gösterilmektedir:

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);
}

Bu örnekte, iki olay işleyicisi, imzaları platformlar arası kısmi sınıfta tanımlanan ve ChangingHandleradlı ChangedHandler kısmi yöntemleri çağırır. Kısmi yöntem uygulamaları daha sonra platforma özgü kısmi sınıflarda tanımlanır ve derleme sisteminin yalnızca belirli bir platform için derleme yaparken yerel kod oluşturmaya çalıştığından emin olmak için doğru Platformlar alt klasörlerine yerleştirilmesi gerekir. Örneğin, aşağıdaki kod projenin Platformlar>Windows klasöründe sınıfını gösterir:CustomizeEntryPartialMethodsPage

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();
        }
    }
}

Bu yaklaşımın avantajı, koşullu derlemenin gerekli olmadığı ve kısmi yöntemlerin her platformda uygulanması gerekmediğinden kaynaklanır. Platformda bir uygulama sağlanmazsa, yöntemi ve yöntemine yapılan tüm çağrılar derleme zamanında kaldırılır. Kısmi yöntemler hakkında bilgi için bkz . Kısmi yöntemler.

.NET MAUI projesinde Platformlar klasörünün organizasyonu hakkında bilgi için bkz. Kısmi sınıflar ve yöntemler. Platform kodunu Platformlar klasörünün alt klasörlerine yerleştirmenize gerek olmayacak şekilde çoklu hedeflemeyi yapılandırma hakkında bilgi için bkz. Çoklu hedeflemeyi yapılandırma.