Menambahkan saran penelusuran khusus

Saat menggunakan dialog penelusuran atau widget penelusuran Android, Anda dapat memberikan saran penelusuran kustom yang dibuat dari data di aplikasi Anda. Misalnya, jika aplikasi Anda berupa kamus, Anda bisa menyarankan kata-kata dari kamus yang cocokkan teks yang dimasukkan di kolom penelusuran sebelum pengguna selesai memasukkan kueri mereka. Saran ini berharga karena dapat secara efektif memprediksi apa yang diinginkan pengguna dan memberikan akses instan ke sana. Gambar 1 menunjukkan contoh dialog penelusuran dengan saran kustom.

Setelah memberikan saran khusus, Anda juga dapat menyediakannya untuk Kotak Penelusuran Cepat seluruh sistem, yang menyediakan akses ke konten Anda dari luar .

Sebelum menambahkan saran khusus, terapkan dialog penelusuran Android atau widget penelusuran untuk penelusuran dalam aplikasi Anda. Lihat Membuat antarmuka penelusuran dan Konten penyedia layanan.

Dasar-dasar

Gambar 1. Screenshot dialog penelusuran dengan saran penelusuran kustom.

Saat pengguna memilih saran kustom, sistem akan mengirimkan Intent ke aktivitas yang dapat ditelusuri. Tidak seperti kueri penelusuran biasa yang mengirimkan intent dengan ACTION_SEARCH Anda bisa mendefinisikan saran kustom untuk menggunakan ACTION_VIEW—atau tindakan intent lainnya—dan juga mencakup data yang relevan dengan saran yang dipilih. Dalam contoh kamus, ketika pengguna memilih saran, aplikasi dapat langsung membuka definisi untuk kata tersebut, sebagai gantinya dalam menelusuri kamus untuk menemukan kecocokan.

Untuk memberikan saran kustom, lakukan langkah-langkah berikut:

  • Mengimplementasikan aktivitas penelusuran dasar, seperti yang dijelaskan dalam Buat antarmuka penelusuran.
  • Mengubah konfigurasi penelusuran dengan informasi tentang konten yang menyediakan saran kustom.
  • Membuat tabel, seperti di SQLiteDatabase, untuk mendapatkan saran Anda dan format tabel dengan kolom yang diperlukan.
  • Membuat konten yang memiliki akses ke tabel saran Anda dan mendeklarasikan di manifes Anda.
  • Deklarasikan jenis Intent yang akan dikirim saat pengguna memilih termasuk tindakan kustom dan data kustom.

Sama seperti sistem Android menampilkan dialog penelusuran, sistem juga menampilkan saran penelusuran. Anda memerlukan penyedia konten yang memungkinkan sistem mengambil saran Anda. {i>Read<i} Penyedia konten untuk mempelajari cara membuat penyedia konten.

Ketika sistem mengidentifikasi bahwa aktivitas Anda dapat ditelusuri dan menyediakan saran penelusuran, prosedur berikut dilakukan saat pengguna memasukkan kueri:

  1. Sistem mengambil teks kueri penelusuran—artinya, apa pun yang dimasukkan sejauh ini—dan melakukan kueri ke penyedia konten Anda yang mengelola ejaan atau mendapatkan saran gaya.
  2. Penyedia konten akan mengembalikan Cursor yang mengarah ke semua saran yang relevan dengan kueri penelusuran teks.
  3. Sistem menampilkan daftar saran yang diberikan oleh Cursor.

Setelah saran kustom ditampilkan, hal berikut dapat terjadi:

  • Jika pengguna memasukkan huruf lain atau mengubah kueri dengan cara apa pun, langkah sebelumnya berulang dan daftar saran akan diperbarui.
  • Jika pengguna menjalankan penelusuran, saran akan diabaikan dan penelusuran dikirim ke aktivitas penelusuran Anda menggunakan ACTION_SEARCH.
  • Jika pengguna memilih saran, intent akan dikirim ke saran yang dapat ditelusuri aktivitas, membawa tindakan khusus dan data khusus sehingga aplikasi Anda dapat membuka konten yang disarankan.

