Pratinjau Developer Android 11 kedua kini tersedia, uji dan sampaikan masukan Anda.

Membuat metode masukan

Editor metode masukan (IME) adalah kontrol pengguna yang memungkinkan pengguna memasukkan teks. Android menyediakan kerangka kerja metode masukan yang dapat diperluas yang memungkinkan aplikasi untuk menyediakan metode masukan alternatif kepada pengguna, seperti keyboard di layar atau bahkan masukan ucapan. Setelah menginstal IME yang diinginkan, pengguna dapat memilih mana yang ingin digunakan dari setelan sistem, lalu menggunakannya di seluruh sistem; hanya satu IME yang dapat diaktifkan dalam satu waktu.

Untuk menambahkan IME ke sistem Android, Anda membuat aplikasi Android yang berisi class yang memperluas InputMethodService. Selain itu, Anda biasanya membuat aktivitas "setelan" yang meneruskan opsi ke layanan IME. Anda juga dapat menentukan UI setelan yang ditampilkan sebagai bagian dari setelan sistem.

Panduan ini mencakup hal-hal berikut:

  • Siklus IME
  • Mendeklarasikan komponen IME dalam manifes aplikasi
  • IME API
  • Mendesain UI IME
  • Mengirim teks dari IME ke aplikasi
  • Bekerja dengan subjenis IME

Jika Anda belum pernah bekerja dengan IME, Anda harus membaca artikel pengantar Metode Masukan Layar terlebih dahulu.

Siklus IME

Diagram berikut menjelaskan siklus IME:

Gambar 1. Siklus IME.

Bagian berikut menjelaskan cara menerapkan UI dan kode terkait dengan IME yang mengikuti siklus ini.

Mendeklarasikan komponen IME dalam manifes

Di sistem Android, IME adalah aplikasi Android yang berisi layanan IME khusus. File manifes aplikasi harus mendeklarasikan layanan, meminta izin yang diperlukan, menyediakan filter intent yang cocok dengan action.view.InputMethod tindakan, dan menyediakan metadata yang mendefinisikan karakteristik IME. Selain itu, untuk menyediakan antarmuka setelan yang memungkinkan pengguna mengubah perilaku IME, Anda dapat menentukan aktivitas "setelan" yang dapat diluncurkan dari Setelan Sistem.

Cuplikan berikut mendeklarasikan layanan IME. Cuplikan ini meminta izin BIND_INPUT_METHOD untuk memungkinkan layanan menyambungkan IME ke sistem, menyiapkan filter intent yang cocok dengan tindakan android.view.InputMethod, dan mendefinisikan metadata IME:

    <!-- Declares the input method service -->
    <service android:name="FastInputIME"
        android:label="@string/fast_input_label"
        android:permission="android.permission.BIND_INPUT_METHOD">
        <intent-filter>
            <action android:name="android.view.InputMethod" />
        </intent-filter>
        <meta-data android:name="android.view.im"
                   android:resource="@xml/method" />
    </service>
    

Cuplikan berikutnya mendeklarasikan aktivitas setelan untuk IME. Cuplikan ini memiliki filter intent untuk ACTION_MAIN yang menunjukkan bahwa aktivitas ini adalah titik masuk utama untuk aplikasi IME:

    <!-- Optional: an activity for controlling the IME settings -->
    <activity android:name="FastInputIMESettings"
        android:label="@string/fast_input_settings">
        <intent-filter>
            <action android:name="android.intent.action.MAIN"/>
        </intent-filter>
    </activity>
    

Anda juga dapat memberikan akses ke setelan IME langsung dari UI-nya.

Metode masukan API

Class spesifik untuk IME ditemukan dalam paket android.inputmethodservice dan android.view.inputmethod. Class KeyEvent penting untuk menangani karakter keyboard.

Bagian tengah dari IME adalah komponen layanan, class yang memperluas InputMethodService. Selain menerapkan siklus layanan normal, class ini juga memiliki callback untuk menyediakan UI IME Anda, menangani masukan pengguna, dan mengirimkan teks ke kolom yang saat ini memiliki fokus. Secara default, class InputMethodService menyediakan sebagian besar penerapan untuk mengelola status dan visibilitas IME dan berkomunikasi dengan kolom masukan saat ini.

Class berikut juga penting:

BaseInputConnection
Mendefinisikan kembali saluran komunikasi dari InputMethod ke aplikasi yang menerima masukan. Anda menggunakannya untuk membaca teks di sekitar kursor, memilih teks ke kotak teks, dan mengirim peristiwa kunci mentah ke aplikasi. Aplikasi harus memperluas class ini, bukan menerapkan antarmuka dasar InputConnection.
KeyboardView
Ekstensi View yang merender keyboard dan merespons peristiwa masukan pengguna. Tata letak keyboard ditentukan oleh instance Keyboard yang dapat Anda tentukan dalam file XML.

Mendesain UI metode masukan

Ada dua elemen visual utama untuk IME: tampilan masukan dan kandidat. Anda hanya perlu menerapkan elemen yang relevan dengan metode masukan yang Anda desain.

Tampilan masukan

Tampilan masukan adalah UI di mana pengguna memasukkan teks dalam bentuk klik tombol, tulisan tangan atau gestur. Ketika IME ditampilkan untuk pertama kalinya, sistem akan memanggil callback onCreateInputView(). Dalam penerapan metode ini, Anda akan membuat tata letak yang ingin ditampilkan di jendela IME dan mengembalikan tata letak ke sistem. Cuplikan ini merupakan contoh penerapan metode onCreateInputView():

Kotlin

    override fun onCreateInputView(): View {
        return layoutInflater.inflate(R.layout.input, null).apply {
            if (this is MyKeyboardView) {
                setOnKeyboardActionListener(this@MyInputMethod)
                keyboard = latinKeyboard
            }
        }
    }
    

Java

    @Override
    public View onCreateInputView() {
        MyKeyboardView inputView =
            (MyKeyboardView) getLayoutInflater().inflate(R.layout.input, null);

        inputView.setOnKeyboardActionListener(this);
        inputView.setKeyboard(latinKeyboard);

        return inputView;
    }
    

Dalam contoh ini, MyKeyboardView adalah instance penerapan kustom dari KeyboardView yang merender Keyboard.

Tampilan kandidat

Tampilan kandidat adalah UI tempat IME menampilkan kemungkinan koreksi kata atau saran bagi pengguna untuk dipilih. Dalam siklus IME, sistem akan memanggil onCreateCandidatesView() jika sudah siap untuk menampilkan tampilan kandidat. Dalam penerapan metode ini, kembalikan tata letak yang menampilkan saran kata, atau kembalikan null jika Anda tidak ingin menampilkan apa pun. Respons null adalah perilaku default, sehingga Anda tidak perlu menerapkannya jika tidak memberikan saran.

Pertimbangan desain UI

Bagian ini menjelaskan beberapa pertimbangan desain UI spesifik untuk IME.

Menangani beberapa ukuran layar

UI bagi IME Anda harus dapat diskalakan untuk berbagai ukuran layar, dan juga harus menangani orientasi lanskap dan potret. Dalam mode IME non-layar penuh, berikan ruang yang cukup untuk menampilkan kolom teks dan konteks terkait, sehingga IME menempati tidak lebih dari setengah layar. Dalam mode IME layar penuh, ini bukanlah masalah.

Menangani jenis masukan yang berbeda

Kolom teks Android memungkinkan Anda menetapkan jenis masukan spesifik, seperti teks bentuk bebas, angka, URL, alamat email, dan string penelusuran. Saat menerapkan IME baru, Anda perlu mendeteksi jenis masukan dari setiap kolom dan memberikan antarmuka yang sesuai. Namun, Anda tidak perlu menyiapkan IME untuk memeriksa apakah pengguna memasukkan teks yang valid untuk jenis masukan; itu adalah tanggung jawab aplikasi yang memiliki kolom teks.

Misalnya, berikut adalah screenshot antarmuka yang IME Latin berikan dengan platform Android untuk masukan teks dan nomor telepon:

Gambar 2. Jenis masukan IME Latin.

Saat kolom masukan menerima fokus dan IME Anda dimulai, sistem akan memanggil onStartInputView(), meneruskan objek EditorInfo yang berisi detail tentang jenis masukan dan atribut lain dari kolom teks. Dalam objek ini, kolom inputType berisi jenis masukan kolom teks.

Kolom inputType adalah int yang berisi pola bit untuk berbagai setelan jenis masukan. Guna mengujinya untuk jenis masukan kolom teks, samarkan dengan konstanta TYPE_MASK_CLASS, seperti ini:

Kotlin

    inputType and InputType.TYPE_MASK_CLASS
    

Java

    inputType & InputType.TYPE_MASK_CLASS
    

Pola bit jenis masukan dapat memiliki salah satu dari beberapa nilai, termasuk:

TYPE_CLASS_NUMBER
Kolom teks untuk memasukkan angka. Seperti ditunjukkan dalam cuplikan layar sebelumnya, IME Latin menampilkan pad angka untuk kolom jenis ini.
TYPE_CLASS_DATETIME
Kolom teks untuk memasukkan tanggal dan waktu.
TYPE_CLASS_PHONE
Kolom teks untuk memasukkan nomor telepon.
TYPE_CLASS_TEXT
Kolom teks untuk memasukkan semua karakter yang didukung.

Konstanta ini dijelaskan secara lebih detail dalam dokumentasi referensi untuk InputType.

Kolom inputType dapat berisi bit lain yang menunjukkan varian jenis kolom teks, seperti:

TYPE_TEXT_VARIATION_PASSWORD
Varian TYPE_CLASS_TEXT untuk memasukkan sandi. Metode masukan akan menampilkan dingbat, bukan teks yang sebenarnya.
TYPE_TEXT_VARIATION_URI
Varian TYPE_CLASS_TEXT untuk memasukkan URL web dan Uniform Resource Identifier (URI) lainnya.
TYPE_TEXT_FLAG_AUTO_COMPLETE
Varian TYPE_CLASS_TEXT untuk memasukkan teks di mana aplikasi melakukan "pengisian otomatis" dari kamus, penelusuran, atau fasilitas lainnya.

Ingat untuk menyamarkan inputType dengan konstanta yang sesuai saat menguji varian ini. Konstanta penyamaran yang tersedia dapat ditemukan dalam dokumentasi referensi untuk InputType.

Perhatian: Dalam IME Anda sendiri, pastikan untuk menangani teks dengan benar saat Anda mengirimkannya ke kolom sandi. Sembunyikan sandi di UI Anda, baik di tampilan masukan dan di tampilan kandidat. Ingat juga bahwa Anda tidak boleh menyimpan sandi di perangkat. Untuk mempelajari lebih lanjut, lihat panduan Mendesain untuk Keamanan.

Mengirim teks ke aplikasi

Saat pengguna memasukkan teks dengan IME Anda, Anda dapat mengirim teks ke aplikasi dengan mengirim peristiwa kunci individual atau dengan mengedit teks di sekitar kursor dalam kolom teks aplikasi. Di kedua kasus tersebut, Anda menggunakan instance InputConnection untuk mengirim teks. Untuk mendapatkan instance ini, panggil InputMethodService.getCurrentInputConnection().

Mengedit teks di sekitar kursor

Saat Anda menangani pengeditan teks yang ada dalam kolom teks, beberapa metode yang lebih bermanfaat di BaseInputConnection adalah:

getTextBeforeCursor()
Mengembalikan CharSequence yang berisi jumlah karakter yang diminta sebelum posisi kursor saat ini.
getTextAfterCursor()
Mengembalikan CharSequence yang berisi jumlah karakter yang diminta sesuai dengan posisi kursor saat ini.
deleteSurroundingText()
Menghapus jumlah karakter yang ditentukan sebelum dan setelah kursor posisi saat ini.
commitText()
Memasukkan CharSequence ke kolom teks dan menyetel posisi kursor baru.

Misalnya, cuplikan berikut menunjukkan cara mengganti empat karakter di sebelah kiri kursor dengan teks "Halo!":

Kotlin

    currentInputConnection.also { ic: InputConnection ->
        ic.deleteSurroundingText(4, 0)
        ic.commitText("Hello", 1)
        ic.commitText("!", 1)
    }
    

Java

    InputConnection ic = getCurrentInputConnection();
    ic.deleteSurroundingText(4, 0);
    ic.commitText("Hello", 1);
    ic.commitText("!", 1);
    

Menulis teks sebelum memilih

Jika IME Anda melakukan prediksi teks atau membutuhkan beberapa langkah untuk menulis glyph atau kata, Anda dapat menampilkan progres di kolom teks hingga pengguna memilih kata, lalu Anda dapat mengganti komposisi sebagian dengan teks yang sudah lengkap. Anda dapat memberikan perlakuan khusus pada teks dengan menambahkan "span" pada kolom tersebut saat Anda meneruskannya ke setComposingText().

