İzlenecek yol: Android Kotlin kitaplığı bağlama

Önemli

Şu anda Xamarin platformunda özel bağlama kullanımını araştırıyoruz. Gelecekteki geliştirme çalışmalarını bilgilendirmek için lütfen bu ankete katılın.

Xamarin, mobil geliştiricilerin Visual Studio ve C# kullanarak platformlar arası yerel mobil uygulamalar oluşturmasını sağlar. Android platformu SDK bileşenlerini kullanıma hazır olarak kullanabilirsiniz, ancak çoğu durumda bu platform için yazılmış üçüncü taraf SDK'ları da kullanmak istersiniz ve Xamarin bunu bağlamalar aracılığıyla yapmanıza olanak tanır. Xamarin.Android uygulamanıza bir üçüncü taraf Android çerçevesi eklemek için, uygulamalarınızda kullanabilmeniz için bir Xamarin.Android bağlaması oluşturmanız gerekir.

Android platformu, anadili ve araçlarıyla birlikte, sonunda Java'nın yerini alacak şekilde ayarlanan Kotlin dilinin yeni tanıtılması da dahil olmak üzere sürekli gelişmektedir. Java'dan Kotlin'e geçirilmiş olan ve bize yeni zorluklarla karşı karşıya olan bir dizi 3b taraf SDK vardır. Kotlin bağlama işlemi Java'ya benzer olsa da, Xamarin.Android uygulamasının bir parçası olarak başarıyla derlemek ve çalıştırmak için ek adımlar ve yapılandırma ayarları gerektirir.

Bu belgenin amacı, bu senaryoyu ele almak için üst düzey bir yaklaşımın ana hatlarını oluşturmak ve basit bir örnekle birlikte ayrıntılı bir adım adım kılavuz sağlamaktır.

Background

Kotlin Şubat 2016'da piyasaya sürüldü ve 2017'ye kadar Standart Java derleyicisine alternatif olarak Android Studio'ya konumlandırıldı. 2019'un ilerleyen bölümlerinde Google, Kotlin programlama dilinin Android uygulama geliştiricileri için tercih edilen dil olacağını duyurdu. Üst düzey bağlama yaklaşımı, birkaç önemli Kotlin özel adımıyla normal Java kitaplıklarının bağlama işlemine benzer.

Önkoşullar

Bu kılavuzu tamamlamak için şunlar gerekir:

• Android Studio
• Mac için Visual Studio
• Java Decompiler

Yerel kitaplık oluşturma

İlk adım, Android Studio kullanarak yerel bir Kotlin kitaplığı oluşturmaktır. Kitaplık genellikle üçüncü taraf bir geliştirici tarafından sağlanır veya Google'ın Maven deposunda ve diğer uzak depolarda kullanılabilir. Örnek olarak, bu öğreticide Kabarcık Seçici Kotlin Kitaplığı için bir bağlama oluşturulur:

1. Kitaplığın kaynak kodunu GitHub'dan indirin ve bubble-picker yerel klasörüne açın.

2. Android Studio'yu başlatın ve Kabarcık Seçici yerel klasörünü seçerek Var olan bir Android Studio projesini aç menü seçeneğini belirleyin:

   

3. Android Studio'nın Gradle dahil olmak üzere güncel olduğunu doğrulayın. Kaynak kod, Android Studio v3.5.3, Gradle v5.4.1 üzerinde başarıyla oluşturulabilir. Gradle'ı en son Gradle sürümüne güncelleştirme yönergelerini burada bulabilirsiniz.

4. Gerekli Android SDK'nın yüklü olduğunu doğrulayın. Kaynak kodu Için Android SDK v25 gerekir. SDK bileşenlerini yüklemek için Araçlar > SDK Yöneticisi menü seçeneğini açın.

