Anpassen eines EintragsCustomizing an Entry

Beispiel herunterladen Das Beispiel herunterladenDownload Sample Download the sample

Mit dem Entry-Steuerelement von Xamarin.Forms kann eine einzelne Textzeile bearbeitet werden. In diesem Artikel wird veranschaulicht, wie Sie einen benutzerdefinierten Renderer für das Entry-Steuerelement erstellen, sodass Entwickler das native Standardrendering mit ihrem eigenen plattformspezifischen Rendering überschreiben können.The Xamarin.Forms Entry control allows a single line of text to be edited. This article demonstrates how to create a custom renderer for the Entry control, enabling developers to override the default native rendering with their own platform-specific customization.

Jedes Xamarin.Forms-Steuerelement verfügt über einen entsprechenden Renderer für jede Plattform, die eine Instanz eines nativen Steuerelements erstellt.Every Xamarin.Forms control has an accompanying renderer for each platform that creates an instance of a native control. Beim Rendern eines Entry-Steuerelements durch eine Xamarin.Forms-App wird in iOS die EntryRenderer-Klasse instanziiert, wodurch wiederum ein natives UITextField-Steuerelement instanziiert wird.When an Entry control is rendered by a Xamarin.Forms application, in iOS the EntryRenderer class is instantiated, which in turns instantiates a native UITextField control. Auf der Android-Plattform instanziiert die EntryRenderer-Klasse ein EditText-Steuerelement.On the Android platform, the EntryRenderer class instantiates an EditText control. Auf der Universellen Windows-Plattform (UWP) instanziiert die EntryRenderer-Klasse ein TextBox-Steuerelement.On the Universal Windows Platform (UWP), the EntryRenderer class instantiates a TextBox control. Weitere Informationen zu den Renderern und Klassen nativer Steuerelemente, denen Xamarin.Forms-Steuerelemente zugeordnet sind, finden Sie unter Rendererbasisklassen und native Steuerelemente.For more information about the renderer and native control classes that Xamarin.Forms controls map to, see Renderer Base Classes and Native Controls.

Das folgende Diagramm veranschaulicht die Beziehungen zwischen dem Entry-Steuerelement und den entsprechenden nativen Steuerelementen, die dieses implementieren:The following diagram illustrates the relationship between the Entry control and the corresponding native controls that implement it:

Der Renderingprozess kann genutzt werden, um plattformspezifische Anpassungen zu implementieren, indem für das Entry-Steuerelement auf jeder Plattform ein benutzerdefinierter Renderer erstellt wird.The rendering process can be taken advantage of to implement platform-specific customizations by creating a custom renderer for the Entry control on each platform. Gehen Sie hierfür folgendermaßen vor:The process for doing this is as follows:

  1. Erstellen Sie ein benutzerdefiniertes Xamarin.Forms-Steuerelement.Create a Xamarin.Forms custom control.
  2. Nutzen Sie das benutzerdefinierte Steuerelement über Xamarin.Forms.Consume the custom control from Xamarin.Forms.
  3. Erstellen Sie den benutzerdefinierten Renderer für das Steuerelement auf jeder Plattform.Create the custom renderer for the control on each platform.

Im Folgenden wird auf jeden dieser Punkte ausführlicher eingegangen, um zu veranschaulichen, wie Sie ein Entry-Steuerelement implementieren können, das auf jeder Plattform eine andere Hintergrundfarbe aufweist.Each item will now be discussed in turn, to implement an Entry control that has a different background color on each platform.

Wichtig

In diesem Artikel wird erläutert, wie Sie einen einfachen benutzerdefinierten Renderer erstellen.This article explains how to create a simple custom renderer. Es ist jedoch nicht erforderlich, einen benutzerdefinierten Renderer zu erstellen, um ein Entry-Steuerelement zu implementieren, das auf jeder Plattform eine andere Hintergrundfarbe aufweist.However, it's not necessary to create a custom renderer to implement an Entry that has a different background color on each platform. Dies erreichen Sie einfacher, indem Sie mithilfe der Device-Klasse oder der OnPlatform-Markuperweiterung plattformspezifische Werte angeben.This can be more easily accomplished by using the Device class, or the OnPlatform markup extension, to provide platform-specific values. Weitere Informationen finden Sie unter Providing Platform-Specific Values (Angeben plattformspezifischer Werte) und OnPlatform Markup Extension (OnPlatform-Markuperweiterung).For more information, see Providing Platform-Specific Values and OnPlatform Markup Extension.

Erstellen des benutzerdefinierten Entry-SteuerelementsCreating the Custom Entry Control

