Funzionalità specifiche della piattaforma

Articolo
03/05/2024

Le specifiche della piattaforma consentono di usare funzionalità disponibili solo in una piattaforma specifica, senza implementare renderer o effetti personalizzati.

Il processo per l'uso di una piattaforma specifica tramite XAML o tramite l'API fluent code è la seguente:

Aggiungere una dichiarazione o using una xmlns direttiva per lo spazio dei Xamarin.Forms.PlatformConfiguration nomi.
Aggiungere una dichiarazione o using una xmlns direttiva per lo spazio dei nomi che contiene la funzionalità specifica della piattaforma:
1. In iOS questo è lo spazio dei Xamarin.Forms.PlatformConfiguration.iOSSpecific nomi .
2. In Android questo è lo spazio dei Xamarin.Forms.PlatformConfiguration.AndroidSpecific nomi . Per Android AppCompat, si tratta dello spazio dei Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat nomi .
3. Nella piattaforma UWP (Universal Windows Platform) questo è lo spazio dei Xamarin.Forms.PlatformConfiguration.WindowsSpecific nomi .
Applicare il codice specifico della piattaforma da XAML o dal codice con l'API On<T> Fluent. Il valore di T può essere i iOStipi , Androido Windows dello spazio dei Xamarin.Forms.PlatformConfiguration nomi .

Nota

Si noti che il tentativo di utilizzare una piattaforma specifica di una piattaforma in cui non è disponibile non genererà un errore. Il codice verrà invece eseguito senza l'applicazione specifica della piattaforma.

Specifiche della piattaforma utilizzate tramite l'API On<T> fluent code restituiscono IPlatformElementConfiguration oggetti. In questo modo è possibile richiamare più specifiche della piattaforma sullo stesso oggetto con propagazione del metodo.

Per altre informazioni sulle specifiche della piattaforma fornite da Xamarin.Forms, vedere Specifiche della piattaforma iOS, Specifiche della piattaforma Android e Specifiche della piattaforma Windows.

Creazione di specifiche della piattaforma

I fornitori possono creare specifiche della piattaforma con Effects. Un effetto fornisce la funzionalità specifica, che viene quindi esposta tramite una piattaforma specifica. Il risultato è un effetto che può essere usato più facilmente tramite XAML e tramite un'API fluent code.

Il processo per la creazione di una piattaforma specifica è il seguente:

Implementare la funzionalità specifica come effetto. Per altre informazioni, vedere Creazione di un effetto.
Creare una classe specifica della piattaforma che esporrà l'effetto. Per altre informazioni, vedere Creazione di una classe specifica della piattaforma.
Nella classe specifica della piattaforma implementare una proprietà associata per consentire l'utilizzo della piattaforma specifica della piattaforma tramite XAML. Per altre informazioni, vedere Aggiunta di una proprietà associata.
Nella classe specifica della piattaforma implementare metodi di estensione per consentire l'utilizzo specifico della piattaforma tramite un'API fluent code. Per altre informazioni, vedere Aggiunta di metodi di estensione.
Modificare l'implementazione dell'effetto in modo che l'effetto venga applicato solo se la piattaforma specifica della piattaforma è stata richiamata nella stessa piattaforma dell'effetto. Per altre informazioni, vedere Creazione dell'effetto.

Il risultato dell'esposizione di un effetto come piattaforma specifica è che l'effetto può essere usato più facilmente tramite XAML e tramite un'API fluent code.

Nota

Si prevede che i fornitori useranno questa tecnica per creare specifiche della piattaforma, per facilitare l'utilizzo da parte degli utenti. Anche se gli utenti possono scegliere di creare specifiche della piattaforma, è necessario notare che richiede più codice rispetto alla creazione e all'utilizzo di un effetto.

L'applicazione di esempio illustra un'ombreggiaturaShadow specifica della piattaforma che aggiunge un'ombreggiatura al testo visualizzato da un Label controllo :

Shadow Platform-Specific

