إضافة اقتراحات بحث مخصّص

يمكنك تقديم اقتراحات البحث بناءً على طلبات البحث الأخيرة في مربع حوار بحث Android أو تطبيق "بحث Google" المصغّر. على سبيل المثال، إذا طلب المستخدم "جراء"، ظهور طلب البحث كاقتراح عندما اكتب نفس الاستعلام مرة أخرى. يعرض الشكل 1 مثالاً لمربع حوار بحث يتضمن طلب بحث حديث الاقتراحات.

قبل البدء، استخدِم مربّع حوار البحث أو أداة "بحث Google" لإجراء عمليات البحث الأساسية. في تطبيقك. لمعرفة كيفية إجراء ذلك، راجع أنشئ واجهة بحث.

الأساسيات

الشكل 1. لقطة شاشة لمربّع حوار بحث يتضمّن طلب بحث حديثًا الاقتراحات.

اقتراحات طلبات البحث الأخيرة هي عمليات بحث محفوظة. عندما يحدد المستخدم اقتراحًا، ستكون نشاط يتلقى هدف واحد (ACTION_SEARCH) مع اقتراح كطلب البحث الذي يعالجه نشاطك القابل للبحث.

لتقديم اقتراحات بشأن طلبات البحث الحديثة، يجب تنفيذ ما يلي:

• قم بتنفيذ نشاط يمكن البحث فيه.
• إنشاء موفّر محتوى يمتد إلى SearchRecentSuggestionsProvider ووضِّح ذلك في بيان التطبيق.
• تعديل التكوين القابل للبحث باستخدام معلومات عن موفّر المحتوى الذي يوفر اقتراحات البحث.
• حفظ طلبات البحث لموفّر المحتوى في كل مرة يتم فيها تنفيذ عملية بحث

مثلما يعرض نظام Android مربّع حوار البحث، سيتم عرض اقتراحات البحث أدناه. مربّع الحوار أو أداة البحث. وتقدِّم المصدر الذي يسترد النظام الاقتراحات منه.

عندما يحدد النظام أن نشاطك قابل للبحث ويقدم اقتراحات بحث، يحدث ما يلي عندما يكتب المستخدم طلب بحث:

1. يأخذ النظام نص طلب البحث - أيًا كان ما يبدأ المستخدم في كتابته - طلب بحث لموفّر المحتوى الذي يحتوي على اقتراحاتك.
2. يعرض موفّر المحتوى Cursor يشير إلى الكل الاقتراحات التي تطابق نص طلب البحث.
3. يعرض النظام قائمة الاقتراحات المقدَّمة من "Cursor".

بعد عرض أحدث اقتراحات طلبات البحث، قد يحدث ما يلي:

• إذا كتب المستخدم مفتاحًا آخر أو غيّر طلب البحث بأي طريقة، فإن الخطوات السابقة هي مرة أخرى وسيتم تحديث قائمة الاقتراحات.
• إذا أجرى المستخدم البحث، يتم تجاهل الاقتراحات ويتم تسليم البحث إلى نشاطك القابل للبحث باستخدام هدف ACTION_SEARCH العادي.
• إذا اختار المستخدم اقتراحًا، سيتم إرسال نية ACTION_SEARCH إلى نشاط البحث باستخدام النص المقترح كطلب.

الفئة SearchRecentSuggestionsProvider التي تمنحها لموفّر المحتوى يقوم بالعمل تلقائيًا في الخطوات السابقة، لذلك هناك القليل من التعليمات البرمجية لكتابتها.

إنشاء موفّر محتوى

إن موفر المحتوى الذي تحتاج إليه لاقتراحات طلب البحث الأخيرة هو تنفيذ SearchRecentSuggestionsProvider سينفّذ هذا الصف كل المهام نيابةً عنك. ما عليك سوى كتابة دالة إنشائية لفئة تعمل على تنفيذ سطر واحد من التعليمة البرمجية.

على سبيل المثال، إليك عملية تنفيذ كاملة لموفّر محتوى لطلب البحث الأخير. الاقتراحات:

Kotlin

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

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

Java

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);
    }
}

الحث على setupSuggestions() يمرر اسم مصدر البحث ووضع قاعدة البيانات. يمكن أن تكون هيئة البحث أي مصدر ولكن أفضل الممارسات هي استخدام اسم مؤهل بالكامل لمقدم المحتوى، مثل اسم الحزمة متبوعًا باسم فئة الموفر. على سبيل المثال: "com.example.MySuggestionProvider"

يجب أن يتضمن وضع قاعدة البيانات DATABASE_MODE_QUERIES ويمكن أن تتضمن اختياريًا DATABASE_MODE_2LINES, والذي يضيف عمودًا إلى جدول الاقتراحات حتى تتمكن من تقديم سطر ثانٍ من النص مع كل اقتراحنا. إذا أردت توفير سطرين في كل اقتراح، يمكنك الاطّلاع على المثال التالي:

Kotlin

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

Java

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

يُرجى تعريف موفّر المحتوى في بيان التطبيق باستخدام سلسلة التفويض نفسها المستخدَمة في صف SearchRecentSuggestionsProvider وفي الإعدادات القابلة للبحث. بالنسبة مثال:

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

تعديل الإعدادات القابلة للبحث

لضبط النظام على استخدام مقدِّم الاقتراحات، أضِف android:searchSuggestAuthority وandroid:searchSuggestSelection إلى العنصر <searchable> في ملف الإعداد القابل للبحث. بالنسبة مثال:

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

يجب أن تكون قيمة android:searchSuggestAuthority اسمًا مؤهلاً بالكامل موفّر المحتوى الذي يتطابق تمامًا مع السلطة المستخدمة في موفّر المحتوى، مثل "com.example.MySuggestionProvider" في الأمثلة السابقة.

يجب أن تكون قيمة android:searchSuggestSelection علامة استفهام واحدة مسبوقة حسب مساحة: " ?" هذا عنصر نائب لوسيطة تحديد SQLite، تلقائيًا بنص طلب البحث الذي أدخله المستخدم.

حفظ الطلبات

لتعبئة مجموعة طلبات البحث الأخيرة، أضف كل طلب بحث استلمته طلبات البحث النشاط على SearchRecentSuggestionsProvider. للقيام بذلك، قم بإنشاء مثيل SearchRecentSuggestions والاتصال saveRecentQuery() في كل مرة يتلقى فيها نشاطك القابل للبحث طلب بحث. على سبيل المثال، إليك كيفية حفظ طلب البحث أثناء نشاطك onCreate() :

Kotlin

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)
        }
    }
}

Java

@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);
    }
}

تتطلب الدالة الإنشائية SearchRecentSuggestionsProvider الجهة نفسها ووضع قاعدة البيانات نفسهما الذي أعلن عنه موفّر المحتوى

تتعامل الطريقة saveRecentQuery() مع سلسلة طلب البحث كمَعلمة أولى. ويمكنك اختياريًا تضمين سلسلة ثانية لتضمينها كسطر ثاني من الاقتراح أو قيمة خالية. الفرصة الثانية فقط إذا قمت بتمكين وضع سطرين لاقتراحات البحث مع DATABASE_MODE_2LINES إذا قمت بتمكين الوضع المكون من سطرين، فسوف يتطابق نص طلب البحث مع السطر الثاني عندما يبحث النظام عن اقتراحات مطابقة.

محو بيانات الاقتراح

لحماية خصوصية المستخدم، يجب دائمًا توفير طريقة تمكّن المستخدم من محو طلب البحث الأخير الاقتراحات. لمحو سجل طلبات البحث، اتصل clearHistory() مثلاً:

Kotlin

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

Java

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

نفِّذ هذا الإجراء بناءً على اختيارك "محو سجلّ البحث". أو عنصر قائمة أو عنصر تفضيل أو زر. توفير مربّع حوار للتأكيد لتأكيد أنّ المستخدم يريد حذف سجلّ البحث