Menambahkan saran penelusuran khusus

Anda dapat memberikan saran penelusuran berdasarkan kueri penelusuran terbaru di dialog penelusuran Android atau widget penelusuran. Misalnya, jika pengguna membuat kueri "anak anjing", kueri muncul sebagai saran ketika mereka mengetik kueri yang sama. Gambar 1 menunjukkan contoh dialog penelusuran dengan kueri terbaru ejaan atau mendapatkan saran gaya.

Sebelum memulai, terapkan dialog penelusuran atau widget penelusuran untuk penelusuran dasar dalam aplikasi Anda. Untuk mempelajari caranya, lihat Buat antarmuka penelusuran.

Dasar-dasar

Gambar 1. Screenshot dialog penelusuran dengan kueri terbaru ejaan atau mendapatkan saran gaya.

Saran kueri terbaru adalah penelusuran yang disimpan. Saat pengguna memilih saran, saran Anda dapat ditelusuri aktivitas menerima ACTION_SEARCH intent dengan saran sebagai kueri penelusuran yang sudah ditangani oleh aktivitas penelusuran Anda.

Untuk memberikan saran kueri terbaru, Anda perlu:

• Mengimplementasikan aktivitas penelusuran.
• Membuat penyedia konten yang memperluas SearchRecentSuggestionsProvider dan mendeklarasikannya dalam manifes aplikasi.
• Ubah konfigurasi yang dapat ditelusuri dengan informasi tentang penyedia konten yang menyediakan saran penelusuran.
• Menyimpan kueri ke penyedia konten setiap kali penelusuran dijalankan.

Sama seperti sistem Android yang menampilkan dialog penelusuran, sistem juga menampilkan saran penelusuran di bawah dialog atau widget penelusuran. Anda menyediakan sumber yang digunakan sistem untuk mengambil saran.

Ketika sistem mengidentifikasi bahwa aktivitas Anda dapat ditelusuri dan memberikan saran penelusuran, berikut ini terjadi saat pengguna mengetik kueri:

1. Sistem mengambil teks kueri penelusuran—apa pun yang mulai diketik pengguna—dan melakukan kueri ke penyedia konten yang berisi saran Anda.
2. Penyedia konten akan mengembalikan Cursor yang mengarah ke semua saran yang cocok dengan teks kueri penelusuran.
3. Sistem menampilkan daftar saran yang diberikan oleh Cursor.

Setelah saran kueri terbaru ditampilkan, berikut ini dapat terjadi:

• Jika pengguna mengetik kunci lain atau mengubah kueri dengan cara apa pun, langkah sebelumnya akan diulang dan daftar saran akan diperbarui.
• Jika pengguna menjalankan penelusuran, saran akan diabaikan dan penelusuran dikirimkan ke aktivitas penelusuran Anda menggunakan intent ACTION_SEARCH normal.
• Jika pengguna memilih saran, intent ACTION_SEARCH akan dikirim ke aktivitas yang dapat ditelusuri dengan menggunakan teks yang disarankan sebagai kueri.

Class SearchRecentSuggestionsProvider yang diperluas untuk penyedia konten Anda secara otomatis melakukan pekerjaan di langkah sebelumnya, sehingga hanya ada sedikit kode yang harus ditulis.

Membuat penyedia konten

Penyedia konten yang Anda butuhkan untuk saran kueri terbaru adalah sebuah implementasi dari SearchRecentSuggestionsProvider. Kelas ini akan melakukan semuanya untuk Anda. Anda hanya perlu menulis konstruktor class yang mengeksekusi satu baris kode.

Misalnya, berikut adalah implementasi lengkap dari penyedia konten untuk kueri terbaru saran:

class MySuggestionProvider : SearchRecentSuggestionsProvider() {
    init {
        setupSuggestions(AUTHORITY, MODE)
    }

    companion object {
        const val AUTHORITY = "com.example.MySuggestionProvider"
        const val MODE: Int = SearchRecentSuggestionsProvider.DATABASE_MODE_QUERIES
    }
}

public class MySuggestionProvider extends SearchRecentSuggestionsProvider {
    public final static String AUTHORITY = "com.example.MySuggestionProvider";
    public final static int MODE = DATABASE_MODE_QUERIES;

