Funkcje specyficzne dla platformy

Artykuł
10/01/2018

Specyficzne dla platformy umożliwiają korzystanie z funkcji, które są dostępne tylko na określonej platformie, bez implementowania niestandardowych modułów renderujących ani efektów.

Proces korzystania z platformy za pomocą języka XAML lub interfejsu API płynnego kodu jest następujący:

Dodaj deklarację lub using dyrektywę xmlns dla Xamarin.Forms.PlatformConfiguration przestrzeni nazw.
Dodaj deklarację lub using dyrektywę xmlns dla przestrzeni nazw, która zawiera funkcje specyficzne dla platformy:
1. W systemie iOS jest Xamarin.Forms.PlatformConfiguration.iOSSpecific to przestrzeń nazw.
2. W systemie Android jest Xamarin.Forms.PlatformConfiguration.AndroidSpecific to przestrzeń nazw. W przypadku aplikacji systemu AndroidCompat jest Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat to przestrzeń nazw.
3. W platforma uniwersalna systemu Windows jest Xamarin.Forms.PlatformConfiguration.WindowsSpecific to przestrzeń nazw.
Zastosuj specyficzny dla platformy kod XAML lub z kodu za pomocą płynnego interfejsu On<T> API. Wartość T może być iOStypu , Androidlub Windows z Xamarin.Forms.PlatformConfiguration przestrzeni nazw.

Uwaga

Należy pamiętać, że próba korzystania z platformy specyficznej dla platformy, na której jest niedostępna, nie spowoduje wystąpienia błędu. Zamiast tego kod zostanie wykonany bez zastosowania specyficznego dla platformy.

Specyficzne dla platformy używane za pośrednictwem płynnych obiektów zwracanych IPlatformElementConfiguration interfejsu On<T> API kodu. Dzięki temu można wywołać wiele specyficznych dla platformy obiektów w tym samym obiekcie z kaskadową metodą.

Aby uzyskać więcej informacji na temat specyficznych dla platformy udostępnianych przez Xamarin.Formsprogram , zobacz iOS Platform-Specifics, Android Platform-Specifics and Windows Platform-Specifics (Specyficzne dla platformy systemu Android i Specyficzne dla platformy systemu Windows).

Tworzenie specyficznych dla platformy

Dostawcy mogą tworzyć własne specyficzne dla platformy efekty. Efekt zapewnia konkretne funkcje, które są następnie udostępniane za pośrednictwem specyficznej dla platformy. Wynikiem jest efekt, który może być łatwiej używany za pomocą języka XAML i za pośrednictwem płynnego interfejsu API kodu.

Proces tworzenia specyficznego dla platformy jest następujący:

Zaimplementuj określoną funkcjonalność jako efekt. Aby uzyskać więcej informacji, zobacz Tworzenie efektu.
Utwórz klasę specyficzną dla platformy, która uwidoczni efekt. Aby uzyskać więcej informacji, zobacz Tworzenie klasy specyficznej dla platformy.
W klasie specyficznej dla platformy zaimplementuj dołączoną właściwość, aby umożliwić korzystanie z platformy za pośrednictwem języka XAML. Aby uzyskać więcej informacji, zobacz Dodawanie dołączonej właściwości.
W klasie specyficznej dla platformy zaimplementuj metody rozszerzenia, aby umożliwić korzystanie z platformy za pośrednictwem płynnego interfejsu API kodu. Aby uzyskać więcej informacji, zobacz Dodawanie metod rozszerzeń.
Zmodyfikuj implementację efektu tak, aby efekt był stosowany tylko wtedy, gdy element specyficzny dla platformy został wywołany na tej samej platformie co efekt. Aby uzyskać więcej informacji, zobacz Tworzenie efektu.

Wynikiem uwidaczniania efektu jako specyficznego dla platformy jest to, że efekt może być łatwiej używany za pośrednictwem języka XAML i za pośrednictwem płynnego interfejsu API kodu.

Uwaga

Przewiduje się, że dostawcy będą używać tej techniki do tworzenia własnych specyficznych dla platformy, aby ułatwić korzystanie przez użytkowników. Chociaż użytkownicy mogą zdecydować się na utworzenie własnych specyficznych dla platformy, należy zauważyć, że wymaga więcej kodu niż tworzenie i używanie efektu.

Przykładowa aplikacja demonstruje specyficzną Shadow dla platformy, która dodaje cień do tekstu wyświetlanego przez kontrolkę Label :

Specyficzne dla platformy w tle

