Konfigurasi penelusuran

Coba cara Compose

Jetpack Compose adalah toolkit UI yang direkomendasikan untuk Android. Pelajari cara menambahkan fungsi penelusuran di Compose.

Kotak penelusuran →

Untuk menerapkan penelusuran dengan bantuan dari sistem Android—yaitu, untuk mengirimkan kueri penelusuran ke sebuah aktivitas dan memberikan saran penelusuran—aplikasi Anda harus menyediakan konfigurasi penelusuran dalam bentuk file XML.

Halaman ini menjelaskan file konfigurasi penelusuran dari segi sintaks dan penggunaannya. Untuk mengetahui informasi selengkapnya tentang cara menerapkan fitur penelusuran untuk aplikasi Anda, lihat Membuat antarmuka penelusuran.

lokasi file:

res/xml/filename.xml
Android menggunakan nama file sebagai ID resource.

sintaksis:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>

elemen:

<searchable>

Menentukan semua konfigurasi penelusuran yang digunakan oleh sistem Android untuk menyediakan penelusuran berbantuan.

Atribut:

android:label

Resource string. (Wajib.) Nama aplikasi Anda. Nama ini harus sama dengan nama yang diterapkan ke atribut android:label <activity> atau <application> elemen manifes. Label ini hanya terlihat oleh pengguna jika Anda menetapkan android:includeInGlobalSearch ke "true", yang dalam hal ini, label tersebut digunakan untuk mengidentifikasi aplikasi Anda sebagai item penelusuran dalam setelan penelusuran sistem.

android:hint

Resource string. (Direkomendasikan.) Teks yang akan ditampilkan di kolom teks penelusuran jika tidak ada teks yang dimasukkan. Teks ini memberikan petunjuk kepada pengguna tentang konten apa yang dapat ditelusuri. Agar konsisten dengan aplikasi Android lainnya, format string untuk android:hint sebagai "Telusuri <konten-atau-produk>". Misalnya, "Telusuri lagu dan artis" atau "Telusuri YouTube".

android:searchMode

Kata kunci. Menetapkan mode tambahan yang mengontrol presentasi penelusuran. Mode yang tersedia menentukan cara teks kueri harus ditulis ulang saat saran kustom menerima fokus. Nilai mode berikut diterima:

Nilai	Deskripsi
"queryRewriteFromData"	Gunakan nilai dari kolom SUGGEST_COLUMN_INTENT_DATA untuk menulis ulang teks kueri. Atribut ini hanya boleh digunakan jika nilai dalam SUGGEST_COLUMN_INTENT_DATA cocok untuk pemeriksaan dan pengeditan pengguna, seperti URI HTTP.
"queryRewriteFromText"	Gunakan nilai dari kolom SUGGEST_COLUMN_TEXT_1 untuk menulis ulang teks kueri.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi tentang menulis ulang teks kueri dalam Menambahkan saran penelusuran kustom.

android:searchButtonText

Resource string. Teks yang akan ditampilkan di tombol yang menjalankan penelusuran. Secara default, tombol menampilkan ikon penelusuran (kaca pembesar), yang ideal untuk internasionalisasi. Jadi, jangan gunakan atribut ini untuk mengubah tombol kecuali jika perilakunya berbeda dengan penelusuran, seperti permintaan URL di browser web.

android:inputType

Kata kunci. Menentukan jenis metode input yang akan digunakan, seperti jenis keyboard software. Untuk sebagian besar penelusuran, yang mengharapkan teks bentuk bebas, Anda tidak memerlukan atribut ini. Lihat inputType untuk mengetahui daftar nilai yang sesuai untuk atribut ini.

android:imeOptions

Kata kunci. Menyediakan opsi tambahan untuk metode input. Untuk sebagian besar penelusuran, yang mengharapkan teks bentuk bebas, Anda tidak memerlukan atribut ini. IME default-nya adalah actionSearch, yang menyediakan tombol "telusuri", bukan "enter" di soft keyboard. Lihat imeOptions untuk mengetahui daftar nilai yang sesuai untuk atribut ini.