Ein benutzerdefiniertes Entry-Steuerelement kann erstellt werden, indem Sie das Entry-Steuerelement wie in folgendem Codebeispiel als Unterklasse verwenden:A custom Entry control can be created by subclassing the Entry control, as shown in the following code example:

public class MyEntry : Entry
{
}

Das MyEntry-Steuerelement wird im .NET-Standard-Bibliotheksprojekt erstellt. Es handelt sich dabei einfach um ein Entry-Steuerelement.The MyEntry control is created in the .NET Standard library project and is simply an Entry control. Die Anpassung des Steuerelements erfolgt im benutzerdefinierten Renderer, sodass keine zusätzliche Implementierung im MyEntry-Steuerelement erforderlich ist.Customization of the control will be carried out in the custom renderer, so no additional implementation is required in the MyEntry control.

Nutzen des benutzerdefinierten SteuerelementsConsuming the Custom Control

Sie können auf das Steuerelement MyEntry in XAML im .NET Standard-Bibliotheksprojekt verweisen, indem Sie einen Namespace für seine Position deklarieren und das Namespacepräfix für das Steuerelement verwenden.The MyEntry control can be referenced in XAML in the .NET Standard library project by declaring a namespace for its location and using the namespace prefix on the control element. Das folgende Codebeispiel veranschaulicht, wie das Steuerelement MyEntry von der XAML-Seite genutzt werden kann:The following code example shows how the MyEntry control can be consumed by a XAML page:

<ContentPage ...
    xmlns:local="clr-namespace:CustomRenderer;assembly=CustomRenderer"
    ...>
    ...
    <local:MyEntry Text="In Shared Code" />
    ...
</ContentPage>

Das local-Namespacepräfix kann beliebig benannt werden.The local namespace prefix can be named anything. Die Werte clr-namespace und assembly müssen jedoch mit den Angaben des benutzerdefinierten Steuerelements übereinstimmen.However, the clr-namespace and assembly values must match the details of the custom control. Wenn der Namespace deklariert wurde, wird das Präfix verwendet, um auf das benutzerdefinierte Steuerelement zu verweisen.Once the namespace is declared the prefix is used to reference the custom control.

Das folgende Codebeispiel veranschaulicht, wie das benutzerdefinierte Steuerelement MyEntry von einer C#-Seite genutzt werden kann:The following code example shows how the MyEntry control can be consumed by a C# page:

public class MainPage : ContentPage
{
  public MainPage ()
  {
    Content = new StackLayout {
      Children = {
        new Label {
          Text = "Hello, Custom Renderer !",
        },
        new MyEntry {
          Text = "In Shared Code",
        }
      },
      VerticalOptions = LayoutOptions.CenterAndExpand,
      HorizontalOptions = LayoutOptions.CenterAndExpand,
    };
  }
}

Dieser Code instanziiert ein neues ContentPage-Objekt, das ein Label- und MyEntry-Steuerelement anzeigt, die auf der Seite vertikal und horizontal zentriert sind.This code instantiates a new ContentPage object that will display a Label and MyEntry control centered both vertically and horizontally on the page.

Ein benutzerdefinierter Renderer kann nun zu jedem Anwendungsprojekt hinzugefügt werden, um die Darstellung des Steuerelements auf jeder Plattform anzupassen.A custom renderer can now be added to each application project to customize the control's appearance on each platform.

Erstellen des benutzerdefinierten Renderers auf jeder PlattformCreating the Custom Renderer on each Platform

Gehen Sie folgendermaßen vor, um eine Klasse für einen benutzerdefinierten Renderer zu erstellen:The process for creating the custom renderer class is as follows:

  1. Erstellen Sie eine Unterklasse der EntryRenderer-Klasse, die das native Steuerelement rendert.Create a subclass of the EntryRenderer class that renders the native control.
  2. Überschreiben Sie die OnElementChanged-Methode, die die native Seite rendert, und schreiben Sie Logik, um das Steuerelement anzupassen.Override the OnElementChanged method that renders the native control and write logic to customize the control. Diese Methode wird aufgerufen, wenn das entsprechende Xamarin.Forms-Steuerelement erstellt wird.This method is called when the corresponding Xamarin.Forms control is created.
  3. Fügen Sie der benutzerdefinierten Rendererklasse ein ExportRenderer-Attribut hinzu, um anzugeben, dass sie zum Rendern des Xamarin.Forms-Steuerelements verwendet werden soll.Add an ExportRenderer attribute to the custom renderer class to specify that it will be used to render the Xamarin.Forms control. Dieses Attribut wird verwendet, um den benutzerdefinierten Renderer bei Xamarin.Forms zu registrieren.This attribute is used to register the custom renderer with Xamarin.Forms.