Cuplikan berikut menunjukkan cara menampilkan progres di kolom teks:

Kotlin

    currentInputConnection.also { ic: InputConnection ->
        ic.setComposingText("Composi", 1)
        ic.setComposingText("Composin", 1)
        ic.commitText("Composing ", 1)
    }
    

Java

    InputConnection ic = getCurrentInputConnection();
    ic.setComposingText("Composi", 1);
    ic.setComposingText("Composin", 1);
    ic.commitText("Composing ", 1);
    

Screenshot berikut menunjukkan tampilannya kepada pengguna:

Gambar 3. Menulis teks sebelum memilih.

Mengintersep peristiwa kunci hardware

Meskipun jendela metode masukan tidak memiliki fokus yang jelas, jendela ini menerima peristiwa kunci hardware dan dapat memilih untuk menggunakannya atau meneruskannya ke aplikasi. Misalnya, Anda mungkin ingin menggunakan kunci arah untuk bernavigasi dalam UI guna memilih kandidat selama penulisan. Anda mungkin juga ingin menekan tombol kembali untuk menutup pop-up yang berasal dari jendela metode masukan.

Untuk mengintersep kunci hardware, ganti onKeyDown() dan onKeyUp().

Jangan lupa memanggil super() untuk kunci yang tidak ingin Anda tangani sendiri.

Membuat subjenis IME

Subjenis memungkinkan IME untuk mengekspos beberapa mode masukan dan bahasa yang didukung oleh IME. Subjenis dapat merepresentasikan:

  • Lokal seperti en_US atau fr_FR.
  • Mode masukan seperti suara, keyboard, atau tulisan tangan.
  • Gaya masukan, bentuk, atau properti lainnya yang spesifik untuk IME, seperti tata letak keyboard 10 tombol atau qwerty.

Pada dasarnya, mode dapat berupa teks seperti "keyboard", "suara", dan sebagainya. Subjenis juga dapat menampilkan kombinasi keduanya.

Informasi subjenis digunakan untuk dialog pengalih IME yang tersedia dari baris notifikasi dan juga untuk setelan IME. Informasi tersebut juga memungkinkan framework memunculkan subjenis IME tertentu secara langsung. Saat Anda membuat IME, gunakan fasilitas subjenis, karena fasilitas tersebut dapat membantu pengguna mengidentifikasi dan beralih antara bahasa dan mode IME berbeda.

Anda menentukan subjenis di salah satu file resource XML pada metode masukan, menggunakan elemen <subtype>. Cuplikan berikut menentukan IME dengan dua subjenis: subjenis keyboard untuk lokal bahasa Inggris AS, dan subjenis keyboard lainnya untuk lokal bahasa Prancis:

    <input-method xmlns:android="http://schemas.android.com/apk/res/android"
            android:settingsActivity="com.example.softkeyboard.Settings"
            android:icon="@drawable/ime_icon">
        <subtype android:name="@string/display_name_english_keyboard_ime"
                android:icon="@drawable/subtype_icon_english_keyboard_ime"
                android:imeSubtypeLanguage="en_US"
                android:imeSubtypeMode="keyboard"
                android:imeSubtypeExtraValue="somePrivateOption=true" />
        <subtype android:name="@string/display_name_french_keyboard_ime"
                android:icon="@drawable/subtype_icon_french_keyboard_ime"
                android:imeSubtypeLanguage="fr_FR"
                android:imeSubtypeMode="keyboard"
                android:imeSubtypeExtraValue="foobar=30,someInternalOption=false" />
        <subtype android:name="@string/display_name_german_keyboard_ime" ... />
    </input-method>
    

Untuk memastikan subjenis diberi label dengan benar di UI, gunakan %s untuk mendapatkan label subjenis yang sama dengan label lokal subjenis. Hal ini ditunjukkan dalam dua cuplikan berikutnya. Cuplikan pertama menunjukkan bagian dari file XML metode masukan:

    <subtype
        android:label="@string/label_subtype_generic"
        android:imeSubtypeLocale="en_US"
        android:icon="@drawable/icon_en_us"
        android:imeSubtypeMode="keyboard" />
    

