Halaman ini diterjemahkan oleh Cloud Translation API.

Menambahkan saran penelusuran khusus

Saat menggunakan dialog penelusuran atau widget penelusuran Android, Anda dapat memberikan saran penelusuran kustom yang dibuat dari data di aplikasi. Misalnya, jika aplikasi berupa kamus, Anda dapat menyarankan kata dari kamus yang cocok dengan teks yang dimasukkan di kolom penelusuran sebelum pengguna selesai memasukkan kuerinya. Saran ini sangat berharga karena dapat secara efektif memprediksi apa yang diinginkan pengguna dan memberikan akses instan ke sana. Gambar 1 menunjukkan contoh dialog penelusuran dengan saran kustom.

Setelah memberikan saran kustom, Anda juga dapat menyediakannya untuk Kotak Penelusuran Cepat seluruh sistem, yang memberikan akses ke konten Anda dari luar aplikasi.

Sebelum menambahkan saran kustom, terapkan dialog penelusuran Android atau widget penelusuran untuk penelusuran di aplikasi Anda. Lihat Membuat antarmuka penelusuran dan Penyedia konten.

Dasar-dasar

Gambar 1. Screenshot dialog penelusuran dengan saran penelusuran kustom.

Saat pengguna memilih saran kustom, sistem akan mengirimkan Intent ke aktivitas yang dapat ditelusuri. Tidak seperti kueri penelusuran biasa yang mengirimkan intent dengan tindakan ACTION_SEARCH, Anda dapat menentukan saran kustom untuk menggunakan ACTION_VIEW—atau tindakan intent lainnya—dan juga menyertakan data yang relevan dengan saran yang dipilih. Dalam contoh kamus, saat pengguna memilih saran, aplikasi dapat langsung membuka definisi kata tersebut, bukan menelusuri kamus untuk menemukan kecocokan.

Untuk memberikan saran kustom, lakukan langkah-langkah berikut:

Terapkan aktivitas penelusuran dasar, seperti yang dijelaskan dalam Membuat antarmuka penelusuran.
Ubah konfigurasi penelusuran dengan informasi tentang penyedia konten yang memberikan saran kustom.
Buat tabel, seperti di SQLiteDatabase, untuk saran Anda, dan format tabel dengan kolom 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.

Sama halnya dengan menampilkan dialog penelusuran, sistem Android juga menampilkan saran penelusuran Anda. Anda memerlukan penyedia konten tempat sistem dapat mengambil saran Anda. Baca Penyedia konten untuk mempelajari cara membuat penyedia konten.

Jika sistem mengidentifikasi bahwa aktivitas Anda dapat ditelusuri dan memberikan saran penelusuran, prosedur berikut akan terjadi saat pengguna memasukkan kueri:

Sistem mengambil teks kueri penelusuran—artinya, apa pun yang dimasukkan sejauh ini—dan melakukan 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 akan menampilkan daftar saran yang diberikan oleh Cursor.

Setelah saran kustom ditampilkan, hal berikut dapat terjadi:

Jika pengguna memasukkan huruf lain atau mengubah kueri dengan cara apa pun, langkah sebelumnya akan diulang dan daftar saran akan diperbarui sebagaimana mestinya.
Jika pengguna menjalankan penelusuran, 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 membawa tindakan kustom dan data kustom sehingga aplikasi Anda dapat membuka konten yang disarankan.

Mengubah konfigurasi penelusuran

Guna menambahkan dukungan untuk saran kustom, tambahkan atribut android:searchSuggestAuthority ke elemen <searchable> dalam file konfigurasi penelusuran Anda, seperti yang ditunjukkan dalam contoh berikut:

<?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 atribut tambahan, bergantung pada jenis intent yang dilampirkan ke setiap saran dan cara Anda memformat kueri ke penyedia konten. Atribut opsional lainnya dibahas di bagian berikut.

Membuat penyedia konten

Agar dapat membuat penyedia konten untuk saran kustom, lihat Penyedia konten terlebih dahulu untuk mempelajari cara membuat penyedia konten. Penyedia konten untuk saran kustom serupa dengan penyedia konten lainnya. Namun, untuk setiap saran yang Anda berikan, masing-masing baris dalam Cursor harus menyertakan kolom tertentu yang dipahami dan digunakan sistem untuk memformat saran.