Mengubah konfigurasi penelusuran

Guna menambahkan dukungan untuk saran kustom, tambahkan android:searchSuggestAuthority ke atribut <searchable> dalam file konfigurasi penelusuran Anda, seperti yang ditunjukkan dalam contoh berikut:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

Anda mungkin memerlukan atribut tambahan, bergantung pada jenis intent yang yang dilampirkan ke setiap saran dan cara memformat kueri ke konten penyedia layanan. Atribut opsional lainnya dibahas pada bagian berikut bagian.

Membuat penyedia konten

Untuk membuat penyedia konten untuk saran kustom, lihat dulu Penyedia konten untuk mempelajari cara membuat penyedia konten. Penyedia konten untuk kustom serupa dengan penyedia konten lainnya. Namun, untuk setiap saran yang Anda berikan, baris terkait dalam Cursor harus menyertakan kolom tertentu yang dipahami dan digunakan sistem untuk memformat ejaan atau mendapatkan saran gaya.

Saat pengguna memasukkan teks dalam dialog penelusuran atau widget penelusuran, mengkueri penyedia konten Anda untuk mendapatkan saran dengan memanggil query() setiap kali huruf dimasukkan. Dalam implementasi query(), penyedia konten Anda harus mencari data saran Anda dan mengembalikan Cursor yang menunjuk ke baris yang dianggap baik ejaan atau mendapatkan saran gaya.

Detail tentang pembuatan penyedia konten untuk saran kustom adalah kita bahas dalam dua bagian berikut:

Menangani kueri saran
Cara sistem mengirimkan permintaan ke penyedia konten dan cara menanganinya mereka.
Membuat tabel saran
Cara menentukan kolom yang diharapkan sistem dalam Cursor ditampilkan dengan setiap kueri.

Menangani kueri saran

Bila sistem meminta saran dari penyedia konten Anda, sistem akan memanggil metode query() penyedia konten Anda. Implementasikan metode ini untuk telusuri data saran Anda dan kembalikan Cursor yang mengarah ke saran yang Anda anggap relevan.

Berikut adalah ringkasan parameter yang diteruskan sistem ke Metode query(), dicantumkan secara berurutan:

  1. uri

    Selalu berupa konten Uri, diformat sebagai berikut ini: 

    content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

    Perilaku default-nya adalah sistem meneruskan URI ini dan menambahkan kueri teks ke dalamnya:

    content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

    Teks kueri di bagian akhir dikodekan menggunakan aturan pengkodean URI, jadi Anda mungkin perlu memecahkan kodenya sebelum melakukan penelusuran.

    Bagian optional.suggest.path hanya disertakan dalam URI jika Anda menetapkan jalur tersebut dalam file konfigurasi yang dapat ditelusuri dengan atribut android:searchSuggestPath. Hanya diperlukan jika Anda menggunakan penyedia konten yang sama untuk beberapa aktivitas yang dapat ditelusuri. Jika dalam kasus ini, bedakan sumber kueri saran.

  2. projection
    Selalu null.
  3. selection
    Nilai yang diberikan di android:searchSuggestSelection dari file konfigurasi yang dapat dicari, atau null jika Anda tidak deklarasikan atribut android:searchSuggestSelection. Tujuan Bagian berikutnya akan membahas hal ini lebih lanjut.
  4. selectionArgs
    Berisi kueri penelusuran sebagai elemen pertama dan satu-satunya pada array jika Anda mendeklarasikan atribut android:searchSuggestSelection pada konfigurasi yang dapat dicari. Jika Anda tidak mendeklarasikan android:searchSuggestSelection, parameter ini adalah null. Bagian berikut membahas hal ini lebih lanjut.
  5. sortOrder
    Selalu null.

