Membuat antarmuka penelusuran

Jika Anda sudah siap menambahkan fungsi penelusuran ke aplikasi, Android akan membantu Anda terapkan antarmuka pengguna dengan dialog penelusuran yang muncul di bagian atas jendela aktivitas atau widget penelusuran yang bisa Anda sisipkan dalam tata letak. Baik dialog penelusuran maupun widget dapat mengirimkan kueri penelusuran pengguna ke aktivitas tertentu di aplikasi Anda. Dengan cara ini, pengguna dapat memulai penelusuran dari aktivitas tempat dialog atau widget penelusuran tersedia, dan sistem akan memulai aktivitas yang sesuai untuk melakukan pencarian dan menampilkan hasil.

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:

• Ikon Desain Material

Dasar-dasar

Sebelum memulai, putuskan apakah Anda ingin menerapkan antarmuka penelusuran menggunakan dialog penelusuran atau widget penelusuran. Keduanya menyediakan penelusuran yang sama khusus, 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 di bagian atas aktivitas.

  Sistem Android mengontrol semua peristiwa dalam dialog penelusuran. Jika pengguna mengirimkan kueri, sistem mengirimkan kueri tersebut ke aktivitas yang yang Anda tentukan untuk menangani penelusuran. Dialog ini juga dapat memberikan hasil penelusuran saran saat pengguna mengetik.

• Widget penelusuran adalah instance SearchView yang Anda bisa diletakkan di mana saja dalam tata letak Anda. Secara default, widget penelusuran berfungsi seperti standar EditText dan tidak melakukan apa pun, namun Anda dapat mengonfigurasinya sehingga menangani semua peristiwa input, mengirimkan kueri ke metode aktivitas Anda, dan memberikan saran penelusuran—sama seperti penelusuran dialog.

Catatan: Dokumen ini berfokus pada cara mengintegrasikan widget penelusuran dengan sistem untuk penerapan penelusuran berbantuan. Tapi Anda juga bisa menangani semua input pengguna ke dalam widget pencarian itu sendiri, dengan menggunakan berbagai metode callback dan pemroses. Jika Anda ingin menangani sendiri input pengguna, baca referensi dokumen untuk SearchView dan antarmuka bertingkatnya.

Saat pengguna menjalankan penelusuran dari dialog penelusuran atau widget penelusuran, sistem membuat Intent dan menyimpan kueri pengguna di dalamnya. Sistem kemudian memulai aktivitas yang Anda deklarasikan untuk menangani penelusuran—"aktivitas penelusuran"—dan mengirimkannya intent. Untuk menyiapkan aplikasi untuk penelusuran berbantuan semacam ini, Anda memerlukan berikut ini:

Konfigurasi penelusuran

File XML yang mengonfigurasi beberapa setelan untuk widget atau dialog penelusuran. Termasuk setelan untuk fitur seperti penelusuran suara, saran penelusuran, dan teks petunjuk untuk kotak penelusuran.

Aktivitas yang dapat ditelusuri

Activity yang menerima kueri penelusuran, menelusuri data Anda, dan menampilkan hasil hasil.

Antarmuka penelusuran, yang disediakan oleh salah satu hal berikut:

Dialog penelusuran

Secara default, dialog penelusuran disembunyikan. Ini muncul di bagian atas layar saat Anda menelepon onSearchRequested() saat pengguna mengetuk tombol Search.

SearchView widget

Menggunakan widget penelusuran memungkinkan Anda meletakkan kotak penelusuran di mana saja di aktivitas Anda, termasuk sebagai tampilan tindakan di panel aplikasi.

Bagian selanjutnya dari dokumen ini menunjukkan cara membuat konfigurasi penelusuran penelusuran, penelusuran, dan cara menerapkan antarmuka penelusuran dengan dialog penelusuran, atau widget penelusuran.

Membuat konfigurasi penelusuran

Hal pertama yang Anda perlukan adalah file XML yang disebut konfigurasi penelusuran. Mengonfigurasi aspek UI tertentu dari dialog atau widget pencarian dan menentukan cara fitur seperti saran dan penelusuran suara akan berfungsi. File ini biasanya yang bernama searchable.xml dan harus disimpan di res/xml/ project.

