Menambahkan Saran Kustom

Saat menggunakan dialog penelusuran atau widget penelusuran Android, Anda dapat memberikan saran penelusuran kustom yang dibuat dari data di aplikasi Anda. Misalnya, jika aplikasi Anda adalah kamus kata, Anda dapat menyarankan kata dari kamus yang cocok dengan teks yang diketikkan sejauh ini. Ini adalah saran yang paling bernilai, karena Anda dapat secara efektif memprediksi apa yang diinginkan pengguna dan memberikan akses instan ke sana. Gambar 1 menunjukkan contoh dialog penelusuran dengan saran kustom.

Setelah menyediakan saran kustom, Anda juga dapat menyediakan saran tersebut bagi Kotak Penelusuran Kilat di seluruh sistem, yang menyediakan akses ke konten Anda dari luar aplikasi.

Sebelum mulai mempelajari panduan untuk menambahkan saran kustom ini, Anda harus menerapkan dialog penelusuran Android atau widget penelusuran untuk penelusuran di aplikasi Anda. Jika belum melakukannya, lihat Membuat Antarmuka Penelusuran. Sebaiknya pelajari juga dokumentasi Penyedia Konten.

Dasar-Dasar

Gambar 1. Screenshot dialog penelusuran dengan saran penelusuran kustom.

Saat pengguna memilih sebuah saran kustom, sistem Android akan mengirim Intent ke aktivitas penelusuran Anda. Sementara kueri penelusuran normal mengirimkan intent bersama dengan tindakan ACTION_SEARCH, Anda dapat menentukan saran kustom agar menggunakan ACTION_VIEW (atau tindakan intent lain apa pun), dan juga menyertakan data yang relevan dengan saran yang dipilih. Melanjutkan contoh kamus di atas, saat pengguna memilih sebuah saran, aplikasi Anda dapat langsung membuka definisi kata tersebut, alih-alih menelusuri kamus untuk menemukan kecocokan.

Untuk memberikan saran kustom, lakukan langkah-langkah berikut:

Terapkan aktivitas penelusuran dasar, seperti yang dijelaskan dalam Membuat Antarmuka Penelusuran.
Modifikasi konfigurasi penelusuran dengan informasi tentang penyedia konten yang memberikan saran kustom.
Buat tabel (seperti dalam SQLiteDatabase) untuk saran Anda, dan format tabel tersebut dengan kolom-kolom yang bersifat wajib.
Buat Penyedia Konten yang memiliki akses ke tabel saran Anda, dan deklarasikan penyedia tersebut dalam manifes Anda.
Deklarasikan jenis Intent yang akan dikirim saat pengguna memilih saran (termasuk tindakan kustom dan data kustom).

Selain menampilkan dialog penelusuran, sistem Android juga menampilkan saran penelusuran. Anda hanya memerlukan penyedia konten tempat sistem dapat mengambil saran. Jika Anda belum menguasai cara membuat penyedia konten, baca panduan developer tentang Penyedia Konten sebelum melanjutkan.

Setelah sistem mengidentifikasi aktivitas penelusuran Anda dan menampilkan saran penelusuran, prosedur berikut akan terjadi saat pengguna mengetik kueri:

Sistem mengambil teks kueri penelusuran (apa pun yang telah diketikkan sejauh ini) dan mengirimkan kueri ke penyedia konten yang mengelola saran Anda.
Penyedia konten akan menampilkan Cursor yang mengarah ke semua saran yang relevan dengan teks kueri penelusuran.
Sistem menampilkan daftar saran yang disediakan oleh Cursor.

Setelah saran kustom ditampilkan, hal berikut dapat terjadi:

Jika pengguna mengetik kunci lain, atau mengubah kueri dengan cara apa pun, langkah di atas akan diulang dan daftar saran akan diperbarui sebagaimana mestinya.
Jika pengguna menjalankan penelusuran itu, saran akan diabaikan dan penelusuran akan dikirim ke aktivitas penelusuran Anda menggunakan intent ACTION_SEARCH normal.
Jika pengguna memilih sebuah saran, intent akan dikirim ke aktivitas penelusuran Anda, yang berisi tindakan kustom dan data kustom sehingga aplikasi Anda dapat membuka konten yang disarankan.

Memodifikasi konfigurasi penelusuran

Untuk menambahkan dukungan bagi saran kustom, tambahkan atribut android:searchSuggestAuthority ke elemen <searchable> dalam file konfigurasi penelusuran Anda. Contoh:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
    </searchable>

