Untuk mengimplementasikan penelusuran dengan bantuan dari sistem Android—yaitu, untuk mengirimkan kueri
penelusuran ke 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 mengimplementasikan fitur penelusuran untuk aplikasi, lihat
Membuat antarmuka penelusuran.
lokasi file:
res/xml/filename.xml
Android menggunakan nama file sebagai ID resource.
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
elemen manifes
<activity>
atau
<application>
Anda. Label ini hanya dapat dilihat oleh pengguna saat Anda menetapkan
android:includeInGlobalSearch ke "true". Dalam hal ini, label ini digunakan
untuk mengidentifikasi aplikasi Anda sebagai item yang dapat ditelusuri di setelan penelusuran sistem.
android:hint
Resource string. (Direkomendasikan.) Teks yang akan ditampilkan di kolom teks penelusuran
ketika tidak ada teks yang dimasukkan. Hasil ini memberikan petunjuk kepada pengguna tentang konten apa yang dapat ditelusuri. Agar konsisten dengan aplikasi Android lainnya, format string untuk android:hint sebagai "Telusuri <content-or-product>". 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 perlu 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 bquery. Ini hanya boleh digunakan jika nilai dalam
SUGGEST_COLUMN_INTENT_DATA cocok untuk pemeriksaan dan pengeditan pengguna,
seperti URI HTTP.
Resource string. Teks yang akan ditampilkan di tombol yang menjalankan penelusuran. Secara
default, tombol tersebut menampilkan ikon penelusuran (kaca pembesar), yang ideal untuk
internasionalisasi. Jadi, jangan gunakan atribut ini untuk mengubah tombol kecuali jika perilakunya bukan penelusuran, seperti permintaan URL di browser web.
android:inputType
Kata kunci. Menentukan jenis metode input yang akan digunakan, seperti jenis keyboard
virtual. Untuk sebagian besar penelusuran, yang mengharapkan teks bentuk bebas, Anda tidak memerlukan atribut ini.
Lihat inputType untuk 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
keyboard virtual. Lihat imeOptions
untuk daftar nilai yang sesuai untuk atribut ini.
Atribut saran penelusuran
Jika Anda menentukan penyedia konten untuk menghasilkan saran penelusuran, Anda harus menentukan
atribut tambahan yang mengonfigurasi komunikasi dengan penyedia konten. 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 diberikan 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. Tindakan ini hanya diperlukan jika Anda memiliki satu penyedia konten yang memberikan jenis saran yang berbeda—seperti untuk jenis data yang berbeda—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 untuk memicu pengiriman 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 ini akan ditempatkan dalam 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 dalam kolom data
Intent saat pengguna mengetuk
saran.
android:searchSuggestThreshold
Bilangan bulat. Jumlah karakter minimum yang diperlukan untuk memicu pencarian saran. Cara ini hanya menjamin bahwa sistem tidak akan mengkueri penyedia konten Anda untuk sesuatu yang lebih pendek dari nilai minimum tersebut. Nilai defaultnya adalah 0.
Agar saran penelusuran kustom Anda tersedia di Kotak Penelusuran Cepat, Anda memerlukan beberapa atribut <searchable> berikut:
android:includeInGlobalSearch
Boolean. (Wajib untuk memberikan saran penelusuran di Kotak Penelusuran Cepat.) Tetapkan ke "true" jika Anda ingin saran disertakan dalam Kotak Penelusuran Cepat yang dapat diakses secara global. Pengguna tetap harus
mengaktifkan aplikasi Anda sebagai item penelusuran di setelan penelusuran sistem sebelum
saran Anda muncul di Kotak Penelusuran Cepat.
android:searchSettingsDescription
Resource string. Memberikan deskripsi singkat tentang saran penelusuran yang Anda berikan ke Kotak Penelusuran Cepat, yang ditampilkan dalam entri item penelusuran untuk aplikasi Anda. Deskripsi 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 dipanggil untuk superset kueri yang sebelumnya menampilkan hasil nol. Misalnya, jika
penyedia konten Anda menampilkan hasil nol untuk "bo", penyedia konten harus menggunakan kueri "bob". Jika
ditetapkan ke "false", superset akan diabaikan untuk satu sesi—"bob"
tidak memanggil kueri ulang. Periode ini hanya berlaku selama dialog penelusuran atau selama
aktivitas 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, "launchWebSearch" atau "launchRecognizer" juga harus ditetapkan, yang dipisahkan dengan karakter pipa (|).
"launchWebSearch"
Tombol penelusuran suara mengarahkan pengguna langsung
ke aktivitas penelusuran web dengan suara. Sebagian besar aplikasi tidak menggunakan flag ini, karena
menjauhkan pengguna dari aktivitas tempat penelusuran dipanggil.
"launchRecognizer"
Tombol penelusuran suara mengarahkan pengguna langsung ke aktivitas perekaman suara bawaan. Aktivitas ini
meminta pengguna untuk mengucapkannya, mentranskripsikan teks yang diucapkan, dan meneruskan
teks kueri yang dihasilkan ke aktivitas penelusuran, seolah-olah pengguna mengetiknya ke dalam
UI penelusuran dan mengetuk tombol penelusuran.
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. Fitur ini dioptimalkan terutama untuk bahasa Inggris. Ini adalah defaultnya.
"web_search"
Gunakan pengenalan istilah penelusuran web untuk frasa menyerupai penelusuran yang lebih singkat. Fitur ini
tersedia dalam lebih banyak bahasa daripada "free_form".
Resource string. Pesan tambahan yang akan ditampilkan dalam dialog input suara.
android:voiceLanguage
String. Bahasa lisan yang diharapkan, dinyatakan sebagai nilai string
konstan dalam Locale, seperti
"de" untuk bahasa Jerman atau "fr" untuk bahasa Prancis. Hal ini diperlukan hanya jika nilai tersebut berbeda
dari nilai Locale.getDefault() saat ini.
android:voiceMaxResults
Bilangan bulat. Menetapkan jumlah hasil maksimum 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 dengan mengetuk tombol pada perangkat, berdasarkan kueri saat ini atau saran yang
difokuskan. Misalnya, aplikasi Kontak menyediakan tindakan penelusuran untuk memulai panggilan telepon ke saran kontak yang saat ini difokuskan saat tombol PANGGIL diketuk.
Tidak semua tombol tindakan tersedia di setiap perangkat, dan tidak semua tombol dapat diganti dengan
cara ini. Misalnya, tombol "Beranda" tidak dapat diganti dan harus selalu kembali ke layar
utama. Selain itu, pastikan untuk tidak menetapkan tombol tindakan ke tombol yang diperlukan untuk mengetik kueri
penelusuran. Hal ini akan membatasi tombol tindakan yang tersedia dan wajar untuk tombol panggil dan tombol
menu.
Anda harus menentukan android:keycode untuk menentukan kunci dan setidaknya satu dari
tiga atribut lainnya untuk menentukan tindakan penelusuran.
Atribut:
android:keycode
String. (Wajib.) Kode tombol dari
KeyEvent yang mewakili
tombol tindakan yang ingin Anda respons—misalnya, "KEYCODE_CALL". 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 tombol tersebut digunakan untuk mengetik,
navigasi, atau fungsi sistem.
android:queryActionMsg
String. Pesan tindakan yang akan dikirim jika tombol tindakan ditekan selagi
pengguna memasukkan teks kueri. Nilai 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 dalam fokus. Kunci ini ditambahkan ke intent yang diteruskan oleh sistem ke aktivitas penelusuran Anda—menggunakan tindakan yang Anda tentukan untuk saran tersebut. Untuk memeriksa string ini, gunakan getStringExtra(SearchManager.ACTION_MSG).
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.
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 saat saran sedang difokus. Atribut ini memungkinkan Anda mengontrol tombol tindakan berdasarkan saran, karena, alih-alih menggunakan atribut android:suggestActionMsg untuk menentukan pesan tindakan untuk semua saran, setiap entri dalam penyedia konten Anda menyediakan pesan tindakannya sendiri.
Pertama, Anda harus menentukan kolom di penyedia konten untuk setiap saran guna memberikan
pesan tindakan, lalu memberikan nama kolom tersebut dalam atribut ini. Sistem
melihat kursor saran Anda, menggunakan string yang disediakan di sini untuk memilih kolom
pesan tindakan, lalu memilih string pesan tindakan dari kursor. String tersebut 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.
Konten dan contoh kode di halaman ini tunduk kepada lisensi yang dijelaskan dalam Lisensi Konten. Java dan OpenJDK adalah merek dagang atau merek dagang terdaftar dari Oracle dan/atau afiliasinya.