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

تجربة طريقة "الكتابة"
‫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_SEARCHintent. يحمل هذا الغرض طلب البحث في السلسلة 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().

يمكنك أيضًا تفعيل وظيفة "الكتابة للبحث" التي تفعّل مربّع حوار البحث عندما يبدأ المستخدم في الكتابة على لوحة المفاتيح. يتم إدراج ضغطات المفاتيح في مربّع حوار البحث. يمكنك تفعيل ميزة &quot;الكتابة للبحث&quot; في نشاطك من خلال استدعاء 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()، كما هو موضّح في مقدمة عن الأنشطة. ومع ذلك، إذا كان النشاط الحالي هو النشاط القابل للبحث، سيحدث أحد الأمرين التاليين:

  • تتلقّى السمة searchable النشاط 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. يدير النظام قائمة الاقتراحات ويتعامل مع الحدث عندما يختار المستخدم اقتراحًا.

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

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