Saat pengguna memasukkan teks di dialog penelusuran atau widget penelusuran, sistem akan mengkueri penyedia konten Anda untuk mendapatkan saran dengan memanggil query() setiap kali huruf dimasukkan. Dalam implementasi query(), penyedia konten Anda harus menelusuri data saran dan menampilkan Cursor yang mengarah ke baris yang dianggapnya sebagai saran yang baik.

Detail tentang cara membuat 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 dengan setiap kueri.

Menangani kueri saran

Saat sistem meminta saran dari penyedia konten, sistem akan memanggil metode query() penyedia konten. Terapkan metode ini untuk menelusuri data saran dan tampilkan Cursor yang mengarah ke saran yang Anda anggap relevan.

Berikut adalah ringkasan parameter yang diteruskan sistem ke metode query() Anda, yang tercantum secara berurutan:

uri: Selalu berupa konten Uri, yang diformat sebagai berikut:
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Perilaku default-nya adalah sistem meneruskan URI ini dan menambahkan teks kueri ke dalamnya:

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

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

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

Catatan: SUGGEST_URI_PATH_QUERY bukan string literal yang disediakan dalam URI; melainkan konstanta. Gunakan jika Anda perlu merujuk ke jalur ini.
projection: Selalu null.
selection: Nilai yang diberikan dalam atribut android:searchSuggestSelection file konfigurasi penelusuran Anda, atau null jika Anda tidak mendeklarasikan atribut android:searchSuggestSelection. Bagian berikut akan membahas hal ini lebih lanjut.
selectionArgs: Berisi kueri penelusuran sebagai elemen pertama dan satu-satunya array jika Anda mendeklarasikan atribut android:searchSuggestSelection dalam konfigurasi penelusuran Anda. Jika Anda tidak mendeklarasikan android:searchSuggestSelection, parameter ini akan bernilai null. Bagian berikut membahas hal ini lebih lanjut.
sortOrder: Selalu null.

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

Mendapatkan kueri dalam URI

Secara default, kueri ditambahkan sebagai segmen terakhir dari parameter uri—objek Uri. Untuk mengambil teks kueri dalam hal ini, gunakan getLastPathSegment(), seperti ditunjukkan pada contoh berikut:

Kotlin

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

Java

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

Tindakan ini menampilkan segmen terakhir Uri, yang merupakan teks kueri yang dimasukkan pengguna.

Mendapatkan kueri dalam argumen pemilihan

Daripada menggunakan URI, mungkin akan lebih tepat jika metode query() menerima semua yang diperlukan untuk melakukan pencarian, dan Anda mungkin ingin parameter selection dan selectionArgs membawa nilai yang sesuai. Dalam hal ini, tambahkan atribut android:searchSuggestSelection ke konfigurasi yang dapat ditelusuri dengan string pemilihan SQLite Anda. Dalam string pemilihan, sertakan tanda tanya (?) sebagai placeholder untuk kueri penelusuran yang sebenarnya. Sistem 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 penelusuran. Jika Anda meneruskannya ke metode query() SQLite, sebagai argumennya masing-masing, argumen tersebut akan disintesis bersama—artinya, tanda tanya diganti dengan teks kueri. Jika Anda menerima kueri saran dengan cara ini dan perlu menambahkan karakter pengganti ke teks kueri, tambahkan atau berikan awalan ke parameter selectionArgs, karena nilai ini digabungkan dalam tanda kutip dan disisipkan sebagai ganti tanda tanya.

Atribut lain dalam contoh sebelumnya adalah android:searchSuggestIntentAction, yang menentukan tindakan intent yang dikirim bersama setiap intent saat pengguna memilih sebuah saran. Hal ini dibahas lebih lanjut di bagian Menyatakan intent untuk saran.