Catatan: Sistem menggunakan file ini untuk membuat instance SearchableInfo . Anda tidak dapat membuat objek ini sendiri saat runtime. Anda harus mendeklarasikan konfigurasi penelusuran dalam XML.

File konfigurasi penelusuran harus menyertakan <searchable> sebagai node root dan menentukan satu atribut atau lebih, seperti yang ditampilkan 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. Ini mengarah ke resource string, yang harus berupa nama aplikasi. Label ini bukan dapat dilihat oleh pengguna hingga Anda mengaktifkan saran penelusuran untuk Kotak Penelusuran Cepat, di di titik mana label terlihat dalam daftar Item yang dapat ditelusuri di sistem setelan.

Meskipun tidak diwajibkan, sebaiknya Anda selalu menyertakan Atribut android:hint, yang memberikan string petunjuk dalam penelusuran sebelum pengguna memasukkan kueri. Petunjuk ini penting karena memberikan petunjuk penting bagi pengguna tentang apa yang dapat mereka cari.

Tips: Agar konsisten dengan aplikasi Android lainnya, format string untuk android:hint sebagai "Search <content-or-product>". Misalnya, "Cari lagu dan artis" atau "Telusuri YouTube".

Elemen <searchable> menerima beberapa atribut lainnya. Namun, sebagian besar atribut tidak diperlukan hingga Anda menambahkan fitur seperti saran penelusuran dan penelusuran suara. Untuk informasi mendetail tentang file konfigurasi penelusuran, lihat Konfigurasi penelusuran dokumen referensi.

Membuat aktivitas penelusuran

Aktivitas penelusuran adalah Activity di aplikasi Anda yang menjalankan mencari berdasarkan {i>string<i} kueri dan menyajikan hasil pencarian.

Saat pengguna menjalankan penelusuran di widget atau dialog penelusuran, sistem memulai aktivitas penelusuran Anda dan mengirimkan kueri penelusuran ke dalamnya Intent dengan ACTION_SEARCH tindakan. Aktivitas penelusuran Anda akan mengambil kueri dari QUERY ekstra, kemudian mencari data Anda dan menyajikan hasilnya.

Karena Anda dapat menyertakan dialog atau widget penelusuran dalam aktivitas lain di aplikasi Anda, sistem harus mengetahui aktivitas mana yang merupakan aktivitas penelusuran Anda sehingga yang dapat mengirimkan kueri penelusuran dengan benar. Jadi, pertama-tama deklarasikan kemampuan aktivitas dalam file manifes Android.

Mendeklarasikan aktivitas penelusuran

Jika Anda belum memilikinya, buat Activity yang menjalankan mencari dan menampilkan hasil. Anda tidak perlu menerapkan istilah penelusuran fungsionalitasnya—cukup buat aktivitas yang bisa Anda deklarasikan dalam manifes. Di dalam manifes <activity> , lakukan hal berikut:

1. Deklarasikan aktivitas untuk menerima intent ACTION_SEARCH dalam elemen <intent-filter> .
2. Menentukan konfigurasi penelusuran yang akan digunakan di <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 android:resource dengan referensi ke file konfigurasi yang dapat ditelusuri. Di kolom contoh sebelumnya, hal ini mengacu pada res/xml/searchable.xml .

Catatan: <intent-filter> tidak memerlukan <category> dengan Nilai DEFAULT—yang biasanya Anda lihat di <activity> — karena sistem mengirimkan ACTION_SEARCH secara eksplisit ke aktivitas yang dapat ditelusuri menggunakan nama komponennya.

Melakukan penelusuran

Setelah Anda mendeklarasikan aktivitas penelusuran dalam manifes, ikuti langkah ini prosedur untuk melakukan penelusuran dalam aktivitas penelusuran Anda:

1. Terima kueri.
2. Telusuri data Anda.
3. Tampilkan hasilnya.

Menerima kueri

Saat pengguna menjalankan penelusuran dari dialog atau widget penelusuran, sistem memulai aktivitas penelusuran Anda dan mengirimkan ACTION_SEARCH intent. Intent ini membawa kueri penelusuran di string QUERY tambahan. Periksa intent ini saat aktivitas dimulai dan ekstrak string tersebut. Misalnya, berikut ini cara mendapatkan kueri penelusuran saat Anda aktivitas 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, kuerinya adalah diambil dan diteruskan ke metode doMySearch() lokal di mana operasi pencarian yang sebenarnya dilakukan.

