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
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
/puppiesTeks 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 atributandroid:searchSuggestPath
. Hal ini hanya diperlukan jika Anda menggunakan penyedia konten yang sama untuk beberapa aktivitas penelusuran. Jika demikian, jelaskan sumber kueri saran.projection
- Selalu null.
selection
- Nilai yang diberikan dalam atribut
android:searchSuggestSelection
file konfigurasi penelusuran Anda, atau null jika Anda tidak mendeklarasikan atributandroid: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 mendeklarasikanandroid: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.
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
.
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 menggunakanandroid: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 menggunakanandroid: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 adalahACTION_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 menggunakanSUGGEST_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 kolomSUGGEST_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.
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 dengangetData()
ataugetDataString()
. - 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 kolomSUGGEST_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 dariandroid:searchSuggestIntentData
, menambahkan garis miring (/), lalu menambahkan nilai masing-masing dari kolomSUGGEST_COLUMN_INTENT_DATA_ID
untuk membentuk URI konten lengkap. Kemudian, Anda dapat mengambilUri
dengangetData()
.
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.
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 kolomSUGGEST_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 kolomSUGGEST_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 URISUGGEST_URI_PATH_SHORTCUT
—bukanSUGGEST_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 kolomSUGGEST_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.