Tips: Jika tidak ingin menentukan klausa pemilihan dalam atribut android:searchSuggestSelection, tetapi tetap ingin menerima teks kueri dalam parameter selectionArgs, berikan nilai non-null untuk atribut android:searchSuggestSelection. Tindakan ini memicu kueri untuk meneruskan selectionArgs, dan Anda dapat mengabaikan parameter selection. Dengan cara ini, Anda dapat menentukan klausa pemilihan sebenarnya pada 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. Terlepas dari apakah Anda menyimpan data saran di database SQLite pada perangkat, database di server web, atau format lain di perangkat atau web, format saran sebagai baris dalam tabel dan tampilkan dengan Cursor.

Catatan: Jika saran penelusuran Anda tidak disimpan dalam format tabel—seperti tabel SQLite—menggunakan kolom yang diperlukan oleh sistem, Anda dapat menelusuri data saran untuk menemukan kecocokan, lalu memformatnya ke dalam tabel yang diperlukan pada setiap permintaan. Untuk melakukannya, buat MatrixCursor menggunakan nama kolom yang diperlukan, lalu tambahkan baris untuk setiap saran menggunakan addRow(Object[]). Tampilkan produk akhir dari metode query() penyedia konten Anda.

Sistem memahami beberapa kolom, tetapi hanya dua yang wajib diisi:

_ID: ID baris unik dalam bentuk integer untuk setiap saran. Sistem memerlukannya untuk memberikan saran dalam ListView.
SUGGEST_COLUMN_TEXT_1: String yang disajikan sebagai saran.

Kolom berikut bersifat opsional. Sebagian besar topik dibahas lebih lanjut di bagian berikut.

SUGGEST_COLUMN_TEXT_2: String. Jika Cursor Anda menyertakan kolom ini, semua saran akan diberikan dalam format dua baris. String dalam kolom ini 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, semua saran akan diberikan dalam format ikon-plus-teks dengan ikon drawable di sebelah kiri. Nilainya bisa null atau nol untuk menunjukkan tidak ada ikon di baris ini.
SUGGEST_COLUMN_ICON_2: Resource, konten, atau string URI file yang bersifat drawable. Jika Cursor Anda menyertakan kolom ini, semua saran akan diberikan dalam format ikon-plus-teks dengan ikon di sebelah kanan. Kolom ini bisa berisi null atau nol 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 ditentukan 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, data ini akan 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 dijelaskan menggunakan bagian konstanta dan ID tertentu, akan lebih efisien untuk 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 kolom data dalam intent. Hanya gunakan metode ini jika kolom data yang ditentukan oleh atribut android:searchSuggestIntentData dalam konfigurasi penelusuran sudah disetel ke string dasar yang sesuai.
SUGGEST_COLUMN_INTENT_EXTRA_DATA: Data arbitrer. Jika kolom ini ada dan berisi nilai di baris tertentu, kolom ini akan menjadi data ekstra yang digunakan saat membentuk intent saran. Jika tidak disediakan, kolom data tambahan intent akan null. Kolom ini memungkinkan saran memberikan data tambahan yang disertakan sebagai tambahan dalam kunci EXTRA_DATA_KEY intent.
SUGGEST_COLUMN_QUERY: Jika kolom ini ada dan elemen ini ada di baris yang ditentukan, maka kolom ini adalah data yang digunakan saat membentuk kueri saran, yang disertakan sebagai tambahan dalam kunci QUERY intent. Atribut ini diperlukan jika tindakan saran adalah ACTION_SEARCH, tetapi opsional jika tidak.
SUGGEST_COLUMN_SHORTCUT_ID: Hanya digunakan saat memberikan saran untuk Kotak Penelusuran Kilat. Kolom ini menunjukkan apakah saran penelusuran harus disimpan sebagai pintasan, dan apakah saran penelusuran harus divalidasi. Pintasan biasanya terbentuk saat pengguna mengetuk saran dari Kotak Penelusuran Cepat. Jika opsi ini tidak ada, hasilnya akan disimpan sebagai pintasan dan tidak pernah di-refresh. Jika ditetapkan ke SUGGEST_NEVER_MAKE_SHORTCUT, hasilnya tidak akan disimpan sebagai pintasan. Jika tidak, ID pintasan akan digunakan untuk memeriksa kembali 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 indikator lingkaran berputar harus ditampilkan, bukan ikon dari SUGGEST_COLUMN_ICON_2, saat pintasan saran ini sedang dimuat ulang di Kotak Penelusuran Cepat.