Anda mungkin memerlukan beberapa atribut tambahan, bergantung pada jenis intent yang Anda tambahkan ke setiap saran dan cara Anda memformat kueri ke penyedia konten. Atribut-atribut opsional lainnya dibahas di bagian selanjutnya.

Membuat Penyedia Konten

Membuat penyedia konten untuk saran kustom memerlukan pengetahuan sebelumnya tentang penyedia konten yang tercakup dalam panduan developer Penyedia Konten . Sebagian besar penyedia konten untuk saran khusus sama dengan penyedia konten lain apa pun. Namun, untuk setiap saran yang Anda berikan, masing-masing baris dalam Cursor harus menyertakan kolom tertentu yang dipahami dan digunakan oleh sistem untuk memformat saran.

Saat pengguna mulai mengetik dalam dialog penelusuran atau widget penelusuran, sistem akan mengkueri penyedia konten Anda untuk meminta saran dengan memanggil query() setiap kali sebuah huruf diketik. Dalam implementasi query() Anda, penyedia konten Anda harus menelusuri data saran Anda dan menampilkan Cursor yang mengarah ke baris-baris yang telah Anda tentukan sebagai saran yang baik.

Detail tentang pembuatan penyedia konten untuk saran kustom dibahas dalam dua bagian berikut:

Menangani kueri saran: Cara sistem mengirimkan permintaan ke penyedia konten dan cara menanganinya
Membuat tabel saran: Cara menentukan kolom yang diharapkan oleh sistem dalam Cursor yang ditampilkan bersama setiap kueri

Menangani kueri saran

Saat sistem meminta saran dari penyedia konten Anda, sistem akan memanggil metode query() milik penyedia konten tersebut. Anda harus menerapkan metode ini untuk menelusuri data saran Anda dan menampilkan Cursor yang mengarah ke saran yang Anda anggap relevan.

Berikut adalah ringkasan parameter yang diteruskan oleh sistem ke metode query() (dicantumkan secara berurutan):

uri

Selalu berupa Uri konten, yang diformat sebagai:

    content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Perilaku default-nya adalah sistem meneruskan URI ini dan menambahkan teks kueri ke bagian akhirnya. Contoh:

    content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

Teks kueri di bagian akhir ini dienkode menggunakan aturan encoding URI, sehingga Anda mungkin perlu mendekodenya sebelum melakukan penelusuran.

Bagian optional.suggest.path hanya disertakan dalam URI jika Anda telah menetapkan jalur tersebut dalam file konfigurasi penelusuran Anda dengan atribut android:searchSuggestPath. Bagian ini hanya diperlukan jika Anda menggunakan penyedia konten yang sama untuk beberapa aktivitas penelusuran, yang dalam hal ini, Anda perlu membedakan sumber kueri saran.

Catatan: SUGGEST_URI_PATH_QUERY bukanlah string literal yang disediakan dalam URI, melainkan konstanta yang harus Anda gunakan jika perlu merujuk ke jalur ini.

projection

Selalu null

selection

Nilai yang dimasukkan ke dalam atribut android:searchSuggestSelection file konfigurasi penelusuran, atau null jika Anda belum mendeklarasikan atribut android:searchSuggestSelection. Selengkapnya tentang penggunaan atribut ini untuk mendapatkan kueri dijelaskan di bawah.

selectionArgs

Berisi kueri penelusuran sebagai elemen pertama (dan satu-satunya) array ini jika Anda telah mendeklarasikan android:searchSuggestSelection di konfigurasi penelusuran. Jika Anda belum mendeklarasikan android:searchSuggestSelection, maka parameter ini bernilai null. Selengkapnya tentang penggunaan atribut ini untuk mendapatkan kueri dijelaskan di bawah.

sortOrder

Selalu null

Sistem dapat mengirimkan teks kueri penelusuran kepada Anda dalam dua cara. Cara default-nya adalah teks kueri disertakan sebagai jalur terakhir pada URI konten yang diteruskan dalam parameter uri. Namun, jika Anda menyertakan nilai pemilihan dalam atribut android:searchSuggestSelection konfigurasi penelusuran Anda, maka teks kueri akan diteruskan sebagai elemen pertama dari array string selectionArgs. Kedua opsi ini dirangkum di bagian selanjutnya.

Mendapatkan kueri dalam URI

Secara default, kueri ditambahkan sebagai segmen terakhir dari parameter uri (objek Uri). Untuk mengambil teks kueri dalam kasus ini, cukup gunakan getLastPathSegment(). Contoh:

Kotlin

    val query: String = uri.lastPathSegment.toLowerCase()