Menelusuri data

Proses penyimpanan dan penelusuran data bersifat unik untuk aplikasi Anda. Anda dapat menyimpan dan menelusuri data Anda dengan banyak cara, dan dokumen ini tidak menunjukkan caranya. Pertimbangkan bagaimana Anda menyimpan dan mencari data dalam hal kebutuhan dan data Anda format font. Berikut tips yang mungkin dapat Anda terapkan:

• Jika data Anda disimpan dalam database SQLite pada perangkat, melakukan penelusuran teks lengkap—menggunakan FTS3, bukan LIKE kueri—dapat menyediakan penelusuran yang lebih andal di seluruh data teks dan dapat memberikan hasil dengan jauh lebih cepat. Lihat plist.org untuk informasi tentang FTS3 dan SQLiteDatabase untuk informasi tentang SQLite di Android.
• Jika data Anda disimpan secara {i>online<i}, maka kinerja penelusuran yang dirasakan mungkin terhalang oleh koneksi data pengguna. Anda mungkin ingin menampilkan progresif hingga penelusuran Anda kembali. Lihat android.net untuk referensi API jaringan dan ProgressBar untuk mengetahui informasi tentang cara menampilkan indikator progres.

Catatan: Jika Anda berencana menggunakan database lokal, lihat Simpan data di {i>database<i} lokal menggunakan Ruang.

Mempresentasikan hasilnya

Di mana pun data Anda berada dan bagaimana Anda menelusurinya, sebaiknya Anda mengembalikan hasil penelusuran ke aktivitas penelusuran Anda dengan Adapter. Ini Anda dapat menyajikan semua hasil penelusuran dalam RecyclerView. Jika data berasal dari kueri database SQLite, Anda bisa menerapkan hasilnya ke RecyclerView menggunakan CursorAdapter. Jika data Anda memiliki format yang berbeda, maka Anda dapat membuat BaseAdapter.

Adapter mengikat setiap item dari set data ke dalam Objek View. Kapan Adapter diterapkan ke RecyclerView, setiap bagian data dimasukkan sebagai tampilan terpisah ke dalam daftar. Adapter sama dengan hanya sebuah antarmuka, jadi implementasi seperti CursorAdapter—untuk mengikat data dari Cursor—adalah diperlukan. Jika tidak satu pun dari penerapan yang ada yang sesuai untuk data Anda, Anda dapat mengimplementasikan sendiri dari BaseAdapter.

Menggunakan dialog penelusuran

Dialog pencarian menyediakan kotak pencarian 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 penelusuran kueri ke aktivitas yang dapat ditelusuri yang melakukan penelusuran.

Secara default, dialog penelusuran selalu disembunyikan hingga pengguna mengaktifkannya. Aplikasi Anda dapat mengaktifkan dialog penelusuran dengan memanggil onSearchRequested(). Namun, metode ini tidak akan berfungsi sampai Anda mengaktifkan dialog penelusuran untuk aktivitas tersebut.

Untuk mengaktifkan dialog penelusuran guna melakukan penelusuran, tunjukkan kepada sistem yang aktivitas penelusuran harus menerima kueri penelusuran dari dialog penelusuran. Sebagai misalnya, di bagian sebelumnya tentang membuat aktivitas penelusuran, aktivitas yang aktivitas bernama SearchableActivity dibuat. Jika Anda menginginkan aktivitas terpisah, seperti aktivitas bernama OtherActivity, untuk menampilkan dialog penelusuran dan kirimkan penelusuran ke SearchableActivity, deklarasikan dalam manifes bahwa SearchableActivity adalah aktivitas yang dapat ditelusuri yang akan digunakan untuk dialog penelusuran di OtherActivity.

Untuk mendeklarasikan aktivitas yang dapat ditelusuri untuk dialog penelusuran aktivitas, tambahkan Elemen <meta-data> di dalam elemen elemen <activity>. <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 ini deklarasi untuk aktivitas yang dapat ditelusuri, 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 kini menyertakan Elemen <meta-data> untuk mendeklarasikan aktivitas penelusuran mana digunakan untuk penelusuran, aktivitas tersebut akan mengaktifkan dialog penelusuran. Meskipun pengguna dalam aktivitas ini, metode onSearchRequested() akan mengaktifkan dialog penelusuran. Saat pengguna menjalankan penelusuran, sistem akan memulai SearchableActivity dan mengirimkan ACTION_SEARCH ke sini intent.

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

