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

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

ننصحك باستخدام أداة 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() لنشاطك:

Kotlin

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

    return true
}

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

صورة تعرض شاشة فارغة مع رمز بحث في شريط التطبيق العلوي
الشكل 1 رمز بحث في شريط التطبيق العلوي

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

صورة تعرض طريقة عرض البحث أثناء الاستخدام
الشكل 2 أداة 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):

Kotlin

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().

Kotlin

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، حيث يمكنك استخدامه في طبقات أخرى من بنيتك لاسترداد نتائج البحث لعرضها.