Bagikan melalui

Panduan: Mengikat pustaka Android Kotlin

Penting

Saat ini kami sedang menyelidiki penggunaan pengikatan kustom pada platform Xamarin. Silakan ikuti survei ini untuk menginformasikan upaya pengembangan di masa mendatang.

Xamarin memungkinkan pengembang seluler untuk membuat aplikasi seluler asli lintas platform menggunakan Visual Studio dan C#. Anda dapat menggunakan komponen SDK platform Android di luar kotak tetapi dalam banyak kasus Anda juga ingin menggunakan SDK pihak ketiga yang ditulis untuk platform tersebut dan Xamarin memungkinkan Anda melakukannya melalui pengikatan. Untuk menggabungkan kerangka kerja Android pihak ketiga ke dalam aplikasi Xamarin.Android Anda, Anda perlu membuat pengikatan Xamarin.Android untuk itu sebelum Anda dapat menggunakannya di aplikasi Anda.

Platform Android, bersama dengan bahasa dan alat aslinya, terus berkembang, termasuk pengenalan bahasa Kotlin baru-baru ini, yang akhirnya diatur untuk menggantikan Java. Ada sejumlah SDK pihak 3d, yang telah dimigrasikan dari Java ke Kotlin dan memberi kami tantangan baru. Meskipun proses pengikatan Kotlin mirip dengan Java, ini memerlukan langkah-langkah tambahan dan pengaturan konfigurasi untuk berhasil membangun dan menjalankan sebagai bagian dari aplikasi Xamarin.Android.

Tujuan dari dokumen ini adalah untuk menguraikan pendekatan tingkat tinggi untuk mengatasi skenario ini dan memberikan panduan langkah demi langkah terperinci dengan contoh sederhana.

Latar belakang

Kotlin dirilis pada Februari 2016 dan diposisikan sebagai alternatif untuk kompilator Java standar ke Android Studio pada tahun 2017. Kemudian pada tahun 2019, Google mengumumkan bahwa bahasa pemrograman Kotlin akan menjadi bahasa pilihannya untuk pengembang aplikasi Android. Pendekatan pengikatan tingkat tinggi mirip dengan proses pengikatan pustaka Java reguler dengan beberapa langkah spesifik Kotlin penting.

Prasyarat

Untuk menyelesaikan panduan ini, Anda akan memerlukan:

Membangun pustaka asli

Langkah pertama adalah membangun pustaka Kotlin asli menggunakan Android Studio. Library biasanya disediakan oleh pengembang pihak ketiga atau tersedia di repositori Maven Google dan repositori jarak jauh lainnya. Sebagai contoh, dalam tutorial ini pengikatan untuk Pustaka Kotlin Pemilih Gelembung dibuat:

GitHub BubblePicker demo

  1. Unduh kode sumber dari GitHub untuk pustaka dan buka kemasannya ke folder lokal Bubble-Picker.

  2. Luncurkan Android Studio dan pilih buka opsi menu proyek Android Studio yang sudah ada dengan memilih folder lokal Bubble-Picker:

    Android Studio Open Project

  3. Verifikasi bahwa Android Studio sudah diperbarui termasuk Gradle. Kode sumber dapat berhasil dibangun di Android Studio v3.5.3, Gradle v5.4.1. Petunjuk tentang cara memperbarui Gradle ke versi Gradle terbaru dapat ditemukan di sini.

  4. Verifikasi bahwa Android SDK yang diperlukan telah diinstal. Kode sumber memerlukan Android SDK v25. Buka opsi menu SDK Manager Alat > untuk menginstal komponen SDK.

  5. Perbarui dan sinkronkan file konfigurasi build.gradle utama yang terletak di akar folder proyek:

    • Atur versi Kotlin ke 1.3.10

      buildscript {
    ext.kotlin_version = '1.3.10'
}

    • Daftarkan repositori Maven Google default sehingga dependensi library dukungan dapat diselesaikan:

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

    • Setelah file konfigurasi diperbarui, file tidak sinkron dan Gradle menunjukkan tombol Sinkronkan Sekarang , tekan dan tunggu hingga proses sinkronisasi selesai:

      Android Studio Gradle Sync Now

      Tip

      Cache dependensi Gradle mungkin rusak, ini terkadang terjadi setelah batas waktu koneksi jaringan. Mengunduh ulang dependensi dan proyek sinkronisasi (memerlukan jaringan).

      Tip

      Status proses build Gradle (daemon) mungkin rusak. Menghentikan semua daemon Gradle dapat menyelesaikan masalah ini. Hentikan proses build Gradle (memerlukan hidupkan ulang). Dalam kasus proses Gradle yang rusak, Anda juga dapat mencoba menutup IDE dan kemudian membunuh semua proses Java.

      Tip

      Proyek Anda mungkin menggunakan plugin pihak ketiga, yang tidak kompatibel dengan plugin lain dalam proyek atau versi Gradle yang diminta oleh proyek.

  6. Buka menu Gradle di sebelah kanan, navigasikan ke menu Tugas bubblepicker>, jalankan tugas build dengan mengetuk dua kali, dan tunggu proses build selesai:

    Android Studio Gradle Execute Task

  7. Buka browser file folder akar dan navigasikan ke folder build: Bubble-Picker -> bubblepicker - build ->> outputs -> aar, simpan file bubblepicker-release.aar sebagai bubblepicker-v1.0.aar, file ini akan digunakan nanti dalam proses pengikatan:

    Android Studio AAR Output

