إنشاء واجهة بحث

تجربة طريقة "الكتابة"
‫Jetpack Compose هي مجموعة أدوات واجهة المستخدم التي يُنصح باستخدامها على Android. تعرَّف على كيفية إضافة وظيفة البحث في "إنشاء".
شريط البحث →

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

تشمل الميزات الأخرى المتاحة لمربّع الحوار وأداة البحث ما يلي:

  • البحث الصوتي
  • اقتراحات البحث استنادًا إلى طلبات البحث الحديثة
  • اقتراحات البحث التي تتطابق مع النتائج الفعلية في بيانات تطبيقك

يوضّح هذا المستند كيفية إعداد تطبيقك لتوفير واجهة بحث يساعد فيها نظام Android في عرض طلبات البحث، وذلك باستخدام إما مربّع حوار البحث أو أداة البحث.

مراجع ذات صلة:

الأساسيات

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

  • مربّع الحوار الخاص بالبحث هو أحد مكوّنات واجهة المستخدم التي يتحكّم فيها نظام التشغيل Android. عندما يفعِّل المستخدم ميزة "البحث أثناء التنقل"، يظهر مربّع حوار البحث في أعلى النشاط.

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

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

عندما ينفّذ المستخدم عملية بحث من مربّع حوار البحث أو أداة البحث، ينشئ النظام Intent ويخزّن طلب البحث الخاص بالمستخدم فيه. يبدأ النظام بعد ذلك النشاط الذي تحدّده للتعامل مع عمليات البحث، وهو "النشاط القابل للبحث"، ويسلّمه عنصر intent. لإعداد تطبيقك لهذا النوع من البحث بمساعدة الذكاء الاصطناعي، يجب توفُّر ما يلي:

  • إعدادات البحث
    ملف XML يضبط بعض الإعدادات لمربّع البحث أو الأداة. ويشمل إعدادات لميزات مثل البحث الصوتي واقتراحات البحث ونص التلميح لمربّع البحث.
  • نشاط قابل للبحث
    Activity الذي يتلقّى طلب البحث ويبحث في بياناتك ويعرض نتائج البحث
  • واجهة بحث يوفّرها أحد الخيارَين التاليَين:
    • مربّع حوار البحث
      يكون مربّع حوار البحث مخفيًا تلقائيًا. يظهر في أعلى الشاشة عند طلب onSearchRequested() عندما ينقر المستخدم على زر بحث.
    • تطبيق SearchView مصغّر
      يتيح لك استخدام أداة البحث وضع مربّع البحث في أي مكان في نشاطك، بما في ذلك كطريقة عرض للإجراءات في شريط التطبيق.

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

إنشاء عملية ضبط قابلة للبحث

أول ما تحتاج إليه هو ملف XML يُعرف باسم إعدادات البحث. ويضبط هذا الملف بعض جوانب واجهة المستخدم لمربّع حوار البحث أو التطبيق المصغّر، ويحدّد طريقة عمل الميزات، مثل الاقتراحات والبحث الصوتي. يُطلق على هذا الملف عادةً الاسم searchable.xml ويجب حفظه في دليل المشروع res/xml/.

يجب أن يتضمّن ملف إعدادات البحث العنصر <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" >
</searchable>

السمة android:label هي السمة الوحيدة المطلوبة. ويشير إلى مورد سلسلة، ويجب أن يكون اسم التطبيق. لا يظهر هذا التصنيف للمستخدم إلا بعد تفعيل اقتراحات البحث في &quot;مربّع البحث السريع&quot;، وعندها يظهر التصنيف في قائمة &quot;العناصر القابلة للبحث&quot; ضمن إعدادات النظام.

على الرغم من أنّها ليست مطلوبة، ننصحك دائمًا بتضمين السمة android:hint التي توفّر سلسلة تلميح في مربّع البحث قبل أن يدخل المستخدمون طلب بحث. تُعدّ التلميحات مهمة لأنّها تقدّم للمستخدمين أدلة مهمة حول ما يمكنهم البحث عنه.

يقبل العنصر <searchable> عدة سمات أخرى. ومع ذلك، لن تحتاج إلى معظم السمات إلا عند إضافة ميزات مثل اقتراحات البحث والبحث الصوتي. للحصول على معلومات مفصّلة حول ملف إعداد البحث، يُرجى الاطّلاع على مستند مرجع إعداد البحث.