L'applicazione di esempio implementa la Shadow piattaforma specifica di ogni piattaforma, per facilitare la comprensione. Tuttavia, a parte ogni implementazione dell'effetto specifica della piattaforma, l'implementazione della classe Shadow è in gran parte identica per ogni piattaforma. Pertanto, questa guida è incentrata sull'implementazione della classe Shadow e sull'effetto associato su una singola piattaforma.

Per altre informazioni sugli effetti, vedere Personalizzazione dei controlli con effetti.

Creazione di una classe specifica della piattaforma

Un elemento specifico della piattaforma viene creato come public static classe:

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

Le sezioni seguenti illustrano l'implementazione dell'effetto specifico della Shadow piattaforma e associato.

Aggiunta di una proprietà associata

È necessario aggiungere una proprietà associata all'elemento specifico della piattaforma per consentire l'utilizzo Shadow tramite 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 proprietà associata viene utilizzata per aggiungere l'effetto MyCompany.LabelShadowEffect a e rimuoverla dal controllo a cui è associata la Shadow classe. Tale proprietà associata registra il metodo OnIsShadowedPropertyChanged che verrà eseguito quando cambia il valore della proprietà. A sua volta, questo metodo chiama il AttachEffect metodo o DetachEffect per aggiungere o rimuovere l'effetto in base al valore della IsShadowed proprietà associata. L'effetto viene aggiunto o rimosso dal controllo modificando la raccolta del Effects controllo.

Nota

Si noti che l'effetto viene risolto specificando un valore che rappresenta una concatenazione del nome del gruppo di risoluzione e dell'identificatore univoco specificato nell'implementazione dell'effetto. Per altre informazioni, vedere Creazione di un effetto.

Per altre informazioni sulle proprietà associate, vedere Proprietà associate.

Aggiunta di metodi di estensione

I metodi di estensione devono essere aggiunti alla piattaforma specifica per consentire l'utilizzo Shadow tramite un'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;
        }
        ...
    }
}

I IsShadowed metodi di estensione e SetIsShadowed richiamano rispettivamente le funzioni di accesso get e set per la IsShadowed proprietà associata. Ogni metodo di estensione opera sul IPlatformElementConfiguration<iOS, FormsElement> tipo , che specifica che è possibile richiamare Label le istanze specifiche della piattaforma da iOS.

Creazione dell'effetto

Lo Shadow specifico della piattaforma aggiunge a MyCompany.LabelShadowEffect un Labeloggetto e lo rimuove. L'esempio di codice seguente mostra l'implementazione di LabelShadowEffect per il progetto 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);
            }
        }
    }
}

Il UpdateShadow metodo imposta Control.Layer le proprietà per creare l'ombreggiatura, purché la IsShadowed proprietà associata sia impostata su truee a condizione che l'oggetto specifico della Shadow piattaforma sia stato richiamato sulla stessa piattaforma per cui viene implementato l'effetto. Questo controllo viene eseguito con il OnThisPlatform metodo .

Se il valore della Shadow.IsShadowed proprietà associata cambia in fase di esecuzione, l'effetto deve rispondere rimuovendo l'ombreggiatura. Pertanto, viene usata una versione sottoposta a override del OnElementPropertyChanged metodo per rispondere alla modifica della proprietà associabile chiamando il UpdateShadow metodo .

Per altre informazioni sulla creazione di un effetto, vedere Creazione di un effetto e passaggio di parametri di effetto come proprietà associate.

Utilizzo della piattaforma specifica della piattaforma

Lo specifico della Shadow piattaforma viene utilizzato in XAML impostando la Shadow.IsShadowed proprietà associata su un boolean valore:

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

In alternativa, può essere usato da C# usando l'API Fluent:

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

...

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

Funzionalità specifiche della piattaforma

Creazione di specifiche della piattaforma

Creazione di una classe specifica della piattaforma

Aggiunta di una proprietà associata

Aggiunta di metodi di estensione

Creazione dell'effetto

Utilizzo della piattaforma specifica della piattaforma

Collegamenti correlati

Risorse aggiuntive