Java

    String query = uri.getLastPathSegment().toLowerCase();

Hasilnya, segmen terakhir Uri, yang merupakan teks kueri yang dimasukkan oleh pengguna, akan ditampilkan.

Mendapatkan kueri dalam argumen pemilihan

Alih-alih menggunakan URI, Anda mungkin lebih suka bila metode query() Anda menerima apa pun yang diperlukannya untuk menjalankan pencarian, dan membiarkan parameter selection dan selectionArgs menyediakan nilai yang sesuai. Dalam kasus semacam ini, tambahkan atribut android:searchSuggestSelection ke konfigurasi penelusuran dengan string pemilihan SQLite Anda. Dalam string pemilihan tersebut, sertakan tanda tanya ("?") sebagai placeholder untuk kueri penelusuran yang sebenarnya. Sistem akan memanggil query() dengan string pemilihan sebagai parameter selection dan kueri penelusuran sebagai elemen pertama dalam array selectionArgs.

Misalnya, berikut ini cara membentuk atribut android:searchSuggestSelection untuk membuat pernyataan penelusuran teks lengkap:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:searchSuggestSelection="word MATCH ?">
    </searchable>

Dengan konfigurasi ini, metode query() Anda akan memberikan parameter selection sebagai "word MATCH ?", dan parameter selectionArgs sebagai kueri penelusurannya. Saat Anda meneruskan parameter ini ke metode query() SQLite, sebagai argumennya masing-masing, parameter tersebut akan disatukan bersama (tanda tanya diganti dengan teks kueri). Jika Anda memilih untuk menerima kueri saran dengan cara ini dan perlu menambahkan karakter pengganti ke teks kueri, tambahkan karakter pengganti tersebut di akhir (dan/atau di awal) parameter selectionArgs, karena nilai ini digabung dalam tanda kutip dan disisipkan di tempat tanda tanya berada.

Atribut baru lainnya dalam contoh di atas adalah android:searchSuggestIntentAction, yang menentukan tindakan intent yang dikirim bersama setiap intent saat pengguna memilih sebuah saran. Hal ini dibahas lebih lanjut di bagian Mendeklarasikan Intent untuk Saran.

Tips: Jika Anda tidak ingin menentukan klausa pemilihan dalam atribut android:searchSuggestSelection, tetapi tetap ingin menerima teks kueri dalam parameter selectionArgs, cukup berikan nilai selain null untuk atribut android:searchSuggestSelection. Tindakan ini memicu kueri yang akan diteruskan dalam selectionArgs, dan Anda dapat mengabaikan parameter selection. Dengan begitu, Anda dapat menentukan klausa pemilihan sebenarnya di tingkat yang lebih rendah, sehingga penyedia konten tidak perlu menanganinya.

Membuat tabel saran

Saat Anda menampilkan saran ke sistem dengan Cursor, sistem mengharapkan kolom spesifik di setiap baris. Jadi, terlepas dari apakah Anda memutuskan untuk menyimpan data saran di database SQLite di perangkat, database di server web, atau format lain di perangkat atau web, Anda harus memformat saran sebagai baris-baris tabel dan menyajikannya dengan Cursor.

Catatan: Jika saran penelusuran Anda tidak disimpan dalam format tabel (seperti tabel SQLite) menggunakan kolom-kolom yang diwajibkan oleh sistem, maka Anda dapat menelusuri data saran untuk menemukan kecocokan, lalu memformatnya ke dalam tabel yang diperlukan di setiap permintaan. Untuk melakukannya, buatlah MatrixCursor menggunakan nama kolom yang diwajibkan, lalu tambahkan sebuah baris untuk setiap saran menggunakan addRow(Object[]). Tampilkan hasil akhir dari metode query() Penyedia Konten Anda.

Sistem memahami berbagai kolom, tetapi hanya dua kolom yang bersifat wajib:

_ID: ID baris unik dalam bentuk integer untuk setiap saran. Sistem mewajibkan kolom ini untuk menyajikan saran dalam ListView.
SUGGEST_COLUMN_TEXT_1: String yang disajikan sebagai saran.

Kolom-kolom berikut bersifat opsional (dan sebagian besar akan dibahas lebih lanjut di bagian berikut):

