Plattformeigenschaften

Plattformspezifische Funktionen ermöglichen es Ihnen, Funktionen zu 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 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. 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. Im 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 kann T die iOS, Android, oder Windows 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, nicht 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 genutzt werden, geben Objekte zurück IPlatformElementConfiguration . Auf diese Weise können mehrere plattformspezifische Objekte für dasselbe Objekt mit Methodenkakadierung aufgerufen werden.

Weitere Informationen zu den plattformspezifischen Xamarin.FormsAngaben finden Sie unter iOS-Plattformspezifischen, Android-Plattformspezifischen und Windows-Plattformspezifischen.

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 Plattform 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 plattformspezifischen 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 Creating the Effect.

Das Ergebnis der Bereitstellung eines Effekts als plattformspezifisch ist, 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 benutzerfreundliche Nutzung zu ermöglichen. Benutzer können zwar ihre eigenen Plattformspezifischen erstellen, es sollte jedoch beachtet werden, dass mehr Code erforderlich ist als das Erstellen und Verwenden eines Effekts.

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

Die Beispielanwendung implementiert die Shadow plattformspezifischen Plattform auf jeder Plattform, um das Verständnis zu erleichtern. Abgesehen von jeder plattformspezifischen Effect-Implementierung ist die Implementierung der Shadow-Klasse jedoch weitgehend identisch für jede Plattform. Daher konzentriert sich dieses Handbuch auf die Implementierung der Shadow-Klasse und den damit verbundenen 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 Shadow plattformspezifischen Eigenschaft hinzugefügt werden, um den 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 Oder-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 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, der eine Verkettung des Auflösungsgruppennamens und des eindeutigen Bezeichners darstellt, der für die Effektimplementierung 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 plattformspezifisch Shadow 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- bzw. Set-Accessoren für die IsShadowed 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 Add-Ins MyCompany.LabelShadowEffect zu einem Label, und 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, die IsShadowed angefügte Eigenschaft ist auf festgelegt trueund vorausgesetzt, dass die Shadow plattformspezifische Auf der gleichen Plattform aufgerufen wurde, für die der Effekt implementiert ist. 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 der Schatten entfernt wird. Daher wird eine überschriebene Version der Methode verwendet, um auf die Änderung der OnElementPropertyChanged bindungsfähigen 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 der plattformspezifischen

Die Shadow plattformspezifischen Daten werden 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 sie mit der Fluent-API von C# genutzt werden:

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

...

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

Verwandte Links

• iOS-Plattformspezifische
• Android-Plattformspezifische
• Windows-Plattformspezifische
• Anpassen von Steuerelementen mit Effekten
• Angefügte Eigenschaften
• PlatformConfiguration-API