Hinweis

Optional kann ein benutzerdefinierter Renderer in jedem Plattformprojekt bereitgestellt werden.It is optional to provide a custom renderer in each platform project. Wenn kein benutzerdefinierter Renderer registriert wurde, wird der Standardrenderer für die Basisklasse des Steuerelements verwendet.If a custom renderer isn't registered, then the default renderer for the control's base class will be used.

Das folgende Diagramm veranschaulicht die Zuständigkeiten jedes Projekts in der Beispielanwendung sowie deren Beziehungen zueinander:The following diagram illustrates the responsibilities of each project in the sample application, along with the relationships between them:

Das Steuerelement MyEntry wird von plattformspezifischen MyEntryRenderer-Klassen gerendert, die alle von der EntryRenderer-Klasse für jede Plattform abgeleitet werden.The MyEntry control is rendered by platform-specific MyEntryRenderer classes, which all derive from the EntryRenderer class for each platform. Dies führt dazu, dass jedes MyEntry-Steuerelement mit einer plattformspezifischen Hintergrundfarbe gerendert wird. Dies wird in folgenden Screenshots veranschaulicht:This results in each MyEntry control being rendered with a platform-specific background color, as shown in the following screenshots:

Die Klasse EntryRenderer macht die Methode OnElementChanged verfügbar, die bei der Erstellung des Xamarin.Forms-Steuerelements aufgerufen wird, um das entsprechende native Steuerelement zu rendern.The EntryRenderer class exposes the OnElementChanged method, which is called when the Xamarin.Forms control is created to render the corresponding native control. Diese Methode akzeptiert einen ElementChangedEventArgs-Parameter, der die Eigenschaften OldElement und NewElement enthält.This method takes an ElementChangedEventArgs parameter that contains OldElement and NewElement properties. Diese Eigenschaften stellen jeweils das Xamarin.Forms-Element, an das der Renderer angefügt war, und das Xamarin.Forms-Element dar, an das der Renderer angefügt ist.These properties represent the Xamarin.Forms element that the renderer was attached to, and the Xamarin.Forms element that the renderer is attached to, respectively. In der Beispielanwendung ist die OldElement-Eigenschaft null, und die NewElement-Eigenschaft enthält einen Verweis auf das MyEntry-Steuerelement.In the sample application the OldElement property will be null and the NewElement property will contain a reference to the MyEntry control.

Das native Steuerelement sollte in der überschriebenen Version der OnElementChanged-Methode in der MyEntryRenderer-Klasse angepasst werden.An overridden version of the OnElementChanged method in the MyEntryRenderer class is the place to perform the native control customization. Über die Control-Eigenschaft können Sie auf einen typisierten Verweis auf das native Steuerelement zugreifen, das auf der Plattform verwendet wird.A typed reference to the native control being used on the platform can be accessed through the Control property. Darüber hinaus kann über die Eigenschaft Element ein Verweis auf das Xamarin.Forms-Steuerelement abgerufen werden, das gerendert wird, obwohl diese in der Beispielanwendung nicht verwendet wird.In addition, a reference to the Xamarin.Forms control that's being rendered can be obtained through the Element property, although it's not used in the sample application.

Jede benutzerdefinierte Rendererklasse ist mit einem ExportRenderer-Attribut versehen, das den Renderer bei Xamarin.Forms registriert.Each custom renderer class is decorated with an ExportRenderer attribute that registers the renderer with Xamarin.Forms. Das Attribut benötigt zwei Parameter: den Typnamen des zu rendernden Xamarin.Forms-Steuerelements und den Typnamen des benutzerdefinierten Renderers.The attribute takes two parameters – the type name of the Xamarin.Forms control being rendered, and the type name of the custom renderer. Das Präfix assembly für das Attribut gibt an, dass das Attribut für die gesamte Assembly gilt.The assembly prefix to the attribute specifies that the attribute applies to the entire assembly.

In den folgenden Abschnitten wird die Implementierung jeder plattformspezifischen, benutzerdefinierten MyEntryRenderer-Rendererklasse erläutert.The following sections discuss the implementation of each platform-specific MyEntryRenderer custom renderer class.

Erstellen des benutzerdefinierten Renderers unter iOSCreating the Custom Renderer on iOS

Im folgenden Codebeispiel wird der benutzerdefinierte Renderer für die iOS-Plattform veranschaulicht:The following code example shows the custom renderer for the iOS platform:

using Xamarin.Forms.Platform.iOS;