SUGGEST_COLUMN_TEXT_2: String. Jika Cursor menyertakan kolom ini, maka semua saran diberikan dalam format dua baris. String dalam kolom ini akan ditampilkan sebagai baris teks kedua yang lebih kecil di bawah teks saran utama. Kolom ini boleh kosong atau null untuk menunjukkan tidak ada teks sekunder.
SUGGEST_COLUMN_ICON_1: Resource, konten, atau string URI file yang bersifat drawable. Jika Cursor menyertakan kolom ini, maka semua saran akan diberikan dalam format ikon-plus-teks dengan ikon drawable di sebelah kiri. Kolom ini boleh kosong atau null untuk menunjukkan tidak ada ikon di baris ini.
SUGGEST_COLUMN_ICON_2: Resource, konten, atau string URI file yang bersifat drawable. Jika Cursor menyertakan kolom ini, maka semua saran akan diberikan dalam format ikon-plus-teks dengan ikon di sebelah kanan. Kolom ini bisa kosong atau null untuk menunjukkan tidak ada ikon di baris ini.
SUGGEST_COLUMN_INTENT_ACTION: String tindakan intent. Jika kolom ini ada dan berisi nilai di baris yang ditentukan, tindakan yang ditetapkan di sini akan digunakan saat membentuk intent saran. Jika elemen ini tidak disediakan, tindakan akan diambil dari kolom android:searchSuggestIntentAction dalam konfigurasi penelusuran Anda. Jika tindakan Anda sama untuk semua saran, akan lebih efisien jika Anda menentukan tindakan menggunakan android:searchSuggestIntentAction dan menghapus kolom ini.
SUGGEST_COLUMN_INTENT_DATA: String URI data. Jika kolom ini ada dan berisi nilai di baris yang ditentukan, maka nilai tersebut akan menjadi data yang digunakan saat membentuk intent saran. Jika elemen ini tidak disediakan, data akan diambil dari kolom android:searchSuggestIntentData dalam konfigurasi penelusuran Anda. Jika tidak ada sumber yang disediakan, kolom data intent akan bernilai null. Jika data Anda sama untuk semua saran, atau dapat dideskripsikan menggunakan sebuah bagian tetap dan sebuah ID tertentu, maka akan lebih efisien jika Anda menentukannya menggunakan android:searchSuggestIntentData dan menghapus kolom ini.
SUGGEST_COLUMN_INTENT_DATA_ID: String jalur URI. Jika kolom ini ada dan berisi nilai di baris yang ditentukan, maka "/" dan nilai ini akan ditambahkan ke akhir kolom data pada intent. Ini hanya boleh digunakan jika kolom data yang ditentukan oleh atribut android:searchSuggestIntentData dalam konfigurasi penelusuran telah disetel ke string dasar yang sesuai.
SUGGEST_COLUMN_INTENT_EXTRA_DATA: Data arbitrer. Jika kolom ini ada dan berisi nilai di baris yang ditentukan, maka nilai tersebut akan menjadi data ekstra yang digunakan saat membentuk intent saran. Jika tidak disediakan, kolom data ekstra untuk intent ini akan bernilai null. Dengan adanya kolom ini, saran dapat memberikan data tambahan yang disertakan sebagai data ekstra dalam kunci EXTRA_DATA_KEY intent.
SUGGEST_COLUMN_QUERY: Jika kolom ini ada dan elemen ini ada di baris yang ditentukan, maka elemen ini akan menjadi data yang digunakan saat membentuk kueri saran, yang disertakan sebagai data ekstra dalam kunci QUERY intent. Diwajibkan jika tindakan saran adalah ACTION_SEARCH; jika sebaliknya, opsional.
SUGGEST_COLUMN_SHORTCUT_ID: Hanya digunakan saat memberikan saran untuk Kotak Penelusuran Kilat. Kolom ini menunjukkan apakah saran penelusuran perlu disimpan sebagai pintasan, dan apakah saran penelusuran perlu divalidasi. Pintasan biasanya terbentuk saat pengguna mengklik saran dari Kotak Penelusuran Kilat. Jika kolom ini tidak ada, hasil akan disimpan sebagai pintasan dan tidak pernah di-refresh. Jika disetel ke SUGGEST_NEVER_MAKE_SHORTCUT, hasil tidak akan disimpan sebagai pintasan. Jika sebaliknya, ID pintasan akan digunakan untuk memeriksa kembali ketersediaan saran terbaru menggunakan SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING: Hanya digunakan saat memberikan saran untuk Kotak Penelusuran Kilat. Kolom ini menetapkan bahwa spinner, bukan ikon dari SUGGEST_COLUMN_ICON_2, perlu ditampilkan selagi pintasan saran ini sedang di-refresh di Kotak Penelusuran Kilat.

Sebagian dari kolom ini dibahas lebih lanjut di bawah.

Mendeklarasikan Intent untuk Saran

