Konfigurasi penelusuran

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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:

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. Harus sama dengan nama yang diterapkan ke atribut android:label <activity> atau <application> manifes. Label ini hanya terlihat oleh pengguna saat Anda menetapkan android: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 di SUGGEST_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. Lihat imeOptions 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 parameter selectionArgs, lalu abaikan 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 SUGGEST_COLUMN_INTENT_ACTION , nilai ditempatkan dalam bidang tindakan dari Intent 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 data Intent 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 nilai Locale.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. 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 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 ke 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 selama pengguna memasukkan teks kueri. Ini ditambahkan ke ACTION_SEARCH yang diteruskan sistem ke aktivitas penelusuran Anda. Untuk memeriksa {i>string<i}, gunakan getStringExtra(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 Atribut android: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>