Spécificités de la plateforme

Article
10/01/2018

Les spécificités de la plateforme vous permettent de consommer des fonctionnalités uniquement disponibles sur une plateforme spécifique, sans implémenter de renderers ou d’effets personnalisés.

Le processus de consommation d’une plateforme spécifique à une plateforme via XAML ou via l’API fluent code est le suivant :

Ajoutez une xmlns déclaration ou using une directive pour l’espace Xamarin.Forms.PlatformConfiguration de noms.
Ajoutez une xmlns déclaration ou using une directive pour l’espace de noms qui contient les fonctionnalités spécifiques à la plateforme :
1. Sur iOS, il s’agit de l’espace Xamarin.Forms.PlatformConfiguration.iOSSpecific de noms.
2. Sur Android, il s’agit de l’espace Xamarin.Forms.PlatformConfiguration.AndroidSpecific de noms. Pour Android AppCompat, il s’agit de l’espace Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat de noms.
3. Sur le plateforme Windows universelle, il s’agit de l’espace Xamarin.Forms.PlatformConfiguration.WindowsSpecific de noms.
Appliquez le code XAML spécifique à la plateforme ou à partir du code avec l’API On<T> Fluent. La valeur de T peut être le iOSou AndroidWindows les types de l’espace Xamarin.Forms.PlatformConfiguration de noms.

Remarque

Notez que la tentative d’utilisation d’une plateforme spécifique à une plateforme où elle n’est pas disponible n’entraîne pas d’erreur. Au lieu de cela, le code s’exécute sans que la plateforme soit appliquée.

Les spécificités de la plateforme consommées par le biais des objets de retour IPlatformElementConfiguration de l’API On<T> fluent code. Cela permet à plusieurs spécificités de la plateforme d’être appelées sur le même objet avec une cascade de méthode.

Pour plus d’informations sur les spécificités de la plateforme fournies par Xamarin.Forms, consultez Les spécificités de la plateforme iOS, les spécificités de la plateforme Android et les spécificités de la plateforme Windows.

Création de spécificités de la plateforme

Les fournisseurs peuvent créer leurs propres spécificités de plateforme avec Effets. Un effet fournit les fonctionnalités spécifiques, qui sont ensuite exposées par le biais d’une plateforme spécifique à la plateforme. Le résultat est un effet qui peut être plus facilement consommé via XAML et via une API fluent code.

Le processus de création d’une plateforme spécifique à la plateforme est le suivant :

Implémentez les fonctionnalités spécifiques en tant qu’effet. Pour plus d’informations, consultez Création d’un effet.
Créez une classe spécifique à la plateforme qui exposera l’effet. Pour plus d’informations, consultez Création d’une classe spécifique à la plateforme.
Dans la classe spécifique à la plateforme, implémentez une propriété jointe pour permettre à la plateforme d’être consommée via XAML. Pour plus d’informations, consultez Ajout d’une propriété jointe.
Dans la classe spécifique à la plateforme, implémentez des méthodes d’extension pour permettre à la plateforme d’être consommée par le biais d’une API fluent code. Pour plus d’informations, consultez Ajout de méthodes d’extension.
Modifiez l’implémentation de l’effet afin que l’effet soit appliqué uniquement si la plateforme spécifique a été appelée sur la même plateforme que l’effet. Pour plus d’informations, consultez Création de l’effet.

Le résultat de l’exposition d’un effet en tant que spécifique à la plateforme est que l’effet peut être plus facilement consommé via XAML et via une API de code Fluent.

Remarque

Il est prévu que les fournisseurs utilisent cette technique pour créer leurs propres spécificités de plateforme, pour faciliter la consommation par les utilisateurs. Bien que les utilisateurs choisissent de créer leurs propres spécificités de plateforme, il convient de noter qu’il nécessite plus de code que la création et la consommation d’un effet.

L’exemple d’application illustre une Shadow plateforme spécifique à la plateforme qui ajoute une ombre au texte affiché par un Label contrôle :

Spécifique à la plateforme d’ombres