Jika Anda ingin setiap aktivitas dalam aplikasi menyediakan dialog penelusuran, masukkan elemen <meta-data> sebelumnya sebagai turunan dari <application> , alih-alih setiap <activity>. Dengan cara ini, setiap aktivitas mewarisi nilainya, menyediakan dialog pencarian, dan mengirimkan penelusuran ke aktivitas penelusuran yang sama. Jika memiliki banyak aktivitas yang dapat ditelusuri, Anda dapat mengganti aktivitas penelusuran default dengan menempatkan Deklarasi <meta-data> di dalam aktivitas individual.

Dengan dialog penelusuran yang sekarang diaktifkan untuk aktivitas Anda, aplikasi Anda siap untuk melakukan pencarian.

Memanggil dialog penelusuran

Meskipun beberapa perangkat menyediakan tombol pencarian khusus, perilaku mungkin bervariasi di antara perangkat, dan banyak perangkat tidak menyediakan informasi tombol ini 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().

Catatan: Jika aplikasi Anda menggunakan aplikasi , lalu 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 "ketik untuk menelusuri" fungsionalitasnya, yang akan mengaktifkan dialog penelusuran saat pengguna mulai mengetik di keyboard. Penekanan tombolnya adalah dimasukkan ke dalam dialog penelusuran. Anda dapat mengaktifkan ketik untuk menelusuri dalam aktivitas Anda dengan memanggil setDefaultKeyMode—atau DEFAULT_KEYS_SEARCH_LOCAL—selama aktivitasmu onCreate() .

Dampak dialog penelusuran terhadap siklus hidup aktivitas

Dialog pencarian adalah Dialog yang mengambang di bagian atas layar. Hal ini tidak menyebabkan perubahan dalam tumpukan aktivitas, jadi ketika dialog penelusuran muncul, tidak ada metode siklus proses—seperti onPause()—adalah 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, adalah indikasi bahwa aktivitas Anda kehilangan fokus input ke dialog penelusuran, jadi Anda dapat melakukan tindakan yang sesuai untuk peristiwa tersebut, seperti menjeda game. Kecuali Anda meneruskan konteks penelusuran data—yang dibahas di bagian lain dalam dokumen ini—mengakhiri 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 ditutup dan aktivitas mendapatkan kembali fokus input. Anda dapat mendaftar untuk mendapatkan notifikasi saat dialog penelusuran ditutup dengan setOnDismissListener(), setOnCancelListener(), atau keduanya. Anda hanya perlu mendaftarkan OnDismissListener, karena dipanggil setiap kali dialog penelusuran ditutup. Tujuan OnCancelListener hanya berkaitan dengan peristiwa di mana pengguna secara eksplisit keluar dari dialog penelusuran, jadi fungsi ini tidak dipanggil saat pencarian dilakukan. Ketika penelusuran dijalankan, dialog penelusuran akan otomatis menghilang.

Jika aktivitas saat ini bukan aktivitas penelusuran, maka normal peristiwa siklus proses aktivitas dipicu saat pengguna menjalankan penelusuran—aktivitas saat ini menerima onPause(), seperti yang dijelaskan di Pengantar aktivitas. Namun, jika aktivitas saat ini adalah aktivitas yang dapat ditelusuri, maka salah satu dari dua hal berikut akan terjadi:

• Secara default, aktivitas penelusuran menerima intent ACTION_SEARCH dengan panggilan ke onCreate(), dan instance baru dari aktivitas tersebut dibawa ke bagian atas aktivitas {i>stack<i}. Sekarang ada dua instance aktivitas penelusuran Anda di tumpukan aktivitas, jadi mengetuk tombol Kembali akan membawa Anda kembali ke aktivitas yang dapat ditelusuri, bukan keluar dari penelusuran aktivitas Anda.
• Jika Anda menetapkan android:launchMode ke "singleTop", maka aktivitas yang dapat ditelusuri akan menerima intent ACTION_SEARCH dengan panggilan ke onNewIntent(Intent), meneruskan intent ACTION_SEARCH baru. Sebagai contoh, berikut ini cara Anda mungkin 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 kode contoh pada bagian tentang melakukan penelusuran, semua kode untuk menangani maksud penelusuran sekarang ada dalam metode handleIntent(), sehingga onCreate() dan onNewIntent() dapat menjalankannya.

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

