رابط جستجو را تنظیم کنید

روش نوشتن را امتحان کنید

Jetpack Compose ابزار رابط کاربری پیشنهادی برای اندروید است. یاد بگیرید که چگونه قابلیت جستجو را در 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() در activity خود inflate کنید:

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: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() که ایجاد می‌کنید، با فراخوانی setSearchableInfo(SearchableInfo) پیکربندی جستجو را با SearchView مرتبط کنید:

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 ارسال کنید، جایی که می‌توانید از آن در لایه‌های دیگر معماری خود برای بازیابی نتایج جستجو و نمایش آنها استفاده کنید.