[assembly: ExportRenderer (typeof(MyEntry), typeof(MyEntryRenderer))]
namespace CustomRenderer.iOS
{
    public class MyEntryRenderer : EntryRenderer
    {
        protected override void OnElementChanged (ElementChangedEventArgs<Entry> e)
        {
            base.OnElementChanged (e);

            if (Control != null) {
                // do whatever you want to the UITextField here!
                Control.BackgroundColor = UIColor.FromRGB (204, 153, 255);
                Control.BorderStyle = UITextBorderStyle.Line;
            }
        }
    }
}

Der Aufruf der OnElementChanged-Methode der Basisklasse instanziiert ein iOS-UITextField-Steuerelement, wobei der Control-Eigenschaft des Renderers ein Verweis auf das Steuerelement zugewiesen wird.The call to the base class's OnElementChanged method instantiates an iOS UITextField control, with a reference to the control being assigned to the renderer's Control property. Die Hintergrundfarbe wird dann mithilfe der UIColor.FromRGB-Methode auf „hellviolett“ festgelegt.The background color is then set to light purple with the UIColor.FromRGB method.

Erstellen des benutzerdefinierten Renderers unter AndroidCreating the Custom Renderer on Android

Im folgenden Codebeispiel wird der benutzerdefinierte Renderer für die Android-Plattform veranschaulicht:The following code example shows the custom renderer for the Android platform:

using Xamarin.Forms.Platform.Android;

[assembly: ExportRenderer(typeof(MyEntry), typeof(MyEntryRenderer))]
namespace CustomRenderer.Android
{
    class MyEntryRenderer : EntryRenderer
    {
        public MyEntryRenderer(Context context) : base(context)
        {
        }

        protected override void OnElementChanged(ElementChangedEventArgs<Entry> e)
        {
            base.OnElementChanged(e);

            if (Control != null)
            {
                Control.SetBackgroundColor(global::Android.Graphics.Color.LightGreen);
            }
        }
    }
}

Der Aufruf der OnElementChanged-Methode der Basisklasse instanziiert ein Android-EditText-Steuerelement, wobei der Control-Eigenschaft des Renderers ein Verweis auf das Steuerelement zugewiesen wird.The call to the base class's OnElementChanged method instantiates an Android EditText control, with a reference to the control being assigned to the renderer's Control property. Die Hintergrundfarbe wird dann mithilfe der Control.SetBackgroundColor-Methode auf „hellgrün“ festgelegt.The background color is then set to light green with the Control.SetBackgroundColor method.

Erstellen des benutzerdefinierten Renderers auf der UWPCreating the Custom Renderer on UWP

Im folgenden Codebeispiel wird der benutzerdefinierte Renderer für die UWP veranschaulicht:The following code example shows the custom renderer for UWP:

[assembly: ExportRenderer(typeof(MyEntry), typeof(MyEntryRenderer))]
namespace CustomRenderer.UWP
{
    public class MyEntryRenderer : EntryRenderer
    {
        protected override void OnElementChanged(ElementChangedEventArgs<Entry> e)
        {
            base.OnElementChanged(e);

            if (Control != null)
            {
                Control.Background = new SolidColorBrush(Colors.Cyan);
            }
        }
    }
}

Der Aufruf der OnElementChanged-Methode der Basisklasse instanziiert ein TextBox-Steuerelement, wobei der Control-Eigenschaft des Renderers ein Verweis auf das Steuerelement zugewiesen wird.The call to the base class's OnElementChanged method instantiates a TextBox control, with a reference to the control being assigned to the renderer's Control property. Die Hintergrundfarbe wird dann durch Erstellen einer SolidColorBrush-Instanz auf „zyanblau“ festgelegt.The background color is then set to cyan by creating a SolidColorBrush instance.

ZusammenfassungSummary

In diesem Artikel wurde veranschaulicht, wie Sie einen benutzerdefinierten Renderer für das Xamarin.Forms-Steuerelement Entry erstellen, sodass Entwickler das native Standardrendering mit ihrem eigenen plattformspezifischen Rendering überschreiben können.This article has demonstrated how to create a custom control renderer for the Xamarin.Forms Entry control, enabling developers to override the default native rendering with their own platform-specific rendering. Benutzerdefinierte Renderer sind eine praktische Methode zum Anpassen der Darstellung von Xamarin.Forms-Steuerelementen.Custom renderers provide a powerful approach to customizing the appearance of Xamarin.Forms controls. Sie können für geringfügige Formatierungsänderungen oder für umfangreiche, plattformspezifische Anpassungen des Layouts und Verhaltens verwendet werden.They can be used for small styling changes or sophisticated platform-specific layout and behavior customization.