L’exemple d’application implémente la Shadow plateforme spécifique à chaque plateforme, pour faciliter la compréhension. Toutefois, outre chaque implémentation d’effet spécifique à la plateforme, l’implémentation de la classe Shadow est largement identique pour chaque plateforme. Par conséquent, ce guide se concentre sur l’implémentation de la classe Shadow et de l’effet associé sur une plateforme unique.

Pour plus d’informations sur les effets, consultez Personnalisation des contrôles avec des effets.

Création d’une classe spécifique à la plateforme

Une plateforme spécifique est créée en tant que public static classe :

namespace MyCompany.Forms.PlatformConfiguration.iOS
{
  public static Shadow
  {
    ...
  }
}

Les sections suivantes décrivent l’implémentation de l’effet spécifique à la Shadow plateforme et associé.

Ajout d’une propriété jointe

Une propriété jointe doit être ajoutée à la plateforme spécifique à la Shadow plateforme pour permettre la consommation via XAML :

namespace MyCompany.Forms.PlatformConfiguration.iOS
{
    using System.Linq;
    using Xamarin.Forms;
    using Xamarin.Forms.PlatformConfiguration;
    using FormsElement = Xamarin.Forms.Label;

    public static class Shadow
    {
        const string EffectName = "MyCompany.LabelShadowEffect";

        public static readonly BindableProperty IsShadowedProperty =
            BindableProperty.CreateAttached("IsShadowed",
                                            typeof(bool),
                                            typeof(Shadow),
                                            false,
                                            propertyChanged: OnIsShadowedPropertyChanged);

        public static bool GetIsShadowed(BindableObject element)
        {
            return (bool)element.GetValue(IsShadowedProperty);
        }

        public static void SetIsShadowed(BindableObject element, bool value)
        {
            element.SetValue(IsShadowedProperty, value);
        }

        ...

        static void OnIsShadowedPropertyChanged(BindableObject element, object oldValue, object newValue)
        {
            if ((bool)newValue)
            {
                AttachEffect(element as FormsElement);
            }
            else
            {
                DetachEffect(element as FormsElement);
            }
        }

        static void AttachEffect(FormsElement element)
        {
            IElementController controller = element;
            if (controller == null || controller.EffectIsAttached(EffectName))
            {
                return;
            }
            element.Effects.Add(Effect.Resolve(EffectName));
        }

        static void DetachEffect(FormsElement element)
        {
            IElementController controller = element;
            if (controller == null || !controller.EffectIsAttached(EffectName))
            {
                return;
            }

            var toRemove = element.Effects.FirstOrDefault(e => e.ResolveId == Effect.Resolve(EffectName).ResolveId);
            if (toRemove != null)
            {
                element.Effects.Remove(toRemove);
            }
        }
    }
}

La IsShadowed propriété jointe est utilisée pour ajouter l’effet MyCompany.LabelShadowEffect et le supprimer, le contrôle auquel la Shadow classe est attachée. Cette propriété jointe inscrit la méthode OnIsShadowedPropertyChanged qui est exécutée au changement de la valeur de la propriété. À son tour, cette méthode appelle la ou DetachEffect la AttachEffect méthode pour ajouter ou supprimer l’effet en fonction de la valeur de la IsShadowed propriété jointe. L’effet est ajouté ou supprimé du contrôle en modifiant la collection du Effects contrôle.

Remarque

Notez que l’effet est résolu en spécifiant une valeur qui est une concaténation du nom du groupe de résolution et un identificateur unique spécifiés dans l’implémentation de l’effet. Pour plus d’informations, consultez Création d’un effet.

Pour plus d’informations sur les propriétés jointes, consultez Propriétés jointes.

Ajout de méthodes d’extension

Les méthodes d’extension doivent être ajoutées à la plateforme spécifique à la Shadow plateforme pour permettre la consommation via une API fluent code :

namespace MyCompany.Forms.PlatformConfiguration.iOS
{
    using System.Linq;
    using Xamarin.Forms;
    using Xamarin.Forms.PlatformConfiguration;
    using FormsElement = Xamarin.Forms.Label;