Saat pengguna memilih saran dari daftar yang ditampilkan di bawah dialog atau widget penelusuran, sistem akan mengirimkan Intent kustom ke aktivitas penelusuran Anda. Anda harus menentukan tindakan dan data untuk intent ini.

Mendeklarasikan tindakan intent

Tindakan intent yang paling umum untuk saran kustom adalah ACTION_VIEW, yang sesuai jika Anda ingin membuka sesuatu, seperti definisi kata, informasi kontak seseorang, atau halaman web. Namun, tindakan intent dapat berupa tindakan lain dan bahkan dapat berbeda untuk setiap saran.

Bergantung pada apakah Anda ingin semua saran menggunakan tindakan intent yang sama, Anda dapat menentukan tindakan dengan dua cara:

Menggunakan atribut android:searchSuggestIntentAction file konfigurasi penelusuran untuk menentukan tindakan untuk semua saran.

Contoh:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW" >
    </searchable>

Menggunakan kolom SUGGEST_COLUMN_INTENT_ACTION untuk menentukan tindakan untuk masing-masing saran.
Tambahkan kolom SUGGEST_COLUMN_INTENT_ACTION ke tabel saran Anda dan, untuk setiap saran, tempatkan tindakan yang akan digunakan (seperti "android.intent.action.VIEW") di dalamnya.

Anda juga dapat menggabungkan kedua teknik ini. Misalnya, Anda dapat menyertakan atribut android:searchSuggestIntentAction dengan tindakan yang akan digunakan untuk semua saran secara default, lalu mengganti tindakan ini untuk beberapa saran dengan mendeklarasikan tindakan berbeda dalam kolom SUGGEST_COLUMN_INTENT_ACTION. Jika Anda tidak menyertakan nilai dalam kolom SUGGEST_COLUMN_INTENT_ACTION, maka intent yang ditentukan dalam atribut android:searchSuggestIntentAction akan digunakan.

Catatan: Jika Anda tidak menyertakan atribut android:searchSuggestIntentAction dalam konfigurasi penelusuran, maka Anda harus menyertakan nilai dalam kolom SUGGEST_COLUMN_INTENT_ACTION untuk setiap saran; jika tidak, intent akan gagal.

Mendeklarasikan data intent

Saat pengguna memilih sebuah saran, aktivitas penelusuran Anda akan menerima intent yang berisi tindakan yang Anda tetapkan (seperti yang dibahas di bagian sebelumnya), tetapi intent ini juga harus menyertakan data agar aktivitas Anda dapat mengidentifikasi saran mana yang dipilih. Secara khusus, data ini harus unik untuk setiap saran, seperti ID baris untuk saran dalam tabel SQLite Anda. Setelah intent diterima, Anda dapat mengambil data yang terlampir dengan getData() atau getDataString().

Anda dapat menentukan data yang disertakan dengan intent melalui dua cara:

Menentukan data untuk setiap saran di dalam kolom SUGGEST_COLUMN_INTENT_DATA tabel saran Anda.
Berikan semua informasi data yang diperlukan untuk setiap intent dalam tabel saran dengan menyertakan kolom SUGGEST_COLUMN_INTENT_DATA lalu mengisinya dengan data unik untuk setiap baris. Data dari kolom ini ditautkan ke intent persis seperti saat Anda menetapkannya dalam kolom ini. Selanjutnya, Anda dapat mengambilnya dengan getData() atau getDataString().

Tips: Biasanya, cara yang paling mudah adalah menggunakan ID baris tabel sebagai data Intent, karena ID ini selalu unik. Dan cara termudah untuk melakukannya adalah dengan menggunakan nama kolom SUGGEST_COLUMN_INTENT_DATA sebagai alias untuk kolom ID baris. Lihat contoh aplikasi Kamus yang Dapat Ditelusuri untuk contoh di mana SQLiteQueryBuilder membuat peta proyeksi nama kolom ke alias.
Memisahkan URI data menjadi dua bagian: bagian yang umum untuk semua saran, dan bagian yang unik untuk setiap saran. Tempatkan bagian-bagian ini, berturut-turut, ke dalam atribut android:searchSuggestintentData konfigurasi penelusuran dan kolom SUGGEST_COLUMN_INTENT_DATA_ID tabel saran Anda.
Deklarasikan bagian URI yang berlaku umum untuk semua saran dalam atribut android:searchSuggestIntentData konfigurasi penelusuran Anda. Contoh:
```
    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:searchSuggestIntentData="content://com.example/datatable" >
    </searchable>
    
```
Kemudian sertakan jalur akhir untuk setiap saran (bagian unik) di dalam kolom SUGGEST_COLUMN_INTENT_DATA_ID tabel saran Anda. Saat pengguna memilih sebuah saran, sistem akan mengambil string dari android:searchSuggestIntentData, menambahkan garis miring ("/") ke bagian akhir, lalu menambahkan nilai yang terkait dari kolom SUGGEST_COLUMN_INTENT_DATA_ID untuk membentuk URI konten lengkap. Selanjutnya, Anda dapat mengambil Uri dengan getData().

