Spesifikasi Platform

Artikel
10/01/2018

Khusus platform memungkinkan Anda untuk menggunakan fungsionalitas yang hanya tersedia pada platform tertentu, tanpa menerapkan perender atau efek kustom.

Proses untuk mengonsumsi platform khusus melalui XAML, atau melalui API kode fasih adalah sebagai berikut:

xmlns Tambahkan deklarasi atau using arahan Xamarin.Forms.PlatformConfiguration untuk namespace.
xmlns Tambahkan deklarasi atau using arahan untuk namespace layanan yang berisi fungsionalitas khusus platform:
1. Di iOS, ini adalah Xamarin.Forms.PlatformConfiguration.iOSSpecific namespace layanan.
2. Di Android, ini adalah Xamarin.Forms.PlatformConfiguration.AndroidSpecific namespace layanan. Untuk Android AppCompat, ini adalah Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat namespace.
3. Pada Platform Windows Universal, ini adalah Xamarin.Forms.PlatformConfiguration.WindowsSpecific namespace layanan.
Terapkan khusus platform dari XAML, atau dari kode dengan API yang On<T> fasih. Nilai T dapat berupa iOSjenis , Android, atau Windows dari Xamarin.Forms.PlatformConfiguration namespace.

Catatan

Perhatikan bahwa mencoba mengonsumsi platform khusus pada platform yang tidak tersedia tidak akan mengakibatkan kesalahan. Sebagai gantinya, kode akan dijalankan tanpa platform khusus yang diterapkan.

Khusus platform yang dikonsumsi melalui On<T> api kode fasih mengembalikan IPlatformElementConfiguration objek. Ini memungkinkan beberapa platform khusus untuk dipanggil pada objek yang sama dengan berkakade metode.

Untuk informasi selengkapnya tentang spesifikasi platform yang disediakan oleh , lihat iOS Platform-Specifics, Android Platform-Specifics, dan Windows Platform-Specifics.Xamarin.Forms

Membuat platform khusus

Vendor dapat membuat spesifikasi platform mereka sendiri dengan Efek. Efek menyediakan fungsionalitas tertentu, yang kemudian diekspos melalui platform khusus. Hasilnya adalah Efek yang dapat lebih mudah dikonsumsi melalui XAML, dan melalui API kode yang fasih.

Proses untuk membuat platform khusus adalah sebagai berikut:

Terapkan fungsionalitas tertentu sebagai Efek. Untuk informasi selengkapnya, lihat Membuat Efek.
Buat kelas khusus platform yang akan mengekspos Efek. Untuk informasi selengkapnya, lihat Membuat Kelas Khusus Platform.
Di kelas khusus platform, terapkan properti terlampir untuk memungkinkan khusus platform dikonsumsi melalui XAML. Untuk informasi selengkapnya, lihat Menambahkan Properti Terlampir.
Di kelas khusus platform, terapkan metode ekstensi untuk memungkinkan khusus platform dikonsumsi melalui API kode yang fasih. Untuk informasi selengkapnya, lihat Menambahkan Metode Ekstensi.
Ubah implementasi Efek sehingga Efek hanya diterapkan jika khusus platform telah dipanggil pada platform yang sama dengan Efek. Untuk informasi selengkapnya, lihat Membuat Efek.

Hasil dari mengekspos Efek sebagai spesifik platform adalah bahwa Efek dapat lebih mudah dikonsumsi melalui XAML dan melalui API kode yang fasih.

Catatan

Sangat disarankan bahwa vendor akan menggunakan teknik ini untuk membuat platform khusus mereka sendiri, untuk kemudahan konsumsi oleh pengguna. Meskipun pengguna dapat memilih untuk membuat spesifikasi platform mereka sendiri, perlu dicatat bahwa itu membutuhkan lebih banyak kode daripada membuat dan mengonsumsi Efek.

Aplikasi sampel menunjukkan Shadow khusus platform yang menambahkan bayangan ke teks yang Label ditampilkan oleh kontrol:

Spesifik Platform Bayangan