File AAR adalah arsip Android, yang berisi kode sumber dan aset Kotlin yang dikompilasi, yang diperlukan oleh Android untuk menjalankan aplikasi menggunakan SDK ini.

Menyiapkan metadata

Langkah kedua adalah menyiapkan file transformasi metadata, yang digunakan oleh Xamarin.Android untuk menghasilkan kelas C# masing-masing. Proyek Pengikatan Xamarin.Android akan menemukan semua kelas dan anggota asli dari arsip Android tertentu kemudian menghasilkan file XML dengan metadata yang sesuai. File transformasi metadata yang dibuat secara manual kemudian diterapkan ke garis besar yang dihasilkan sebelumnya untuk membuat file definisi XML akhir yang digunakan untuk menghasilkan kode C#.

Metadata menggunakan sintaks XPath dan digunakan oleh Generator Pengikatan untuk memengaruhi pembuatan rakitan pengikatan. Artikel Metadata Pengikatan Java menyediakan informasi selengkapnya tentang transformasi, yang dapat diterapkan:

  1. Buat file Metadata.xml kosong:

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

  2. Tentukan transformasi xml:

  • Pustaka Kotlin asli memiliki dua dependensi, yang tidak ingin Anda ekspos ke dunia C#, tentukan dua transformasi untuk mengabaikannya sepenuhnya. Penting untuk dikatakan, anggota asli tidak akan dilucuti dari biner yang dihasilkan, hanya kelas C# yang tidak akan dihasilkan. Java Decompiler dapat digunakan untuk mengidentifikasi dependensi. Jalankan alat dan buka file AAR yang dibuat sebelumnya, akibatnya struktur arsip Android akan ditampilkan, mencerminkan semua dependensi, nilai, sumber daya, manifes, dan kelas:

    Java Decompiler Dependencies

    Transformasi untuk melewati pemrosesan paket ini didefinisikan menggunakan instruksi XPath:

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

  • Kelas asli BubblePicker memiliki dua metode getBackgroundColor dan setBackgroundColor dan transformasi berikut akan mengubahnya menjadi properti C# BackgroundColor :

    <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>

  • Jenis UInt, UShort, ULong, UByte yang tidak ditandatangani memerlukan penanganan khusus. Untuk jenis ini Kotlin mengubah nama metode dan jenis parameter secara otomatis, yang tercermin dalam kode yang dihasilkan:

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

    Kode ini dikompilasi ke dalam kode byte Java berikut:

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

    Selain itu, jenis terkait seperti UIntArray, UShortArray, ULongArray, UByteArray juga dipengaruhi oleh Kotlin. Nama metode diubah untuk menyertakan akhiran dan parameter tambahan diubah ke array elemen versi yang ditandatangani dari jenis yang sama. Dalam contoh di bawah parameter jenis UIntArray dikonversi secara otomatis menjadi int[] dan nama metode diubah dari fooUIntArrayMethod ke fooUIntArrayMethod--ajY-9A. Yang terakhir ditemukan oleh alat Xamarin.Android dan dihasilkan sebagai nama metode yang valid:

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

    Kode ini dikompilasi ke dalam kode byte Java berikut:

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

    Untuk memberinya nama yang bermakna, metadata berikut dapat ditambahkan ke Metadata.xml, yang akan memperbarui nama kembali ke yang awalnya ditentukan dalam kode Kotlin:

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

    Dalam sampel BubblePicker, tidak ada anggota yang menggunakan jenis yang tidak ditandatangani sehingga tidak diperlukan perubahan tambahan.

  • Anggota Kotlin dengan parameter generik secara default diubah menjadi parameter Java.Lang.Object Jenis. Misalnya, metode Kotlin memiliki parameter <generik T>:

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

    Setelah pengikatan Xamarin.Android dihasilkan, metode ini diekspos ke C# seperti di bawah ini:

    [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);

    Generik Java dan Kotlin tidak didukung oleh pengikatan Xamarin.Android, sehingga metode C# umum untuk mengakses API generik dibuat. Sebagai pekerjaan, Anda dapat membuat pustaka Kotlin pembungkus dan mengekspos API yang diperlukan dengan cara yang kuat tanpa generik. Atau, Anda dapat membuat pembantu di sisi C# untuk mengatasi masalah dengan cara yang sama melalui API berjenis kuat.

    Tip

    Dengan mengubah metadata, setiap perubahan dapat diterapkan pada pengikatan yang dihasilkan. Artikel Mengikat Pustaka Java menjelaskan secara detail bagaimana metadata dihasilkan dan diproses.

