Présentation des renderers personnalisésIntroduction to Custom Renderers

Les renderers personnalisés fournissent une approche puissante pour personnaliser l’apparence et le comportement des contrôles Xamarin.Forms. Ils peuvent être utilisés aussi bien pour les petits changements de style que pour la personnalisation sophistiquée de la disposition et du comportement d’une plateforme. Cet article présente les renderers personnalisés et décrit leur processus de création.Custom renderers provide a powerful approach for customizing the appearance and behavior of Xamarin.Forms controls. They can be used for small styling changes or sophisticated platform-specific layout and behavior customization. This article provides an introduction to custom renderers, and outlines the process for creating a custom renderer.

Les pages, dispositions et contrôles Xamarin.Forms présentent une API commune pour décrire des interfaces utilisateur mobiles multiplateformes.Xamarin.Forms Pages, Layouts and Controls present a common API to describe cross-platform mobile user interfaces. Chaque page, disposition et contrôle est restitué différemment sur chaque plateforme avec une classe Renderer qui crée à son tour un contrôle natif (correspondant à la représentation de Xamarin.Forms), le dispose sur l’écran et ajoute le comportement spécifié dans le code partagé.Each page, layout, and control is rendered differently on each platform, using a Renderer class that in turn creates a native control (corresponding to the Xamarin.Forms representation), arranges it on the screen, and adds the behavior specified in the shared code.

Les développeurs peuvent implémenter leurs propres classes Renderer pour personnaliser l’apparence et/ou le comportement d’un contrôle.Developers can implement their own custom Renderer classes to customize the appearance and/or behavior of a control. Vous pouvez ajouter des renderers personnalisés pour un type donné à un projet d’application afin de personnaliser le contrôle dans un emplacement tout en autorisant le comportement par défaut sur d’autres plateformes. Vous pouvez également ajouter différents renderers personnalisés à chaque projet d’application pour créer une apparence différente sur iOS, Android et la plateforme universelle Windows (UWP).Custom renderers for a given type can be added to one application project to customize the control in one place while allowing the default behavior on other platforms; or different custom renderers can be added to each application project to create a different look and feel on iOS, Android, and the Universal Windows Platform (UWP). Cependant, l’implémentation d’une classe de renderer personnalisée pour effectuer une simple personnalisation d’un contrôle est souvent une réponse trop lourde.However, implementing a custom renderer class to perform a simple control customization is often a heavy-weight response. Les effets simplifient ce processus et sont généralement utilisés pour les petits changements de style.Effects simplify this process, and are typically used for small styling changes. Pour plus d’informations, consultez Effets.For more information, see Effects.

Pourquoi les renderers personnalisés sont-ils nécessaires ?Examining Why Custom Renderers are Necessary

Le changement de l’apparence d’un contrôle Xamarin.Forms, sans renderer personnalisé, est un processus en deux étapes qui implique la création d’un contrôle personnalisé par l’intermédiaire d’une sous-classe, puis la consommation du contrôle personnalisé à la place du contrôle d’origine.Changing the appearance of a Xamarin.Forms control, without using a custom renderer, is a two-step process that involves creating a custom control through subclassing, and then consuming the custom control in place of the original control. L’exemple de code suivant montre un exemple d’utilisation d’une sous-classe du contrôle Entry :The following code example shows an example of subclassing the Entry control:

public class MyEntry : Entry
{
  public MyEntry ()
  {
    BackgroundColor = Color.Gray;
  }
}

Le contrôle MyEntry est un contrôle EntryBackgroundColor est de couleur grise. Vous pouvez le référencer en XAML en déclarant un espace de noms pour son emplacement et en utilisant le préfixe d’espace de noms sur l’élément de contrôle.The MyEntry control is an Entry control where the BackgroundColor is set to gray, and can be referenced in Xaml by declaring a namespace for its location and using the namespace prefix on the control element. L’exemple de code suivant montre comment le contrôle personnalisé MyEntry peut être consommé par ContentPage :The following code example shows how the MyEntry custom control can be consumed by a ContentPage:

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

Le préfixe d’espace de noms local peut varier.The local namespace prefix can be anything. Toutefois, les valeurs namespace et assembly doivent correspondre aux détails du contrôle personnalisé.However, the namespace and assembly values must match the details of the custom control. Une fois l’espace de noms déclaré, le préfixe est utilisé pour référencer le contrôle personnalisé.Once the namespace is declared, the prefix is used to reference the custom control.

Notes

Il est beaucoup plus simple de définir xmlns dans des projets de bibliothèque .NET Standard que dans des projets partagés.Defining the xmlns is much simpler in .NET Standard library projects than Shared Projects. Une bibliothèque .NET Standard étant compilée dans un assembly, il est facile de déterminer ce que la valeur assembly=CustomRenderer doit être.A .NET Standard library is compiled into an assembly so it's easy to determine what the assembly=CustomRenderer value should be. Quand vous utilisez des projets partagés, toutes les ressources partagées (y compris le XAML) sont compilées dans chacun des projets de référence. Si les projets iOS, Android et UWP ont leurs propres noms d’assemblys, il est alors impossible d’écrire la déclaration xmlns puisque la valeur doit être différente pour chaque application.When using Shared Projects, all the shared assets (including the XAML) are compiled into each of the referencing projects, which means that if the iOS, Android, and UWP projects have their own assembly names it is impossible to write the xmlns declaration because the value needs to be different for each application. Les contrôles personnalisés en XAML pour les projets partagés nécessitent que chaque projet d’application soit configuré avec le même nom d’assembly.Custom controls in XAML for Shared Projects will require every application project to be configured with the same assembly name.