Cuplikan berikutnya adalah bagian dari IME strings.xml file. Resource string label_subtype_generic, yang digunakan oleh definisi UI metode masukan untuk menyetel label subjenis, didefinisikan sebagai:

    <string name="label_subtype_generic">%s</string>
    

Setelan ini membuat nama tampilan subjenis dicocokkan dengan setelan lokal. Misalnya, dalam lokal bahasa Inggris, nama tampilan adalah “English (United States)”.

Memilih subjenis IME dari baris notifikasi

Sistem Android mengelola semua subjenis yang diekspos oleh semua IME. Subjenis IME diperlakukan sebagai mode IME milik mereka. Di baris notifikasi, pengguna dapat memilih subjenis yang tersedia untuk IME yang saat ini ditetapkan, seperti yang ditunjukkan pada screenshot berikut:

Gambar 4. Memilih subjenis IME dari baris notifikasi

Gambar 5. Menyetel preferensi subjenis di Setelan Sistem.

Memilih subjenis IME dari Setelan Sistem

Pengguna dapat mengontrol bagaimana subjenis digunakan pada panel setelan “Bahasa & masukan” di area Setelan Sistem.

Gambar 6. Memilih bahasa untuk IME.

Beralih antara subjenis IME

Anda dapat mengizinkan pengguna beralih dengan mudah antara beberapa subjenis IME dengan memberikan tombol pengalih, seperti ikon bahasa berbentuk globe, sebagai bagian dari keyboard. Hal tersebut sangat meningkatkan kegunaan keyboard, dan dapat mempermudah pengguna. Untuk mengaktifkan pengalihan tersebut, lakukan langkah-langkah berikut:

  1. Deklarasikan supportsSwitchingToNextInputMethod = "true" di file resource XML metode masukan. Deklarasi Anda harus mirip dengan cuplikan berikut.
        <input-method xmlns:android="http://schemas.android.com/apk/res/android"
                android:settingsActivity="com.example.softkeyboard.Settings"
                android:icon="@drawable/ime_icon"
                android:supportsSwitchingToNextInputMethod="true">
        
  2. Panggil metode shouldOfferSwitchingToNextInputMethod().
  3. Jika metode mengembalikan nilai true, tampilkan tombol pengalih.
  4. Saat pengguna mengetuk tombol pengalih, panggil switchToNextInputMethod(), yang meneruskan nilai false ke parameter kedua. Nilai false memberi tahu sistem untuk memperlakukan semua subjenis secara sama, apa pun IME miliknya. Sistem perlu melakukan siklus ke semua subjenis dalam IME saat ini ketika menentukan nilai true.

Perhatian: Sebelum Android 5.0 (API level 21), switchToNextInputMethod() tidak mengenali atribut supportsSwitchingToNextInputMethod. Jika beralih ke IME tanpa beralih kunci, pengguna dapat terjebak dalam IME, dan tidak dapat keluar dengan mudah.

Pertimbangan IME umum

Berikut adalah beberapa hal lain yang perlu dipertimbangkan saat Anda menerapkan IME:

  • Berikan cara bagi pengguna untuk menyetel opsi langsung dari UI IME.
  • Karena beberapa IME dapat diinstal di perangkat, berikan cara bagi pengguna untuk beralih ke IME yang berbeda langsung dari UI metode masukan.
  • Munculkan UI IME dengan cepat. Pramuat atau muat resource yang besar berdasarkan permintaan sehingga pengguna dapat langsung melihat IME setelah mereka mengetuk kolom teks. Resource dan tampilan cache untuk pemanggilan metode masukan berikutnya.
  • Sebaliknya, Anda harus langsung merilis alokasi memori yang besar setelah jendela metode masukan disembunyikan, sehingga aplikasi memiliki cukup memori untuk berjalan. Pertimbangkan untuk menggunakan pesan tertunda guna merilis resource jika IME berada dalam status tersembunyi selama beberapa detik.
  • Pastikan bahwa pengguna dapat memasukkan karakter sebanyak mungkin untuk bahasa atau lokal yang terkait dengan IME. Ingatlah bahwa pengguna dapat menggunakan tanda baca dalam sandi atau nama pengguna, sehingga IME Anda harus menyediakan banyak karakter yang berbeda guna memungkinkan pengguna memasukkan sandi dan mendapatkan akses ke perangkat.