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

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

وتشمل الميزات الأخرى المتاحة لمربّع حوار البحث والتطبيقات المصغّرة ما يلي:

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

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

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

• رموز التصميم المتعدد الأبعاد

الأساسيّات

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

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

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

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

عندما ينفّذ المستخدم عملية بحث من مربّع حوار البحث أو أداة بحث، ينشئ النظام Intent ويخزِّن طلب بحث المستخدم فيه. يبدأ النظام بعد ذلك النشاط الذي تعلن عنه للتعامل مع عمليات البحث - أي "النشاط القابل للبحث" - ويحقق الغرض منه. لإعداد تطبيقك لهذا النوع من البحث المدعوم، عليك توفير ما يلي:

إعدادات بحث

ملف XML يضبط بعض إعدادات مربّع حوار البحث أو التطبيق المصغّر ويتضمن إعدادات لميزات مثل البحث الصوتي واقتراح البحث ونص التلميح لمربّع البحث.

نشاط يمكن البحث فيه

Activity الذي يتلقّى طلب البحث ويبحث في بياناتك ويعرض نتائج البحث.

واجهة بحث يتم تقديمها من خلال أي مما يلي:

مربع حوار البحث

يكون مربّع حوار البحث مخفيًا بشكل تلقائي. تظهر في أعلى الشاشة عند طلب رمز onSearchRequested() عندما ينقر المستخدم على زر بحث.

تطبيق SearchView المصغّر

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

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

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

أول ما تحتاج إليه هو ملف 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 هي السمة الوحيدة المطلوبة. إنه يشير إلى مورد سلسلة، والذي يجب أن يكون اسم التطبيق. لن يكون هذا التصنيف مرئيًا للمستخدم حتى يتم تفعيل اقتراحات البحث لـ "مربع البحث السريع"، حيث يكون التصنيف مرئيًا في قائمة العناصر القابلة للبحث ضمن إعدادات النظام.

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

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

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

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

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

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

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

إذا لم يكن لديك عنوان URL من قبل، أنشِئ 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. يتضمّن هذا الغرض طلب البحث في سلسلة QUERY إضافية. تحقَّق من هذا الهدف عند بدء النشاط، ثم استخرِج السلسلة. على سبيل المثال، إليك كيفية الحصول على طلب البحث عند بدء نشاطك في البحث:

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

@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. إذا كنت تريد عرض مربّع حوار البحث وتقديم عمليات البحث في SearchableActivity ضمن نشاط منفصل، مثل نشاط باسم OtherActivity، يجب الإشارة في البيان إلى أنّ 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الشكل 1. الأداة SearchView على شكل عرض إجراء في شريط التطبيقات

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

ضبط تطبيق "بحث Google" المصغّر

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

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

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

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
}

@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). يمكنك أيضًا تبديل شكل تطبيق "بحث Google" المصغّر من خلال طلب الرقم setIconified().

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

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

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

للتعامل مع هذا الموقف، يجب أن ينشط عنصر القائمة الذي يتم إرفاق أداة البحث به مربع حوار البحث عندما يختاره المستخدم من القائمة الكاملة. لتحقيق ذلك، نفِّذ 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. يدير النظام قائمة الاقتراحات ويعالج الحدث الذي يتم فيه اختيار المستخدم لاقتراح ما.

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

اقتراحات البحث الأخيرة لطلب البحث

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

اقتراحات البحث المخصّص

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