Untuk menerapkan penelusuran dengan bantuan dari sistem Android, yaitu menayangkan hasil penelusuran kueri ke aktivitas dan memberikan saran penelusuran—aplikasi Anda harus menyediakan layanan konfigurasi dalam bentuk file XML.
Halaman ini menjelaskan file konfigurasi penelusuran dari segi sintaks dan penggunaannya. Untuk selengkapnya informasi tentang cara mengimplementasikan fitur penelusuran untuk aplikasi Anda, lihat Buat antarmuka penelusuran.
- lokasi file:
- 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. Harus sama dengan
nama yang diterapkan ke atribut
android:label
<activity>
atau<application>
manifes. Label ini hanya terlihat oleh pengguna saat Anda menetapkanandroid:includeInGlobalSearch
menjadi"true"
, dalam hal ini label ini digunakan untuk mengidentifikasi aplikasi Anda sebagai item yang dapat ditelusuri dalam setelan penelusuran sistem. android:hint
- Resource string. (Direkomendasikan.) Teks yang akan ditampilkan
di {i>field<i} teks pencarian ketika
tidak ada teks yang dimasukkan. Memberikan petunjuk kepada pengguna tentang konten apa yang dapat ditelusuri. Untuk konsistensi
dengan aplikasi Android lain, format string untuk
android:hint
sebagai "Penelusuran <content-or-product>". Misalnya, "Telusuri lagu dan artis" atau "Telusuri YouTube". android:searchMode
- Kata kunci. Menetapkan mode tambahan yang mengontrol presentasi penelusuran. Tersedia
menentukan cara teks kueri harus ditulis ulang saat saran kustom menerima
fokus. Nilai mode berikut diterima:
Nilai Deskripsi "queryRewriteFromData"
Gunakan nilai dari SUGGEST_COLUMN_INTENT_DATA
untuk menulis ulang teks kueri. Ini hanya boleh digunakan bila nilai-nilai diSUGGEST_COLUMN_INTENT_DATA
cocok untuk pemeriksaan dan pengeditan pengguna, seperti URI HTTP."queryRewriteFromText"
Gunakan nilai dari SUGGEST_COLUMN_TEXT_1
kolom untuk menulis ulang teks kueri.Untuk informasi selengkapnya, lihat dokumentasi tentang menulis ulang teks kueri di Tambahkan saran penelusuran kustom.
android:searchButtonText
- Resource string. Teks yang akan ditampilkan di tombol yang menjalankan penelusuran. Menurut secara {i>default<i}, tombolnya menunjukkan ikon pencarian (kaca pembesar), yang ideal untuk internasionalisasi. Jadi, jangan gunakan atribut ini untuk mengubah tombol kecuali perilakunya sesuatu selain penelusuran, seperti permintaan URL di {i>browser<i} web.
android:inputType
- Kata kunci. Mendefinisikan jenis metode input yang akan digunakan, seperti jenis metode
{i>keyboard<i}. 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, di
teks bentuk bebas yang diharapkan, Anda tidak memerlukan atribut ini. IME default-nya adalah
actionSearch
, yang menyediakan fitur "penelusuran" alih-alih menggunakan enter, keyboard virtual. LihatimeOptions
untuk daftar nilai yang cocok untuk atribut ini.
Atribut saran penelusuran
Jika Anda mendefinisikan penyedia konten untuk menghasilkan saran penelusuran, Anda harus mendefinisikan atribut tambahan yang mengkonfigurasi komunikasi dengan penyedia konten. Saat memberikan informasi penelusuran yang disarankan, Anda memerlukan beberapa atribut
<searchable>
berikut:
android:searchSuggestAuthority
- String. (Wajib, untuk memberikan saran penelusuran.) Nilai ini harus cocok dengan
string otoritas yang disediakan dalam
android:authorities
dari elemen<provider>
manifes Android. android:searchSuggestPath
- String. Jalur ini digunakan sebagai bagian dari saran
kueri
Uri
, setelah awalan dan {i>authority<i} dan sebelum jalur saran standar. Tindakan ini hanya diperlukan jika Anda memiliki penyedia konten tunggal yang memberikan berbagai jenis saran—seperti untuk tipe data — dan Anda memerlukan cara untuk membedakan kueri saran saat menerima mereka. android:searchSuggestSelection
- String. Nilai ini diteruskan ke
fungsi kueri sebagai parameter
selection
. Biasanya ini adalah klausa WHERE untuk {i>database<i} 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 {i>non-null<i} untuk memicu pengiriman teks kueri menggunakan parameterselectionArgs
, lalu abaikan parameterselection
). 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 menggunakanSUGGEST_COLUMN_INTENT_ACTION
, nilai ditempatkan dalam bidang tindakan dariIntent
saat pengguna mengetuk atau memberikan saran. android:searchSuggestIntentData
- String. Data intent default yang akan digunakan saat pengguna
mengetuk saran penelusuran kustom.
Jika tidak diganti oleh saran yang dipilih—melalui
SUGGEST_COLUMN_INTENT_DATA
—nilai ini ditempatkan dalam bidang dataIntent
saat pengguna mengetuk atau memberikan saran. android:searchSuggestThreshold
- Bilangan bulat. Jumlah karakter minimum yang diperlukan untuk memicu pencarian saran. Ini hanya menjamin bahwa sistem tidak meminta informasi Anda penyedia konten untuk apa pun yang lebih pendek dari ambang batas. Nilai defaultnya adalah 0.
Untuk informasi selengkapnya tentang atribut di atas untuk saran penelusuran, lihat dokumentasi untuk menambahkan saran penelusuran kustom dan menambahkan saran kustom.
Atribut Kotak Penelusuran Kilat
Agar saran penelusuran khusus 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 di seluruh dunia. Pengguna harus masih mengaktifkan aplikasi Anda sebagai item yang dapat ditelusuri dalam setelan penelusuran sistem sebelum saran Anda ditampilkan di Kotak Penelusuran Cepat. android:searchSettingsDescription
- Resource string. Memberikan deskripsi singkat tentang saran penelusuran yang yang Anda berikan ke Kotak Penelusuran Cepat, yang ditampilkan di entri item yang dapat ditelusuri untuk aplikasi. Deskripsi Anda harus menjelaskan secara singkat konten yang dapat ditelusuri. Sebagai 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 mengembalikan hasil nol. Misalnya, jika penyedia konten Anda menampilkan nol hasil untuk "bo", maka harus dikueri untuk "bob". Jika disetel ke"false"
, superset diabaikan untuk satu sesi—"bob" tidak memanggil kueri ulang. Ini hanya berlaku selama dialog penelusuran tersedia atau aktivitas saat menggunakan widget penelusuran. Saat aktivitas atau dialog penelusuran dibuka kembali, "bo" 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 suara bawaan. Kebanyakan aplikasi tidak menggunakan penanda ini, karena pengguna akan diberhentikan dari aktivitas tempat penelusuran dipanggil. "launchRecognizer"
Tombol penelusuran suara mengambil pengguna secara langsung ke aktivitas perekaman suara bawaan. Aktivitas ini meminta pengguna untuk berbicara, mentranskripsikan teks lisan, dan meneruskan teks yang teks kueri ke aktivitas yang dapat ditelusuri, sama seperti jika 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. Fungsi ini terutama dioptimalkan untuk bahasa Inggris. Ini adalah defaultnya. "web_search"
Gunakan pengenalan istilah penelusuran web untuk frasa menyerupai penelusuran yang lebih singkat. Ini adalah tersedia dalam lebih banyak bahasa dari "free_form"
.Lihat
EXTRA_LANGUAGE_MODEL
untuk melihat selengkapnya tidak akurat atau tidak sesuai. android:voicePromptText
- Resource string. Pesan tambahan yang akan ditampilkan dalam dialog input suara.
android:voiceLanguage
- String. Bahasa lisan yang diharapkan, dinyatakan sebagai nilai string
konstanta di
Locale
, seperti"de"
untuk bahasa Jerman atau"fr"
untuk Prancis. Ini hanya diperlukan jika berbeda dari nilaiLocale.getDefault()
saat ini. android:voiceMaxResults
- Bilangan bulat. Menetapkan jumlah maksimum hasil yang akan ditampilkan,
termasuk yang "terbaik" , yang selalu disediakan sebagai
ACTION_SEARCH
kueri utama intent. Harus 1 atau lebih besar. GunakanEXTRA_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 ketika tombol diketuk pada perangkat, berdasarkan kueri saat ini atau fokus
saran. Misalnya, aplikasi Kontak menyediakan tindakan penelusuran untuk memulai telepon
panggilan ke saran kontak yang saat ini difokuskan bila tombol PANGGILAN diketuk.
Tidak semua tombol tindakan tersedia di setiap perangkat, dan tidak semua tombol dapat diganti di perangkat ini sebelumnya. Misalnya, "Rumah" kunci tidak dapat diganti dan harus selalu kembali ke beranda layar. Juga, pastikan untuk tidak menetapkan tombol tindakan untuk tombol yang diperlukan guna mengetik penelusuran kueri. Tindakan ini membatasi tombol tindakan yang tersedia dan wajar untuk tombol telepon dan menu tombol.
Anda harus menentukan
android:keycode
untuk menentukan kunci dan setidaknya salah satu tiga atribut lainnya untuk menentukan tindakan penelusuran.Atribut:
android:keycode
- String. (Wajib.) Kode kunci dari
KeyEvent
yang mewakili tombol tindakan yang ingin Anda respons—misalnya,"KEYCODE_CALL"
. Ini ditambahkan keACTION_SEARCH
yang diteruskan ke aktivitas penelusuran Anda. Untuk memeriksa kode tombol, gunakangetIntExtra(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 selama
pengguna memasukkan teks kueri. Ini ditambahkan ke
ACTION_SEARCH
yang diteruskan sistem ke aktivitas penelusuran Anda. Untuk memeriksa {i>string<i}, gunakangetStringExtra(SearchManager.ACTION_MSG)
. android:suggestActionMsg
- String. Pesan tindakan yang akan dikirim jika tombol tindakan ditekan selama
saran menjadi fokus. Ini ditambahkan ke intent yang diteruskan sistem ke
aktivitas yang dapat ditelusuri—menggunakan tindakan yang Anda tetapkan untuk saran. Untuk memeriksa
{i>string<i}, gunakan
getStringExtra(SearchManager.ACTION_MSG)
. Tombol ini hanya boleh digunakan jika semua saran Anda mendukung tombol tindakan ini. Jika tidak semua saran dapat menangani tombol tindakan yang sama, maka Anda harus menggunakan Atributandroid:suggestActionMsgColumn
. android:suggestActionMsgColumn
- String. Nama kolom di penyedia konten Anda yang mendefinisikan
pesan tindakan untuk tombol tindakan ini, yang akan dikirim jika pengguna menekan tombol tindakan
saat ada saran yang sedang difokuskan. Atribut ini memungkinkan Anda mengontrol tombol tindakan pada
saran demi saran, karena alih-alih menggunakan
Atribut
android:suggestActionMsg
untuk menentukan pesan tindakan untuk semua saran, setiap entri di penyedia konten akan memberikan pesan tindakannya sendiri.Pertama, Anda harus menentukan kolom di penyedia konten untuk setiap saran yang diberikan pesan tindakan, kemudian berikan nama untuk kolom tersebut dalam atribut ini. Sistem melihat kursor saran Anda, menggunakan string yang disediakan di sini untuk memilih tindakan kolom pesan, lalu memilih string pesan tindakan dari kursor. {i>String<i} itu adalah ditambahkan ke intent yang diteruskan sistem ke aktivitas penelusuran Anda, dengan menggunakan tindakan yang untuk saran. Untuk memeriksa {i>string<i}, 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>
res/xml/filename.xml