5. Proje klasörünün kökünde bulunan ana build.gradle yapılandırma dosyasını güncelleştirin ve eşitleyin:

   • Kotlin sürümünü 1.3.10 olarak ayarlayın

     buildscript {
         ext.kotlin_version = '1.3.10'
     }
     

   • Destek kitaplığı bağımlılığının çözümlenebilmesi için varsayılan Google Maven deposunu kaydedin:

     allprojects {
         repositories {
             jcenter()
             maven {
                 url "https://maven.google.com"
             }
         }
     }
     

   • Yapılandırma dosyası güncelleştirildikten sonra eşitlenmemiştir ve Gradle Şimdi Eşitle düğmesini gösterir, buna basın ve eşitleme işleminin tamamlanmasını bekleyin:

     

     İpucu

     Gradle'ın bağımlılık önbelleği bozuk olabilir, bu bazen bir ağ bağlantısı zaman aşımı sonrasında oluşur. Bağımlılıkları yeniden indirme ve projeyi eşitleme (ağ gerektirir).

     İpucu

     Gradle derleme işleminin (daemon) durumu bozuk olabilir. Tüm Gradle daemon'larının durdurulması bu sorunu çözebilir. Gradle derleme işlemlerini durdurun (yeniden başlatma gerektirir). Bozuk Gradle işlemleri söz konusu olduğunda, IDE'yi kapatmayı ve ardından tüm Java işlemlerini öldürmeyi de deneyebilirsiniz.

     İpucu

     Projeniz, projedeki diğer eklentilerle veya proje tarafından istenen Gradle sürümüyle uyumlu olmayan bir üçüncü taraf eklentisi kullanıyor olabilir.

6. Sağdaki Gradle menüsünü açın, kabarcıklı görevler> menüsüne gidin, iki kez dokunarak derleme görevini yürütun ve derleme işleminin tamamlanmasını bekleyin:

   

7. Kök klasör dosyaları tarayıcısını açın ve derleme klasörüne gidin: Bubble-Picker -> bubblepicker -> build -> outputs -> aar, save the bubblepicker-release.aar file as bubblepicker-v1.0.aar, bu dosya bağlama işleminde daha sonra kullanılacaktır:

   

AAR dosyası, Android tarafından bu SDK'yı kullanarak bir uygulamayı çalıştırmak için gereken derlenmiş Kotlin kaynak kodunu ve varlıklarını içeren bir Android arşividir.

Meta verileri hazırlama

İkinci adım, Xamarin.Android tarafından ilgili C# sınıflarını oluşturmak için kullanılan meta veri dönüştürme dosyasını hazırlamaktır. Xamarin.Android Bağlama Projesi, belirli bir Android arşivinden gelen tüm yerel sınıfları ve üyeleri keşfeder ve uygun meta verilerle bir XML dosyası oluşturur. El ile oluşturulan meta veri dönüştürme dosyası, daha önce oluşturulan temele uygulanarak C# kodunu oluşturmak için kullanılan son XML tanım dosyasını oluşturur.

Meta veriler XPath söz dizimini kullanır ve Bağlama Oluşturucu tarafından bağlama derlemesinin oluşturulmasını etkilemek için kullanılır. Java Bağlama Meta Verileri makalesi, uygulanabilecek dönüştürmeler hakkında daha fazla bilgi sağlar:

1. Boş bir Metadata.xml dosyası oluşturun:

   <?xml version="1.0" encoding="UTF-8"?>
   <metadata>
   </metadata>
   

2. Xml dönüşümlerini tanımlama:

• Yerel Kotlin kitaplığının iki bağımlılığı vardır ve bu bağımlılıkları C# dünyasına göstermek istemezsiniz, bunları tamamen yoksaymak için iki dönüştürme tanımlayın. Yerel üyelerin sonuçta elde edilen ikili dosyadan çıkarılmayacağını, yalnızca C# sınıflarının oluşturulmayacağını söylemek önemlidir. Java Decompiler , bağımlılıkları tanımlamak için kullanılabilir. Aracı çalıştırın ve daha önce oluşturulan AAR dosyasını açın; sonuç olarak Android arşivinin yapısı tüm bağımlılıkları, değerleri, kaynakları, bildirimi ve sınıfları yansıtan şekilde gösterilir:

  

  Bu paketlerin işlenmesini atlamak için dönüştürmeler XPath yönergeleri kullanılarak tanımlanır:

  <remove-node path="/api/package[starts-with(@name,'org.jbox2d')]" />
  <remove-node path="/api/package[starts-with(@name,'org.slf4j')]" />
  

• Yerel BubblePicker sınıfın iki yöntemi getBackgroundColor vardır ve setBackgroundColor aşağıdaki dönüştürme bunu C# BackgroundColor özelliğine dönüştürecektir:

  <attr path="/api/package[@name='com.igalata.bubblepicker.rendering']/class[@name='BubblePicker']/method[@name='getBackground' and count(parameter)=0]" name="propertyName">BackgroundColor</attr>
  <attr path="/api/package[@name='com.igalata.bubblepicker.rendering']/class[@name='BubblePicker']/method[@name='setBackground' and count(parameter)=1 and parameter[1][@type='int']]" name="propertyName">BackgroundColor</attr>
  