Atribut saran penelusuran

Jika Anda menentukan penyedia konten untuk menghasilkan saran penelusuran, Anda perlu menentukan atribut tambahan yang akan mengonfigurasi komunikasi dengan penyedia konten tersebut. Saat memberikan saran penelusuran, Anda memerlukan beberapa atribut <searchable> berikut:

android:searchSuggestAuthority

String. (Wajib, untuk memberikan saran penelusuran.) Nilai ini harus cocok dengan string otoritas yang disediakan dalam atribut android:authorities elemen <provider> manifes Android.

android:searchSuggestPath

String. Jalur ini digunakan sebagai bagian dari Uri kueri saran, setelah awalan dan otoritas, serta sebelum jalur saran standar. Atribut ini hanya wajib jika Anda memiliki satu penyedia konten yang memberikan berbagai jenis saran, misalnya untuk jenis data yang berlainan, dan Anda memerlukan cara untuk membedakan kueri saran saat menerimanya.

android:searchSuggestSelection

String. Nilai ini diteruskan ke fungsi kueri Anda sebagai parameter selection. Biasanya ini adalah klausa WHERE untuk database Anda, dan harus berisi satu tanda tanya sebagai placeholder untuk string kueri sebenarnya yang dimasukkan oleh pengguna—misalnya, "query=?". Namun, Anda juga dapat menggunakan nilai non-null apa pun untuk memicu penayangan teks kueri menggunakan parameter selectionArgs, lalu mengabaikan parameter selection).

android:searchSuggestIntentAction

String. Tindakan intent default yang akan digunakan saat pengguna mengetuk saran penelusuran kustom—seperti "android.intent.action.VIEW". Jika nilai ini tidak diganti oleh saran yang dipilih menggunakan kolom SUGGEST_COLUMN_INTENT_ACTION, nilai tersebut akan ditempatkan di kolom tindakan Intent saat pengguna mengetuk saran.

android:searchSuggestIntentData

String. Data intent default yang akan digunakan saat pengguna mengetuk saran penelusuran kustom. Jika tidak diganti oleh saran yang dipilih—melalui kolom SUGGEST_COLUMN_INTENT_DATA—nilai ini akan ditempatkan di kolom data Intent saat pengguna mengetuk saran.

android:searchSuggestThreshold

Bilangan bulat. Jumlah minimum karakter yang diperlukan untuk memicu pencarian saran. Hal ini hanya menjamin bahwa sistem tidak akan mengkueri penyedia konten Anda untuk sesuatu yang lebih pendek daripada ambang batas ini. Nilai defaultnya adalah 0.

Untuk mengetahui informasi selengkapnya tentang atribut saran penelusuran di atas, lihat dokumentasi tentang menambahkan saran penelusuran kustom dan menambahkan saran kustom.

Atribut Kotak Penelusuran Kilat

Agar saran penelusuran kustom Anda tersedia di Kotak Penelusuran Kilat, Anda memerlukan beberapa atribut <searchable> berikut:

android:includeInGlobalSearch

Boolean. (Wajib, untuk memberikan saran penelusuran di Kotak Penelusuran Kilat.) Tetapkan ke "true" jika Anda ingin saran disertakan dalam Kotak Penelusuran Kilat yang dapat diakses secara global. Pengguna tetap harus mengaktifkan aplikasi Anda sebagai item yang dapat ditelusuri di setelan penelusuran sistem agar saran Anda dapat muncul di Kotak Penelusuran Kilat.

android:searchSettingsDescription

Resource string. Memberikan deskripsi singkat tentang saran penelusuran yang Anda berikan ke Kotak Penelusuran Kilat, yang ditampilkan dalam entri item yang dapat ditelusuri untuk aplikasi Anda. Deskripsi Anda harus menjelaskan secara singkat konten yang dapat ditelusuri. Misalnya, "Artis, album, dan lagu" untuk aplikasi musik, atau "Catatan tersimpan" untuk aplikasi notepad.