Menambahkan lebih banyak data

Jika Anda perlu menyampaikan lebih banyak informasi dengan intent Anda, Anda dapat menambahkan kolom tabel lain, SUGGEST_COLUMN_INTENT_EXTRA_DATA, yang dapat menyimpan informasi tambahan tentang saran tersebut. Data yang disimpan dalam kolom ini ditempatkan di EXTRA_DATA_KEY pada Bundle ekstra intent tersebut.

Menangani Intent

Setelah Anda menyediakan saran penelusuran kustom dengan intent kustom, aktivitas penelusuran Anda harus dapat menangani intent tersebut saat pengguna memilih saran. Hal ini selain menangani intent ACTION_SEARCH, yang telah dilakukan oleh aktivitas penelusuran Anda. Berikut ini contoh cara menangani intent selama callback onCreate() aktivitas Anda:

Kotlin

    when(intent.action) {
        Intent.ACTION_SEARCH -> {
            // Handle the normal search query case
            intent.getStringExtra(SearchManager.QUERY)?.also { query ->
                doSearch(query)
            }
        }
        Intent.ACTION_VIEW -> {
            // Handle a suggestions click (because the suggestions all use ACTION_VIEW)
            showResult(intent.data)
        }
    }

Java

    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        // Handle the normal search query case
        String query = intent.getStringExtra(SearchManager.QUERY);
        doSearch(query);
    } else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
        // Handle a suggestions click (because the suggestions all use ACTION_VIEW)
        Uri data = intent.getData();
        showResult(data);
    }

Dalam contoh ini, tindakan intent adalah ACTION_VIEW dan data berisi URI lengkap yang mengarah ke item yang disarankan, seperti yang disintesis oleh string android:searchSuggestIntentData dan kolom SUGGEST_COLUMN_INTENT_DATA_ID. URI ini lalu diteruskan ke metode showResult() lokal yang mengkueri penyedia konten untuk item yang ditentukan oleh URI.

Catatan: Anda tidak perlu menambahkan filter intent ke file manifes Android untuk tindakan intent yang Anda tetapkan dengan atribut android:searchSuggestIntentAction atau kolom SUGGEST_COLUMN_INTENT_ACTION. Sistem akan membuka aktivitas penelusuran Anda menurut nama untuk mengirim intent saran, sehingga aktivitas tidak perlu mendeklarasikan tindakan yang diterima.

Menulis ulang teks kueri

Jika pengguna membuka daftar saran menggunakan kontrol arah (misalnya dengan trackball atau d-pad), secara default teks kueri tidak diperbarui. Namun, Anda dapat menulis ulang teks kueri pengguna untuk sementara saat teks tersebut ditampilkan di kotak teks bersama kueri yang cocok dengan saran yang sedang difokus. Dengan begitu, pengguna dapat melihat kueri yang sedang disarankan (jika ada), lalu memilih kotak penelusuran dan mengedit kueri sebelum mengirimkannya sebagai penelusuran.

Anda dapat menulis ulang teks kueri dengan cara berikut:

Menambahkan atribut android:searchMode ke konfigurasi penelusuran Anda dengan nilai "queryRewriteFromText". Dalam hal ini, isi kolom SUGGEST_COLUMN_TEXT_1 saran akan digunakan untuk menulis ulang teks kueri.
Menambahkan atribut android:searchMode ke konfigurasi penelusuran Anda dengan nilai "queryRewriteFromData". Dalam hal ini, isi kolom SUGGEST_COLUMN_INTENT_DATA saran akan digunakan untuk menulis ulang teks kueri. Cara ini hanya boleh digunakan dengan URI atau format data lain yang diharapkan untuk terlihat oleh pengguna, seperti URL HTTP. Skema URI internal tidak boleh digunakan untuk menulis ulang kueri dengan cara ini.
Memberikan string teks kueri unik di kolom SUGGEST_COLUMN_QUERY tabel saran Anda. Jika kolom ini ada dan berisi nilai untuk saran saat ini, kolom ini akan digunakan untuk menulis ulang teks kueri (dan mengganti salah satu implementasi sebelumnya).