• İmzasız türler UInt, UShort, ULong, UByte özel işleme gerektirir. Bu türlerde Kotlin, yöntem adlarını ve parametre türlerini otomatik olarak değiştirir ve bu da oluşturulan koda yansıtılır:

  public open fun fooUIntMethod(value: UInt) : String {
      return "fooUIntMethod${value}"
  }
  

  Bu kod aşağıdaki Java bayt kodunda derlenmiş:

  @NotNull
  public String fooUIntMethod-WZ4Q5Ns(int value) {
  return "fooUIntMethod" + UInt.toString-impl(value);
  }
  

  Ayrıca, gibi UIntArray, UShortArray, ULongArray, UByteArray ilgili türler de Kotlin'den etkilenir. Yöntem adı ek bir son ek içerecek şekilde değiştirilir ve parametreler aynı türlerdeki imzalı sürümlerin öğe dizisine değiştirilir. Aşağıdaki örnekte türündeki UIntArray bir parametre otomatik olarak öğesine int[] dönüştürülür ve yöntem adı olarak fooUIntArrayMethodfooUIntArrayMethod--ajY-9Adeğiştirilir. İkincisi Xamarin.Android araçları tarafından bulunur ve geçerli bir yöntem adı olarak oluşturulur:

  public open fun fooUIntArrayMethod(value: UIntArray) : String {
      return "fooUIntArrayMethod${value.size}"
  }
  

  Bu kod aşağıdaki Java bayt kodunda derlenmiş:

  @NotNull
  public String fooUIntArrayMethod--ajY-9A(@NotNull int[] value) {
      Intrinsics.checkParameterIsNotNull(value, "value");
      return "fooUIntArrayMethod" + UIntArray.getSize-impl(value);
  }
  

  Anlamlı bir ad vermek için, Metadata.xml aşağıdaki meta veriler eklenebilir ve bu da adı Kotlin kodunda başlangıçta tanımlanana geri güncelleştirir:

  <attr path="/api/package[@name='com.microsoft.simplekotlinlib']/class[@name='FooClass']/method[@name='fooUIntArrayMethod--ajY-9A']" name="managedName">fooUIntArrayMethod</attr>
  

  BubblePicker örneğinde imzasız türleri kullanan üye olmadığından ek değişiklik gerekmez.

• Varsayılan olarak genel parametrelere sahip Kotlin üyeleri Java parametrelerine dönüştürülür.Lang.Object Türü. Örneğin, Kotlin yönteminin genel bir T parametresi <>vardır:

  public open fun <T>fooGenericMethod(value: T) : String {
  return "fooGenericMethod${value}"
  }
  

  Xamarin.Android bağlaması oluşturulduktan sonra yöntemi aşağıdaki gibi C# ile kullanıma sunulur:

  [Register ("fooGenericMethod", "(Ljava/lang/Object;)Ljava/lang/String;", "GetFooGenericMethod_Ljava_lang_Object_Handler")]
  [JavaTypeParameters (new string[] {
      "T"
  })]
  
  public virtual string FooGenericMethod (Java.Lang.Object value);
  

  Java ve Kotlin genel türleri Xamarin.Android bağlamaları tarafından desteklenmez, bu nedenle genel API'ye erişmek için genelleştirilmiş bir C# yöntemi oluşturulur. Geçici çözüm olarak bir sarmalayıcı Kotlin kitaplığı oluşturabilir ve gerekli API'leri genel değerler olmadan güçlü türde bir şekilde kullanıma sağlayabilirsiniz. Alternatif olarak, güçlü türdeki API'ler aracılığıyla sorunu aynı şekilde çözmek için C# tarafında yardımcılar oluşturabilirsiniz.

  İpucu

  Meta veriler dönüştürülerek, oluşturulan bağlamaya tüm değişiklikler uygulanabilir. Bağlama Java Kitaplığı makalesinde meta verilerin nasıl oluşturulduğu ve işlendiği ayrıntılı olarak açıklanmaktadır.

Bağlama kitaplığı oluşturma

Sonraki adım, Visual Studio bağlama şablonunu kullanarak bir Xamarin.Android bağlama projesi oluşturmak, gerekli meta verileri, yerel başvuruları eklemek ve ardından projeyi oluşturarak kullanılabilir bir kitaplık oluşturmaktır:

1. Mac için Visual Studio açın ve yeni bir Xamarin.Android Bağlama Kitaplığı projesi oluşturun, bu örnekte testBubblePicker.Binding adlı bir ad verin ve sihirbazı tamamlayın. Xamarin.Android bağlama şablonu şu yolda bulunur: Android > Kitaplığı > Bağlama Kitaplığı:

   

   Dönüşümler klasöründe üç ana dönüştürme dosyası vardır:

   • Metadata.xml : Oluşturulan bağlamanın ad alanını değiştirme gibi son API'de değişiklik yapılmasına izin verir.
   • EnumFields.xml – Java int sabitleri ile C# sabit listeleri arasındaki eşlemeyi içerir.
   • EnumMethods.xml – Yöntem parametrelerinin değiştirilmesine ve Java int sabitlerinden C# sabitlerine dönüş türlerinin değiştirilmesine izin verir.

   EnumFields.xml ve EnumMethods.xml dosyalarını boş tutun ve dönüştürmelerinizi tanımlamak için Metadata.xml güncelleştirin.

2. Var olan Transformations/Metadata.xml dosyasını önceki adımda oluşturulan Metadata.xml dosyasıyla değiştirin. Özellikler penceresinde, Derleme Eylemi dosyasının TransformationFile olarak ayarlandığını doğrulayın:

   

3. 1. Adımda oluşturduğunuz bubblepicker-v1.0.aar dosyasını bağlama projesine yerel başvuru olarak ekleyin. Yerel kitaplık başvuruları eklemek için bulucuyu açın ve Android arşivinin olduğu klasöre gidin. Arşivi sürükleyip Çözüm Gezgini'deki Jars klasörüne bırakın. Alternatif olarak, Jars klasöründe bağlam menüsü ekle seçeneğini kullanabilir ve Mevcut Dosyalar... seçeneğini belirleyebilirsiniz. Bu kılavuzun amaçları doğrultusunda dosyayı dizine kopyalamayı seçin. Derleme Eylemi'nin LibraryProjectZip olarak ayarlandığını doğrulayın:

   

4. Xamarin.Kotlin.StdLib NuGet paketine başvuru ekleyin. Bu paket, Kotlin Standart Kitaplığı için bir bağlamadır. Bu paket olmadan bağlama yalnızca Kotlin kitaplığı Kotlin'e özgü türler kullanmıyorsa çalışır, aksi takdirde tüm bu üyeler C# ile kullanıma sunulmaz ve bağlamayı kullanmaya çalışan tüm uygulamalar çalışma zamanında kilitlenir.

   İpucu

   Xamarin.Android sınırlaması nedeniyle bağlama araçları bağlama projesi başına yalnızca tek bir Android arşivi (AAR) eklenebilir. Birden çok AAR dosyasının dahil edilmesi gerekiyorsa, her AAR için bir tane olmak üzere birden çok Xamarin.Android projesi gerekir. Bu izlenecek yol için bu durum söz konusuysa, bu adımın önceki dört eyleminin her arşiv için tekrarlanması gerekir. Alternatif bir seçenek olarak, birden çok Android arşivlerini tek bir arşiv olarak el ile birleştirmek mümkündür ve sonuç olarak tek bir Xamarin.Android bağlama projesi kullanabilirsiniz.

5. Son eylem, kitaplığı oluşturmak ve derleme hatası içermemektir. Derleme hataları söz konusu olduğunda, bunlar daha önce xml dönüştürme meta verileri ekleyerek oluşturduğunuz ve kitaplık üyelerini ekleyecek, kaldıracak veya yeniden adlandıracak Metadata.xml dosyası kullanılarak ele alınıp işlenebilir.

Bağlama kitaplığını kullanma

Son adım, Xamarin.Android bağlama kitaplığını bir Xamarin.Android uygulamasında kullanmaktır. Yeni bir Xamarin.Android projesi oluşturun, bağlama kitaplığına başvuru ekleyin ve Kabarcık Seçici kullanıcı arabirimini işleyin:

1. Xamarin.Android projesi oluşturun. Android > Uygulaması > Android Uygulamasını başlangıç noktası olarak kullanın ve uyumluluk sorunlarından kaçınmak için Hedef Platformlar olarak En Son ve En Büyük seçeneğini belirleyin. Aşağıdaki adımların tümü bu projeyi hedefler:

   