Sebagian besar kolom ini dibahas lebih lanjut di bagian berikut.

Mendeklarasikan intent untuk saran

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

Mendeklarasikan tindakan intent

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

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

Gunakan atribut android:searchSuggestIntentAction dari file konfigurasi penelusuran Anda guna menentukan tindakan untuk semua saran, seperti yang ditunjukkan dalam contoh berikut:

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

Gunakan kolom SUGGEST_COLUMN_INTENT_ACTION guna menentukan tindakan untuk setiap saran. Untuk melakukannya, tambahkan kolom SUGGEST_COLUMN_INTENT_ACTION ke tabel saran Anda dan, untuk setiap saran, tempatkan tindakan yang akan digunakan—seperti "android.intent.action.VIEW".

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

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

Mendeklarasikan data intent

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

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

Tentukan data untuk setiap saran di dalam kolom SUGGEST_COLUMN_INTENT_DATA pada 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 akan disertakan ke intent persis seperti yang Anda tentukan dalam kolom ini. Selanjutnya, Anda dapat mengambilnya dengan getData() atau getDataString().

Tips: Biasanya lebih mudah menggunakan ID baris tabel sebagai data intent, karena ID baris ini selalu unik. Cara termudah untuk melakukannya adalah dengan menggunakan nama kolom SUGGEST_COLUMN_INTENT_DATA sebagai alias untuk kolom ID baris.
Membagi URI data menjadi dua bagian: bagian yang umum untuk semua saran dan bagian yang unik untuk setiap saran. Tempatkan bagian-bagian ini ke dalam atribut android:searchSuggestintentData konfigurasi penelusuran dan kolom SUGGEST_COLUMN_INTENT_DATA_ID tabel saran Anda.
Contoh berikut menunjukkan cara mendeklarasikan bagian URI yang sama untuk semua saran dalam atribut android:searchSuggestIntentData konfigurasi penelusuran Anda:
```
  <?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>
  
```
Sertakan jalur akhir untuk setiap saran—bagian unik—di kolom SUGGEST_COLUMN_INTENT_DATA_ID pada tabel saran Anda. Saat pengguna memilih saran, sistem akan mengambil string dari android:searchSuggestIntentData, menambahkan garis miring (/), lalu menambahkan nilai masing-masing dari kolom SUGGEST_COLUMN_INTENT_DATA_ID untuk membentuk URI konten lengkap. Kemudian, Anda dapat mengambil Uri dengan getData().

Menambahkan lebih banyak data

Jika perlu mengungkapkan lebih banyak informasi dengan intent, Anda dapat menambahkan kolom tabel lain, seperti SUGGEST_COLUMN_INTENT_EXTRA_DATA, yang dapat menyimpan informasi tambahan tentang saran. Data yang disimpan di kolom ini ditempatkan di EXTRA_DATA_KEY paket tambahan intent.

Menangani intent

Setelah memberikan saran penelusuran kustom dengan intent kustom, Anda memerlukan aktivitas penelusuran untuk menangani intent ini saat pengguna memilih saran. Hal ini selain menangani intent ACTION_SEARCH, yang telah dilakukan oleh aktivitas penelusuran Anda. Berikut adalah contoh cara menangani intent selama callback onCreate() aktivitas:

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 membawa URI lengkap yang mengarah ke item yang disarankan, seperti yang disintesis oleh string android:searchSuggestIntentData dan kolom SUGGEST_COLUMN_INTENT_DATA_ID. Selanjutnya, URI akan 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 tentukan dengan atribut android:searchSuggestIntentAction atau kolom SUGGEST_COLUMN_INTENT_ACTION. Sistem akan membuka aktivitas penelusuran Anda berdasarkan nama untuk mengirimkan intent saran, sehingga aktivitas tidak perlu mendeklarasikan tindakan yang diterima.

Menulis ulang teks kueri