Membangun pustaka pengikatan

Langkah selanjutnya adalah membuat proyek pengikatan Xamarin.Android menggunakan templat pengikatan Visual Studio, menambahkan metadata yang diperlukan, referensi asli, lalu membangun proyek untuk menghasilkan pustaka yang dapat digunakan:

  1. Buka Visual Studio untuk Mac dan buat proyek Pustaka Pengikatan Xamarin.Android baru, beri nama, dalam hal ini testBubblePicker.Binding dan selesaikan wizard. Templat pengikatan Xamarin.Android terletak di jalur berikut: Android > Library > Binding Library:

    Visual Studio Create Binding

    Di folder Transformasi ada tiga file transformasi utama:

    • Metadata.xml – Memungkinkan perubahan dilakukan pada API akhir, seperti mengubah namespace pengikatan yang dihasilkan.
    • EnumFields.xml – Berisi pemetaan antara konstanta int Java dan enum C#.
    • EnumMethods.xml – Memungkinkan perubahan parameter metode dan mengembalikan jenis dari konstanta int Java ke enum C#.

    Kosongkan file EnumFields.xml dan EnumMethods.xml dan perbarui Metadata.xml untuk menentukan transformasi Anda.

  2. Ganti file Transformasi/Metadata.xml yang ada dengan file Metadata.xml yang dibuat pada langkah sebelumnya. Di jendela properti, verifikasi bahwa File Build Action diatur ke TransformationFile:

    Visual Studio Metadata

  3. Tambahkan file bubblepicker-v1.0.aar yang Anda buat di Langkah 1 ke proyek pengikatan sebagai referensi asli. Untuk menambahkan referensi pustaka asli, buka finder dan navigasikan ke folder dengan arsip Android. Seret dan letakkan arsip ke folder Jars di Penjelajah Solusi. Atau, Anda dapat menggunakan opsi menu Tambahkan konteks pada folder Jars dan pilih File yang Ada.... Pilih untuk menyalin file ke direktori untuk tujuan panduan ini. Pastikan untuk memverifikasi bahwa Tindakan Build diatur ke LibraryProjectZip:

    Visual Studio Native Reference

  4. Tambahkan referensi ke paket Xamarin.Kotlin.StdLib NuGet . Paket ini adalah pengikatan untuk Pustaka Standar Kotlin. Tanpa paket ini, pengikatan hanya akan berfungsi jika pustaka Kotlin tidak menggunakan jenis tertentu Kotlin, jika tidak, semua anggota ini tidak akan terekspos ke C# dan aplikasi apa pun yang mencoba mengonsumsi pengikatan akan crash saat runtime.

    Tip

    Karena keterbatasan Xamarin.Android, alat pengikatan hanya satu arsip Android (AAR) yang dapat ditambahkan per proyek pengikatan. Jika beberapa file AAR perlu disertakan, maka beberapa proyek Xamarin.Android diperlukan, satu per setiap AAR. Jika ini terjadi untuk panduan ini, maka empat tindakan sebelumnya dari langkah ini harus diulang untuk setiap arsip. Sebagai opsi alternatif, Anda dapat menggabungkan beberapa arsip Android secara manual sebagai arsip tunggal dan sebagai hasilnya Anda dapat menggunakan satu proyek pengikatan Xamarin.Android.

  5. Tindakan terakhir adalah membangun pustaka dan membuat tidak memiliki kesalahan kompilasi. Jika terjadi kesalahan kompilasi, kesalahan tersebut dapat diatasi dan ditangani menggunakan file Metadata.xml, yang Anda buat sebelumnya dengan menambahkan metadata transformasi xml, yang akan menambahkan, menghapus, atau mengganti nama anggota pustaka.