Sistem dapat mengirimkan teks kueri penelusuran kepada Anda dalam dua cara. Cara defaultnya adalah bagi teks kueri yang akan disertakan sebagai jalur terakhir dari URI konten yang diteruskan parameter uri. Namun, jika Anda menyertakan nilai pilihan pada android:searchSuggestSelection konfigurasi penelusuran Anda maka teks kueri akan diteruskan sebagai elemen pertama Array string selectionArgs. Kedua opsi ini dijelaskan berikutnya.

Mendapatkan kueri dalam URI

Secara default, kueri ditambahkan sebagai segmen terakhir dari uri —objek Uri. Untuk mengambil teks kueri dalam kasus, gunakan getLastPathSegment(), seperti yang ditunjukkan dalam contoh berikut:

Kotlin

val query: String = uri.lastPathSegment.toLowerCase()

Java

String query = uri.getLastPathSegment().toLowerCase();

Ini akan menampilkan segmen terakhir dari Uri, yang merupakan kueri teks yang dimasukkan pengguna.

Mendapatkan kueri dalam argumen pemilihan

Alih-alih menggunakan URI, mungkin lebih masuk akal untuk Metode query() untuk menerima semua yang diperlukan dalam melakukan cari, dan Anda mungkin menginginkan selection dan selectionArgs untuk membawa nilai yang sesuai. Di sini kasus, tambahkan atribut android:searchSuggestSelection ke yang dapat ditelusuri dengan string pemilihan SQLite. Dalam pilihan sertakan tanda tanya (?) sebagai placeholder untuk string kueri penelusuran. Sistem memanggil query() dengan string pemilihan sebagai parameter selection dan kueri penelusuran sebagai elemen pertama dalam array selectionArgs.

Misalnya, berikut ini cara membuat Atribut android:searchSuggestSelection untuk membuat teks lengkap pernyataan pencarian:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

Dengan konfigurasi ini, metode query() Anda akan mengirimkan selection sebagai "word MATCH ?" dan selectionArgs sebagai kueri penelusuran. Ketika Anda meneruskannya ke SQLite query() sebagai argumen masing-masing, metode tersebut disintesis bersama-sama—artinya, tanda tanya diganti dengan teks kueri. Jika Anda menerima kueri saran dengan cara ini dan perlu menambahkan karakter pengganti ke kueri tambahkan atau tambahkan awalan ke parameter selectionArgs, karena nilai ini diapit dalam tanda kutip dan disisipkan di tempat tanda tanya.

Atribut lain dalam contoh sebelumnya adalah android:searchSuggestIntentAction, yang menentukan tindakan intent yang dikirim dengan setiap intent saat pengguna memilih saran. Hal ini didiskusikan lebih lanjut di bagian Mendeklarasikan intent untuk saran.

Membuat tabel saran

Saat Anda menampilkan saran ke sistem dengan Cursor, metode sistem mengharapkan kolom tertentu di setiap baris. Terlepas dari apakah Anda menyimpan data saran Anda dalam database SQLite di perangkat, atau database di web server, atau format lain di perangkat atau web, memformat saran sebagai baris dalam tabel dan menampilkan Cursor.

Sistem memahami beberapa kolom, tetapi hanya dua yang diperlukan:

_ID
ID baris unik dalam bentuk integer untuk setiap saran. Sistem mengharuskan ini untuk menyajikan saran di ListView.
SUGGEST_COLUMN_TEXT_1
String yang disajikan sebagai saran.

Kolom-kolom berikut bersifat opsional. Sebagian besar akan dibahas lebih lanjut dalam bagian berikut ini.

