Plattformeigenschaften

  • Artikel

Beispiel herunterladen Das Beispiel herunterladen

Mit plattformspezifischen Funktionen können Sie Funktionen nutzen, die nur auf einer bestimmten Plattform verfügbar sind, ohne benutzerdefinierte Renderer oder Effekte zu implementieren.

Der Prozess für die Verwendung einer plattformspezifischen über XAML oder über die Fluent-Code-API sieht wie folgt aus:

  1. Fügen Sie eine xmlns Deklaration oder using Direktive für den Xamarin.Forms.PlatformConfiguration Namespace hinzu.
  2. Fügen Sie eine xmlns Deklaration oder using Direktive für den Namespace hinzu, der die plattformspezifische Funktionalität enthält:
    1. Unter iOS ist dies der Xamarin.Forms.PlatformConfiguration.iOSSpecific Namespace.
    2. Unter Android ist dies der Xamarin.Forms.PlatformConfiguration.AndroidSpecific Namespace. Für Android AppCompat ist dies der Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat Namespace.
    3. Auf der Universelle Windows-Plattform ist dies der Xamarin.Forms.PlatformConfiguration.WindowsSpecific Namespace.
  3. Wenden Sie die plattformspezifische aus XAML oder aus Code mit der On<T> Fluent-API an. Der Wert von T kann die iOSTypen , Androidoder Windows aus dem Xamarin.Forms.PlatformConfiguration Namespace sein.

Hinweis

Beachten Sie, dass der Versuch, eine plattformspezifische Plattform auf einer Plattform zu nutzen, auf der sie nicht verfügbar ist, nicht zu einem Fehler führt. Stattdessen wird der Code ausgeführt, ohne dass der plattformspezifische angewendet wird.

Plattformspezifische Objekte, die über die On<T> Fluent-Code-API verwendet werden, geben Objekte zurück IPlatformElementConfiguration . Dadurch können mehrere plattformspezifische Elemente für dasselbe Objekt mit Methodenkadierung aufgerufen werden.

Weitere Informationen zu den von bereitgestellten Xamarin.FormsPlattformspezifischen Informationen finden Sie unter iOS-Plattformspezifischen, Android-Plattformspezifischen und Windows-Plattformspezifischen.

Erstellen von Plattformspezifischen

Anbieter können mit Effects ihre eigenen Plattformspezifischen erstellen. Ein Effekt stellt die spezifische Funktionalität bereit, die dann über eine plattformspezifische verfügbar gemacht wird. Das Ergebnis ist ein Effekt, der einfacher über XAML und eine Fluent-Code-API genutzt werden kann.

Der Prozess zum Erstellen einer plattformspezifischen Datei sieht wie folgt aus:

  1. Implementieren Sie die spezifische Funktionalität als Effekt. Weitere Informationen finden Sie unter Erstellen eines Effekts.
  2. Erstellen Sie eine plattformspezifische Klasse, die den Effekt verfügbar macht. Weitere Informationen finden Sie unter Erstellen einer Platform-Specific-Klasse.
  3. Implementieren Sie in der plattformspezifischen Klasse eine angefügte Eigenschaft, damit die plattformspezifische über XAML verwendet werden kann. Weitere Informationen finden Sie unter Hinzufügen einer angefügten Eigenschaft.
  4. Implementieren Sie in der plattformspezifischen Klasse Erweiterungsmethoden, um die plattformspezifische Nutzung über eine Fluent-Code-API zu ermöglichen. Weitere Informationen finden Sie unter Hinzufügen von Erweiterungsmethoden.
  5. Ändern Sie die Effektimplementierung so, dass der Effekt nur angewendet wird, wenn der plattformspezifische auf derselben Plattform wie der Effekt aufgerufen wurde. Weitere Informationen finden Sie unter Erstellen des Effekts.

Das Ergebnis der Bereitstellung eines Effekts als plattformspezifisch ist, dass der Effekt einfacher über XAML und eine Fluent-Code-API genutzt werden kann.

Hinweis

Es ist geplant, dass Anbieter diese Technik verwenden, um ihre eigenen Plattformspezifischen zu erstellen, um die Benutzer zu vereinfachen. Benutzer können zwar ihre eigenen Plattformspezifischen erstellen, es sollte jedoch beachtet werden, dass es mehr Code erfordert als das Erstellen und Verwenden eines Effekts.

Die Beispielanwendung veranschaulicht eine Shadow plattformspezifische, die dem Text, der von einem Steuerelement angezeigt wird, einen Label Schatten hinzufügt:

Schattenplattformspezifisch

Die Beispielanwendung implementiert die Shadow plattformspezifische auf jeder Plattform, um das Verständnis zu erleichtern. Abgesehen von jeder plattformspezifischen Effect-Implementierung ist die Implementierung der Shadow-Klasse jedoch für jede Plattform weitgehend identisch. Daher konzentriert sich dieser Leitfaden auf die Implementierung der Shadow-Klasse und der zugehörigen Effect-Klasse auf einer einzelnen Plattform.

Weitere Informationen zu Effekten finden Sie unter Anpassen von Steuerelementen mit Effekten.

Erstellen einer plattformspezifischen Klasse

Eine plattformspezifische Klasse wird erstellt public static :

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

In den folgenden Abschnitten wird die Implementierung des Shadow plattformspezifischen und zugehörigen Effekts erläutert.

Hinzufügen einer angefügten Eigenschaft

Eine angefügte Eigenschaft muss der plattformspezifischen hinzugefügt werden, um die Shadow Nutzung über XAML zu ermöglichen:

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);
            }
        }
    }
}

Die IsShadowed angefügte Eigenschaft wird verwendet, um dem SteuerelementShadow, an das die MyCompany.LabelShadowEffect Klasse angefügt ist, den Effekt hinzuzufügen und daraus zu entfernen. Diese angefügte Eigenschaft registriert die OnIsShadowedPropertyChanged-Methode, die ausgeführt wird, wenn der Wert der Eigenschaft geändert wird. Diese Methode ruft wiederum die - oder DetachEffect -AttachEffectMethode auf, um den Effekt basierend auf dem Wert der IsShadowed angefügten Eigenschaft hinzuzufügen oder zu entfernen. Der Effekt wird dem Steuerelement hinzugefügt oder daraus entfernt, indem die Auflistung des Steuerelements Effects geändert wird.

Hinweis

Beachten Sie, dass der Effekt aufgelöst wird, indem ein Wert angegeben wird, bei dem es sich um eine Verkettung des Auflösungsgruppennamens und des eindeutigen Bezeichners handelt, der in der Effect-Implementierung angegeben ist. Weitere Informationen finden Sie unter Erstellen eines Effekts.

Weitere Informationen zu angefügten Eigenschaften finden Sie unter Angefügte Eigenschaften.

Hinzufügen von Erweiterungsmethoden

Erweiterungsmethoden müssen der plattformspezifischen hinzugefügt werden, um die Shadow Nutzung über eine Fluent-Code-API zu ermöglichen:

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;
        }
        ...
    }
}

Die IsShadowed Erweiterungsmethoden und SetIsShadowed rufen die Get- und Set-Accessoren für die IsShadowed angefügte Eigenschaft auf. Jede Erweiterungsmethode arbeitet mit dem IPlatformElementConfiguration<iOS, FormsElement> Typ, der angibt, dass das plattformspezifische auf Instanzen von iOS aufgerufen Label werden kann.

Erstellen des Effekts

Der Shadow plattformspezifische fügt einem MyCompany.LabelShadowEffectLabelhinzu und entfernt es. Im folgenden Codebeispiel wird die Implementierung von LabelShadowEffect für das iOS-Projekt veranschaulicht:

[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);
            }
        }
    }
}

Die UpdateShadow -Methode legt Eigenschaften zum Erstellen des Schattens fest Control.Layer , vorausgesetzt, die IsShadowed angefügte Eigenschaft ist auf truefestgelegt, und vorausgesetzt, dass die Shadow plattformspezifische auf derselben Plattform aufgerufen wurde, für die der Effekt implementiert wurde. Diese Überprüfung wird mit der OnThisPlatform -Methode durchgeführt.

Wenn sich der Wert der Shadow.IsShadowed angefügten Eigenschaft zur Laufzeit ändert, muss der Effekt reagieren, indem er den Schatten entfernt. Daher wird eine überschriebene Version der OnElementPropertyChanged -Methode verwendet, um auf die Änderung der bindbaren Eigenschaft durch Aufrufen der UpdateShadow -Methode zu reagieren.

Weitere Informationen zum Erstellen eines Effekts finden Sie unter Erstellen eines Effekts und Übergeben von Effektparametern als angefügte Eigenschaften.

Nutzen des plattformspezifischen

Das Shadow plattformspezifische wird in XAML verwendet, indem die Shadow.IsShadowed angefügte Eigenschaft auf einen boolean Wert festgelegt wird:

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

Alternativ kann es über C# mithilfe der Fluent-API verwendet werden:

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

...

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