Menyediakan saran penelusuran ke Kotak Penelusuran Kilat

Setelah mengonfigurasi aplikasi Anda agar memberikan saran penelusuran kustom, menyediakan saran tersebut bagi Kotak Penelusuran Kilat yang dapat diakses secara global dapat dilakukan dengan hanya mengubah konfigurasi penelusuran Anda agar menyertakan android:includeInGlobalSearch sebagai "true".

Satu-satunya skenario yang memerlukan kerja tambahan adalah jika penyedia konten Anda meminta izin baca. Dalam hal ini, Anda perlu menambahkan elemen <path-permission> khusus agar penyedia memberi Kotak Penelusuran Kilat akses baca ke penyedia konten Anda. Contoh:

    <provider android:name="MySuggestionProvider"
              android:authorities="com.example.MyCustomSuggestionProvider"
              android:readPermission="com.example.provider.READ_MY_DATA"
              android:writePermission="com.example.provider.WRITE_MY_DATA">
      <path-permission android:pathPrefix="/search_suggest_query"
                       android:readPermission="android.permission.GLOBAL_SEARCH" />
    </provider>

Dalam contoh ini, penyedia membatasi akses baca dan tulis ke konten. Elemen <path-permission> mengubah pembatasan itu dengan memberikan akses baca ke konten yang berada di dalam awalan jalur "/search_suggest_query" jika izin "android.permission.GLOBAL_SEARCH" ada. Cara ini memberikan akses ke Kotak Penelusuran Kilat sehingga dapat mengkueri penyedia konten Anda agar menyediakan saran.

Jika penyedia konten Anda tidak menerapkan izin baca, Kotak Penelusuran Kilat dapat membacanya secara default.

Mengaktifkan saran di perangkat

Meskipun dikonfigurasi untuk memberikan saran di Kotak Penelusuran Kilat, aplikasi Anda tidak benar-benar diaktifkan untuk memberikan saran di Kotak Penelusuran Kilat. Pengguna-lah yang harus memilih apakah akan menyertakan saran dari aplikasi Anda di Kotak Penelusuran Kilat atau tidak. Untuk mengaktifkan saran penelusuran dari aplikasi Anda, pengguna harus membuka "Item yang dapat ditelusuri" (di Setelan > Penelusuran) dan mengaktifkan aplikasi Anda sebagai item yang dapat ditelusuri.

Setiap aplikasi yang tersedia untuk Kotak Penelusuran Kilat memiliki entri di halaman setelan Item yang dapat ditelusuri. Entri ini menyertakan nama aplikasi dan deskripsi singkat dari konten yang dapat ditelusuri dari aplikasi tersebut dan disediakan sebagai saran di Kotak Penelusuran Kilat. Untuk menentukan teks deskripsi bagi aplikasi penelusuran Anda, tambahkan atribut android:searchSettingsDescription ke konfigurasi penelusuran Anda. Contoh:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:includeInGlobalSearch="true"
        android:searchSettingsDescription="@string/search_description" >
    </searchable>

String untuk android:searchSettingsDescription harus sesingkat mungkin dan menyatakan konten yang dapat ditelusuri. Misalnya, "Artis, album, dan lagu" untuk aplikasi musik, atau "Catatan tersimpan" untuk aplikasi notepad. Pemberian deskripsi ini penting agar pengguna mengetahui jenis saran yang disediakan. Anda harus selalu menyertakan atribut ini jika android:includeInGlobalSearch bernilai "true".

Ingat bahwa pengguna harus mengakses menu setelan untuk mengaktifkan saran penelusuran untuk aplikasi Anda sebelum saran penelusuran tersebut ditampilkan di Kotak Penelusuran Kilat. Dengan demikian, jika penelusuran merupakan aspek penting dari aplikasi Anda, maka sebaiknya Anda memikirkan cara untuk menyampaikan hal itu kepada pengguna. Misalnya, saat pengguna meluncurkan aplikasi untuk pertama kalinya, Anda dapat memberikan catatan yang berisi petunjuk cara mengaktifkan saran penelusuran untuk Kotak Penelusuran Kilat.

Mengelola pintasan saran Kotak Penelusuran Kilat

Saran yang dipilih pengguna dari Kotak Penelusuran Kilat dapat otomatis dibuat menjadi pintasan. Ini adalah saran yang telah disalin sistem dari penyedia konten Anda, sehingga dapat mengakses saran dengan cepat tanpa perlu mengkueri ulang penyedia konten Anda.