Secara default, jika pengguna membuka daftar saran menggunakan kontrol arah, seperti dengan trackball atau D-pad, teks kueri tidak akan diperbarui. Namun, Anda dapat menulis ulang teks kueri pengguna untuk sementara saat teks tersebut muncul di kotak teks dengan kueri yang cocok dengan saran yang menjadi fokus. Hal ini memungkinkan pengguna melihat kueri yang disarankan, serta memilih kotak penelusuran dan mengedit kueri sebelum mengirimkannya sebagai penelusuran.

Anda dapat menulis ulang teks kueri dengan cara berikut:

Tambahkan atribut android:searchMode ke konfigurasi penelusuran Anda dengan nilai "queryRewriteFromText". Dalam hal ini, konten dari kolom SUGGEST_COLUMN_TEXT_1 saran akan digunakan untuk menulis ulang teks kueri.
Tambahkan atribut android:searchMode ke konfigurasi\ penelusuran Anda dengan nilai "queryRewriteFromData". Dalam hal ini, konten dari kolom SUGGEST_COLUMN_INTENT_DATA saran akan digunakan untuk menulis ulang teks kueri. Hanya gunakan ini dengan URI atau format data lain yang dimaksudkan agar dapat dilihat pengguna, seperti URL HTTP. Jangan gunakan skema URI internal untuk menulis ulang kueri dengan cara ini.
Berikan string teks kueri unik di kolom SUGGEST_COLUMN_QUERY tabel saran Anda. Jika kolom ini ada dan berisi nilai untuk saran saat ini, kolom tersebut akan digunakan untuk menulis ulang teks kueri dan mengganti salah satu implementasi sebelumnya.

Mengekspos saran penelusuran ke Kotak Penelusuran Cepat

Setelah mengonfigurasi aplikasi Anda untuk memberikan saran penelusuran kustom, membuatnya tersedia untuk Kotak Penelusuran Cepat yang dapat diakses secara global semudah mengubah konfigurasi penelusuran untuk menyertakan android:includeInGlobalSearch dengan nilai "true".

Satu-satunya skenario yang memerlukan pekerjaan tambahan adalah saat penyedia konten Anda meminta izin baca. Dalam hal ini, Anda harus menambahkan elemen <path-permission> agar penyedia memberikan akses baca Kotak Penelusuran Cepat ke penyedia konten Anda, seperti yang ditunjukkan pada contoh berikut:

<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 batasan tersebut dengan memberikan akses baca ke konten di dalam awalan jalur "/search_suggest_query" saat izin "android.permission.GLOBAL_SEARCH" ada. Tindakan ini memberikan akses ke Kotak Penelusuran Cepat sehingga dapat mengkueri penyedia konten Anda untuk mendapatkan saran.

Jika penyedia konten Anda tidak menerapkan izin baca, Quick Search Box akan membacanya secara default.

Mengaktifkan saran di perangkat

Secara default, aplikasi tidak diaktifkan untuk memberikan saran di Kotak Penelusuran Cepat, meskipun dikonfigurasi untuk melakukannya. Pengguna dapat memilih apakah akan menyertakan saran dari aplikasi Anda di Kotak Penelusuran Cepat dengan membuka Item yang dapat ditelusuri—berada di Setelan > Penelusuran—dan mengaktifkan aplikasi Anda sebagai item yang dapat ditelusuri.

Setiap aplikasi yang tersedia untuk Kotak Penelusuran Cepat memiliki entri di halaman setelan Item yang dapat ditelusuri. Entri ini menyertakan nama aplikasi dan deskripsi singkat tentang konten yang dapat ditelusuri dari aplikasi dan disediakan untuk saran di Kotak Penelusuran Cepat. Untuk menentukan teks deskripsi aplikasi penelusuran Anda, tambahkan atribut android:searchSettingsDescription ke konfigurasi penelusuran Anda, seperti yang ditunjukkan pada contoh berikut:

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

Buat string untuk android:searchSettingsDescription sesingkat mungkin dan nyatakan konten yang dapat ditelusuri. Misalnya, "Artis, album, dan lagu" untuk aplikasi musik, atau "Catatan tersimpan" untuk aplikasi catatan. Deskripsi ini penting agar pengguna tahu jenis saran yang diberikan. Selalu sertakan atribut ini jika android:includeInGlobalSearch bernilai benar (true).