android:queryAfterZeroResults

Boolean. Tetapkan ke "true" jika Anda ingin penyedia konten Anda dipanggil untuk superset kueri yang sebelumnya menampilkan hasil nol. Misalnya, jika penyedia konten Anda menampilkan hasil nol untuk "bo", penyedia konten tersebut harus dikueri ulang untuk "bob". Jika ditetapkan ke "false", superset akan diabaikan selama satu sesi—"bob" tidak akan memanggil kueri ulang. Pengabaian ini hanya bertahan selama dialog penelusuran aktif atau selama aktivitas aktif saat menggunakan widget penelusuran. Saat dialog atau aktivitas penelusuran dibuka kembali, "bo" akan mengkueri penyedia konten Anda lagi. Nilai defaultnya adalah false.

Atribut penelusuran suara

Untuk mengaktifkan penelusuran suara, Anda memerlukan beberapa atribut <searchable> berikut:

android:voiceSearchMode

Kata kunci. (Wajib, untuk memberikan kapabilitas penelusuran suara.) Mengaktifkan penelusuran suara, dengan mode khusus untuk penelusuran suara. Penelusuran suara mungkin tidak disediakan oleh perangkat, sehingga tanda ini tidak berpengaruh. Nilai mode berikut diterima:

Nilai	Deskripsi
"showVoiceSearchButton"	Tampilkan tombol penelusuran suara, jika penelusuran suara tersedia di perangkat. Jika ditetapkan, maka "launchWebSearch" atau "launchRecognizer" juga harus ditetapkan, dipisahkan dengan karakter pipa (|).
"launchWebSearch"	Tombol penelusuran suara mengarahkan pengguna langsung ke aktivitas penelusuran web dengan suara bawaan. Sebagian besar aplikasi tidak menggunakan tanda ini, karena tanda ini menjauhkan pengguna dari aktivitas tempat penelusuran dimulai.
"launchRecognizer"	Tombol penelusuran suara mengarahkan pengguna langsung ke aktivitas perekaman suara bawaan. Aktivitas ini meminta pengguna mengucapkan kueri penelusuran, mentranskripsi teks yang diucapkan, dan meneruskan teks kueri yang dihasilkan ke aktivitas penelusuran, sama seperti jika pengguna mengetikkannya ke UI penelusuran dan mengetuk tombol Telusuri.

android:voiceLanguageModel

Kata kunci. Model bahasa yang harus digunakan oleh sistem pengenalan suara. Nilai berikut diterima:

Nilai	Deskripsi
"free_form"	Gunakan pengenalan ucapan bentuk bebas untuk mendiktekan kueri. Kapabilitas ini terutama dioptimalkan untuk bahasa Inggris. Ini adalah defaultnya.
"web_search"	Gunakan pengenalan istilah penelusuran web untuk frasa menyerupai penelusuran yang lebih singkat. Atribut ini tersedia dalam lebih banyak bahasa dibandingkan dengan "free_form".

Lihat EXTRA_LANGUAGE_MODEL untuk informasi selengkapnya.

android:voicePromptText

Resource string. Pesan tambahan yang akan ditampilkan dalam dialog input suara.

android:voiceLanguage

String. Bahasa lisan yang diharapkan, dinyatakan sebagai nilai string dari konstanta dalam Locale, seperti "de" untuk bahasa Jerman atau "fr" untuk bahasa Prancis. Diperlukan hanya jika nilai ini berbeda dengan nilai Locale.getDefault() saat ini.

android:voiceMaxResults

Bilangan bulat. Menetapkan jumlah maksimum hasil yang akan ditampilkan, termasuk hasil "terbaik", yang selalu diberikan sebagai kueri utama intent ACTION_SEARCH. Harus 1 atau lebih besar. Gunakan EXTRA_RESULTS untuk mendapatkan hasil dari intent. Jika tidak disediakan, recognizer akan memilih banyaknya hasil yang ditampilkan.

<actionkey>

