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 dalam aplikasi Anda. Dengan cara ini, pengguna dapat memulai penelusuran dari aktivitas mana pun di mana dialog atau widget penelusuran tersedia, dan sistem akan memulai aktivitas yang sesuai untuk menjalankan 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
Panduan ini menjelaskan cara menyiapkan aplikasi Anda untuk menyediakan antarmuka penelusuran dengan bantuan sistem Android untuk mengirimkan kueri penelusuran, menggunakan dialog penelusuran atau widget penelusuran.
Referensi terkait:
Dasar-Dasar

Gambar 1. Screenshot dialog penelusuran aplikasi.
Sebelum memulai, Anda perlu memutuskan apakah Anda akan 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, seperti yang ditunjukkan dalam gambar 1.
Sistem Android mengontrol semua peristiwa dalam dialog penelusuran. Saat pengguna mengirimkan kueri, sistem akan meneruskan kueri tersebut ke aktivitas yang Anda tentukan untuk menangani penelusuran. Dialog ini juga dapat memberikan saran penelusuran selagi pengguna mengetik.
- Widget penelusuran adalah instance dari
SearchView
yang dapat Anda tempatkan di mana saja dalam tata letak Anda. Secara default, widget penelusuran berperilaku seperti widgetEditText
standar dan tidak melakukan apa pun, tetapi Anda dapat mengonfigurasinya sehingga sistem Android menangani semua peristiwa input, mengirimkan kueri ke aktivitas yang sesuai, dan memberikan saran penelusuran (sama seperti dialog penelusuran).Catatan: Jika mau, Anda dapat menangani sendiri semua input pengguna ke dalam widget penelusuran, menggunakan berbagai metode callback dan pemroses. Namun, dokumen ini berfokus pada cara mengintegrasikan widget penelusuran dengan sistem Android untuk penerapan penelusuran berbantuan. Jika Anda ingin menangani sendiri semua input pengguna, silakan baca dokumentasi referensi untuk
SearchView
dan antarmuka bertingkatnya.
Saat pengguna menjalankan penelusuran dari dialog penelusuran atau widget penelusuran, sistem akan membuat Intent
dan menyimpan kueri pengguna di dalamnya. Kemudian, sistem akan memulai aktivitas yang telah Anda deklarasikan untuk menangani penelusuran (“aktivitas penelusuran”) dan mengirimkannya ke intent. Untuk menyiapkan aplikasi Anda untuk jenis penelusuran berbantuan ini, Anda memerlukan:
- 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:
- Dialog penelusuran
Secara default, dialog penelusuran ini tersembunyi, tetapi muncul di bagian atas layar saat Anda memanggil
onSearchRequested()
(saat pengguna menekan tombol Telusuri). - Atau, widget
SearchView
Dengan widget penelusuran, Anda dapat menempatkan kotak penelusuran di mana saja dalam aktivitas. Alih-alih memasukkannya ke dalam tata letak aktivitas, biasanya Anda perlu menggunakan
SearchView
sebagai tampilan tindakan di panel aplikasi.
- Dialog penelusuran
Sisa dokumen ini menjelaskan cara membuat konfigurasi penelusuran, aktivitas penelusuran, dan menerapkan antarmuka penelusuran dengan dialog penelusuran atau widget penelusuran.
Membuat Konfigurasi Penelusuran
Hal pertama yang Anda perlukan adalah file XML yang disebut dengan konfigurasi penelusuran. File ini mengonfigurasi aspek-aspek UI tertentu dari dialog atau widget penelusuran dan menentukan perilaku berbagai fitur seperti saran dan penelusuran suara. File ini biasanya dinamai searchable.xml
dan harus disimpan di dalam direktori project res/xml/
.
Catatan: Sistem menggunakan file ini untuk menjalankan objek SearchableInfo
, tetapi Anda tidak dapat membuat sendiri objek ini pada waktu proses—Anda harus mendeklarasikan konfigurasi penelusuran dalam XML.
File konfigurasi penelusuran harus menyertakan elemen <searchable>
sebagai node root dan menentukan satu atau beberapa atribut. 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" > </searchable>
Atribut android:label
adalah satu-satunya atribut yang bersifat wajib. Atribut ini menunjuk ke resource string, yang biasanya adalah nama aplikasi. Label ini tidak terlihat oleh pengguna sampai Anda mengaktifkan saran penelusuran untuk Kotak Penelusuran Kilat. Pada titik itu, label ini akan terlihat dalam daftar Item yang dapat ditelusuri di Setelan sistem.
Meskipun tidak wajib, sebaiknya selalu sertakan atribut android:hint
, yang memberikan string petunjuk di kotak penelusuran sebelum pengguna memasukkan kueri. Petunjuk ini penting karena memberikan isyarat penting kepada pengguna tentang apa yang dapat mereka telusuri.
Tips: Agar konsisten dengan banyak aplikasi Android lainnya, sebaiknya Anda memformat string android:hint
sebagai "Telusuri <kontet-atau-produk>". Misalnya, "Telusuri lagu atau artis" atau "Telusuri YouTube".
Elemen <searchable>
menerima beberapa atribut lainnya. Namun, Anda tidak memerlukan sebagian besar atribut ini sebelum 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
dalam 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 ke sana dalam Intent
dengan tindakan ACTION_SEARCH
. Aktivitas penelusuran mengambil kueri dari QUERY
ekstra dalam intent, lalu menelusuri data Anda dan menampilkan hasilnya.
Karena Anda dapat menyertakan dialog atau widget penelusuran dalam aktivitas lain apa pun dalam aplikasi Anda, sistem harus mengetahui aktivitas mana yang merupakan aktivitas penelusuran agar dapat mengirimkan kueri penelusuran dengan tepat. Untuk itu, Anda harus mendeklarasikan dulu aktivitas penelusuran dalam file manifes Android.
Mendeklarasikan aktivitas penelusuran
Jika Anda belum memilikinya, buatlah Activity
yang akan menjalankan penelusuran dan menampilkan hasilnya. Anda belum perlu menerapkan fungsi penelusuran—cukup buat aktivitas yang dapat Anda deklarasikan dalam manifes. Di dalam elemen <activity>
manifes:
- Deklarasikan aktivitas untuk menerima intent
ACTION_SEARCH
, dalam elemen<intent-filter>
. - Tentukan konfigurasi penelusuran yang akan digunakan, dalam elemen
<meta-data>
.
Contoh:
<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 penelusuran (dalam contoh ini, merujuk ke file res/xml/searchable.xml
).
Catatan: <intent-filter>
tidak memerlukan <category>
dengan nilai DEFAULT
(yang biasanya Anda lihat dalam elemen <activity>
), karena sistem mengirimkan intent ACTION_SEARCH
secara eksplisit ke aktivitas penelusuran Anda, menggunakan nama komponennya.
Menjalankan penelusuran
Setelah Anda mendeklarasikan aktivitas penelusuran di dalam manifes, diperlukan tiga langkah untuk menjalankan penelusuran di aktivitas penelusuran Anda:
Biasanya, hasil penelusuran akan disajikan dalam ListView
, jadi sebaiknya aktivitas penelusuran Anda memperluas ListActivity
. Objek ini mencakup tata letak default dengan satu ListView
dan menyediakan beberapa metode praktis untuk menangani ListView
.
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 string QUERY
ekstra. Anda harus memeriksa keberadaan intent ini saat aktivitas dimulai dan mengekstrak 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
. Dalam contoh ini, kueri diambil dan diteruskan ke metode doMySearch()
lokal tempat operasi penelusuran sebenarnya dilakukan.
Menelusuri data
Proses menyimpan dan menelusuri data bersifat unik untuk aplikasi Anda. Anda dapat menyimpan dan menelusuri data dengan banyak cara, tetapi panduan ini tidak menunjukkan cara menyimpan data dan menelusurinya. Menyimpan dan menelusuri data adalah langkah yang harus dipertimbangkan dengan cermat dari segi kebutuhan dan format data Anda. Namun, berikut beberapa tips yang mungkin dapat Anda terapkan:
- Jika data Anda tersimpan 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 memberikan hasil jauh lebih cepat. Lihat sqlite.org untuk informasi tentang FTS3 dan classSQLiteDatabase
untuk informasi tentang SQLite di Android. - Jika data Anda tersimpan secara online, performa penelusuran yang dirasakan mungkin terhambat oleh koneksi data pengguna. Sebaiknya Anda menampilkan spinner progres sampai penelusuran Anda ditampilkan. Lihat
android.net
untuk referensi API jaringan dan Membuat Dialog Progres untuk informasi tentang cara menampilkan spinner progres.
Menampilkan hasil
Terlepas dari lokasi data Anda dan cara Anda menelusurinya, sebaiknya Anda menggunakan Adapter
untuk menampilkan hasil penelusuran ke aktivitas penelusuran Anda. Dengan begitu, Anda dapat menampilkan semua hasil penelusuran dalam ListView
dengan mudah. Jika data Anda berasal dari kueri database SQLite, Anda dapat menerapkan hasil ke ListView
menggunakan CursorAdapter
. Jika data Anda tersedia dalam jenis format lain, Anda dapat membuat ekstensi BaseAdapter
.
Adapter
mengikat setiap item dari set data ke dalam objek View
. Jika Adapter
diterapkan ke ListView
, setiap bagian data akan disisipkan sebagai tampilan terpisah ke dalam daftar. Adapter
hanyalah antarmuka, jadi implementasi seperti CursorAdapter
(untuk mengikat data dari Cursor
) diperlukan.
Jika semua implementasi yang ada tidak dapat digunakan dengan data Anda, maka Anda dapat menggunakan implementasi Anda sendiri dari BaseAdapter
.
Anda mungkin ingin aktivitas penelusuran Anda memperluas ListActivity
. Untuk itu, Anda dapat memanggil setListAdapter()
, yang akan meneruskan Adapter
yang terikat dengan data Anda ke sana. Dengan begitu semua hasil penelusuran akan diinjeksikan ke dalam aktivitas ListView
.
Untuk bantuan lebih lanjut dalam menyajikan hasil dalam daftar, lihat dokumentasi ListActivity
.
Menggunakan Dialog Penelusuran
Dialog penelusuran menyediakan kotak penelusuran mengambang di bagian atas layar, dengan ikon aplikasi di sebelah kirinya. Dialog penelusuran dapat memberikan saran penelusuran selagi pengguna mengetik dan, saat pengguna mengeksekusi penelusuran, sistem akan mengirimkan kueri penelusuran tersebut ke aktivitas penelusuran Anda yang akan menjalankan penelusuran. Namun, jika Anda mengembangkan aplikasi untuk perangkat yang menjalankan Android 3.0, sebaiknya pertimbangkan untuk menggunakan widget penelusuran saja (lihat bagian Menggunakan Widget Penelusuran.
Secara default, dialog penelusuran selalu tersembunyi sampai pengguna mengaktifkannya. Aplikasi Anda dapat mengaktifkan dialog penelusuran dengan memanggil onSearchRequested()
. Namun, metode ini tidak berfungsi sampai Anda mengaktifkan dialog penelusuran untuk aktivitas tersebut.
Untuk mengaktifkan dialog penelusuran, Anda harus menunjukkan kepada sistem aktivitas penelusuran mana yang akan menerima kueri penelusuran dari dialog penelusuran, agar penelusuran dapat dijalankan. Misalnya, di bagian sebelumnya tentang Membuat Aktivitas Penelusuran, sebuah aktivitas penelusuran dengan nama SearchableActivity
telah dibuat. Jika Anda menginginkan aktivitas terpisah, dengan nama OtherActivity
, untuk menampilkan dialog penelusuran dan mengirimkan penelusuran ke SearchableActivity
, di dalam manifes Anda harus mendeklarasikan bahwa SearchableActivity
adalah aktivitas penelusuran yang digunakan untuk dialog penelusuran di OtherActivity
.
Untuk mendeklarasikan aktivitas penelusuran bagi dialog penelusuran dari sebuah aktivitas, tambahkan elemen <meta-data>
di dalam elemen <activity>
masing-masing aktivitas
Elemen <meta-data>
harus menyertakan atribut android:value
yang menentukan nama class aktivitas penelusuran dan atribut android:name
dengan nilai "android.app.default_searchable"
.
Misalnya, berikut adalah deklarasi untuk aktivitas penelusuran, SearchableActivity
, dan aktivitas lainnya, OtherActivity
, yang menggunakan untuk menjalankan 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
sekarang menyertakan elemen <meta-data>
untuk mendeklarasikan aktivitas penelusuran mana yang akan digunakan untuk penelusuran, aktivitas ini telah mengaktifkan dialog penelusuran.
Saat 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.
Catatan: Aktivitas penelusuran itu sendiri menyediakan dialog penelusuran secara default, jadi Anda tidak perlu menambahkan deklarasi ini ke SearchableActivity
.
Jika Anda ingin setiap aktivitas dalam aplikasi Anda menyediakan dialog penelusuran, sisipkan elemen <meta-data>
di atas sebagai turunan dari elemen <application>
, bukan masing-masing <activity>
. Dengan cara ini, setiap aktivitas akan mewarisi nilai, menyediakan dialog penelusuran, dan mengirimkan penelusuran ke aktivitas penelusuran yang sama. (Jika terdapat beberapa aktivitas penelusuran, Anda dapat mengganti aktivitas penelusuran default dengan menempatkan deklarasi <meta-data>
berbeda di dalam setiap aktivitas.)
Setelah dialog penelusuran diaktifkan untuk aktivitas Anda, aplikasi Anda siap menjalankan penelusuran.
Memanggil dialog penelusuran
Meskipun beberapa perangkat menyediakan tombol Telusuri khusus, perilaku tombol ini di setiap perangkat dapat berlainan. Selain itu, ada banyak perangkat yang tidak memiliki tombol Telusuri. Jadi, saat menggunakan dialog penelusuran, Anda harus menyediakan tombol Telusuri di UI yang mengaktifkan dialog penelusuran dengan memanggil onSearchRequested()
.
Misalnya, Anda perlu menambahkan tombol Telusuri di Menu Opsi atau tata letak UI yang memanggil onSearchRequested()
. Agar konsisten dengan sistem Android dan aplikasi lainnya, sebaiknya Anda melabeli tombol ini dengan ikon Penelusuran Android yang tersedia dari Paket Ikon Panel Tindakan.
Catatan: Jika aplikasi Anda menggunakan panel aplikasi, sebaiknya jangan gunakan dialog penelusuran untuk antarmuka penelusuran Anda. Sebagai gantinya, gunakan widget penelusuran sebagai tampilan yang dapat diciutkan di panel aplikasi.
Anda juga dapat mengaktifkan fungsi “ketik-untuk-menelusuri”, yang akan mengaktifkan dialog penelusuran saat pengguna mulai mengetik di keyboard—ketukan tombol disisipkan ke dalam dialog penelusuran. Anda dapat mengaktifkan fungsi ketik-untuk-menelusuri dalam aktivitas Anda dengan memanggil setDefaultKeyMode
(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, jadi saat dialog penelusuran ditampilkan, tidak ada metode siklus hidup (seperti onPause()
) yang dipanggil. Aktivitas Anda hanya 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, hal tersebut menunjukkan bahwa aktivitas Anda telah kehilangan fokus input ke dialog penelusuran, sehingga Anda dapat melakukan pekerjaan apa pun yang sesuai dengan peristiwa tersebut (seperti menjeda game). Kecuali jika Anda meneruskan data konteks penelusuran (dibahas di bawah), Anda harus mengakhiri metode ini dengan memanggil implementasi super class. Contoh:
Kotlin
override fun onSearchRequested(): Boolean { pauseSomeStuff() return super.onSearchRequested() }
Java
@Override public boolean onSearchRequested() { pauseSomeStuff(); return super.onSearchRequested(); }
Jika pengguna membatalkan penelusuran dengan menekan tombol Kembali, dialog penelusuran akan menutup dan aktivitas mendapatkan kembali fokus input. Anda dapat mendaftar untuk diberi tahu saat dialog penelusuran ditutup dengan setOnDismissListener()
dan/atau setOnCancelListener()
. Anda hanya perlu mendaftarkan OnDismissListener
yang akan dipanggil setiap kali dialog penelusuran ditutup. OnCancelListener
hanya berkaitan dengan peristiwa di mana pengguna keluar dari dialog penelusuran secara eksplisit, sehingga tidak dipanggil saat penelusuran dijalankan (dalam hal ini, dialog penelusuran menghilang secara alami).
Jika aktivitas saat ini bukan merupakan aktivitas penelusuran, maka peristiwa siklus hidup aktivitas normal akan dipicu setelah pengguna menjalankan penelusuran (aktivitas saat ini menerima onPause()
dan sebagainya, seperti yang dijelaskan dalam dokumen Aktivitas). Namun, jika aktivitas saat ini merupakan aktivitas penelusuran, maka salah satu dari dua hal berikut akan terjadi:
- Secara default, aktivitas penelusuran menerima intent
ACTION_SEARCH
dengan panggilan keonCreate()
dan instance baru aktivitas tersebut akan dimunculkan di bagian teratas tumpukan aktivitas. Sekarang ada dua instance aktivitas penelusuran dalam tumpukan aktivitas (jadi menekan tombol Kembali akan mengembalikan ke instance aktivitas penelusuran sebelumnya, bukan keluar dari aktivitas penelusuran). - Jika Anda menetapkan
android:launchMode
ke"singleTop"
, maka aktivitas penelusuran akan menerima intentACTION_SEARCH
dengan panggilan keonNewIntent(Intent)
, sehingga meneruskan intentACTION_SEARCH
baru di sini. Misalnya, berikut adalah cara menangani kasus ini, di mana 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) { 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) { 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 contoh kode di bagian Menjalankan Penelusuran, semua kode untuk menangani intent penelusuran sekarang berada di metode
handleIntent()
, sehingga baikonCreate()
maupunonNewIntent()
dapat menjalankannya.Saat sistem memanggil
onNewIntent(Intent)
, aktivitas belum dimulai ulang, sehingga metodegetIntent()
menampilkan intent yang sama seperti yang diterima denganonCreate()
. Inilah alasan mengapa Anda harus memanggilsetIntent(Intent)
di dalamonNewIntent(Intent)
(agar intent yang disimpan oleh aktivitas diperbarui jika Anda memanggilgetIntent()
di masa mendatang).
Skenario kedua yang menggunakan mode peluncuran "singleTop"
biasanya ideal, karena setelah penelusuran dilakukan, kemungkinan besar pengguna akan melakukan penelusuran tambahan, dan akan menjadi pengalaman yang buruk jika aplikasi Anda membuat beberapa instance dari aktivitas penelusuran tersebut. Jadi, sebaiknya tetapkan aktivitas penelusuran Anda ke mode peluncuran "singleTop"
dalam manifes aplikasi. Contoh:
<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 mempersempit kriteria penelusuran berdasarkan aktivitas dari mana pengguna melakukan penelusuran, Anda dapat memberikan data tambahan di dalam intent yang dikirim oleh sistem ke aktivitas penelusuran Anda. Anda dapat meneruskan data tambahan ini dalam APP_DATA
Bundle
, yang disertakan dalam intent ACTION_SEARCH
.
Untuk meneruskan jenis data ini ke aktivitas penelusuran Anda, ganti metode onSearchRequested()
untuk aktivitas dari mana pengguna dapat 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 "true" menunjukkan bahwa Anda berhasil menangani peristiwa callback ini dan memanggil startSearch()
untuk mengaktifkan dialog penelusuran. Setelah pengguna mengirim kueri, kueri tersebut akan diteruskan ke aktivitas penelusuran Anda beserta data yang Anda tambahkan. Anda dapat mengekstrak data tambahan ini dari APP_DATA
Bundle
untuk mempersempit penelusuran. Contoh:
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); }
Perhatian: Jangan memanggil startSearch()
dari luar metode callback onSearchRequested()
. Untuk mengaktifkan dialog penelusuran dalam aktivitas Anda, selalu panggil onSearchRequested()
. Jika tidak, onSearchRequested()
tidak akan dipanggil dan penyesuaian (seperti penambahan appData
dalam contoh di atas) akan terlewatkan.
Menggunakan Widget Penelusuran