Karena pengguna harus membuka menu setelan untuk mengaktifkan saran penelusuran untuk aplikasi Anda, jika penelusuran menjadi aspek penting aplikasi Anda, pertimbangkan cara menyampaikannya kepada pengguna. Misalnya, Anda dapat memberikan catatan saat pengguna pertama kali meluncurkan aplikasi yang menjelaskan cara mengaktifkan saran penelusuran untuk Kotak Penelusuran Cepat.

Mengelola pintasan saran Kotak Penelusuran Cepat

Saran yang dipilih pengguna dari Kotak Penelusuran Cepat dapat otomatis dibuat menjadi pintasan. Ini adalah saran yang disalin oleh sistem dari penyedia konten Anda sehingga dapat dengan cepat mengakses saran tanpa perlu melakukan kueri ulang penyedia konten.

Secara default, ini diaktifkan untuk semua saran yang diambil oleh Kotak Penelusuran Cepat, tetapi jika data saran Anda berubah dari waktu ke waktu, Anda dapat meminta agar pintasan diperbarui. Misalnya, jika saran Anda merujuk ke data dinamis, seperti status kehadiran kontak, mintalah agar pintasan saran dimuat ulang saat ditampilkan kepada pengguna. Untuk melakukannya, sertakan SUGGEST_COLUMN_SHORTCUT_ID dalam tabel saran Anda. Anda dapat menggunakan kolom ini untuk mengonfigurasi perilaku pintasan untuk setiap saran dengan salah satu cara berikut:

Buat Kotak Penelusuran Cepat mengkueri ulang penyedia konten Anda untuk versi baru pintasan saran.

Berikan nilai dalam kolom SUGGEST_COLUMN_SHORTCUT_ID agar saran dikueri ulang untuk versi baru setiap kali pintasan ditampilkan. Pintasan ditampilkan dengan cepat bersama data apa pun yang terbaru tersedia hingga kueri refresh ditampilkan, dan pada saat itu saran diperbarui dengan informasi baru. Kueri refresh dikirim ke penyedia konten Anda dengan jalur URI SUGGEST_URI_PATH_SHORTCUT—bukan SUGGEST_URI_PATH_QUERY.

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

Jika saran merujuk pada data yang memerlukan waktu lebih lama untuk dimuat ulang, seperti refresh berbasis jaringan, Anda juga dapat menambahkan kolom SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING ke tabel saran dengan nilai true untuk menampilkan indikator lingkaran berputar progres bagi ikon sebelah kanan hingga refresh selesai. Nilai apa pun selain true (benar) tidak akan menampilkan indikator lingkaran berputar progres.
Mencegah saran disalin ke pintasan.

Berikan nilai SUGGEST_NEVER_MAKE_SHORTCUT di 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 muncul. Jika Anda memberikan nilai normal untuk kolom, pintasan saran hanya akan muncul sampai kueri refresh ditampilkan.
Biarkan perilaku pintasan default diterapkan.

Biarkan SUGGEST_COLUMN_SHORTCUT_ID kosong untuk setiap saran yang tidak berubah dan yang dapat disimpan sebagai pintasan.

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

Tentang peringkat saran Kotak Penelusuran Kilat

Setelah saran penelusuran aplikasi Anda tersedia untuk Kotak Penelusuran Cepat, peringkat Kotak Penelusuran Cepat menentukan cara saran ditampilkan kepada pengguna untuk kueri tertentu. Hal ini mungkin bergantung pada berapa banyak aplikasi lain yang memiliki hasil untuk kueri tersebut dan seberapa sering pengguna memilih hasil Anda dibandingkan dengan aplikasi lain. Tidak ada jaminan terkait bagaimana saran Anda diberi peringkat atau apakah saran aplikasi Anda akan ditampilkan untuk kueri tertentu. Secara umum, memberikan hasil yang berkualitas akan meningkatkan kemungkinan saran aplikasi Anda diberikan di posisi yang jelas, dan aplikasi yang memberikan saran berkualitas rendah cenderung diberi peringkat lebih rendah atau tidak ditampilkan.