إنشاء نشاط قابل للبحث

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

عندما ينفّذ المستخدم عملية بحث في مربّع الحوار أو الأداة الخاصة بالبحث، يبدأ النظام نشاطك القابل للبحث ويقدّم له طلب البحث في Intent مع الإجراء ACTION_SEARCH. يسترد النشاط القابل للبحث طلب البحث من البيانات الإضافية الخاصة بالغرض، ثم يبحث في بياناتك ويعرض النتائج.QUERY

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

تعريف نشاط قابل للبحث

إذا لم يكن لديك واحد، أنشئ Activity يمكنه إجراء عمليات بحث وعرض النتائج. لست بحاجة إلى تنفيذ وظيفة البحث بعد، بل عليك إنشاء نشاط يمكنك تعريفه في ملف البيان. داخل العنصر <activity> في ملف البيان، اتّبِع الخطوات التالية:

  1. عليك تعريف النشاط لقبول الغرض ACTION_SEARCH في عنصر <intent-filter>.
  2. حدِّد إعدادات البحث التي تريد استخدامها في عنصر <meta-data>.

يظهر ذلك في المثال التالي:

<application ... >
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>
    ...
</application>

يجب أن يتضمّن العنصر <meta-data> السمة android:name بالقيمة "android.app.searchable" والسمة android:resource مع مرجع إلى ملف الإعداد القابل للبحث. في المثال السابق، يشير ذلك إلى الملف res/xml/searchable.xml.

إجراء بحث

بعد تعريف النشاط القابل للبحث في ملف البيان، اتّبِع الإجراء التالي لإجراء بحث في النشاط القابل للبحث:

  1. تلقّي طلب البحث
  2. البحث في بياناتك
  3. عرض النتائج

تلقّي طلب البحث

عندما ينفّذ المستخدم عملية بحث من مربّع حوار البحث أو الأداة، يبدأ النظام نشاطك القابل للبحث ويرسل إليه ACTION_SEARCH intent. يحمل هذا الغرض طلب البحث في السلسلة QUERY الإضافية. تحقَّق من هذا الهدف عند بدء النشاط واستخرِج السلسلة. على سبيل المثال، إليك كيفية الحصول على طلب البحث عندما يبدأ نشاطك القابل للبحث:

Kotlin

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

    // Verify the action and get the query.
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

Java

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

    // Get the intent, verify the action, and get the query.
    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

يتم دائمًا تضمين السلسلة QUERY مع الغرض ACTION_SEARCH. في المثال السابق، يتم استرداد طلب البحث وتمريره إلى طريقة doMySearch() محلية يتم فيها تنفيذ عملية البحث الفعلية.

البحث في بياناتك

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

  • إذا كانت بياناتك مخزّنة في قاعدة بيانات SQLite على الجهاز، يمكن أن يوفّر إجراء بحث بنص كامل باستخدام FTS3 بدلاً من طلب بحث LIKE بحثًا أكثر فعالية في بيانات النص، ويمكن أن يعرض النتائج بشكل أسرع بكثير. يمكنك الاطّلاع على sqlite.org للحصول على معلومات حول FTS3، وعلى SQLiteDatabase للحصول على معلومات حول SQLite على Android.
  • إذا كانت بياناتك مخزَّنة على الإنترنت، قد يتأثر أداء البحث المتوقّع بسبب اتصال المستخدم بالإنترنت. قد تحتاج إلى عرض مؤشر تقدّم إلى أن تظهر نتائج البحث. يمكنك الاطّلاع على android.net للحصول على مرجع لواجهات برمجة التطبيقات الخاصة بالشبكة، وعلى ProgressBar للحصول على معلومات حول كيفية عرض مؤشر التقدّم.

عرض النتائج

بغض النظر عن مكان تخزين بياناتك وطريقة البحث فيها، ننصحك بإرجاع نتائج البحث إلى نشاطك القابل للبحث باستخدام Adapter. بهذه الطريقة، يمكنك عرض جميع نتائج البحث في RecyclerView. إذا كانت بياناتك واردة من طلب بحث في قاعدة بيانات SQLite، يمكنك تطبيق النتائج على RecyclerView باستخدام CursorAdapter. إذا كانت بياناتك بتنسيق مختلف، يمكنك إنشاء امتداد لـ BaseAdapter.