Przykładowa aplikacja implementuje platformę Shadow specyficzną dla każdej platformy, aby ułatwić zrozumienie. Jednak oprócz każdej implementacji efektu specyficznego dla platformy implementacja klasy Shadow jest w dużej mierze identyczna dla każdej platformy. W związku z tym ten przewodnik koncentruje się na implementacji klasy Shadow i skojarzonego wpływu na jedną platformę.

Aby uzyskać więcej informacji na temat efektów, zobacz Dostosowywanie kontrolek za pomocą efektów.

Tworzenie klasy specyficznej dla platformy

Specyficzna dla platformy jest tworzona public static jako klasa:

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

W poniższych sekcjach omówiono implementację efektu specyficznego Shadow dla platformy i skojarzonego z nią efektu.

Dodawanie dołączonej właściwości

Dołączona właściwość musi zostać dodana do specyficznej Shadow dla platformy, aby umożliwić użycie za pomocą języka 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);
            }
        }
    }
}

Dołączona IsShadowed właściwość służy do dodawania efektu do kontrolki MyCompany.LabelShadowEffect dołączonej Shadow do niej i usuwania jej z niej. Ta dołączona właściwość rejestruje metodę OnIsShadowedPropertyChanged , która zostanie wykonana po zmianie wartości właściwości. Z kolei ta metoda wywołuje metodę AttachEffect or DetachEffect , aby dodać lub usunąć efekt na podstawie wartości dołączonej IsShadowed właściwości. Efekt jest dodawany do kontrolki lub usuwany z tej kontrolki przez zmodyfikowanie kolekcji kontrolki Effects .

Uwaga

Należy pamiętać, że efekt jest rozpoznawany przez określenie wartości, która jest łączeniem nazwy grupy rozpoznawania i unikatowego identyfikatora określonego w implementacji efektu. Aby uzyskać więcej informacji, zobacz Tworzenie efektu.

Aby uzyskać więcej informacji na temat dołączonych właściwości, zobacz Dołączone właściwości.

Dodawanie metod rozszerzeń

Metody rozszerzeń należy dodać do specyficznego Shadow dla platformy, aby umożliwić użycie za pośrednictwem płynnego interfejsu API kodu:

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

Metody IsShadowed i SetIsShadowed rozszerzenia wywołują metody get i set dla dołączonej IsShadowed właściwości odpowiednio. Każda metoda rozszerzenia działa na IPlatformElementConfiguration<iOS, FormsElement> typie, który określa, że można wywołać Label specyficzne dla platformy wystąpienia z systemu iOS.

Tworzenie efektu

Specyficzny Shadow dla platformy element dodaje element MyCompany.LabelShadowEffect do Labelelementu i usuwa go. Poniższy przykład kodu przedstawia implementację LabelShadowEffect projektu systemu 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);
            }
        }
    }
}

Metoda UpdateShadow ustawia Control.Layer właściwości w celu utworzenia cienia, pod warunkiem, że IsShadowed dołączona właściwość jest ustawiona na true, i pod warunkiem, że Shadow właściwość specyficzna dla platformy została wywołana na tej samej platformie, dla którego zaimplementowano efekt. Ta kontrola jest wykonywana przy użyciu OnThisPlatform metody .

Shadow.IsShadowed Jeśli dołączona wartość właściwości zmieni się w czasie wykonywania, efekt musi odpowiadać przez usunięcie cienia. W związku z tym przesłonięć wersję OnElementPropertyChanged metody jest używana do reagowania na zmianę właściwości możliwej do powiązania przez wywołanie UpdateShadow metody .

Aby uzyskać więcej informacji na temat tworzenia efektu, zobacz Creating an Effect and Passing Effect Parameters as Attached Properties (Tworzenie efektu i przekazywanie parametrów efektu jako dołączone właściwości).

Korzystanie z platformy

Specyficzny Shadow dla platformy jest używany w języku XAML, ustawiając Shadow.IsShadowed dołączoną boolean właściwość na wartość:

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

Alternatywnie można go używać z poziomu języka C# przy użyciu płynnego interfejsu API:

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

...

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

Udostępnij za pośrednictwem

Funkcje specyficzne dla platformy

Tworzenie specyficznych dla platformy

Tworzenie klasy specyficznej dla platformy

Dodawanie dołączonej właściwości

Dodawanie metod rozszerzeń

Tworzenie efektu

Korzystanie z platformy

Dodatkowe zasoby

Udostępnij za pośrednictwem

Funkcje specyficzne dla platformy

Tworzenie specyficznych dla platformy

Tworzenie klasy specyficznej dla platformy

Dodawanie dołączonej właściwości

Dodawanie metod rozszerzeń

Tworzenie efektu

Korzystanie z platformy

Pokrewne łącza

Dodatkowe zasoby