Skenario kedua, yang menggunakan mode peluncuran "singleTop", biasanya lebih disukai, karena setelah pencarian dilakukan, pengguna mungkin melakukan tambahan penelusuran, dan Anda tidak ingin aplikasi membuat beberapa instance aktivitas yang dapat ditelusuri. Sebaiknya tetapkan aktivitas penelusuran Anda ke Mode peluncuran "singleTop" di manifes aplikasi, seperti yang ditampilkan di 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 melakukan penyempurnaan yang diperlukan pada kueri penelusuran di dalam aktivitas yang dapat ditelusuri untuk setiap pencarian yang dilakukan. Namun, jika Anda ingin menyempurnakan kriteria pencarian berdasarkan aktivitas dari pengguna yang melakukan penelusuran, Anda dapat menyediakan data tambahan dengan maksud yang dikirim sistem ke aktivitas penelusuran Anda. Anda dapat meneruskan data tambahan di kolom APP_DATA Bundle, yang merupakan disertakan dalam intent ACTION_SEARCH.

Untuk meneruskan data jenis ini ke aktivitas penelusuran Anda, ganti metode Metode onSearchRequested() untuk aktivitas yang dapat digunakan pengguna melakukan penelusuran, membuat Bundle dengan data tambahan, dan panggilan telepon 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 (benar) menunjukkan bahwa Anda berhasil menangani peristiwa callback ini dan panggil startSearch() untuk mengaktifkan dialog penelusuran. Setelah pengguna mengirim kueri, kueri itu 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);
}

Perhatian: Jangan pernah memanggil metode startSearch() dari luar metode callback onSearchRequested(). Untuk mengaktifkan penelusuran dalam aktivitas Anda, selalu panggil onSearchRequested(). Jika tidak, onSearchRequested() tidak akan dipanggil dan penyesuaian—seperti penambahan appData di contoh sebelumnya—yang terlewatkan.

Menggunakan widget penelusuran

Gambar 1. Widget SearchView sebagai tampilan tindakan di panel aplikasi.

Widget penelusuran menyediakan fungsionalitas yang sama dengan dialog penelusuran. Ini memulai aktivitas yang sesuai saat pengguna menjalankan penelusuran, dan dapat memberikan saran penelusuran dan melakukan penelusuran suara. Jika itu bukan pilihan untuk menempatkan widget penelusuran di panel aplikasi, Anda dapat menempatkan widget di suatu tempat dalam tata letak aktivitas Anda.

Catatan: Saat menggunakan widget penelusuran sebagai tampilan tindakan, Anda mungkin masih mendukung penggunaan dialog penelusuran jika widget penelusuran tidak muat di bilah aplikasi. Lihat bagian tentang menggunakan widget dan dialog.

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 yang dapat ditelusuri.

Anda bisa mendapatkan referensi ke SearchableInfo dengan memanggil getSearchableInfo() nyala SearchManager.

Misalnya, jika Anda menggunakan SearchView sebagai tampilan tindakan di panel aplikasi, aktifkan widget selama 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 telah dikonfigurasi, dan sistem mengirimkan kueri penelusuran ke aktivitas penelusuran Anda. Anda juga dapat mengaktifkan saran penelusuran untuk widget penelusuran tersebut.

Catatan: Jika ingin menangani sendiri semua input pengguna, Anda dapat melakukannya dengan beberapa metode callback dan pemroses peristiwa. Untuk informasi selengkapnya, lihat dokumentasi referensi untuk SearchView dan antarmuka bertingkatnya.

Untuk informasi selengkapnya tentang tampilan tindakan di panel aplikasi, lihat Menggunakan tampilan tindakan dan tindakan penyedia layanan.

Fitur widget penelusuran lainnya

Widget SearchView menyediakan beberapa fitur tambahan yang mungkin ingin:

Tombol kirim

