Spécificités de la plateforme

Article
07/13/2023

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

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

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

Notes

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 spécifique soit appliquée.

Les spécificités de la plateforme consommées via les objets de retour IPlatformElementConfiguration de l’API On<T> fluent code. Cela permet d’appeler plusieurs spécificités de la plateforme sur le même objet avec une méthode en cascade.

Pour plus d’informations sur les spécificités de la plateforme fournies par Xamarin.Forms, consultez Spécificités de la plateforme iOS, Spécificités de la plateforme Android et 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 Effects. Un effet fournit la fonctionnalité spécifique, qui est ensuite exposée via une plateforme spécifique. Le résultat est un effet qui peut être consommé plus facilement via XAML et via une API fluent code.

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

Implémentez la fonctionnalité spécifique 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 Platform-Specific.
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 spécifique d’être consommée via 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 propre à la plateforme est que l’effet peut être consommé plus facilement via XAML et via une API fluent code.

Notes

Il est prévu que les fournisseurs utilisent cette technique pour créer leurs propres caractéristiques de la plateforme, afin de faciliter la consommation par les utilisateurs. Bien que les utilisateurs puissent choisir de créer leurs propres caractéristiques de la plateforme, il convient de noter que cela 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 qui ajoute une ombre au texte affiché par un Label contrôle :

Spécifique à la plateforme de l’ombre

L’exemple d’application implémente le Shadow propre à la plateforme sur chaque plateforme, pour faciliter la compréhension. Toutefois, à part chaque implémentation d’effet spécifique à la plateforme, l’implémentation de la classe Shadow est en grande partie 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 classe spécifique à la plateforme est créée en tant que public static classe :

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

Les sections suivantes traitent de 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 pour permettre la Shadow 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 permet d’ajouter l’Effet MyCompany.LabelShadowEffect au contrôle auquel la Shadow classe est attachée et de le supprimer. 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 AttachEffect méthode ou DetachEffect 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.

Notes

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 de l’identificateur unique spécifié sur 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 pour permettre la Shadow 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 et SetIsShadowed appellent les accesseurs get et set pour la IsShadowed propriété jointe, respectivement. 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 les instances d’iOS.

Création de l’effet

Le Shadow spécifique à la plateforme ajoute à MyCompany.LabelShadowEffect un Labelet le 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 ait la truevaleur , et à condition que la Shadow plateforme spécifique ait été appelée sur la même plateforme pour laquelle l’effet est implémenté. Cette case activée est effectuée avec la OnThisPlatform méthode .

Si la valeur de la Shadow.IsShadowed propriété jointe change au moment de l’exécution, l’effet doit répondre en supprimant l’ombre. Par conséquent, une version remplacé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 des paramètres d’effet en tant que propriétés jointes.

Consommation de la plateforme propre à la plateforme

L’élément Shadow spécifique à la plateforme est consommé 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>

Vous pouvez également la consommer à 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 propre à la plateforme

Ressources supplémentaires

Ressources supplémentaires

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 propre à la plateforme

Liens connexes

Ressources supplémentaires

Ressources supplémentaires