Agar dapat menerapkan peneIusuran dengan bantuan sistem Android (untuk mengirim 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 informasi selengkapnya tentang cara menerapkan fitur penelusuran untuk aplikasi Anda, mulailah dengan mempelajari panduan developer tentang Membuat Antarmuka Penelusuran.
- lokasi file:
res/xml/filename.xml
Android menggunakan nama file sebagai ID resource.- sintaks:
-
<?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 elemen manifes <application>. 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. Teksi ini memberikan petunjuk kepada pengguna tentang konten apa yang dapat ditelusuri. Agar konsisten dengan aplikasi Android lainnya, sebaiknya Anda memformat string untuk
android:hint sebagai "Telusuri <kontet-atau-produk>". Misalnya, "Telusuri lagu atau artis" atau "Telusuri YouTube".
android:searchMode- Kata kunci. Menetapkan mode tambahan yang mengontrol presentasi penelusuran.
Mode yang tersedia saat ini menentukan bagaimana teks kueri harus ditulis ulang saat saran kustom menerima fokus. Nilai mode berikut diterima:
| Nilai | Deskripsi |
|---|
"queryRewriteFromText" |
Gunakan nilai dari kolom SUGGEST_COLUMN_TEXT_1 untuk menulis ulang teks kueri. |
"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, biasanya URI HTTP. |
Untuk informasi selengkapnya, lihat diskusi tentang menulis ulang teks kueri dalam Menambahkan Saran 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, sehingga Anda tidak boleh menggunakan atribut ini untuk mengubah tombol kecuali jika perilakunya berbeda dengan penelusuran (misalnya permintaan URL di browser web).
android:inputType- Kata kunci. Menentukan jenis metode input (misalnya jenis soft keyboard) yang akan digunakan. 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" (menyediakan tombol "Telusuri", bukan "Enter" dalam soft keyboard). Lihat
imeOptions untuk daftar nilai yang sesuai untuk atribut ini.
Atribut saran penelusuran
Jika Anda telah 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, tetapi 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 tanda tanya tunggal, yang merupakan placeholder untuk string kueri sebenarnya yang telah diketik oleh pengguna (misalnya "query=?"). Namun, Anda juga dapat menggunakan nilai selain null untuk memicu pengiriman teks kueri melalui parameter selectionArgs (lalu mengabaikan parameter selection).
android:searchSuggestIntentAction- String. Tindakan intent default yang akan digunakan saat pengguna mengklik saran penelusuran kustom (misalnya
"android.intent.action.VIEW"). Jika tidak diganti oleh saran yang dipilih (melalui kolom SUGGEST_COLUMN_INTENT_ACTION), nilai ini akan ditempatkan dalam kolom tindakan Intent saat pengguna mengklik sebuah saran.
android:searchSuggestIntentData- String. Data intent default yang akan digunakan saat pengguna mengklik 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 mengklik sebuah saran.
android:searchSuggestThreshold- Integer. Jumlah minimum karakter yang diperlukan untuk memicu pencarian saran. Hanya menjamin bahwa sistem tidak akan mengkueri penyedia konten Anda untuk sesuatu yang lebih pendek daripada ambang batas ini. Nilai defaultnya adalah 0.
Untuk informasi selengkapnya tentang atribut saran penelusuran di atas, lihat panduan untuk Menambahkan Saran Kueri Terbaru 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 penelusuran di setelan penelusuran sistem agar saran Anda dapat muncul di Kotak Penelusuran Kilat.
android:searchSettingsDescription- String. Memberikan deskripsi singkat tentang saran penelusuran yang Anda berikan ke Kotak Penelusuran Kilat, yang ditampilkan dalam entri item penelusuran 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 ingin penyedia konten Anda dipanggil untuk superset kueri yang sebelumnya menampilkan hasil nol. Misalnya, jika sebelumnya menampilkan hasil nol untuk "bo", penyedia konten Anda akan dikueri ulang untuk "bob". Jika ditetapkan ke "false", superset akan diabaikan selama satu sesi ("bob" tidak akan memanggil kueri ulang). Jika Anda menggunakan widget penelusuran, pengabaian ini hanya bertahan selama dialog atau aktivitas penelusuran aktif (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. Sebagian besar aplikasi tidak memerlukan tanda ini, yang 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 mengeklik 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 merupakan setelan defaultnya. |
"web_search" |
Gunakan pengenalan istilah penelusuran web untuk frasa menyerupai penelusuran yang lebih singkat. Atribut ini tersedia dalam lebih banyak bahasa dibandingkan dengan "bentuk_bebas". |
Lihat juga EXTRA_LANGUAGE_MODEL untuk informasi selengkapnya.
android:voicePromptText- String. Pesan tambahan yang akan ditampilkan dalam dialog masukan suara.
android:voiceLanguage- String. Bahasa lisan yang diharapkan, dinyatakan sebagai nilai string yang terdiri dari sebuah konstanta dalam
Locale (misalnya "de" untuk bahasa Jerman atau "fr" untuk bahasa Prancis). Diperlukan hanya jika nilai ini berbeda dengan nilai saat ini Locale.getDefault().
android:voiceMaxResults- Integer. Memaksakan 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 disentuh, 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 ditekan.
Tidak semua tombol tindakan tersedia di setiap perangkat, dan tidak semua tombol dapat diganti dengan cara ini. Misalnya, tombol "Utama" tidak dapat digunakan 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. Perhatikan juga bahwa tombol tindakan umumnya tidak dapat ditemukan, sehingga sebaiknya Anda tidak menyediakannya sebagai fitur pengguna inti.
Anda harus menetapkan android:keycode untuk menentukan tombol ini dan setidaknya salah satu dari tiga atribut lainnya agar dapat menentukan tindakan penelusuran.
atribut:
android:keycode- String. (Wajib.) Kode tombol dari
KeyEvent yang menunjukkan tombol tindakan yang ingin Anda respons (misalnya "KEYCODE_CALL"). Kode tombol ini ditambahkan ke intent ACTION_SEARCH yang diteruskan ke aktivitas penelusuran Anda. Untuk memeriksa kode tombol, gunakan getIntExtra(SearchManager.ACTION_KEY). Tidak semua tombol dapat digunakan 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 intent yang Anda tentukan untuk saran tersebut). Untuk memeriksa string ini, gunakan
getStringExtra(SearchManager.ACTION_MSG). Sebaiknya hanya gunakan atribut ini jika semua saran Anda mendukung tombol tindakan ini. Jika tidak semua saran dapat menangani tombol tindakan yang sama, gunakan 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 Cursor. 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>