Secara default, tidak ada tombol untuk mengirimkan kueri penelusuran, sehingga pengguna harus melakukannya tekan tombol Return di keyboard untuk memulai penelusuran. Anda dapat menambahkan "{i>submit<i}" tombol dengan memanggil setSubmitButtonEnabled(true).

Mempersempit kueri untuk saran penelusuran

Saat mengaktifkan saran penelusuran, Anda biasanya mengharapkan pengguna memilih Anda, tetapi mereka mungkin juga ingin menyaring saran kueri penelusuran. Anda dapat menambahkan tombol di samping setiap saran yang menyisipkan saran di kotak penelusuran untuk menyaring oleh pengguna dengan memanggil setQueryRefinementEnabled(true).

Kemampuan untuk mengubah visibilitas kotak penelusuran

Secara default, widget penelusuran "diikonkan", artinya itu adalah hanya diwakili oleh ikon pencarian—kaca pembesar. Menu ini diperluas ke menampilkan kotak penelusuran ketika pengguna mengetuk ikon. Seperti yang ditunjukkan di video sebelumnya Anda dapat menampilkan kotak penelusuran secara default dengan memanggil setIconifiedByDefault(false). Anda juga dapat mengubah tampilan widget penelusuran dengan memanggil setIconified().

Ada beberapa API lain di class SearchView yang memungkinkan menyesuaikan widget penelusuran tersebut. Namun, kebanyakan dari mereka hanya digunakan ketika Anda menangani sendiri semua input pengguna, alih-alih 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 mengaktifkan agar muncul di panel aplikasi jika ada ruang—dengan mengatur android:showAsAction="ifRoom"—widget penelusuran mungkin tidak muncul sebagai tampilan tindakan. Sebagai gantinya, item menu mungkin muncul di Google Spreadsheet. Misalnya, ketika aplikasi Anda berjalan pada layar yang lebih kecil, mungkin tidak ada cukup ruang di panel aplikasi untuk menampilkan widget penelusuran beserta tindakan lainnya atau elemen navigasi, sehingga item menu akan muncul dalam menu tambahan Google Spreadsheet. Jika ditempatkan di menu tambahan, item berfungsi seperti menu biasa item dan tidak menampilkan tampilan tindakan—yaitu, widget penelusuran.

Untuk menangani situasi ini, item menu tempat Anda melampirkan widget penelusuran harus mengaktifkan dialog penelusuran bila pengguna memilihnya dari menu tambahan. Untuk melakukannya, terapkan onOptionsItemSelected() untuk menangani “Penelusuran” dan membuka dialog penelusuran dengan memanggil onSearchRequested().

Untuk informasi selengkapnya tentang cara kerja item di panel aplikasi dan cara menangani situasi ini, lihat Tambahkan panel aplikasi.

Tambahkan penelusuran suara

Anda dapat menambahkan fungsi penelusuran suara ke dialog atau widget penelusuran dengan menambahkan atribut android:voiceSearchMode ke konten yang dapat ditelusuri konfigurasi Anda. Tindakan ini akan menambahkan tombol penelusuran suara yang meluncurkan perintah suara. Setelah pengguna selesai berbicara, kueri penelusuran yang 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 suara cari. Nilai kedua, launchRecognizer, menentukan bahwa tombol penelusuran suara harus meluncurkan pengenalan yang menampilkan teks yang ditranskripsikan ke aktivitas yang dapat ditelusuri.

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

Catatan: Pertimbangkan dengan cermat apakah penelusuran suara sesuai untuk . Penelusuran yang dilakukan dengan tombol penelusuran suara akan langsung dikirim ke aktivitas penelusuran Anda, tanpa memberikan kesempatan bagi pengguna untuk meninjau kueri yang ditranskripsikan. Uji pengenalan suara dan pastikan pengenalan suara jenis kueri yang mungkin dikirimkan pengguna di aplikasi Anda.

Tambahkan saran penelusuran

Dialog penelusuran dan widget penelusuran dapat memberikan saran penelusuran saat 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 penelusuran kueri tertentu di aplikasi Anda. Lihat Tambahkan 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 untuk segera memilih ejaan atau item yang benar yang mereka telusuri untuk mereka. Lihat Menambahkan penelusuran khusus untuk informasi selengkapnya.