Aplikasi sampel mengimplementasikan Shadow platform khusus pada setiap platform, untuk kemudahan pemahaman. Namun, selain dari setiap implementasi Efek khusus platform, implementasi kelas Shadow sebagian besar identik untuk setiap platform. Oleh karena itu, panduan ini berfokus pada implementasi kelas Shadow dan Efek terkait pada satu platform.

Untuk informasi selengkapnya tentang Efek, lihat Menyesuaikan Kontrol dengan Efek.

Membuat kelas khusus platform

Khusus platform dibuat sebagai public static kelas:

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

Bagian berikut membahas implementasi Shadow Efek khusus platform dan terkait.

Menambahkan properti terlampir

Properti terlampir harus ditambahkan ke Shadow platform khusus untuk memungkinkan konsumsi melalui 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);
            }
        }
    }
}

Properti IsShadowed terlampir digunakan untuk menambahkan MyCompany.LabelShadowEffect Efek ke, dan menghapusnya dari, kontrol tempat Shadow kelas dilampirkan. Properti terlampir ini mendaftarkan OnIsShadowedPropertyChanged metode yang akan dijalankan ketika nilai properti berubah. Pada gilirannya, metode ini memanggil AttachEffect metode atau DetachEffect untuk menambahkan atau menghapus efek berdasarkan nilai IsShadowed properti terlampir. Efek ditambahkan ke atau dihapus dari kontrol dengan memodifikasi koleksi kontrol Effects .

Catatan

Perhatikan bahwa Efek diselesaikan dengan menentukan nilai yang merupakan penggabungan nama grup resolusi dan pengidentifikasi unik yang ditentukan pada implementasi Efek. Untuk informasi selengkapnya, lihat Membuat Efek.

Untuk informasi selengkapnya tentang properti terlampir, lihat Properti Terlampir.

Menambahkan Metode Ekstensi

Metode ekstensi harus ditambahkan ke Shadow platform khusus untuk memungkinkan konsumsi melalui API kode yang fasih:

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

Metode IsShadowed ekstensi dan SetIsShadowed memanggil aksesor get dan set untuk IsShadowed properti terlampir, masing-masing. Setiap metode ekstensi beroperasi pada IPlatformElementConfiguration<iOS, FormsElement> jenis , yang menentukan bahwa khusus platform dapat dipanggil pada Label instans dari iOS.

Membuat efek

Platform Shadow khusus menambahkan ke MyCompany.LabelShadowEffectLabel, dan menghapusnya. Contoh kode berikut menunjukkan LabelShadowEffect implementasi untuk proyek 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);
            }
        }
    }
}

Metode UpdateShadow ini mengatur Control.Layer properti untuk membuat bayangan, asalkan properti terlampir IsShadowed diatur ke true, dan asalkan Shadow khusus platform telah dipanggil pada platform yang sama dengan yang diimplementasikan oleh Efek. Pemeriksaan ini dilakukan dengan OnThisPlatform metode .

Shadow.IsShadowed Jika nilai properti terlampir berubah pada runtime, Efek perlu merespons dengan menghapus bayangan. Oleh karena itu, versi penggantian OnElementPropertyChanged metode digunakan untuk menanggapi perubahan properti yang dapat diikat dengan memanggil UpdateShadow metode .

Untuk informasi selengkapnya tentang membuat efek, lihat Membuat Parameter Efek dan Efek Passing sebagai Properti Terlampir.

Mengonsumsi platform khusus

Khusus Shadow platform digunakan dalam XAML dengan mengatur Shadow.IsShadowed properti terlampir ke boolean nilai:

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

Atau, dapat dikonsumsi dari C# menggunakan API fasih:

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

...

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

Bagikan melalui

Spesifikasi Platform

Membuat platform khusus

Membuat kelas khusus platform

Menambahkan properti terlampir

Menambahkan Metode Ekstensi

Membuat efek

Mengonsumsi platform khusus

Sumber Daya Tambahan:

Bagikan melalui

Spesifikasi Platform

Membuat platform khusus

Membuat kelas khusus platform

Menambahkan properti terlampir

Menambahkan Metode Ekstensi

Membuat efek

Mengonsumsi platform khusus

Tautan terkait

Sumber Daya Tambahan: