Halaman ini diterjemahkan oleh Cloud Translation API.

Konfigurasi penelusuran

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.

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 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.
`"queryRewriteFromText"`	Gunakan nilai dari kolom `SUGGEST_COLUMN_TEXT_1` untuk menulis ulang teks kueri.

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

android:searchButtonText

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.

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

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"`.

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 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.

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>

Konfigurasi penelusuran

Atribut saran penelusuran

Atribut Kotak Penelusuran Kilat

Atribut penelusuran suara