يربط Adapter كل عنصر من مجموعة بيانات بكائن View. عند تطبيق Adapter على RecyclerView، يتم إدراج كل جزء من البيانات كعرض فردي في القائمة. ‫Adapter هي مجرد واجهة، لذا يجب استخدام عمليات تنفيذ مثل CursorAdapter لربط البيانات من Cursor. إذا لم تنجح أي من عمليات التنفيذ الحالية مع بياناتك، يمكنك تنفيذ عملية خاصة بك من BaseAdapter.

استخدام مربّع حوار البحث

يوفر مربّع الحوار "بحث" مربّع بحث عائمًا في أعلى الشاشة، مع رمز التطبيق على اليمين. يمكن أن يوفّر مربّع حوار البحث اقتراحات بحث أثناء كتابة المستخدم. عندما ينفّذ المستخدم عملية بحث، يرسل النظام طلب البحث إلى نشاط قابل للبحث ينفّذ عملية البحث.

يتم إخفاء مربّع حوار البحث تلقائيًا إلى أن يفعّله المستخدم. يمكن لتطبيقك تفعيل مربّع حوار البحث من خلال طلب البيانات من onSearchRequested(). ومع ذلك، لن ينجح هذا الإجراء إلا بعد تفعيل مربّع حوار البحث للنشاط.

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

لتحديد النشاط القابل للبحث في مربّع حوار البحث الخاص بنشاط معيّن، أضِف عنصر <meta-data> داخل عنصر <activity> الخاص بالنشاط المعنيّ. يجب أن يتضمّن العنصر <meta-data> السمة android:value التي تحدّد اسم فئة النشاط القابل للبحث والسمة android:name التي تتضمّن القيمة "android.app.default_searchable".

على سبيل المثال، إليك بيانًا لكل من النشاط القابل للبحث، SearchableActivity، ونشاط آخر، OtherActivity، يستخدم SearchableActivity لإجراء عمليات البحث التي يتم تنفيذها من مربّع حوار البحث الخاص به:

<application ... >
    <!-- This is the searchable activity; it performs searches. -->
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>

    <!-- This activity enables the search dialog to initiate searches
         in the SearchableActivity. -->
    <activity android:name=".OtherActivity" ... >
        <!-- Enable the search dialog to send searches to SearchableActivity. -->
        <meta-data android:name="android.app.default_searchable"
                   android:value=".SearchableActivity" />
    </activity>
    ...
</application>

بما أنّ OtherActivity يتضمّن الآن عنصر <meta-data> لتحديد النشاط القابل للبحث الذي سيتم استخدامه في عمليات البحث، يتيح النشاط مربع حوار البحث. على الرغم من أنّ المستخدم يكون في هذا النشاط، إلا أنّ الطريقة onSearchRequested() تفعّل مربّع البحث. عندما ينفّذ المستخدم عملية البحث، يبدأ النظام SearchableActivity ويقدّم له ACTION_SEARCH intent.

إذا كنت تريد أن يوفّر كل نشاط في تطبيقك مربّع حوار البحث، أدرِج عنصر <meta-data> السابق كعنصر فرعي من عنصر <application> بدلاً من كل <activity>. بهذه الطريقة، يرث كل نشاط القيمة، ويوفّر مربّع حوار البحث، ويقدّم عمليات البحث إلى النشاط نفسه القابل للبحث. إذا كان لديك أنشطة متعدّدة قابلة للبحث، يمكنك إلغاء النشاط التلقائي القابل للبحث من خلال وضع تصريح <meta-data> مختلف داخل الأنشطة الفردية.

بعد تفعيل مربّع حوار البحث لأنشطتك، يصبح تطبيقك جاهزًا لإجراء عمليات البحث.

استدعاء مربّع حوار البحث

على الرغم من أنّ بعض الأجهزة توفّر زر بحث مخصّصًا، قد يختلف سلوك الزر من جهاز إلى آخر، ولا توفّر العديد من الأجهزة زر بحث على الإطلاق. لذا، عند استخدام مربّع حوار البحث، عليك توفير زر بحث في واجهة المستخدم يفعّل مربّع حوار البحث من خلال استدعاء onSearchRequested().

على سبيل المثال، يمكنك إضافة زر بحث في قائمة الخيارات أو تخطيط واجهة المستخدم الذي يستدعي onSearchRequested().