    public MySuggestionProvider() {
        setupSuggestions(AUTHORITY, MODE);
    }
}

Panggilan ke setupSuggestions() meneruskan nama otoritas pencarian dan mode {i>database<i}. Otoritas penelusuran dapat berupa namun praktik terbaiknya adalah menggunakan nama yang sepenuhnya memenuhi syarat untuk penyedia konten, seperti nama paket diikuti dengan nama class penyedia. Misalnya, "com.example.MySuggestionProvider".

Mode {i>database<i} harus mencakup DATABASE_MODE_QUERIES dan secara opsional dapat mencakup DATABASE_MODE_2LINES, yang menambahkan kolom ke tabel saran sehingga Anda dapat menyediakan baris teks kedua dengan saran. Jika Anda ingin memberikan dua baris di setiap saran, lihat contoh berikut:

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

Deklarasikan penyedia konten dalam manifes aplikasi Anda dengan string otoritas yang sama dengan yang digunakan di class SearchRecentSuggestionsProvider Anda dan dalam konfigurasi penelusuran. Contoh:

<application>
    <provider android:name=".MySuggestionProvider"
              android:authorities="com.example.MySuggestionProvider" />
    ...
</application>

Mengubah konfigurasi penelusuran

Untuk mengonfigurasi sistem agar menggunakan penyedia saran Anda, tambahkan atribut android:searchSuggestAuthority dan android:searchSuggestSelection ke elemen <searchable> dalam file konfigurasi penelusuran Anda. 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.MySuggestionProvider"
    android:searchSuggestSelection=" ?" >
</searchable>

Nilai untuk android:searchSuggestAuthority harus berupa nama yang sepenuhnya memenuhi syarat untuk penyedia konten yang sama persis dengan otoritas yang digunakan dalam penyedia konten, seperti "com.example.MySuggestionProvider" dalam contoh sebelumnya.

Nilai untuk android:searchSuggestSelection harus diawali dengan satu tanda tanya dengan spasi: " ?". Ini adalah placeholder untuk argumen pemilihan SQLite, dan ini otomatis digantikan oleh teks kueri yang dimasukkan oleh pengguna.

Simpan kueri

Untuk mengisi koleksi kueri terbaru, tambahkan setiap kueri yang diterima oleh kueri penelusuran aktivitas ke SearchRecentSuggestionsProvider Anda. Untuk melakukannya, buat instance SearchRecentSuggestions dan panggil saveRecentQuery() setiap kali aktivitas penelusuran Anda menerima kueri. Misalnya, berikut ini cara menyimpan kueri selama aktivitas onCreate() berikut:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            SearchRecentSuggestions(this, MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE)
                    .saveRecentQuery(query, null)
        }
    }
}

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent  = getIntent();

    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        String query = intent.getStringExtra(SearchManager.QUERY);
        SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
                MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
        suggestions.saveRecentQuery(query, null);
    }
}

Konstruktor SearchRecentSuggestionsProvider memerlukan mode database dan otoritas yang sama yang dideklarasikan oleh penyedia konten Anda.

Metode saveRecentQuery() menggunakan string kueri penelusuran sebagai parameter pertama dan, bisa juga, string kedua untuk disertakan sebagai baris kedua saran atau null. Yang kedua hanya digunakan jika Anda mengaktifkan mode dua baris untuk saran penelusuran dengan DATABASE_MODE_2LINES. Jika Anda mengaktifkan mode dua baris, maka teks kueri akan cocok dengan baris kedua ketika sistem mencari saran yang cocok.

Hapus data saran

Untuk melindungi privasi pengguna, selalu berikan cara bagi pengguna untuk menghapus kueri terbaru ejaan atau mendapatkan saran gaya. Untuk menghapus histori kueri, panggil clearHistory(). Contoh:

SearchRecentSuggestions(this, HelloSuggestionsProvider.AUTHORITY, HelloSuggestionsProvider.MODE)
        .clearHistory()

SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
        HelloSuggestionProvider.AUTHORITY, HelloSuggestionProvider.MODE);
suggestions.clearHistory();

Jalankan dari opsi "Hapus Histori Penelusuran" pilihan Anda item menu, item preferensi, atau tombol. Menyediakan dialog konfirmasi untuk memverifikasi bahwa pengguna ingin menghapus histori penelusurannya.