SUGGEST_COLUMN_TEXT_2
String. Jika Cursor Anda menyertakan kolom ini, semua saran yang diberikan dalam format dua baris. {i>String<i} dalam kolom ini ditampilkan sebagai baris teks kedua yang lebih kecil di bawah saran utama teks. Kolom ini boleh kosong atau null untuk menunjukkan tidak ada teks sekunder.
SUGGEST_COLUMN_ICON_1
Resource, konten, atau string URI file yang bersifat drawable. Jika Cursor menyertakan kolom ini, lalu semua saran akan diberikan dalam format ikon-plus-teks dengan ikon drawable di sisi kiri. Ini bisa nol atau nol untuk menunjukkan tidak ada ikon di baris ini.
SUGGEST_COLUMN_ICON_2
Resource, konten, atau string URI file yang bersifat drawable. Jika Cursor menyertakan kolom ini, lalu semua saran akan diberikan dalam format ikon-plus-teks dengan ikon di sisi kanan. Dapat berupa nol atau nol untuk mengindikasikan tidak adanya ikon di baris ini.
SUGGEST_COLUMN_INTENT_ACTION
String tindakan intent. Jika kolom ini ada dan berisi nilai pada baris tertentu, aksi yang didefinisikan di sini digunakan saat membuat intent. Jika elemen tersebut tidak disediakan, tindakan akan diambil dari Kolom android:searchSuggestIntentAction di kolom penelusuran konfigurasi Anda. Jika tindakan Anda sama untuk semua saran, tindakan tersebut lebih efisien untuk menentukan tindakan menggunakan android:searchSuggestIntentAction dan hapus kolom ini.
SUGGEST_COLUMN_INTENT_DATA
String URI data. Jika kolom ini ada dan berisi nilai yang diberikan , data ini digunakan saat membentuk maksud saran. Jika elemen tidak tersedia, data ini diambil dari Kolom android:searchSuggestIntentData di kolom penelusuran konfigurasi Anda. Jika tidak ada sumber yang diberikan, kolom data intent akan null. Jika data Anda sama untuk semua saran, atau dapat dijelaskan menggunakan bagian konstan dan ID tertentu, akan lebih efisien untuk menentukannya menggunakan android:searchSuggestIntentData dan menghilangkannya .
SUGGEST_COLUMN_INTENT_DATA_ID
String jalur URI. Jika kolom ini ada dan berisi nilai yang diberikan baris, lalu "/" dan nilai ini ditambahkan ke kolom data dalam intent tersebut. Hanya gunakan ini jika {i>field<i} data yang ditentukan oleh Atribut android:searchSuggestIntentData tidak dapat ditelusuri konfigurasi sudah diatur ke string dasar yang sesuai.
SUGGEST_COLUMN_INTENT_EXTRA_DATA
Data arbitrer. Jika kolom ini ada dan berisi sebuah nilai di baris tertentu, ini adalah data tambahan yang digunakan saat membentuk intent saran. Jika tidak diberikan, kolom data tambahan intent adalah null. Kolom ini memungkinkan memberikan data tambahan yang disertakan sebagai tambahan dalam intent EXTRA_DATA_KEY tombol.
SUGGEST_COLUMN_QUERY
Jika kolom ini ada dan elemen ini ada di baris tertentu, maka data yang digunakan saat membuat kueri saran, termasuk sebagai ekstra di kolom intent QUERY tombol. Atribut ini diperlukan jika tindakan saran adalah ACTION_SEARCH, tetapi opsional sebaliknya.
SUGGEST_COLUMN_SHORTCUT_ID
Hanya digunakan saat memberikan saran untuk Kotak Penelusuran Kilat. Kolom ini menunjukkan apakah saran penelusuran harus disimpan sebagai pintasan dan apakah harus divalidasi. Pintasan biasanya dibentuk ketika pengguna mengetuk saran dari Kotak Penelusuran Cepat. Jika tidak ada, hasilnya akan disimpan sebagai {i>shortcut<i} dan tidak pernah di-refresh. Jika ditetapkan ke SUGGEST_NEVER_MAKE_SHORTCUT, hasilnya tidak disimpan sebagai pintasan. Jika tidak, ID pintasan akan digunakan untuk periksa kembali untuk mendapatkan saran terbaru menggunakan SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
Hanya digunakan saat memberikan saran untuk Kotak Penelusuran Kilat. Kolom ini menetapkan bahwa indikator lingkaran berputar harus ditampilkan, bukan ikon dari SUGGEST_COLUMN_ICON_2 sementara pintasan saran ini adalah menyegarkan di Kotak Penelusuran Cepat.

Sebagian besar kolom ini dibahas lebih lanjut di bagian berikut.

Mendeklarasikan intent untuk saran

Bila pengguna memilih saran dari daftar yang muncul di bawah dialog atau widget penelusuran, sistem akan mengirimkan Intent kustom ke aktivitas yang dapat ditelusuri. Anda harus menentukan tindakan dan data untuk intent ini.

Mendeklarasikan tindakan intent

Tindakan intent yang paling umum untuk saran kustom adalah ACTION_VIEW, yang sesuai saat Anda ingin membuka sesuatu, seperti definisi kata, informasi kontak seseorang, atau halaman web. Namun, tindakan intent dapat berupa tindakan lain dan dapat berbeda untuk setiap tindakan saran.

Bergantung pada apakah Anda ingin semua saran menggunakan tindakan intent yang sama, Anda dapat menentukan tindakan dalam dua cara:

  • Gunakan atribut android:searchSuggestIntentAction file konfigurasi yang dapat ditelusuri guna menentukan tindakan untuk semua saran, yang ditunjukkan dalam contoh berikut: 
    <?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW" >
</searchable>
  • Gunakan kolom SUGGEST_COLUMN_INTENT_ACTION untuk menentukan tindakan untuk saran individual. Untuk melakukannya, tambahkan metode SUGGEST_COLUMN_INTENT_ACTION kolom ke tabel saran Anda dan, untuk setiap saran, tempatkan di dalamnya tindakan yang akan digunakan—seperti "android.intent.action.VIEW".

Anda juga dapat menggabungkan kedua teknik ini. Misalnya, Anda dapat menyertakan Atribut android:searchSuggestIntentAction dengan tindakan yang akan digunakan pada semua saran secara default, lalu menimpa tindakan ini untuk beberapa saran dengan mendeklarasikan tindakan berbeda dalam Kolom SUGGEST_COLUMN_INTENT_ACTION. Jika Anda tidak menyertakan nilai di kolom SUGGEST_COLUMN_INTENT_ACTION, maka intent yang diberikan dalam atribut android:searchSuggestIntentAction adalah data

Mendeklarasikan data intent

Saat pengguna memilih saran, aktivitas penelusuran Anda akan menerima dengan tindakan yang Anda tentukan—seperti yang dibahas dalam — tetapi intent juga harus membawa data agar aktivitas Anda dapat mengidentifikasi saran mana yang dipilih. Secara khusus, data harus sesuatu yang unik bagi setiap saran, seperti ID baris untuk saran dalam tabel SQLite Anda. Saat intent diterima, Anda bisa mengambil data yang terlampir dengan getData() atau getDataString().

Anda dapat menentukan data yang disertakan dengan intent melalui dua cara:

  • Tentukan data untuk setiap saran di dalam SUGGEST_COLUMN_INTENT_DATA kolom tabel saran Anda.

    Memberikan semua informasi data yang diperlukan untuk setiap intent dalam saran tabel dengan menyertakan kolom SUGGEST_COLUMN_INTENT_DATA dan kemudian mengisinya dengan data unik untuk setiap baris. Data dari kolom ini dilampirkan ke intent persis seperti yang Anda definisikan dalam kolom ini. Anda dapat lalu mengambilnya dengan getData() atau getDataString().

  • Memisahkan URI data menjadi dua bagian: bagian yang umum untuk semua saran dan bagian unik untuk setiap saran. Tempatkan bagian-bagian ini ke dalam Atribut android:searchSuggestintentData yang dapat ditelusuri konfigurasi dan kolom SUGGEST_COLUMN_INTENT_DATA_ID dari tabel saran Anda.

    Contoh berikut menunjukkan cara mendeklarasikan bagian URI yang umum untuk semua saran dalam Atribut android:searchSuggestIntentData Anda dapat ditelusuri konfigurasi:

      <?xml version="1.0" encoding="utf-8"?>
  <searchable xmlns:android="http://schemas.android.com/apk/res/android"
      android:label="@string/app_label"
      android:hint="@string/search_hint"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW"
      android:searchSuggestIntentData="content://com.example/datatable" >
  </searchable>

    Sertakan jalur terakhir untuk setiap saran—bagian unik—di kolom SUGGEST_COLUMN_INTENT_DATA_ID saran Anda tabel sementara. Ketika pengguna memilih sebuah saran, sistem akan mengambil {i>string<i} dari android:searchSuggestIntentData, menambahkan garis miring (/), lalu tambahkan nilai masing-masing dari Kolom SUGGEST_COLUMN_INTENT_DATA_ID untuk membuat konten yang lengkap URI. Anda kemudian dapat mengambil Uri dengan getData().

Menambahkan lebih banyak data

Jika perlu menyatakan lebih banyak informasi dengan intent, Anda dapat menambahkan tabel, seperti SUGGEST_COLUMN_INTENT_EXTRA_DATA, yang dapat menyimpan informasi tambahan tentang saran. Data yang disimpan di kolom ini ditempatkan di EXTRA_DATA_KEY paket tambahan intent.

Menangani intent

Setelah memberikan saran penelusuran kustom dengan niat kustom, Anda memerlukan aktivitas penelusuran Anda untuk menangani intent ini saat pengguna memilih saran. Tindakan ini merupakan tambahan untuk menangani ACTION_SEARCH intent, yang sudah dilakukan oleh aktivitas penelusuran Anda. Berikut adalah contoh Anda bisa menangani intent selama aktivitas onCreate() telepon balik:

Kotlin

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Java

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

Dalam contoh ini, tindakan intent adalah ACTION_VIEW dan datanya membawa URI lengkap yang mengarah ke item yang disarankan, seperti yang disintesis oleh String android:searchSuggestIntentData dan Kolom SUGGEST_COLUMN_INTENT_DATA_ID. URI tersebut kemudian diteruskan ke metode showResult() lokal yang mengkueri penyedia konten untuk item yang ditentukan oleh URI.

Menulis ulang teks kueri

Secara default, jika pengguna menjelajahi daftar saran menggunakan kontrol arah, seperti dengan trackball atau D-pad, teks kueri tidak memperbarui. Namun, Anda dapat menulis ulang teks kueri pengguna untuk sementara saat muncul di kotak teks dengan kueri yang cocok dengan saran yang difokus. Hal ini memungkinkan melihat kueri yang disarankan, dan mereka dapat memilih kotak penelusuran serta mengedit kueri sebelum mengirimkannya sebagai pencarian.

Anda dapat menulis ulang teks kueri dengan cara berikut:

  • Tambahkan atribut android:searchMode ke penelusuran Anda konfigurasi dengan nilai "queryRewriteFromText". Di sini kasus, konten dari SUGGEST_COLUMN_TEXT_1 saran digunakan untuk menulis ulang teks kueri.
  • Tambahkan atribut android:searchMode ke file yang dapat ditelusuri\ konfigurasi dengan nilai "queryRewriteFromData". Di sini ini, konten dari Kolom SUGGEST_COLUMN_INTENT_DATA digunakan untuk menulis ulang kueri teks. Hanya gunakan ini dengan URI atau format data lain yang dimaksudkan untuk terlihat oleh pengguna, seperti URL HTTP. Jangan gunakan skema URI internal untuk menulis ulang kueri dengan cara ini.
  • Berikan string teks kueri unik di SUGGEST_COLUMN_QUERY kolom tabel saran Anda. Jika ini ada dan berisi nilai untuk saran yang ada, maka digunakan untuk menulis ulang teks kueri dan mengganti salah satu teks sebelumnya implementasi yang tepat.