Le contrôle personnalisé MyEntry est ensuite restitué sur chaque plateforme, avec un arrière-plan de couleur grise, comme le montrent les captures d’écran suivantes :The MyEntry custom control is then rendered on each platform, with a gray background, as shown in the following screenshots:

Pour changer la couleur d’arrière-plan du contrôle sur chaque plateforme, nous avons recouru exclusivement à une sous-classe du contrôle.Changing the background color of the control on each platform has been accomplished purely through subclassing the control. Le champ d’action de cette technique est toutefois limité, car il n’est pas possible de tirer parti des améliorations et des personnalisations spécifiques à la plateforme.However, this technique is limited in what it can achieve as it is not possible to take advantage of platform-specific enhancements and customizations. Quand ils sont nécessaires, des renderers personnalisés doivent être implémentés.When they are required, custom renderers must be implemented.

Création d’une classe de renderer personnaliséCreating a Custom Renderer Class

Le processus de création d’une classe de renderer personnalisé est le suivant :The process for creating a custom renderer class is as follows:

  1. Créez une sous-classe de la classe de renderer qui restitue le contrôle natif.Create a subclass of the renderer class that renders the native control.
  2. Remplacez la méthode qui restitue le contrôle natif et écrivez la logique pour le personnaliser.Override the method that renders the native control and write logic to customize the control. La méthode OnElementChanged est souvent utilisée pour restituer le contrôle natif, qui est appelé quand le contrôle Xamarin.Forms correspondant est créé.Often, the OnElementChanged method is used to render the native control, which is called when the corresponding Xamarin.Forms control is created.
  3. Ajoutez un attribut ExportRenderer à la classe du renderer personnalisé pour spécifier qu’il sera utilisé pour restituer le contrôle Xamarin.Forms.Add an ExportRenderer attribute to the custom renderer class to specify that it will be used to render the Xamarin.Forms control. Cet attribut est utilisé pour inscrire le renderer personnalisé auprès de Xamarin.Forms.This attribute is used to register the custom renderer with Xamarin.Forms.

Notes

Pour la plupart des éléments Xamarin.Forms, il est facultatif de fournir un renderer personnalisé dans chaque projet de plateforme.For most Xamarin.Forms elements, it is optional to provide a custom renderer in each platform project. Si un renderer personnalisé n’est pas inscrit, le renderer par défaut de la classe de base du contrôle est utilisé.If a custom renderer isn't registered, then the default renderer for the control's base class will be used. Toutefois, des renderers personnalisés sont nécessaires dans chaque projet de plateforme au moment de la restitution d’un élément View ou ViewCell.However, custom renderers are required in each platform project when rendering a View or ViewCell element.

Les rubriques de cette série fournissent des démonstrations et des explications de ce processus pour différents éléments Xamarin.Forms.The topics in this series will provide demonstrations and explanations of this process for different Xamarin.Forms elements.

Résolution des problèmesTroubleshooting

Si un contrôle personnalisé est contenu dans un projet de bibliothèque .NET Standard ajouté à la solution (autrement dit, pas la bibliothèque .NET Standard créée par le modèle de projet d’application Xamarin.Forms dans Visual Studio pour Mac/Visual Studio), une exception peut se produire dans iOS lors d’une tentative d’accès au contrôle personnalisé.If a custom control is contained in a .NET Standard library project that's been added to the solution (i.e. not the .NET Standard library created by the Visual Studio for Mac/Visual Studio Xamarin.Forms App project template), an exception may occur in iOS when attempting to access the custom control. Si ce problème se produit, vous pouvez le résoudre en créant une référence au contrôle personnalisé à partir de la classe AppDelegate :If this issue occurs it can be resolved by creating a reference to the custom control from the AppDelegate class:

var temp = new ClassInPCL(); // in AppDelegate, but temp not used anywhere

Le compilateur est ainsi forcé à reconnaître le type ClassInPCL en le résolvant.This forces the compiler to recognize the ClassInPCL type by resolving it. Vous pouvez également ajouter l’attribut Preserve à la classe AppDelegate pour obtenir le même résultat :Alternatively, the Preserve attribute can be added to the AppDelegate class to achieve the same result:

[assembly: Preserve (typeof (ClassInPCL))]

Une référence au type ClassInPCL est alors créée, indiquant son caractère obligatoire au moment de l’exécution.This creates a reference to the ClassInPCL type, indicating that it's required at runtime. Pour plus d’informations, consultez Conservation du code.For more information, see Preserving Code.

RécapitulatifSummary

Dans cet article, nous avons examiné les renderers personnalisés et décrit leur processus de création.This article has provided an introduction to custom renderers, and has outlined the process for creating a custom renderer. Les renderers personnalisés fournissent une approche puissante pour personnaliser l’apparence et le comportement des contrôles Xamarin.Forms.Custom renderers provide a powerful approach for customizing the appearance and behavior of Xamarin.Forms controls. Ils peuvent être utilisés aussi bien pour les petits changements de style que pour la personnalisation sophistiquée de la disposition et du comportement d’une plateforme.They can be used for small styling changes or sophisticated platform-specific layout and behavior customization.