2. Bağlama projesine bir proje başvurusu ekleyin veya daha önce oluşturulan DLL'ye bir başvuru ekleyin:

   

3. Daha önce Xamarin.Android bağlama projesine eklediğiniz Xamarin.Kotlin.StdLib NuGet paketine bir başvuru ekleyin. Çalışma zamanında teslimi gereken kotlin'e özgü türlere destek ekler. Bu paket olmadan uygulama derlenebilir ancak çalışma zamanında kilitlenir:

   

4. BubblePicker denetimini için MainActivityAndroid düzenine ekleyin. testBubblePicker/Resources/layout/content_main.xml dosyasını açın ve BubblePicker denetim düğümünü kök RelativeLayout denetiminin son öğesi olarak ekleyin:

   <?xml version="1.0" encoding="utf-8"?>
   <RelativeLayout …>
       …
       <com.igalata.bubblepicker.rendering.BubblePicker
           android:id="@+id/picker"
           android:layout_width="match_parent"
           android:layout_height="match_parent"
           app:backgroundColor="@android:color/white" />
   </RelativeLayout>
   

5. Uygulamanın kaynak kodunu güncelleştirin ve başlatma mantığını uygulamasına MainActivityekleyerek Kabarcık Seçici SDK'sını etkinleştirir:

   protected override void OnCreate(Bundle savedInstanceState)
   {
       ...
       var picker = FindViewById<BubblePicker>(Resource.Id.picker);
       picker.BubbleSize = 20;
       picker.Adapter = new BubblePickerAdapter();
       picker.Listener = new BubblePickerListener(picker);
       ...
   }
   

   BubblePickerAdapter ve BubblePickerListener sıfırdan oluşturulacak, kabarcık verilerini işleyen ve etkileşimi denetleyen iki sınıftır:

   public class BubblePickerAdapter : Java.Lang.Object, IBubblePickerAdapter
   {
       private List<string> _bubbles = new List<string>();
       public int TotalCount => _bubbles.Count;
       public BubblePickerAdapter()
       {
           for (int i = 0; i < 10; i++)
           {
               _bubbles.Add($"Item {i}");
           }
       }
   
       public PickerItem GetItem(int itemIndex)
       {
           if (itemIndex < 0 || itemIndex >= _bubbles.Count)
               return null;
   
           var result = _bubbles[itemIndex];
           var item = new PickerItem(result);
           return item;
       }
   }
   
   public class BubblePickerListener : Java.Lang.Object, IBubblePickerListener
   {
       public View Picker { get; }
       public BubblePickerListener(View picker)
       {
           Picker = picker;
       }
   
       public void OnBubbleDeselected(PickerItem item)
       {
           Snackbar.Make(Picker, $"Deselected: {item.Title}", Snackbar.LengthLong)
               .SetAction("Action", (Android.Views.View.IOnClickListener)null)
               .Show();
       }
   
       public void OnBubbleSelected(PickerItem item)
       {
           Snackbar.Make(Picker, $"Selected: {item.Title}", Snackbar.LengthLong)
           .SetAction("Action", (Android.Views.View.IOnClickListener)null)
           .Show();
       }
   }
   

6. Kabarcık Seçici kullanıcı arabirimini işlemesi gereken uygulamayı çalıştırın:

   

   Örnek, öğe stilini işlemek ve etkileşimleri işlemek için ek kod gerektirir, ancak BubblePicker denetim başarıyla oluşturulmuş ve etkinleştirilmiştir.

Tebrikler! Başarıyla bir Xamarin.Android uygulaması ve Kotlin kitaplığı kullanan bir bağlama kitaplığı oluşturdunuz.

Artık Xamarin.Android bağlama kitaplığı aracılığıyla yerel kotlin kitaplığı kullanan temel bir Xamarin.Android uygulamanız olmalıdır. Bu kılavuzda, tanıtılan temel kavramları daha iyi vurgulama amacıyla bilerek temel bir örnek kullanılır. Gerçek dünya senaryolarında, büyük olasılıkla daha fazla sayıda API'yi kullanıma sunmanız ve bunlara meta veri dönüştürmeleri uygulamanız gerekecektir.

İlgili bağlantılar

• Android Studio
• Gradle Yüklemesi
• Mac için Visual Studio
• Java Decompiler
• BubblePicker Kotlin Kitaplığı
• Java Kitaplığını Bağlama
• Xpath
• Java Bağlama Meta Verileri
• Xamarin.Kotlin.StdLib NuGet
• Örnek proje deposu