Mengekspos saran penelusuran ke Kotak Penelusuran Cepat

Setelah mengonfigurasi aplikasi untuk memberikan saran penelusuran kustom, membuatnya yang tersedia untuk Kotak Penelusuran Cepat yang dapat diakses secara global semudah memodifikasi konfigurasi yang dapat ditelusuri untuk disertakan android:includeInGlobalSearch dengan nilai "true".

Satu-satunya skenario yang memerlukan upaya tambahan adalah saat konten Anda memerlukan izin baca. Dalam hal ini, Anda perlu menambahkan Elemen <path-permission> yang akan digunakan penyedia untuk memberikan Quick Akses baca Kotak Penelusuran ke penyedia konten Anda, seperti yang ditunjukkan di bawah contoh:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

Dalam contoh ini, penyedia membatasi akses baca dan tulis ke konten. Elemen <path-permission> mengubah batasan tersebut dengan memberikan akses baca ke konten di dalam "/search_suggest_query" awalan jalur ketika izin "android.permission.GLOBAL_SEARCH" sudah ada. Tindakan ini memberikan akses ke Kotak Penelusuran Cepat sehingga dapat mengkueri konten Anda untuk mendapatkan saran.

Jika penyedia konten Anda tidak menerapkan izin baca, {i>Quick Search<i} Box akan membacanya secara default.

Mengaktifkan saran di perangkat

Secara default, aplikasi tidak diaktifkan untuk memberikan saran di Kotak Penelusuran Cepat, bahkan jika mereka dikonfigurasi untuk melakukannya. Pengguna memilih apakah akan menyertakan saran dari aplikasi Anda di Kotak Penelusuran Cepat dengan membuka Dapat ditelusuri item—ada di Setelan > Penelusuran—dan mengaktifkan sebagai item yang dapat ditelusuri.

Setiap aplikasi yang tersedia untuk Kotak Penelusuran Cepat memiliki entri di Halaman setelan Item yang dapat ditelusuri. Entri tersebut menyertakan nama aplikasi dan deskripsi singkat tentang konten apa yang dapat ditelusuri dari aplikasi dan dibuat tersedia untuk saran di Kotak Penelusuran Cepat. Untuk menentukan teks deskripsi untuk aplikasi yang dapat ditelusuri, tambahkan android:searchSettingsDescription ke konfigurasi penelusuran Anda, seperti yang ditampilkan dalam contoh:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

Buat string untuk android:searchSettingsDescription sesingkat mungkin mungkin dan nyatakan konten yang dapat ditelusuri. Misalnya, "Artis, album, dan lagu" untuk aplikasi musik, atau "Catatan tersimpan" untuk aplikasi catatan. Pemberian deskripsi ini penting agar pengguna tahu seperti apa saran yang diberikan. Selalu sertakan atribut ini saat android:includeInGlobalSearch benar.

Karena pengguna harus membuka menu setelan untuk mengaktifkan saran penelusuran untuk aplikasi Anda, jika penelusuran merupakan aspek penting aplikasi, pertimbangkan cara menyampaikannya kepada pengguna. Misalnya, Anda dapat memberikan catatan saat pertama kali pengguna meluncurkan aplikasi yang menjelaskan cara mengaktifkan saran penelusuran untuk fitur Quick Kotak Penelusuran.

Mengelola pintasan saran Kotak Penelusuran Cepat

Saran yang dipilih pengguna dari Kotak Penelusuran Cepat dapat secara otomatis dibuat menjadi pintasan. Ini adalah saran yang disalin oleh sistem dari penyedia konten agar dapat mengakses saran dengan cepat tanpa perlu melakukan kueri ulang terhadap penyedia konten Anda.

