Plattformeigenschaften

Download Sample Das Beispiel herunterladen

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

Der Prozess zum Verwenden einer plattformspezifischen Über XAML oder über die Fluent-Code-API lautet wie folgt:

  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. Bei iOS ist dies der Xamarin.Forms.PlatformConfiguration.iOSSpecific Namespace.
    2. Auf Android ist dies der Xamarin.Forms.PlatformConfiguration.AndroidSpecific Namespace. Für Android AppCompat ist dies der Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat Namespace.
    3. Auf dem Universelle Windows-Plattform ist dies der Xamarin.Forms.PlatformConfiguration.WindowsSpecific Namespace.
  3. Wenden Sie die Plattformspezifisch aus XAML oder code mit der On<T> Fluent-API an. Der Wert kann T das iOS, Androidoder Windows die Typen 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, zu einem Fehler führt. Stattdessen wird der Code ohne die plattformspezifische Anwendung ausgeführt.

Plattformspezifische Elemente, die über die On<T> Fluent-Code-API verwendet werden, geben Objekte zurück IPlatformElementConfiguration . Auf diese Weise können mehrere Plattformspezifische Objekte auf demselben Objekt mit Methodenkakacading aufgerufen werden.

Weitere Informationen zu den plattformspezifischen Informationen Xamarin.Formsfinden Sie unter iOS Platform-Specifics, Android Platform-Specifics und Windows Platform-Specifics.

Erstellen von Plattformspezifischen

Anbieter können ihre eigenen Plattformspezifischen mit Effects 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 über eine Fluent-Code-API genutzt werden kann.

Der Prozess zum Erstellen einer plattformspezifischen Version lautet wie folgt:

  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, um die plattformspezifische Nutzung über XAML zu ermöglichen. 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 die plattformspezifische Plattform auf derselben Plattform wie der Effekt aufgerufen wurde. Weitere Informationen finden Sie unter Erstellen des Effekts.

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

Hinweis

Es ist vorgesehen, dass Anbieter diese Technik verwenden werden, um ihre eigenen Plattformspezifischen zu erstellen, um die Nutzung durch Benutzer zu erleichtern. Während Benutzer sich für die Erstellung eigener Plattformspezifischer entscheiden, sollte darauf hingewiesen werden, dass es mehr Code erfordert als das Erstellen und Verwenden eines Effekts.

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

Shadow Platform-Specific

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

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

Erstellen einer plattformspezifischen Klasse

Eine plattformspezifische Klasse wird als public static Klasse erstellt:

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

In den folgenden Abschnitten wird die Implementierung des Shadow plattformspezifischen und damit verbundenen Effekts erläutert.

Hinzufügen einer angefügten Eigenschaft

Eine angefügte Eigenschaft muss der plattformspezifischen Eigenschaft hinzugefügt werden, um den Shadow Verbrauch ü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 den MyCompany.LabelShadowEffect Effekt hinzuzufügen und daraus zu entfernen, dem Steuerelement, an das die Shadow Klasse angefügt ist. 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 AttachEffect Methode DetachEffect 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 entfernt, indem die Auflistung des Steuerelements Effects geändert wird.

Hinweis

Beachten Sie, dass der Effekt aufgelöst wird, indem sie einen Wert angeben, der eine Verkettung des Auflösungsgruppennamens und eindeutigen Bezeichners darstellt, der für die 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 Shadow plattformspezifischen Hinzugefügt werden, um den Verbrauch ü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 Methoden und SetIsShadowed Erweiterungsmethoden rufen die Get- und Set-Accessors für die IsShadowed angefügte Eigenschaft bzw. die angefügte Eigenschaft auf. Jede Erweiterungsmethode wird auf dem IPlatformElementConfiguration<iOS, FormsElement> Typ ausgeführt, der angibt, dass die plattformspezifischen Instanzen von iOS aufgerufen Label werden können.

Erstellen des Effekts

Die Shadow plattformspezifische fügt das MyCompany.LabelShadowEffect Element zu einem Labelund entfernt sie. 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 Control.Layer Eigenschaften fest, um den Schatten zu erstellen, vorausgesetzt, dass die IsShadowed angefügte Eigenschaft auf truefestgelegt ist, und vorausgesetzt, dass die Shadow plattformspezifische Plattform auf derselben Plattform aufgerufen wurde, für die der Effekt implementiert wird. Diese Überprüfung wird mit der OnThisPlatform Methode ausgeführt.

Wenn sich der Shadow.IsShadowed angefügte Eigenschaftswert 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 bindungsfähigen Eigenschaft durch Aufrufen der UpdateShadow Methode zu reagieren.

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

Nutzen der plattformspezifischen

Die Shadow plattformspezifische Nutzung in XAML erfolgt durch Festlegen der Shadow.IsShadowed angefügten Eigenschaft auf einen boolean Wert:

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

Alternativ kann sie über die Fluent-API von C# genutzt werden:

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

...

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