    public static class Shadow
    {
        ...
        public static bool IsShadowed(this IPlatformElementConfiguration<iOS, FormsElement> config)
        {
            return GetIsShadowed(config.Element);
        }

        public static IPlatformElementConfiguration<iOS, FormsElement> SetIsShadowed(this IPlatformElementConfiguration<iOS, FormsElement> config, bool value)
        {
            SetIsShadowed(config.Element, value);
            return config;
        }
        ...
    }
}

Les IsShadowed méthodes d’extension SetIsShadowed appellent respectivement les accesseurs get et set pour la IsShadowed propriété jointe. Chaque méthode d’extension fonctionne sur le IPlatformElementConfiguration<iOS, FormsElement> type, qui spécifie que la plateforme spécifique peut être appelée sur Label des instances à partir d’iOS.

Création de l’effet

La Shadow plateforme spécifique à la plateforme ajoute à MyCompany.LabelShadowEffect un Label, et la supprime. L’exemple de code suivant illustre l’implémentation de LabelShadowEffect pour le projet iOS :

[assembly: ResolutionGroupName("MyCompany")]
[assembly: ExportEffect(typeof(LabelShadowEffect), "LabelShadowEffect")]
namespace ShadowPlatformSpecific.iOS
{
    public class LabelShadowEffect : PlatformEffect
    {
        protected override void OnAttached()
        {
            UpdateShadow();
        }

        protected override void OnDetached()
        {
        }

        protected override void OnElementPropertyChanged(PropertyChangedEventArgs args)
        {
            base.OnElementPropertyChanged(args);

            if (args.PropertyName == Shadow.IsShadowedProperty.PropertyName)
            {
                UpdateShadow();
            }
        }

        void UpdateShadow()
        {
            try
            {
                if (((Label)Element).OnThisPlatform().IsShadowed())
                {
                    Control.Layer.CornerRadius = 5;
                    Control.Layer.ShadowColor = UIColor.Black.CGColor;
                    Control.Layer.ShadowOffset = new CGSize(5, 5);
                    Control.Layer.ShadowOpacity = 1.0f;
                }
                else if (!((Label)Element).OnThisPlatform().IsShadowed())
                {
                    Control.Layer.ShadowOpacity = 0;
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Cannot set property on attached control. Error: ", ex.Message);
            }
        }
    }
}

La UpdateShadow méthode définit les Control.Layer propriétés pour créer l’ombre, à condition que la IsShadowed propriété jointe soit définie truesur , et à condition que la Shadow plateforme spécifique a été appelée sur la même plateforme que celle pour laquelle l’effet est implémenté. Cette case activée est effectuée avec la OnThisPlatform méthode.

Si la valeur de propriété jointe change au moment de l’exécution Shadow.IsShadowed , l’effet doit répondre en supprimant l’ombre. Par conséquent, une version substituée de la OnElementPropertyChanged méthode est utilisée pour répondre à la modification de propriété pouvant être liée en appelant la UpdateShadow méthode.

Pour plus d’informations sur la création d’un effet, consultez Création d’un effet et passage de paramètres d’effet en tant que propriétés jointes.

Consommation de la plateforme spécifique à la plateforme

La Shadow plateforme spécifique à la plateforme est consommée en XAML en définissant la Shadow.IsShadowed propriété jointe sur une boolean valeur :

<ContentPage xmlns:ios="clr-namespace:MyCompany.Forms.PlatformConfiguration.iOS" ...>
  ...
  <Label Text="Label Shadow Effect" ios:Shadow.IsShadowed="true" ... />
  ...
</ContentPage>

Elle peut également être consommée à partir de C# à l’aide de l’API Fluent :

using Xamarin.Forms.PlatformConfiguration;
using MyCompany.Forms.PlatformConfiguration.iOS;

...

shadowLabel.On<iOS>().SetIsShadowed(true);

Spécificités de la plateforme

Création de spécificités de la plateforme

Création d’une classe spécifique à la plateforme

Ajout d’une propriété jointe

Ajout de méthodes d’extension

Création de l’effet

Consommation de la plateforme spécifique à la plateforme

Liens connexes

Ressources supplémentaires