Jika Anda sudah siap menambahkan fungsi penelusuran ke aplikasi, Android membantu Anda menerapkan antarmuka pengguna dengan dialog penelusuran yang muncul di bagian atas jendela aktivitas atau widget penelusuran yang dapat Anda sisipkan dalam tata letak. Baik dialog penelusuran maupun widget penelusuran dapat mengirimkan kueri penelusuran pengguna ke aktivitas tertentu di aplikasi Anda. Dengan cara ini, pengguna dapat memulai penelusuran dari aktivitas apa pun tempat dialog atau widget penelusuran tersedia, dan sistem akan memulai aktivitas yang sesuai untuk melakukan penelusuran dan menampilkan hasilnya.
Fitur lain yang tersedia untuk dialog dan widget penelusuran meliputi:
- Penelusuran suara
- Saran penelusuran berdasarkan kueri terakhir
- Saran penelusuran yang cocok dengan hasil sebenarnya di data aplikasi Anda
Dokumen ini menunjukkan cara menyiapkan aplikasi Anda untuk menyediakan antarmuka penelusuran yang dibantu oleh sistem Android untuk mengirimkan kueri penelusuran, menggunakan dialog penelusuran atau widget penelusuran.
Referensi terkait:
Dasar-dasar
Sebelum memulai, tentukan apakah Anda ingin menerapkan antarmuka penelusuran menggunakan dialog penelusuran atau widget penelusuran. Keduanya menyediakan fitur penelusuran yang sama, tetapi dengan cara yang sedikit berbeda:
- Dialog penelusuran adalah komponen UI yang dikontrol oleh
sistem Android. Jika diaktifkan oleh pengguna, dialog penelusuran akan muncul di
bagian atas aktivitas.
Sistem Android mengontrol semua peristiwa dalam dialog penelusuran. Ketika pengguna mengirimkan kueri, sistem akan mengirimkan kueri tersebut ke aktivitas yang Anda tentukan untuk menangani penelusuran. Dialog ini juga dapat memberikan saran penelusuran saat pengguna mengetik.
- Widget penelusuran adalah instance
SearchView
yang dapat Anda tempatkan di mana saja dalam tata letak. Secara default, widget penelusuran berperilaku seperti widgetEditText
standar dan tidak melakukan apa pun, tetapi Anda dapat mengonfigurasinya agar sistem Android menangani semua peristiwa input, mengirimkan kueri ke aktivitas yang sesuai, dan memberikan saran penelusuran—sama seperti dialog penelusuran.
Saat pengguna menjalankan penelusuran dari dialog penelusuran atau widget penelusuran,
sistem akan membuat
Intent
dan
menyimpan kueri pengguna di dalamnya. Selanjutnya, sistem akan memulai aktivitas yang Anda
deklarasikan untuk menangani penelusuran—"aktivitas penelusuran"—dan mengirimkan
intent ke sana. Guna menyiapkan aplikasi untuk jenis penelusuran berbantuan ini, Anda memerlukan hal berikut:
- Konfigurasi penelusuran
- File XML yang mengonfigurasi beberapa setelan untuk dialog atau widget penelusuran. File ini mencakup setelan untuk fitur seperti penelusuran suara, saran penelusuran, dan teks petunjuk untuk kotak penelusuran.
- Aktivitas penelusuran
Activity
yang menerima kueri penelusuran, menelusuri data Anda, dan menampilkan hasil penelusuran.- Antarmuka penelusuran yang disediakan oleh salah satu hal berikut:
- Dialog penelusuran
- Secara default, dialog penelusuran disembunyikan. Kolom ini muncul di bagian atas layar saat Anda memanggil
onSearchRequested()
saat pengguna mengetuk tombol Search.- Widget
SearchView
- Dengan widget penelusuran, Anda dapat menempatkan kotak penelusuran di mana saja dalam aktivitas Anda, termasuk sebagai tampilan tindakan di panel aplikasi.
- Widget
Bagian selanjutnya dari dokumen ini menunjukkan cara membuat konfigurasi penelusuran dan aktivitas penelusuran, serta cara menerapkan antarmuka penelusuran dengan dialog penelusuran atau widget penelusuran.
Membuat konfigurasi yang dapat ditelusuri
Hal pertama yang Anda perlukan adalah file XML yang disebut
konfigurasi penelusuran.
Fitur ini mengonfigurasi aspek UI tertentu dari dialog atau widget penelusuran dan menentukan perilaku fitur seperti saran dan penelusuran suara. File ini biasanya diberi nama searchable.xml
dan harus disimpan dalam direktori project res/xml/
.
File konfigurasi penelusuran harus menyertakan elemen
<searchable>
sebagai node root-nya dan menentukan satu atau beberapa atribut, 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" > </searchable>
Atribut android:label
adalah satu-satunya atribut yang bersifat wajib. Atribut ini
mengarah ke resource string, yang harus berupa nama aplikasi. Label ini tidak akan terlihat oleh pengguna hingga Anda mengaktifkan saran penelusuran untuk Kotak Penelusuran Cepat. Setelah itu, label akan terlihat dalam daftar item yang Dapat Ditelusuri di setelan sistem.
Meskipun tidak diwajibkan, sebaiknya Anda selalu menyertakan
atribut android:hint
, yang memberikan string petunjuk di kotak
penelusuran sebelum pengguna memasukkan kueri. Petunjuk ini penting karena dapat memberikan petunjuk
penting kepada pengguna tentang apa yang dapat mereka cari.
Elemen <searchable>
menerima beberapa atribut lainnya.
Namun, Anda tidak memerlukan sebagian besar atribut hingga menambahkan fitur seperti
saran penelusuran dan
penelusuran suara. Untuk informasi mendetail tentang file konfigurasi penelusuran, lihat dokumen referensi Konfigurasi penelusuran.
Membuat aktivitas penelusuran
Aktivitas penelusuran adalah Activity
di aplikasi Anda yang melakukan
penelusuran berdasarkan string kueri dan menampilkan hasil penelusuran.
Saat pengguna menjalankan penelusuran di dialog atau widget penelusuran, sistem
akan memulai aktivitas penelusuran Anda dan mengirimkan kueri penelusuran dalam
Intent
dengan
tindakan
ACTION_SEARCH
. Aktivitas penelusuran akan mengambil kueri dari tambahan
QUERY
intent, lalu menelusuri data Anda dan menampilkan hasilnya.
Karena Anda dapat menyertakan dialog atau widget penelusuran dalam aktivitas lain di aplikasi, sistem harus mengetahui aktivitas mana yang merupakan aktivitas penelusuran Anda sehingga sistem dapat mengirimkan kueri penelusuran dengan benar. Jadi, deklarasikan aktivitas penelusuran Anda terlebih dahulu dalam file manifes Android.
Mendeklarasikan aktivitas penelusuran
Jika Anda belum memilikinya, buat Activity
yang akan melakukan
penelusuran dan menampilkan hasil. Anda belum perlu menerapkan fungsi
penelusuran—cukup buat aktivitas yang dapat Anda deklarasikan dalam
manifes. Di dalam elemen
<activity>
manifes, lakukan hal berikut:
- Deklarasikan aktivitas untuk menerima intent
ACTION_SEARCH
dalam elemen<intent-filter>
. - Tentukan konfigurasi penelusuran yang akan digunakan dalam elemen
<meta-data>
.
Hal ini ditunjukkan dalam contoh berikut:
<application ... > <activity android:name=".SearchableActivity" > <intent-filter> <action android:name="android.intent.action.SEARCH" /> </intent-filter> <meta-data android:name="android.app.searchable" android:resource="@xml/searchable"/> </activity> ... </application>
Elemen <meta-data>
harus menyertakan
atribut android:name
dengan nilai
"android.app.searchable"
dan atribut android:resource
dengan referensi ke file konfigurasi yang dapat ditelusuri. Dalam
contoh sebelumnya, ini merujuk pada file
res/xml/searchable.xml
.
Melakukan penelusuran
Setelah mendeklarasikan aktivitas penelusuran Anda dalam manifes, ikuti prosedur berikut untuk melakukan penelusuran dalam aktivitas penelusuran Anda:
Menerima kueri
Saat pengguna menjalankan penelusuran dari dialog atau widget penelusuran, sistem
akan memulai aktivitas penelusuran Anda dan mengirimkan intent
ACTION_SEARCH
ke sana. Intent ini membawa kueri penelusuran dalam tambahan string
QUERY
. Periksa intent ini saat aktivitas dimulai dan ekstrak string.
Misalnya, berikut ini cara mendapatkan kueri penelusuran saat aktivitas penelusuran Anda dimulai:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.search) // Verify the action and get the query. if (Intent.ACTION_SEARCH == intent.action) { intent.getStringExtra(SearchManager.QUERY)?.also { query -> doMySearch(query) } } }
Java
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.search); // Get the intent, verify the action, and get the query. Intent intent = getIntent(); if (Intent.ACTION_SEARCH.equals(intent.getAction())) { String query = intent.getStringExtra(SearchManager.QUERY); doMySearch(query); } }
String QUERY
selalu disertakan dengan
intent ACTION_SEARCH
. Pada contoh sebelumnya, kueri
diambil dan diteruskan ke metode doMySearch()
lokal tempat
operasi penelusuran sebenarnya dilakukan.
Telusuri data Anda
Proses penyimpanan dan penelusuran data bersifat unik untuk aplikasi Anda. Anda dapat menyimpan dan menelusuri data dengan berbagai cara, dan dokumen ini tidak menunjukkan caranya. Pertimbangkan cara Anda menyimpan dan menelusuri data dalam hal kebutuhan dan format data Anda. Berikut adalah tips yang mungkin dapat Anda terapkan:
- Jika data Anda disimpan dalam database SQLite di perangkat, menjalankan penelusuran teks lengkap — menggunakan FTS3, bukan kueri
LIKE
— dapat memberikan penelusuran yang lebih andal di seluruh data teks dan dapat memberikan hasil yang jauh lebih cepat. Lihat sqlite.org untuk informasi tentang FTS3 dan classSQLiteDatabase
untuk informasi tentang SQLite di Android. - Jika data Anda disimpan secara online, performa penelusuran yang dirasakan mungkin
terhambat oleh koneksi data pengguna. Sebaiknya tampilkan
indikator progres hingga penelusuran Anda ditampilkan. Lihat
android.net
untuk referensi API jaringan danProgressBar
untuk informasi tentang cara menampilkan indikator progres.
Sajikan hasilnya
Terlepas dari lokasi data Anda dan cara Anda menelusurinya, sebaiknya kembalikan hasil penelusuran ke aktivitas penelusuran Anda dengan Adapter
. Dengan
cara ini, Anda dapat menampilkan semua hasil penelusuran dalam
RecyclerView
.
Jika data berasal dari kueri database SQLite, Anda dapat menerapkan hasil ke
RecyclerView
menggunakan
CursorAdapter
.
Jika data tersedia dalam format yang berbeda, Anda dapat membuat ekstensi BaseAdapter
.
Adapter
mengikat setiap item dari kumpulan data ke dalam
objek View
. Saat
Adapter
diterapkan ke RecyclerView
, setiap bagian
data disisipkan sebagai tampilan individual ke dalam daftar. Adapter
hanyalah
antarmuka, sehingga implementasi seperti
CursorAdapter
—untuk mengikat data dari
Cursor
—diperlukan. Jika tidak ada implementasi yang ada yang berfungsi untuk data, Anda dapat
mengimplementasikan implementasi Anda sendiri dari BaseAdapter
.
Menggunakan dialog penelusuran
Dialog penelusuran menyediakan kotak penelusuran mengambang di bagian atas layar, dengan ikon aplikasi di sebelah kiri. Dialog penelusuran dapat memberikan saran penelusuran saat pengguna mengetik. Saat pengguna menjalankan penelusuran, sistem akan mengirimkan kueri penelusuran ke aktivitas penelusuran yang melakukan penelusuran tersebut.
Secara default, dialog penelusuran selalu disembunyikan hingga pengguna mengaktifkannya.
Aplikasi Anda dapat mengaktifkan dialog penelusuran dengan memanggil
onSearchRequested()
. Namun, metode ini tidak berfungsi sampai Anda
mengaktifkan dialog penelusuran untuk aktivitas tersebut.
Agar dialog penelusuran dapat melakukan penelusuran, tunjukkan kepada sistem aktivitas penelusuran mana yang harus menerima kueri penelusuran dari dialog penelusuran. Misalnya, di bagian sebelumnya tentang
membuat aktivitas penelusuran, aktivitas
penelusuran bernama SearchableActivity
akan dibuat. Jika Anda ingin
aktivitas terpisah, seperti aktivitas bernama OtherActivity
, menampilkan
dialog penelusuran dan mengirimkan penelusuran ke SearchableActivity
, deklarasikan
dalam manifes bahwa SearchableActivity
adalah aktivitas penelusuran
yang akan digunakan untuk dialog penelusuran di OtherActivity
.
Untuk mendeklarasikan aktivitas penelusuran bagi dialog penelusuran aktivitas, tambahkan
elemen <meta-data>
di dalam elemen
<activity>
aktivitas masing-masing. Elemen <meta-data>
harus menyertakan atribut android:value
yang menetapkan
nama class aktivitas yang dapat ditelusuri dan atribut android:name
dengan nilai "android.app.default_searchable"
.
Misalnya, berikut adalah deklarasi untuk aktivitas penelusuran,
SearchableActivity
, dan aktivitas lainnya,
OtherActivity
, yang menggunakan SearchableActivity
untuk
melakukan penelusuran yang dilakukan dari dialog penelusurannya:
<application ... > <!-- This is the searchable activity; it performs searches. --> <activity android:name=".SearchableActivity" > <intent-filter> <action android:name="android.intent.action.SEARCH" /> </intent-filter> <meta-data android:name="android.app.searchable" android:resource="@xml/searchable"/> </activity> <!-- This activity enables the search dialog to initiate searches in the SearchableActivity. --> <activity android:name=".OtherActivity" ... > <!-- Enable the search dialog to send searches to SearchableActivity. --> <meta-data android:name="android.app.default_searchable" android:value=".SearchableActivity" /> </activity> ... </application>
Karena OtherActivity
kini menyertakan
elemen <meta-data>
untuk mendeklarasikan aktivitas penelusuran mana yang akan
digunakan untuk penelusuran, aktivitas ini akan mengaktifkan dialog penelusuran. Meskipun pengguna berada
dalam aktivitas ini, metode onSearchRequested()
akan mengaktifkan
dialog penelusuran. Saat pengguna menjalankan penelusuran, sistem akan memulai
SearchableActivity
dan mengirimkan intent
ACTION_SEARCH
ke sana.
Jika Anda ingin setiap aktivitas di aplikasi menyediakan dialog penelusuran, sisipkan
elemen <meta-data>
sebelumnya sebagai turunan dari
elemen <application>
, bukan setiap <activity>
. Dengan cara ini, setiap aktivitas
mewarisi nilai, menyediakan dialog penelusuran, dan mengirimkan penelusuran ke
aktivitas penelusuran yang sama. Jika memiliki beberapa aktivitas penelusuran, Anda dapat
mengganti aktivitas penelusuran default dengan menempatkan deklarasi <meta-data>
yang berbeda
di dalam setiap aktivitas.
Setelah dialog penelusuran diaktifkan untuk aktivitas Anda, aplikasi siap melakukan penelusuran.
Memanggil dialog penelusuran
Meskipun beberapa perangkat menyediakan tombol penelusuran khusus, perilaku tombol
tersebut mungkin berbeda-beda antarperangkat, dan banyak perangkat tidak menyediakan tombol
penelusuran sama sekali. Jadi, saat menggunakan dialog penelusuran, Anda harus menyediakan tombol penelusuran
di UI yang mengaktifkan dialog penelusuran dengan memanggil
onSearchRequested()
.
Misalnya, tambahkan tombol penelusuran di
menu opsi atau tata letak UI
yang memanggil onSearchRequested()
.
Anda juga dapat mengaktifkan fungsi "ketik untuk menelusuri", yang akan mengaktifkan
dialog penelusuran saat pengguna mulai mengetik di keyboard. Tombol tersebut akan
disisipkan ke dalam dialog penelusuran. Anda dapat mengaktifkan fitur ketik untuk menelusuri dalam aktivitas
dengan memanggil
setDefaultKeyMode
—atau
DEFAULT_KEYS_SEARCH_LOCAL
—selama
metode
onCreate()
aktivitas Anda.
Dampak dialog penelusuran terhadap siklus hidup aktivitas
Dialog penelusuran adalah
Dialog
yang mengambang
di bagian atas layar. Dialog ini tidak menyebabkan perubahan apa pun dalam tumpukan aktivitas sehingga
saat dialog penelusuran muncul, tidak ada metode siklus proses—seperti
onPause()
—yang
dipanggil. Aktivitas Anda kehilangan fokus input karena fokus input diberikan ke
dialog penelusuran.
Jika Anda ingin diberi tahu saat dialog penelusuran diaktifkan, ganti
metode onSearchRequested()
. Saat sistem memanggil metode ini, itu merupakan indikasi bahwa aktivitas Anda kehilangan fokus input ke dialog penelusuran, sehingga
Anda dapat melakukan pekerjaan apa pun yang sesuai untuk peristiwa tersebut, seperti menjeda game. Kecuali jika Anda meneruskan data konteks penelusuran—yang dibahas di bagian lain dalam dokumen ini—akhiri metode tersebut dengan memanggil implementasi superclass:
Kotlin
override fun onSearchRequested(): Boolean { pauseSomeStuff() return super.onSearchRequested() }
Java
@Override public boolean onSearchRequested() { pauseSomeStuff(); return super.onSearchRequested(); }
Jika pengguna membatalkan penelusuran dengan mengetuk tombol Kembali, dialog penelusuran
akan ditutup dan aktivitas mendapatkan kembali fokus input. Anda dapat mendaftar agar diberi tahu
saat dialog penelusuran ditutup dengan
setOnDismissListener()
,
setOnCancelListener()
,
atau keduanya. Anda hanya perlu mendaftarkan
OnDismissListener
,
karena dipanggil setiap kali dialog penelusuran ditutup. OnCancelListener
hanya berkaitan dengan peristiwa saat pengguna keluar dari dialog penelusuran secara eksplisit, sehingga
tidak dipanggil saat penelusuran dijalankan. Saat penelusuran dijalankan, dialog
penelusuran akan otomatis menghilang.
Jika aktivitas saat ini bukan aktivitas penelusuran, maka peristiwa siklus proses
aktivitas normal akan dipicu saat pengguna menjalankan
penelusuran—aktivitas saat ini menerima onPause()
, seperti yang dijelaskan
dalam Pengantar
aktivitas. Namun, jika aktivitas saat ini adalah aktivitas penelusuran,
salah satu dari dua hal berikut akan terjadi:
- Secara default, aktivitas penelusuran menerima intent
ACTION_SEARCH
dengan panggilan keonCreate()
, dan instance baru dari aktivitas tersebut dibawa ke bagian atas tumpukan aktivitas. Kini ada dua instance aktivitas penelusuran dalam tumpukan aktivitas. Jadi, mengetuk tombol Kembali akan membawa Anda kembali ke instance aktivitas penelusuran sebelumnya, bukan keluar dari aktivitas penelusuran. - Jika Anda menetapkan
android:launchMode
ke"singleTop"
, aktivitas penelusuran akan menerima intentACTION_SEARCH
dengan panggilan keonNewIntent(Intent)
, sehingga meneruskan intentACTION_SEARCH
baru. Misalnya, berikut adalah cara menangani kasus ini, saat mode peluncuran aktivitas penelusuran adalah"singleTop"
:Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.search) handleIntent(intent) } override fun onNewIntent(intent: Intent) { super.onNewIntent(intent) setIntent(intent) handleIntent(intent) } private fun handleIntent(intent: Intent) { if (Intent.ACTION_SEARCH == intent.action) { intent.getStringExtra(SearchManager.QUERY)?.also { query -> doMySearch(query) } } }
Java
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.search); handleIntent(getIntent()); } @Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); setIntent(intent); handleIntent(intent); } private void handleIntent(Intent intent) { if (Intent.ACTION_SEARCH.equals(intent.getAction())) { String query = intent.getStringExtra(SearchManager.QUERY); doMySearch(query); } }
Dibandingkan dengan kode contoh di bagian tentang melakukan penelusuran, semua kode untuk menangani intent penelusuran kini berada di metode
handleIntent()
, sehinggaonCreate()
danonNewIntent()
dapat menjalankannya.Saat sistem memanggil
onNewIntent(Intent)
, aktivitas tidak dimulai ulang, sehingga metodegetIntent()
menampilkan intent yang sama seperti yang diterima denganonCreate()
. Inilah alasan Anda harus memanggilsetIntent(Intent)
dalamonNewIntent(Intent)
: agar intent yang disimpan oleh aktivitas diupdate jika Anda memanggilgetIntent()
pada masa mendatang.
Skenario kedua, menggunakan mode peluncuran "singleTop"
, biasanya
lebih disarankan, karena setelah penelusuran selesai, pengguna mungkin melakukan penelusuran
tambahan, dan Anda tidak ingin aplikasi membuat beberapa instance dari
aktivitas yang dapat ditelusuri. Sebaiknya tetapkan aktivitas penelusuran Anda ke
mode peluncuran "singleTop"
dalam manifes aplikasi, seperti yang ditunjukkan
dalam contoh berikut:
<activity android:name=".SearchableActivity" android:launchMode="singleTop" > <intent-filter> <action android:name="android.intent.action.SEARCH" /> </intent-filter> <meta-data android:name="android.app.searchable" android:resource="@xml/searchable"/> </activity>
Meneruskan data konteks penelusuran
Dalam beberapa kasus, Anda dapat mempersempit kueri penelusuran di dalam
aktivitas penelusuran untuk setiap penelusuran yang dilakukan. Namun, jika Anda ingin menyaring kriteria penelusuran berdasarkan aktivitas dari mana pengguna melakukan penelusuran, Anda dapat memberikan data tambahan dalam intent yang dikirimkan sistem ke aktivitas penelusuran Anda. Anda dapat meneruskan data tambahan dalam
APP_DATA
Bundle
, yang
disertakan dalam intent ACTION_SEARCH
.
Untuk meneruskan jenis data ini ke aktivitas penelusuran Anda, ganti
metode onSearchRequested()
untuk aktivitas yang dapat digunakan pengguna
untuk melakukan penelusuran, buat Bundle
dengan data tambahan, dan
panggil
startSearch()
untuk mengaktifkan dialog penelusuran. Contoh:
Kotlin
override fun onSearchRequested(): Boolean { val appData = Bundle().apply { putBoolean(JARGON, true) } startSearch(null, false, appData, false) return true }
Java
@Override public boolean onSearchRequested() { Bundle appData = new Bundle(); appData.putBoolean(SearchableActivity.JARGON, true); startSearch(null, false, appData, false); return true; }
Menampilkan nilai benar akan menunjukkan bahwa Anda berhasil menangani peristiwa callback ini dan
memanggil startSearch()
untuk mengaktifkan dialog penelusuran. Setelah pengguna
mengirimkan kueri, kueri tersebut akan dikirim ke aktivitas penelusuran Anda bersama dengan data
yang Anda tambahkan. Anda dapat mengekstrak data tambahan dari APP_DATA
Bundle
untuk menyaring penelusuran, seperti yang ditunjukkan dalam contoh berikut:
Kotlin
val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false
Java
Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA); if (appData != null) { boolean jargon = appData.getBoolean(SearchableActivity.JARGON); }
Menggunakan widget penelusuran
![Gambar yang menunjukkan tampilan penelusuran di panel atas aplikasi](https://developer.android.google.cn/static/images/ui/search-ui-topbar-33.png?authuser=19&hl=id)
Gambar 1. Widget SearchView
sebagai
tampilan tindakan di panel aplikasi.
Widget penelusuran menyediakan fungsionalitas yang sama dengan dialog penelusuran. Fungsi ini memulai aktivitas yang sesuai saat pengguna menjalankan penelusuran, dan dapat memberikan saran penelusuran serta melakukan penelusuran suara. Jika tidak memungkinkan Anda menempatkan widget penelusuran di panel aplikasi, Anda dapat menempatkan widget penelusuran di suatu tempat dalam tata letak aktivitas.
Mengonfigurasi widget penelusuran
Setelah membuat
konfigurasi penelusuran dan
aktivitas penelusuran, aktifkan penelusuran berbantuan
untuk setiap SearchView
dengan memanggil
setSearchableInfo()
dan meneruskan objek SearchableInfo
yang mewakili
konfigurasi penelusuran Anda.
Anda bisa mendapatkan referensi ke SearchableInfo
dengan memanggil
getSearchableInfo()
di
SearchManager
.
Misalnya, jika Anda menggunakan SearchView
sebagai tampilan tindakan di panel aplikasi, aktifkan widget selama callback onCreateOptionsMenu()
, seperti yang ditunjukkan dalam contoh berikut:
Kotlin
override fun onCreateOptionsMenu(menu: Menu): Boolean { // Inflate the options menu from XML. val inflater = menuInflater inflater.inflate(R.menu.options_menu, menu) // Get the SearchView and set the searchable configuration. val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager (menu.findItem(R.id.menu_search).actionView as SearchView).apply { // Assumes current activity is the searchable activity. setSearchableInfo(searchManager.getSearchableInfo(componentName)) setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default. } return true }
Java
@Override public boolean onCreateOptionsMenu(Menu menu) { // Inflate the options menu from XML. MenuInflater inflater = getMenuInflater(); inflater.inflate(R.menu.options_menu, menu); // Get the SearchView and set the searchable configuration. SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE); SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView(); // Assumes current activity is the searchable activity. searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName())); searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default. return true; }
Widget penelusuran kini dikonfigurasi, dan sistem akan mengirimkan kueri penelusuran ke aktivitas penelusuran Anda. Anda juga dapat mengaktifkan saran penelusuran untuk widget penelusuran.
Untuk mengetahui informasi selengkapnya tentang tampilan tindakan di panel aplikasi, baca Menggunakan tampilan tindakan dan penyedia tindakan.
Fitur widget penelusuran lainnya
Widget SearchView
menyediakan beberapa fitur tambahan yang mungkin Anda inginkan:
- Tombol kirim
- Secara default, tidak ada tombol untuk mengirimkan kueri penelusuran, sehingga pengguna harus
menekan tombol Return di keyboard untuk memulai penelusuran. Anda
dapat menambahkan tombol "kirim" dengan memanggil
setSubmitButtonEnabled(true)
. - Mempersempit kueri untuk saran penelusuran
- Saat mengaktifkan saran penelusuran, Anda biasanya berharap pengguna akan memilih sebuah saran, tetapi mereka mungkin juga ingin menyaring kueri penelusuran yang disarankan.
Anda dapat menambahkan tombol di samping setiap saran, yang akan menyisipkan saran tersebut di kotak penelusuran untuk menyaring pengguna dengan memanggil
setQueryRefinementEnabled(true)
. - Kemampuan untuk mengaktifkan/menonaktifkan visibilitas kotak penelusuran
- Secara default, widget penelusuran diikonkan, yang berarti widget tersebut
hanya diwakili oleh ikon penelusuran, yaitu kaca pembesar. Ikon ini akan diluaskan agar
kotak penelusuran ditampilkan saat pengguna mengetuk ikon. Seperti ditunjukkan dalam contoh sebelumnya, Anda dapat menampilkan kotak penelusuran secara default dengan memanggil
setIconifiedByDefault(false)
. Anda juga dapat mengubah tampilan widget penelusuran dengan memanggilsetIconified()
.
Ada beberapa API lain dalam class SearchView
yang memungkinkan Anda menyesuaikan widget penelusuran. Namun, sebagian besar API tersebut hanya digunakan saat Anda
menangani sendiri semua input pengguna, bukan menggunakan sistem Android untuk mengirimkan
kueri penelusuran dan menampilkan saran penelusuran.
Menggunakan widget dan dialog
Jika Anda menyisipkan widget penelusuran di panel aplikasi sebagai
tampilan tindakan dan mengaktifkannya
agar muncul di panel aplikasi jika ada ruang—dengan menyetel
android:showAsAction="ifRoom"
—widget penelusuran mungkin
tidak muncul sebagai tampilan tindakan. Sebagai gantinya, item menu mungkin muncul di menu
tambahan. Misalnya, saat aplikasi berjalan di layar yang lebih kecil, mungkin tidak ada
cukup ruang di panel aplikasi untuk menampilkan widget penelusuran bersama item tindakan
atau elemen navigasi lainnya, sehingga item menu akan muncul di menu
tambahan. Saat ditempatkan di menu tambahan, item tersebut berfungsi seperti item menu
biasa dan tidak menampilkan tampilan tindakan—yaitu, widget penelusuran.
Untuk menangani situasi ini, item menu tempat Anda memasang widget penelusuran
harus mengaktifkan dialog penelusuran saat pengguna memilihnya dari menu tambahan.
Untuk melakukannya, implementasikan
onOptionsItemSelected()
untuk menangani item menu "Telusuri" dan buka dialog penelusuran dengan memanggil
onSearchRequested()
.
Untuk mengetahui informasi selengkapnya tentang cara kerja item di panel aplikasi dan cara menangani situasi ini, lihat Menambahkan panel aplikasi.
Tambahkan penelusuran suara
Anda dapat menambahkan fungsi penelusuran suara ke dialog atau widget penelusuran dengan menambahkan atribut android:voiceSearchMode
ke konfigurasi penelusuran Anda. Tindakan ini akan menambahkan tombol penelusuran suara yang meluncurkan perintah suara.
Setelah pengguna selesai berbicara, kueri penelusuran yang telah ditranskripsikan akan dikirim ke
aktivitas yang dapat ditelusuri.
Hal ini ditunjukkan dalam contoh berikut:
<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/search_label" android:hint="@string/search_hint" android:voiceSearchMode="showVoiceSearchButton|launchRecognizer" > </searchable>
Nilai showVoiceSearchButton
diperlukan untuk mengaktifkan penelusuran
suara. Nilai kedua, launchRecognizer
, menentukan bahwa
tombol penelusuran suara harus meluncurkan pengenal yang menampilkan
teks yang ditranskripsikan ke aktivitas penelusuran.
Anda dapat memberikan atribut tambahan untuk menentukan perilaku penelusuran suara, seperti bahasa yang diharapkan dan jumlah hasil maksimum yang akan ditampilkan. Lihat referensi Konfigurasi penelusuran untuk mengetahui informasi selengkapnya tentang atribut yang tersedia.
Tambahkan saran penelusuran
Baik dialog penelusuran maupun widget penelusuran dapat memberikan saran penelusuran saat pengguna mengetik, dengan bantuan dari sistem Android. Sistem akan mengelola daftar saran dan menangani peristiwa saat pengguna memilih saran.
Anda dapat memberikan dua jenis saran penelusuran:
- Saran penelusuran kueri terbaru
- Saran ini adalah kata-kata yang sebelumnya digunakan pengguna sebagai kueri penelusuran dalam aplikasi Anda. Lihat Menambahkan saran penelusuran kustom untuk mengetahui informasi selengkapnya.
- Saran penelusuran kustom
- Ini adalah saran penelusuran yang Anda berikan dari sumber data Anda sendiri untuk membantu pengguna segera memilih ejaan atau item yang benar yang mereka telusuri. Lihat Menambahkan saran penelusuran kustom untuk informasi selengkapnya.