Menentukan tombol perangkat dan perilaku tindakan penelusuran. Tindakan penelusuran memberikan perilaku khusus saat tombol di perangkat diketuk, yang didasarkan pada kueri saat ini atau saran yang difokus. Misalnya, aplikasi Kontak memberikan tindakan penelusuran untuk memulai panggilan telepon ke saran kontak yang sedang difokus saat tombol PANGGIL diketuk.

Tidak semua tombol tindakan tersedia di setiap perangkat, dan tidak semua tombol dapat diganti dengan cara ini. Misalnya, tombol "Utama" tidak dapat diganti dan harus selalu kembali ke layar utama. Selain itu, pastikan untuk tidak menetapkan tombol tindakan ke tombol yang diperlukan untuk mengetikkan kueri penelusuran. Dengan demikian, tombol tindakan yang tersedia dan masuk akal hanyalah tombol panggil dan tombol menu.

Anda harus menentukan android:keycode untuk menentukan tombol ini dan setidaknya salah satu dari tiga atribut lainnya untuk menentukan tindakan penelusuran.

Atribut:

android:keycode

String. (Wajib.) Kode tombol dari KeyEvent yang menunjukkan tombol tindakan yang ingin Anda respons—misalnya, "KEYCODE_CALL". Pesan ini ditambahkan ke intent ACTION_SEARCH yang diteruskan ke aktivitas penelusuran Anda. Untuk memeriksa kode tombol, gunakan getIntExtra(SearchManager.ACTION_KEY). Tidak semua tombol didukung untuk tindakan penelusuran, karena banyak di antaranya digunakan untuk mengetik, navigasi, atau fungsi sistem.

android:queryActionMsg

String. Pesan tindakan yang akan dikirim jika tombol tindakan ditekan selagi pengguna memasukkan teks kueri. Pesan ini ditambahkan ke intent ACTION_SEARCH yang diteruskan oleh sistem ke aktivitas penelusuran Anda. Untuk memeriksa string ini, gunakan getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

String. Pesan tindakan yang akan dikirim jika tombol tindakan ditekan selagi saran sedang difokus. Pesan ini ditambahkan ke intent yang diteruskan oleh sistem ke aktivitas penelusuran Anda—menggunakan tindakan yang Anda tentukan untuk saran tersebut. Untuk memeriksa string, gunakan getStringExtra(SearchManager.ACTION_MSG). Atribut ini hanya boleh digunakan jika semua saran Anda mendukung tombol tindakan ini. Jika tidak semua saran dapat menangani tombol tindakan yang sama, Anda harus menggunakan atribut android:suggestActionMsgColumn berikut sebagai gantinya.

android:suggestActionMsgColumn

String. Nama kolom di penyedia konten Anda yang menentukan pesan tindakan untuk tombol tindakan ini, yang akan dikirim jika pengguna menekan tombol tindakan selagi saran sedang difokus. Atribut ini memungkinkan Anda mengontrol tombol tindakan di tingkat saran karena, alih-alih menggunakan atribut android:suggestActionMsg untuk menentukan pesan tindakan untuk semua saran, setiap entri di penyedia konten Anda menyediakan pesan tindakannya sendiri-sendiri.

Pertama-tama, Anda harus menentukan sebuah kolom di penyedia konten Anda agar setiap saran dapat menyediakan pesan tindakan, lalu menamai kolom tersebut dalam atribut ini. Sistem akan melihat kursor saran Anda, menggunakan string yang diberikan di sini untuk memilih kolom pesan tindakan Anda, lalu memilih string pesan tindakan dari kursor. String tersebut akan ditambahkan ke intent yang diteruskan oleh sistem ke aktivitas penelusuran Anda, menggunakan tindakan yang Anda tentukan untuk saran. Untuk memeriksa string ini, gunakan getStringExtra(SearchManager.ACTION_MSG). Jika data tidak ada untuk saran yang dipilih, tombol tindakan akan diabaikan.

contoh:

File XML yang disimpan di res/xml/searchable.xml:

<?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:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>