Secara default, setelan ini diaktifkan untuk semua saran yang diambil oleh Penelusuran Cepat Box, tetapi jika data saran Anda berubah seiring waktu, Anda dapat memintanya pintasan dimuat ulang. Misalnya, jika saran Anda mengacu pada data, seperti status kehadiran kontak, lalu minta agar saran tersebut pintasan diperbarui saat ditampilkan kepada pengguna. Untuk melakukannya, sertakan SUGGEST_COLUMN_SHORTCUT_ID di tabel saran Anda. Anda dapat menggunakan kolom ini untuk mengonfigurasi perilaku pintasan bagi setiap saran di salah satu cara berikut:

  • Buat Kotak Penelusuran Cepat melakukan kueri ulang penyedia konten Anda untuk dari pintasan saran.

    Berikan nilai di kolom SUGGEST_COLUMN_SHORTCUT_ID untuk saran yang dikueri ulang untuk versi baru setiap kali pintasan yang ditampilkan. Pintasan secara cepat ditampilkan dengan data apa pun yang paling baru-baru ini tersedia hingga kueri {i>refresh <i}ditampilkan, yang pada saat itu saran diperbarui dengan informasi baru. Kueri pembaruannya adalah dikirim ke penyedia konten Anda dengan jalur URI SUGGEST_URI_PATH_SHORTCUT—bukan SUGGEST_URI_PATH_QUERY.

    Buat Cursor yang Anda tampilkan berisi satu saran menggunakan kolom yang sama dengan saran awal atau kosong, yang menunjukkan bahwa pintasan tidak lagi valid—dalam hal ini, saran akan hilang dan {i>shortcut<i} akan dihapus.

    Jika saran merujuk pada data yang memerlukan waktu lebih lama untuk dimuat ulang, seperti pembaruan berbasis jaringan, Anda juga dapat menambahkan SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING kolom ke tabel saran dengan nilai true untuk menampilkan indikator lingkaran berputar progres untuk ikon di sebelah kanan hingga pemuatan ulang selesai. Nilai apa pun selain true tidak menampilkan indikator lingkaran berputar progres.

  • Mencegah saran disalin ke pintasan.

    Berikan nilai SUGGEST_NEVER_MAKE_SHORTCUT di kolom Kolom SUGGEST_COLUMN_SHORTCUT_ID. Dalam hal ini, saran tidak akan pernah disalin ke pintasan. Ini hanya diperlukan jika Anda sama sekali tidak ingin saran yang disalin sebelumnya muncul. Jika Anda berikan nilai normal untuk kolom, lalu pintasan saran hanya muncul sampai kueri refresh ditampilkan.

  • Membiarkan perilaku pintasan default berlaku.

    Biarkan SUGGEST_COLUMN_SHORTCUT_ID kosong untuk setiap saran yang tidak berubah dan yang dapat disimpan sebagai {i>shortcut<i}.

Jika tidak ada saran yang berubah, Anda tidak memerlukan Kolom SUGGEST_COLUMN_SHORTCUT_ID.

Tentang peringkat saran Kotak Penelusuran Kilat

Setelah saran penelusuran aplikasi Anda tersedia untuk Kotak Penelusuran Cepat, peringkat Kotak Penelusuran Cepat menentukan bagaimana saran dimunculkan ke untuk kueri tertentu. Hal ini mungkin bergantung pada berapa banyak aplikasi lain hasil untuk kueri itu dan seberapa sering pengguna memilih hasil Anda dibandingkan dengan {i>tool <i}itu dari aplikasi lain. Tidak ada jaminan terkait bagaimana saran Anda peringkat atau apakah saran aplikasi ditampilkan untuk kueri tertentu. Di beberapa umum, memberikan hasil yang berkualitas akan meningkatkan kemungkinan bahwa saran diberikan di posisi yang terlihat jelas, dan aplikasi yang memberikan saran berkualitas rendah cenderung memiliki peringkat yang lebih rendah atau tidak ditampilkan.