Gambar 2. Widget SearchView
sebagai "tampilan tindakan" di Panel Tindakan.
Widget SearchView
tersedia di Android 3.0 dan yang lebih tinggi. Jika Anda mengembangkan aplikasi untuk Android 3.0 dan telah memutuskan untuk menggunakan widget penelusuran, sebaiknya Anda menyisipkan widget penelusuran sebagai tampilan tindakan di panel aplikasi, bukannya menggunakan dialog penelusuran (dan bukannya menempatkan widget penelusuran dalam tata letak aktivitas Anda). Misalnya, gambar 2 menunjukkan widget penelusuran di panel aplikasi.
Widget penelusuran menyediakan fungsionalitas yang sama dengan dialog penelusuran. Widget ini memulai aktivitas yang sesuai saat pengguna menjalankan penelusuran, dan dapat memberikan saran penelusuran serta melakukan penelusuran suara. Jika opsi menempatkan widget penelusuran di Panel Tindakan ini tidak sesuai untuk Anda, sebagai gantinya Anda dapat menempatkan widget penelusuran di suatu tempat dalam tata letak aktivitas.
Catatan: Saat menggunakan widget penelusuran sebagai tampilan tindakan, Anda mungkin masih perlu mendukung penggunaan dialog penelusuran, khususnya ketika widget penelusuran tidak pas di Panel Tindakan. Lihat bagian berikut tentang Menggunakan widget dan dialog penelusuran bersama-sama.
Mengonfigurasi widget penelusuran
Setelah Anda membuat konfigurasi penelusuran dan aktivitas penelusuran, seperti yang dibahas di atas, Anda harus mengaktifkan penelusuran berbantuan untuk setiap SearchView
. Anda dapat melakukannya dengan memanggil setSearchableInfo()
dan meneruskan objek SearchableInfo
yang mewakili konfigurasi penelusuran Anda ke sana.
Anda dapat memperoleh referensi ke SearchableInfo
dengan memanggil getSearchableInfo()
di SearchManager
.
Misalnya, jika Anda menggunakan SearchView
sebagai tampilan tindakan di panel aplikasi, Anda harus mengaktifkan widget selama callback onCreateOptionsMenu()
:
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) // Do not 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); // Do not iconify the widget; expand it by default return true; }
Itu saja yang Anda perlukan. Widget penelusuran kini sudah dikonfigurasi dan sistem akan mengirimkan kueri penelusuran ke aktivitas penelusuran Anda. Anda juga dapat mengaktifkan saran penelusuran untuk widget penelusuran.
Catatan: Jika ingin menangani sendiri semua input pengguna, Anda dapat melakukannya dengan metode callback dan pemroses peristiwa. Untuk informasi selengkapnya, lihat dokumentasi referensi untuk SearchView
dan antarmuka bertingkatnya untuk pemroses peristiwa yang sesuai.
Untuk informasi selengkapnya tentang tampilan tindakan di Panel Tindakan, lihat Tampilan Tindakan dan Penyedia Tindakan.
Fitur widget penelusuran lainnya
Widget SearchView
mendukung beberapa fitur tambahan yang mungkin Anda inginkan:
- Tombol kirim
- Secara default, tidak ada tombol untuk mengirim kueri penelusuran, jadi pengguna harus menekan tombol "Enter" di keyboard untuk memulai penelusuran. Anda dapat menambahkan tombol "kirim" dengan memanggil
setSubmitButtonEnabled(true)
. - Mempersempit kueri untuk saran penelusuran
- Setelah mengaktifkan saran penelusuran, biasanya Anda berharap pengguna akan langsung memilih sebuah saran, tetapi mereka mungkin juga ingin mempersempit kueri penelusuran yang disarankan. Anda dapat menambahkan tombol di samping setiap saran, yang akan menyisipkan saran tersebut ke dalam kotak penelusuran untuk mempersempit kueri pengguna, dengan memanggil
setQueryRefinementEnabled(true)
. - Kemampuan untuk mengubah visibilitas kotak penelusuran
- Secara default, widget penelusuran diwakili oleh ikon penelusuran (kaca pembesar), yang akan meluas untuk menampilkan kotak penelusuran saat pengguna menyentuhnya.
Seperti yang ditunjukkan di atas, Anda dapat menampilkan kotak penelusuran secara default, dengan memanggil
setIconifiedByDefault(false)
. Anda juga dapat mengganti tampilan widget penelusuran dengan memanggilsetIconified()
.
Ada beberapa API lain dalam class SearchView
yang memungkinkan Anda menyesuaikan widget penelusuran. Namun, sebagian besar API tersebut digunakan hanya jika Anda menangani sendiri semua input pengguna, bukannya menggunakan sistem Android untuk mengirim kueri penelusuran dan menampilkan saran penelusuran.
Menggunakan widget dan dialog penelusuran bersama-sama
Jika Anda menyisipkan widget penelusuran di Panel Tindakan sebagai tampilan tindakan, dan Anda mengaktifkannya agar muncul di Panel Tindakan "jika ada ruang" (dengan menyetel android:showAsAction="ifRoom"
), maka ada kemungkinan widget penelusuran tidak akan muncul sebagai tampilan tindakan, tetapi item menu tersebut akan muncul di menu tambahan. Misalnya, jika aplikasi Anda berjalan di layar berukuran kecil, mungkin tidak ada cukup ruang di Panel Tindakan untuk menampilkan widget penelusuran bersama item tindakan atau elemen navigasi lainnya, sehingga item menu tersebut akan muncul di menu tambahan. Jika ditempatkan di menu tambahan, item tersebut berfungsi seperti item menu biasa dan tidak menampilkan tampilan tindakan (widget penelusuran).
Untuk menangani situasi ini, item menu tempa Anda mengaitkan widget penelusuran harus mengaktifkan dialog penelusuran saat pengguna memilihnya dari menu tambahan. Untuk melakukannya, Anda harus menerapkan onOptionsItemSelected()
untuk menangani item menu "Telusuri" dan membuka dialog penelusuran dengan memanggil onSearchRequested()
.
Untuk informasi selengkapnya tentang cara kerja item di Panel Tindakan dan cara menangani situasi ini, lihat panduan developer Panel Tindakan.
Menambahkan Penelusuran Suara
Anda dapat menambahkan fungsionalitas 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. Saat pengguna selesai berbicara, kueri penelusuran yang telah ditranskripsi akan dikirim ke aktivitas penelusuran Anda.
Contoh:
<?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, sedangkan nilai kedua, launchRecognizer
, menentukan bahwa tombol penelusuran suara harus meluncurkan pengenal yang menampilkan teks hasil transkripsi ke aktivitas penelusuran.
Anda dapat menyediakan atribut tambahan untuk menentukan perilaku penelusuran suara, seperti bahasa yang diharapkan dan jumlah hasil maksimum yang akan ditampilkan. Lihat referensi Konfigurasi Penelusuran untuk informasi selengkapnya tentang atribut yang tersedia.
Catatan: Pertimbangkan dengan saksama apakah penelusuran suara sesuai untuk aplikasi Anda. Semua penelusuran yang dilakukan dengan tombol penelusuran suara akan segera dikirim ke aktivitas penelusuran Anda tanpa memberi kesempatan kepada pengguna untuk meninjau kueri yang telah ditranskripsi. Uji pengenalan suara secara memadai dan pastikan pengenalan suara memahami jenis kueri yang mungkin dikirimkan pengguna di dalam aplikasi Anda.
Menambahkan Saran Penelusuran

Gambar 3. Screenshot dialog penelusuran dengan saran penelusuran kustom.
Baik dialog penelusuran maupun widget penelusuran dapat memberikan saran penelusuran selagi pengguna mengetik, dengan bantuan dari sistem Android. Sistem Android mengelola daftar saran ini dan menangani peristiwa saat pengguna memilih sebuah 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.
- Saran penelusuran kustom
- Saran ini adalah saran penelusuran yang Anda berikan dari sumber data Anda sendiri, untuk membantu pengguna memilih dengan cepat ejaan atau item yang benar yang mereka telusuri. Gambar 3 menunjukkan contoh saran kustom untuk aplikasi kamus—pengguna dapat memilih sebuah saran untuk membuka definisi dengan seketika.
Lihat Menambahkan Saran Kustom