إعداد واجهة البحث

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تجربة ميزة "الكتابة"

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

فلترة قائمة →

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

إضافة SearchView إلى شريط التطبيق

لإضافة تطبيق مصغّر SearchView إلى شريط التطبيقات، أنشئ ملفًا في مشروعك باسم res/menu/options_menu.xml وأضِف الرمز التالي إلى الملف. يحدّد هذا الرمز كيفية إنشاء عنصر البحث، مثل الرمز الذي يجب استخدامه وعنوان العنصر. تتيح لك سمة collapseActionView توسيع SearchView ليشغل مساحة شريط التطبيق بالكامل ثم تصغيره مرة أخرى إلى عنصر عادي في شريط التطبيق عندما لا يكون قيد الاستخدام. بسبب محدودية المساحة في شريط التطبيقات على الأجهزة الجوّالة، ننصحك باستخدام السمة collapsibleActionView لتوفير تجربة أفضل للمستخدم.

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/search"
        android:title="@string/search_title"
        android:icon="@drawable/ic_search"
        android:showAsAction="collapseActionView|ifRoom"
        android:actionViewClass="androidx.appcompat.widget.SearchView" />
</menu>

إذا كنت تريد رمز بحث يسهل الوصول إليه، أنشئ ملفًا بتنسيق ic_search.xml في المجلد /res/drawable و أدرِج الرمز التالي فيه:

<vector
    android:height="24dp"
    android:tint="#000000"
    android:viewportHeight="24"
    android:viewportWidth="24"
    android:width="24dp"
    xmlns:android="http://schemas.android.com/apk/res/android">
        <path android:fillColor="@android:color/white" android:pathData="M15.5,14h-0.79l-0.28,-0.27C15.41,12.59 16,11.11 16,9.5 16,5.91 13.09,3 9.5,3S3,5.91 3,9.5 5.91,16 9.5,16c1.61,0 3.09,-0.59 4.23,-1.57l0.27,0.28v0.79l5,4.99L20.49,19l-4.99,-5zM9.5,14C7.01,14 5,11.99 5,9.5S7.01,5 9.5,5 14,7.01 14,9.5 11.99,14 9.5,14z"/>
</vector>

لعرض الرمز SearchView في شريط التطبيق، عليك تضخيم ملف XML الذي يحتوي على مصدر القائمة res/menu/options_menu.xml في onCreateOptionsMenu() طريقة نشاطك:

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    menuInflater.inflate(R.menu.options_menu, menu)

    return true
}

يؤدي تشغيل التطبيق إلى إنشاء ما يلي:

يظهر الرمز SearchView في شريط التطبيقات في تطبيقك، ولكنه ليس وظيفيًا. في حال النقر على رمز البحث، ستظهر لك رسالة مشابهة لما يلي:

لجعل SearchView وظيفيًا، عليك تحديد سلوك SearchView.

إنشاء إعدادات بحث

تحدِّد إعدادات البحث سلوك SearchView ويتم تحديدها في ملف res/xml/searchable.xml. يجب أن تحتوي إعدادات البحث على سمة android:label على الأقل لها القيمة نفسها لسمة android:label في عنصر <application> أو <activity> في ملف بيان Android. ومع ذلك، ننصحك أيضًا بإضافة سمة android:hint لتزويد المستخدم بفكرة عن ما يجب إدخاله في مربّع البحث.

<?xml version="1.0" encoding="utf-8"?>

<searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_name"
        android:hint="@string/search_hint" />

في ملف بيان تطبيقك، حدِّد عنصر <meta-data> يشير إلى ملف res/xml/searchable.xml. حدِّد العنصر في <activity> الذي تريد عرض SearchView فيه.

<activity
android:name=".SearchResultsActivity"
android:exported="false"
android:label="@string/title_activity_search_results"
android:launchMode="singleTop"
android:theme="@style/Theme.AppCompat.Light">
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    <meta-data
        android:name="android.app.searchable"
        android:resource="@xml/searchable" />
</activity>

في طريقة onCreateOptionsMenu() التي تنشئها، اربط إعدادات البحث بـ SearchView من خلال استدعاء setSearchableInfo(SearchableInfo):

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    menuInflater.inflate(R.menu.options_menu, menu)

    val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
    val searchView = menu.findItem(R.id.search).actionView as SearchView
    val component = ComponentName(this, SearchResultsActivity::class.java)
    val searchableInfo = searchManager.getSearchableInfo(component)
    searchView.setSearchableInfo(searchableInfo)
    return true
}

تحصل المكالمة إلى getSearchableInfo() على عنصر SearchableInfo يتم إنشاؤه من ملف XML الخاص بإعدادات البحث. عندما تكون إعدادات البحث مرتبطة بشكل صحيح بتطبيق SearchView ويُرسِل المستخدِم طلب بحث، يبدأ تطبيق SearchView نشاطًا بالهدف ACTION_SEARCH. بعد ذلك، ستحتاج إلى نشاط يمكنه الفلترة حسب هذا الغرض ومعالجة طلب البحث.

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

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

<activity android:name=".SearchResultsActivity" ... >
    ...
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    ...
</activity>

في نشاطك القابل للبحث، يمكنك معالجة طلب ACTION_SEARCH من خلال البحث عنه في onCreate() الطريقة.

class SearchResultsActivity : AppCompatActivity() {

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

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

    private fun handleIntent(intent: Intent) {
        if (Intent.ACTION_SEARCH == intent.action) {
            val query = intent.getStringExtra(SearchManager.QUERY)
            Log.d("SEARCH", "Search query was: $query")
        }
    }
}

الآن، يمكن لتطبيق SearchView قبول طلب بحث المستخدم وبدء نشاطك القابل للبحث باستخدام نية ACTION_SEARCH.

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