Secara default, setelan ini diaktifkan untuk semua saran yang diambil oleh Kotak Penelusuran Kilat, tetapi jika data saran Anda berubah dari waktu ke waktu, maka Anda dapat meminta agar pintasan di-refresh. Misalnya, jika saran Anda merujuk pada data dinamis, seperti status kehadiran kontak, sebaiknya Anda meminta agar pintasan saran di-refresh saat ditampilkan kepada pengguna. Untuk melakukannya, sertakan SUGGEST_COLUMN_SHORTCUT_ID dalam tabel saran Anda. Dengan kolom ini, Anda dapat mengonfigurasi perilaku pintasan untuk setiap saran melalui salah satu cara berikut:

Meminta Kotak Penelusuran Kilat mengkueri ulang penyedia konten Anda agar memberikan versi baru pintasan saran.
Berikan nilai dalam kolom SUGGEST_COLUMN_SHORTCUT_ID dan saran akan dikueri ulang agar memberikan versi baru setiap kali pintasan ditampilkan. Pintasan ditampilkan dengan cepat bersama data apa pun yang terakhir tersedia sampai kueri refresh ditampilkan, yang pada saat itu saran di-refresh dengan informasi baru. Kueri refresh dikirim ke penyedia konten Anda dengan jalur URI SUGGEST_URI_PATH_SHORTCUT (bukan SUGGEST_URI_PATH_QUERY).

Cursor yang Anda tampilkan harus berisi satu saran yang menggunakan kolom yang sama dengan saran aslinya, atau kosong, yang menunjukkan bahwa pintasan tidak lagi valid (dalam hal ini, saran menghilang dan pintasan akan dihapus).

Jika saran mengacu pada data yang perlu waktu lama untuk di-refresh, seperti refresh berbasis jaringan, Anda juga dapat menambahkan kolom SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING ke tabel saran dengan nilai "true" agar dapat menampilkan spinner progres untuk ikon di sebelah kanan hingga refresh selesai. Nilai apa pun selain "true" tidak akan menampilkan spinner progres.
Mencegah saran disalin ke pintasan.
Berikan nilai SUGGEST_NEVER_MAKE_SHORTCUT dalam kolom SUGGEST_COLUMN_SHORTCUT_ID. Dalam hal ini, saran tidak akan pernah disalin ke pintasan. Tindakan ini hanya diperlukan jika Anda benar-benar tidak ingin saran yang disalin sebelumnya ditampilkan. (Ingat bahwa jika Anda memberikan nilai normal untuk kolom ini, maka pintasan saran hanya muncul sampai kueri refresh ditampilkan.)
Mengizinkan perilaku pintasan default untuk diterapkan.
Biarkan SUGGEST_COLUMN_SHORTCUT_ID kosong untuk setiap saran yang tidak akan berubah dan dapat disimpan sebagai pintasan.

Jika tidak ada saran yang berubah, Anda tidak memerlukan kolom SUGGEST_COLUMN_SHORTCUT_ID sama sekali.

Catatan: Kotak Penelusuran Kilat pada akhirnya memutuskan apakah pintasan untuk sebuah saran akan dibuat atau tidak, dengan mempertimbangkan nilai ini sebagai permintaan yang kuat dari aplikasi Anda. Tidak ada jaminan bahwa perilaku yang Anda minta untuk pintasan saran akan dipenuhi.

Tentang peringkat saran Kotak Penelusuran Kilat

Setelah saran penelusuran aplikasi Anda tersedia untuk Kotak Penelusuran Kilat, peringkat Kotak Penelusuran Kilat menentukan bagaimana saran tersebut ditampilkan kepada pengguna untuk kueri tertentu. Hal ini dapat dipengaruhi oleh banyaknya aplikasi lain yang memiliki hasil untuk kueri tersebut, dan seberapa sering pengguna memilih hasil dari aplikasi Anda dibandingkan dengan hasil dari aplikasi lain. Tidak ada jaminan terkait cara memeringkatkan saran Anda, atau apakah saran aplikasi Anda akan ditampilkan untuk kueri tertentu. Secara umum, jika Anda memberikan hasil yang berkualitas, peluang bagi saran aplikasi Anda untuk ditampilkan di posisi yang menonjol akan lebih besar. Sebaliknya, aplikasi yang memberikan saran tidak berkualitas lebih mungkin untuk menempati peringkat yang rendah atau tidak ditampilkan.

Lihat contoh aplikasi Kamus yang Dapat Ditelusuri untuk demonstrasi lengkap saran penelusuran kustom.