Menggunakan pustaka pengikatan

Langkah terakhir adalah menggunakan pustaka pengikatan Xamarin.Android dalam aplikasi Xamarin.Android. Buat proyek Xamarin.Android baru, tambahkan referensi ke pustaka pengikatan dan render UI Pemilih Gelembung:

  1. Buat proyek Xamarin.Android. Gunakan Aplikasi Android >> Android sebagai titik awal dan pilih opsi Terbaru dan Terbesar saat Anda Menargetkan Platform untuk menghindari masalah kompatibilitas. Semua langkah berikut menargetkan proyek ini:

    Visual Studio Create App

  2. Tambahkan referensi proyek ke proyek pengikatan atau tambahkan referensi dll yang dibuat sebelumnya:

    Visual Studio Add Binding Reference.png

  3. Tambahkan referensi ke paket Xamarin.Kotlin.StdLib NuGet , yang Anda tambahkan ke proyek pengikatan Xamarin.Android sebelumnya. Ini menambahkan dukungan ke jenis spesifik Kotlin apa pun yang perlu diserahkan dalam runtime. Tanpa paket ini, aplikasi dapat dikompilasi tetapi akan mengalami crash saat runtime:

    Visual Studio Add StdLib NuGet

  4. BubblePicker Tambahkan kontrol ke tata letak Android untuk MainActivity. Buka file testBubblePicker/Resources/layout/content_main.xml dan tambahkan simpul kontrol BubblePicker sebagai elemen terakhir dari kontrol RelativeLayout root:

    <?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. Perbarui kode sumber aplikasi dan tambahkan logika inisialisasi ke MainActivity, yang mengaktifkan SDK Pemilih Gelembung:

    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 dan BubblePickerListener adalah dua kelas yang akan dibuat dari awal, yang menangani data gelembung dan mengontrol interaksi:

    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. Jalankan aplikasi, yang harus merender UI Pemilih Gelembung:

    BubblePicker demo

    Sampel memerlukan kode tambahan untuk merender gaya elemen dan menangani interaksi tetapi BubblePicker kontrol telah berhasil dibuat dan diaktifkan.

Selamat! Anda telah berhasil membuat aplikasi Xamarin.Android dan pustaka pengikatan, yang menggunakan pustaka Kotlin.

Anda sekarang harus memiliki aplikasi Xamarin.Android dasar yang menggunakan pustaka Kotlin asli melalui pustaka pengikatan Xamarin.Android. Panduan ini sengaja menggunakan contoh dasar untuk lebih menekankan konsep utama yang diperkenalkan. Dalam skenario dunia nyata, Anda kemungkinan akan diminta untuk mengekspos sejumlah besar API dan menerapkan transformasi metadata kepada mereka.