يمكنك أيضًا تفعيل وظيفة "الكتابة للبحث" التي تفعّل مربّع حوار البحث عندما يبدأ المستخدم في الكتابة على لوحة المفاتيح. يتم إدراج ضغطات المفاتيح في مربّع حوار البحث. يمكنك تفعيل ميزة "الكتابة للبحث" في نشاطك من خلال استدعاء setDefaultKeyMode أو DEFAULT_KEYS_SEARCH_LOCAL أثناء تنفيذ طريقة onCreate() في نشاطك.

تأثير مربّع حوار البحث في مراحل نشاطك

مربّع حوار البحث هو Dialog يظهر في أعلى الشاشة. لا يؤدي ذلك إلى أي تغيير في حزمة الأنشطة، لذا عند ظهور مربّع حوار البحث، لا يتم استدعاء أي طرق لدورة الحياة، مثل onPause(). يفقد نشاطك تركيز الإدخال لأنّه يتم منح تركيز الإدخال لمربّع حوار البحث.

إذا أردت تلقّي إشعار عند تفعيل مربّع حوار البحث، عليك إلغاء طريقة onSearchRequested(). عندما يستدعي النظام هذه الطريقة، يكون ذلك مؤشرًا على أنّ نشاطك يفقد تركيز الإدخال لصالح مربّع حوار البحث، لذا يمكنك تنفيذ أي عمل مناسب للحدث، مثل إيقاف لعبة مؤقتًا. ما لم تكن تمرّر بيانات سياق البحث، كما هو موضّح في قسم آخر من هذا المستند، عليك إنهاء الطريقة من خلال استدعاء تنفيذ الفئة الرئيسية:

Kotlin

override fun onSearchRequested(): Boolean {
    pauseSomeStuff()
    return super.onSearchRequested()
}

Java

@Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}

إذا ألغى المستخدم البحث من خلال النقر على زر &quot;الرجوع&quot;، سيتم إغلاق مربّع حوار البحث وسيستعيد النشاط تركيز الإدخال. يمكنك التسجيل لتلقّي إشعار عند إغلاق مربّع حوار البحث باستخدام setOnDismissListener() أو setOnCancelListener() أو كليهما. ما عليك سوى تسجيل OnDismissListener، لأنّه يتم استدعاؤه في كل مرة يتم فيها إغلاق مربّع حوار البحث. لا ينطبق هذا الحدث إلا على الأحداث التي يخرج فيها المستخدم بشكل صريح من مربّع حوار البحث، وبالتالي لا يتم استدعاؤه عند تنفيذ عملية بحث.OnCancelListener عند تنفيذ عملية البحث، يختفي مربع حوار البحث تلقائيًا.

إذا لم يكن النشاط الحالي هو النشاط القابل للبحث، يتم تنشيط أحداث مراحل النشاط العادية عندما ينفّذ المستخدم عملية بحث، ويتلقّى النشاط الحالي onPause()، كما هو موضّح في مقدمة عن الأنشطة. ومع ذلك، إذا كان النشاط الحالي هو النشاط القابل للبحث، سيحدث أحد الأمرين التاليين:

  • تتلقّى الأنشطة القابلة للبحث تلقائيًا الغرض ACTION_SEARCH مع طلب إلى onCreate()، ويتم نقل مثيل جديد من النشاط إلى أعلى حزمة الأنشطة. يتضمّن الآن حزمة الأنشطة مثيلَين لنشاطك القابل للبحث، لذا يؤدي النقر على زر الرجوع إلى نقلك إلى المثيل السابق للنشاط القابل للبحث بدلاً من الخروج من هذا النشاط.
  • إذا ضبطت android:launchMode على "singleTop"، سيتلقّى النشاط القابل للبحث الغرض ACTION_SEARCH مع طلب إلى onNewIntent(Intent)، مع تمرير الغرض ACTION_SEARCH الجديد. على سبيل المثال، إليك كيفية التعامل مع هذه الحالة التي يكون فيها وضع تشغيل النشاط القابل للبحث هو "singleTop":

    Kotlin

    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.search)
    handleIntent(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    handleIntent(intent)
}

private fun handleIntent(intent: Intent) {
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

    Java

    @Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);
    handleIntent(getIntent());
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
    handleIntent(intent);
}

private void handleIntent(Intent intent) {
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

    مقارنةً بالرمز النموذجي في القسم حول إجراء عملية بحث، أصبح كل الرمز اللازم للتعامل مع نية البحث الآن في الطريقة handleIntent()، ما يتيح لكل من onCreate() وonNewIntent() تنفيذه.

    عندما يستدعي النظام onNewIntent(Intent)، لا تتم إعادة تشغيل النشاط، وبالتالي تعرض الطريقة getIntent() الغرض نفسه الذي تم تلقّيه باستخدام onCreate(). لهذا السبب، يجب استدعاء setIntent(Intent) داخل onNewIntent(Intent)، وذلك لتعديل الغرض الذي تم حفظه بواسطة النشاط في حال استدعاء getIntent() في المستقبل.

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

<activity android:name=".SearchableActivity"
          android:launchMode="singleTop" >
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    <meta-data
          android:name="android.app.searchable"
          android:resource="@xml/searchable"/>
  </activity>

تمرير بيانات سياق البحث

في بعض الحالات، يمكنك إجراء التحسينات اللازمة على طلب البحث داخل النشاط القابل للبحث لكل عملية بحث يتم إجراؤها. ومع ذلك، إذا أردت تحسين معايير البحث استنادًا إلى النشاط الذي يجري المستخدم بحثًا منه، يمكنك تقديم بيانات إضافية في الغرض الذي يرسله النظام إلى نشاطك القابل للبحث. يمكنك تمرير البيانات الإضافية في APP_DATA Bundle، والتي يتم تضمينها في الغرض ACTION_SEARCH.

لتمرير هذا النوع من البيانات إلى النشاط القابل للبحث، عليك إلغاء طريقة onSearchRequested() للنشاط الذي يمكن للمستخدم من خلاله إجراء بحث، وإنشاء Bundle باستخدام البيانات الإضافية، واستدعاء startSearch() لتفعيل مربّع حوار البحث. مثلاً:

Kotlin

override fun onSearchRequested(): Boolean {
    val appData = Bundle().apply {
        putBoolean(JARGON, true)
    }
    startSearch(null, false, appData, false)
    return true
}

Java

@Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }

يشير عرض القيمة "صحيح" إلى أنّك تعاملت بنجاح مع حدث معاودة الاتصال هذا واستدعيت startSearch() لتفعيل مربّع حوار البحث. بعد أن يرسل المستخدم طلب بحث، يتم تسليمه إلى نشاطك القابل للبحث مع البيانات التي تضيفها. يمكنك استخراج البيانات الإضافية من APP_DATA Bundle لتحسين البحث، كما هو موضّح في المثال التالي:

Kotlin

val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false

Java

Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}

استخدام تطبيق البحث المصغَّر

صورة تعرض طريقة عرض البحث في الشريط العلوي للتطبيق

الشكل 1. SearchViewالتطبيق المصغّر كطريقة عرض إجراء في شريط التطبيق

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

ضبط إعدادات أداة البحث

بعد إنشاء إعدادات البحث ونشاط قابل للبحث، فعِّل ميزة البحث بمساعدة الذكاء الاصطناعي لكل SearchView من خلال استدعاء setSearchableInfo() وتمرير عنصر SearchableInfo الذي يمثّل إعدادات البحث القابلة للبحث.

يمكنك الحصول على مرجع إلى SearchableInfo من خلال الاتصال بالرقم getSearchableInfo() على SearchManager.

على سبيل المثال، إذا كنت تستخدم SearchView كطريقة عرض إجراء في شريط التطبيق، فعِّل الأداة أثناء عملية ردّ الاتصال onCreateOptionsMenu()، كما هو موضّح في المثال التالي:

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    // Inflate the options menu from XML.
    val inflater = menuInflater
    inflater.inflate(R.menu.options_menu, menu)

    // Get the SearchView and set the searchable configuration.
    val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
    (menu.findItem(R.id.menu_search).actionView as SearchView).apply {
        // Assumes current activity is the searchable activity.
        setSearchableInfo(searchManager.getSearchableInfo(componentName))
        setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default.
    }

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the options menu from XML.
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options_menu, menu);

    // Get the SearchView and set the searchable configuration.
    SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE);
    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
    // Assumes current activity is the searchable activity.
    searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName()));
    searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default.

    return true;
}

تم الآن ضبط تطبيق البحث المصغّر، وسيرسل النظام طلبات البحث إلى النشاط القابل للبحث. يمكنك أيضًا تفعيل اقتراحات البحث لتطبيق البحث المصغّر.

لمزيد من المعلومات حول طرق عرض الإجراءات في شريط التطبيق، يُرجى الاطّلاع على استخدام طرق عرض الإجراءات وموفّري الإجراءات.

ميزات أخرى لتطبيق "بحث Google" المصغّر

يوفّر التطبيق المصغّر SearchView بعض الميزات الإضافية التي قد تحتاج إليها:

زر إرسال
لا يتوفّر زر لإرسال طلب بحث تلقائيًا، لذا على المستخدم الضغط على مفتاح Return في لوحة المفاتيح لبدء البحث. يمكنك إضافة زر "إرسال" من خلال استدعاء setSubmitButtonEnabled(true).
تحسين طلب البحث لاقتراحات البحث
عند تفعيل اقتراحات البحث، تتوقّع عادةً أن يختار المستخدمون اقتراحًا، ولكن قد يريدون أيضًا تحسين طلب البحث المقترَح. يمكنك إضافة زر بجانب كل اقتراح يدرج الاقتراح في مربّع البحث ليتمكّن المستخدم من تحسينه من خلال استدعاء setQueryRefinementEnabled(true).
إمكانية تبديل مستوى ظهور مربّع البحث
يكون تطبيق البحث المصغّر "مختصرًا" تلقائيًا، أي أنّه يتم تمثيله فقط برمز البحث، وهو عبارة عن عدسة مكبّرة. ويتم توسيعه لعرض مربّع البحث عندما ينقر المستخدم على الرمز. كما هو موضّح في المثال السابق، يمكنك عرض مربّع البحث تلقائيًا من خلال استدعاء setIconifiedByDefault(false). يمكنك أيضًا تبديل مظهر التطبيق المصغّر الخاص بالبحث من خلال استدعاء setIconified().

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

استخدام كلّ من التطبيق المصغّر ومربّع الحوار

إذا أدرجت أداة البحث في شريط التطبيق كـ طريقة عرض للإجراء وفعّلت إمكانية ظهورها في شريط التطبيق إذا توفّرت مساحة، وذلك من خلال ضبط android:showAsAction="ifRoom"، قد لا تظهر أداة البحث كطريقة عرض للإجراء. بدلاً من ذلك، قد يظهر عنصر قائمة في قائمة الخيارات الإضافية. على سبيل المثال، عندما يتم تشغيل تطبيقك على شاشة أصغر، قد لا يتوفّر مساحة كافية في شريط التطبيق لعرض أداة البحث مع عناصر الإجراءات أو عناصر التنقّل الأخرى، لذا يظهر عنصر القائمة بدلاً من ذلك في قائمة الخيارات الإضافية. عند وضع العنصر في القائمة الكاملة، يعمل كعنصر قائمة عادي ولا يعرض طريقة عرض الإجراء، أي أداة البحث.

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

لمزيد من المعلومات حول طريقة عمل العناصر في شريط التطبيق وكيفية التعامل مع هذه الحالة، راجِع مقالة إضافة شريط التطبيق.

إضافة ميزة "البحث الصوتي"

يمكنك إضافة وظيفة البحث الصوتي إلى مربّع الحوار أو الأداة المصغّرة الخاصة بالبحث من خلال إضافة السمة android:voiceSearchMode إلى الإعدادات القابلة للبحث. يؤدي ذلك إلى إضافة زر بحث صوتي يطلق طلبًا صوتيًا. عندما ينتهي المستخدم من التحدّث، يتم إرسال طلب البحث المحوّل إلى نص إلى نشاطك القابل للبحث.

يظهر ذلك في المثال التالي:

<?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:voiceSearchMode="showVoiceSearchButton|launchRecognizer" >
</searchable>

القيمة showVoiceSearchButton مطلوبة لتفعيل البحث الصوتي. تحدّد القيمة الثانية، launchRecognizer، أنّه يجب أن يطلق زر البحث الصوتي أداة التعرّف التي تعرض النص المحوّل إلى كلام في النشاط القابل للبحث.

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

إضافة اقتراحات البحث

يمكن أن يقدّم كلّ من مربّع حوار البحث وأداة البحث اقتراحات بحث أثناء كتابة المستخدم، وذلك بمساعدة نظام التشغيل Android. يدير النظام قائمة الاقتراحات ويتعامل مع الحدث عندما يختار المستخدم اقتراحًا.

يمكنك تقديم نوعَين من اقتراحات البحث:

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