Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat antarmuka penelusuran

Jika Anda sudah siap menambahkan fungsi penelusuran ke aplikasi, Android akan 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

Dokumen ini menunjukkan cara menyiapkan aplikasi Anda untuk menyediakan antarmuka penelusuran dengan bantuan sistem Android untuk mengirimkan kueri penelusuran, menggunakan dialog penelusuran atau widget penelusuran.

Referensi terkait:

Ikon Desain Material

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. 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 widget EditText 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: Dokumen ini berfokus pada cara mengintegrasikan widget penelusuran dengan sistem untuk penerapan penelusuran berbantuan. Namun, Anda juga dapat menangani sendiri semua input pengguna ke dalam widget penelusuran, menggunakan berbagai metode callback dan pemroses. Jika Anda ingin menangani sendiri input pengguna, baca dokumen 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 Anda deklarasikan untuk menangani penelusuran—"aktivitas penelusuran"—dan mengirimkan intent ke sana. Untuk menyiapkan aplikasi Anda untuk jenis penelusuran berbantuan ini, Anda memerlukan hal-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 dari berikut ini:

Bagian lain dari dokumen ini menunjukkan cara membuat konfigurasi penelusuran dan aktivitas yang dapat ditelusuri 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. 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 direktori project res/xml/.

Catatan: Sistem menggunakan file ini untuk membuat instance objek SearchableInfo. Anda tidak dapat membuat objek ini sendiri saat runtime. Anda harus mendeklarasikan konfigurasi penelusuran di 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 menunjuk ke resource string, yang harus berupa nama aplikasi. Label ini tidak terlihat oleh pengguna sampai Anda mengaktifkan saran penelusuran untuk Kotak Penelusuran Kilat, yang pada saat itu label tersebut 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 aplikasi Android lainnya, format string untuk android:hint sebagai "Telusuri <konten-atau-produk>". Misalnya, "Telusuri lagu dan 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 yang dapat ditelusuri

Aktivitas yang dapat ditelusuri 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 Anda 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 di aplikasi Anda, sistem harus mengetahui aktivitas mana yang merupakan aktivitas penelusuran agar dapat mengirimkan kueri penelusuran dengan tepat. Jadi, deklarasikan terlebih dahulu aktivitas penelusuran Anda dalam file manifes Android.

Mendeklarasikan aktivitas penelusuran

Jika Anda belum memilikinya, buat Activity yang melakukan penelusuran dan menampilkan hasilnya. 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 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.

Melakukan penelusuran

Setelah Anda mendeklarasikan aktivitas penelusuran di dalam manifes, ikuti prosedur ini untuk menjalankan penelusuran di aktivitas penelusuran Anda:

Menerima kueri.
Menelusuri data Anda.
Menampilkan hasil.

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. Periksa keberadaan 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. Dalam contoh sebelumnya, kueri diambil dan diteruskan ke metode doMySearch() lokal tempat operasi penelusuran sebenarnya dilakukan.

Menelusuri data Anda

Proses menyimpan dan menelusuri data bersifat unik untuk aplikasi Anda. Anda dapat menyimpan dan menelusuri data dengan banyak cara, dan dokumen ini tidak menunjukkan caranya. Pertimbangkan cara Anda menyimpan dan menelusuri data dari segi kebutuhan dan format data Anda. Berikut adalah tips yang 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 dapat memberikan hasil jauh lebih cepat. Lihat sqlite.org untuk informasi tentang FTS3 dan class SQLiteDatabase 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 indikator progres sampai penelusuran Anda ditampilkan. Lihat android.net untuk referensi API jaringan dan ProgressBar untuk informasi tentang cara menampilkan indikator 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 RecyclerView. Jika data Anda berasal dari kueri database SQLite, Anda dapat menerapkan hasil ke RecyclerView menggunakan CursorAdapter. Jika data Anda tersedia dalam format lain, Anda dapat membuat ekstensi BaseAdapter.

Adapter mengikat setiap item dari set data ke dalam objek View. Jika Adapter diterapkan ke RecyclerView, 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.

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. Saat pengguna menjalankan penelusuran, sistem akan mengirimkan kueri penelusuran ke aktivitas penelusuran yang menjalankan 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 agar 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 dengan nama SearchableActivity dibuat. Jika Anda menginginkan aktivitas terpisah, seperti yang bernama OtherActivity, untuk menampilkan dialog penelusuran dan mengirimkan penelusuran ke SearchableActivity, deklarasikan di manifes bahwa SearchableActivity adalah aktivitas penelusuran yang akan 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 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 dijalankan 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 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.

Catatan: Aktivitas penelusuran itu sendiri menyediakan dialog penelusuran secara default, jadi Anda tidak perlu menambahkan deklarasi ini ke SearchableActivity.

Jika Anda ingin setiap aktivitas di aplikasi Anda menyediakan dialog penelusuran, sisipkan elemen <meta-data> sebelumnya sebagai turunan dari elemen <application>, bukan setiap <activity>. Dengan cara ini, setiap aktivitas akan 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 Anda siap menjalankan penelusuran.

Memanggil dialog penelusuran

Meskipun beberapa perangkat menyediakan tombol penelusuran khusus, perilaku tombol ini di setiap perangkat dapat berlainan. Selain itu, ada banyak perangkat yang tidak memiliki tombol penelusuran. 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. Ketukan tombol disisipkan ke dalam dialog penelusuran. Anda dapat mengaktifkan fungsi ketik-untuk-menelusuri dalam aktivitas Anda 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, jadi saat dialog penelusuran ditampilkan, 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, hal tersebut menunjukkan bahwa aktivitas Anda 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—yang dibahas di bagian lain dalam dokumen ini—akhiri metode 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 untuk 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 merupakan aktivitas yang dapat ditelusuri, 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 merupakan aktivitas penelusuran, maka salah satu dari dua hal berikut akan terjadi:

Secara default, aktivitas yang dapat ditelusuri menerima intent ACTION_SEARCH dengan panggilan ke onCreate(), dan instance baru aktivitas tersebut akan dimunculkan di bagian teratas tumpukan aktivitas. Sekarang ada dua instance aktivitas penelusuran Anda 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", maka aktivitas yang dapat ditelusuri akan menerima intent ACTION_SEARCH dengan panggilan ke onNewIntent(Intent), sambil meneruskan intent ACTION_SEARCH baru. Misalnya, berikut 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) {
    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 contoh kode di bagian menjalankan penelusuran, semua kode untuk menangani intent penelusuran sekarang berada di metode handleIntent(), sehingga baik onCreate() maupun onNewIntent() dapat menjalankannya.

Saat sistem memanggil onNewIntent(Intent), aktivitas tidak dimulai ulang, sehingga metode getIntent() menampilkan intent yang sama seperti yang diterima dengan onCreate(). Inilah alasan mengapa Anda harus memanggil setIntent(Intent) di dalam onNewIntent(Intent): agar intent yang disimpan oleh aktivitas diperbarui jika Anda memanggil getIntent() di masa mendatang.

Skenario kedua, yang menggunakan mode peluncuran "singleTop", biasanya lebih disukai, karena setelah penelusuran dilakukan, pengguna dapat melakukan penelusuran tambahan, dan Anda tidak ingin aplikasi Anda membuat beberapa instance dari aktivitas penelusuran. 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 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 benar 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 beserta data yang Anda tambahkan. Anda dapat mengekstrak data tambahan dari APP_DATA Bundle untuk mempersempit 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);
}

Perhatian: Jangan pernah memanggil metode 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 sebelumnya—akan terlewatkan.

Menggunakan widget penelusuran

Gambar yang menampilkan tampilan penelusuran di panel atas aplikasi

Gambar 1. Widget SearchView sebagai tampilan tindakan 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 aplikasi ini tidak sesuai untuk Anda, sebagai gantinya Anda dapat menempatkan widget penelusuran di suatu tempat dalam tata letak aktivitas.

Mengonfigurasi widget penelusuran

Setelah Anda 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 dapat memperoleh 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 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 beberapa metode callback dan pemroses peristiwa. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi untuk SearchView dan antarmuka bertingkatnya.

Untuk mengetahui informasi selengkapnya tentang tampilan tindakan di panel aplikasi, lihat 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 mengirim kueri penelusuran, jadi 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, biasanya Anda berharap pengguna akan 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). Ikon ini akan meluas untuk menampilkan kotak penelusuran saat pengguna mengetuk ikon. Seperti yang ditunjukkan dalam contoh sebelumnya, Anda dapat menampilkan kotak penelusuran secara default dengan memanggil setIconifiedByDefault(false). Anda juga dapat mengganti tampilan widget penelusuran dengan memanggil setIconified().

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 aplikasi sebagai tampilan tindakan dan mengaktifkannya agar muncul di panel aplikasi jika ada ruang—dengan menyetel android:showAsAction="ifRoom"—maka widget penelusuran mungkin tidak muncul sebagai tampilan tindakan. Sebagai gantinya, item menu mungkin muncul di menu tambahan. Misalnya, jika aplikasi Anda berjalan di layar berukuran kecil, mungkin tidak ada cukup ruang di panel aplikasi 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, yaitu widget penelusuran.

Untuk menangani situasi ini, item menu tempat Anda melampirkan widget penelusuran harus mengaktifkan dialog penelusuran saat pengguna memilihnya dari menu tambahan. Untuk melakukannya, terapkan onOptionsItemSelected() untuk menangani item menu "Telusuri" dan membuka 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.

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.

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 hasil transkripsi ke aktivitas yang dapat ditelusuri.

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 mengetahui informasi selengkapnya tentang atribut yang tersedia.

Menambahkan saran penelusuran

Baik dialog penelusuran maupun widget penelusuran dapat memberikan saran penelusuran selagi pengguna mengetik, dengan bantuan dari sistem Android. Sistem 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 di aplikasi Anda. Lihat Menambahkan saran penelusuran kustom untuk mengetahui informasi selengkapnya.
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. Lihat Menambahkan saran penelusuran kustom untuk mengetahui informasi selengkapnya.

Membuat antarmuka penelusuran Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Dasar-dasar

Membuat konfigurasi yang dapat ditelusuri

Membuat aktivitas yang dapat ditelusuri

Mendeklarasikan aktivitas penelusuran

Melakukan penelusuran

Menerima kueri

Kotlin

Java

Menelusuri data Anda

Menampilkan hasil

Menggunakan dialog penelusuran

Memanggil dialog penelusuran

Dampak dialog penelusuran terhadap siklus hidup aktivitas

Kotlin

Java

Kotlin

Java

Meneruskan data konteks penelusuran

Kotlin

Java

Kotlin

Java

Menggunakan widget penelusuran

Mengonfigurasi widget penelusuran

Kotlin

Java

Fitur widget penelusuran lainnya

Menggunakan widget dan dialog penelusuran bersama-sama

Menambahkan penelusuran suara

Menambahkan saran penelusuran

Membuat antarmuka penelusuran