وقتی آمادهاید تا قابلیت جستجو را به برنامه خود اضافه کنید، اندروید به شما کمک میکند تا رابط کاربری را با یک کادر محاورهای جستجو که در بالای پنجره فعالیت ظاهر میشود یا یک ویجت جستجو که میتوانید در طرح خود وارد کنید، پیادهسازی کنید. هم کادر محاورهای جستجو و هم ویجت میتوانند عبارت جستجوی کاربر را به یک فعالیت خاص در برنامه شما تحویل دهند. به این ترتیب، کاربر میتواند جستجو را از هر فعالیتی که کادر محاورهای یا ویجت جستجو در آن موجود است، آغاز کند و سیستم، فعالیت مناسب را برای انجام جستجو و ارائه نتایج آغاز میکند.
سایر ویژگیهای موجود برای کادر محاورهای جستجو و ویجت عبارتند از:
- جستجوی صوتی
- پیشنهادات جستجو بر اساس پرس و جوهای اخیر
- پیشنهادهای جستجویی که با نتایج واقعی در دادههای برنامه شما مطابقت دارند
این سند نحوه تنظیم برنامه شما را برای ارائه یک رابط جستجو که توسط سیستم اندروید برای ارائه پرسوجوهای جستجو، با استفاده از کادر محاورهای جستجو یا ویجت جستجو، پشتیبانی میشود، نشان میدهد.
منابع مرتبط:
اصول اولیه
قبل از شروع، تصمیم بگیرید که آیا میخواهید رابط جستجوی خود را با استفاده از کادر محاورهای جستجو یا ویجت جستجو پیادهسازی کنید. آنها ویژگیهای جستجوی یکسانی را ارائه میدهند، اما به روشهای کمی متفاوت:
- کادر محاورهای جستجو یک کامپوننت رابط کاربری است که توسط سیستم اندروید کنترل میشود. وقتی توسط کاربر فعال میشود، کادر محاورهای جستجو در بالای activity ظاهر میشود.
سیستم اندروید تمام رویدادهای موجود در کادر محاورهای جستجو را کنترل میکند. وقتی کاربر یک پرسوجو ارسال میکند، سیستم پرسوجو را به فعالیتی که شما برای مدیریت جستجوها مشخص کردهاید، ارسال میکند. این کادر محاورهای همچنین میتواند در حین تایپ کاربر، پیشنهادات جستجو را ارائه دهد.
- ویجت جستجو نمونهای از
SearchViewاست که میتوانید آن را در هر جایی از طرحبندی خود قرار دهید. به طور پیشفرض، ویجت جستجو مانند یک ویجت استانداردEditTextرفتار میکند و هیچ کاری انجام نمیدهد، اما میتوانید آن را طوری پیکربندی کنید که سیستم اندروید تمام رویدادهای ورودی را مدیریت کند، پرسوجوها را به فعالیت مربوطه تحویل دهد و پیشنهادات جستجو را ارائه دهد - درست مانند کادر محاورهای جستجو.
وقتی کاربر از طریق کادر محاورهای جستجو یا ویجت جستجو، جستجویی را انجام میدهد، سیستم یک Intent ایجاد کرده و کوئری کاربر را در آن ذخیره میکند. سپس سیستم، activity ای را که شما برای مدیریت جستجوها تعریف کردهاید - "searchable activity" - آغاز میکند و intent را به آن تحویل میدهد. برای تنظیم برنامه خود برای این نوع جستجوی کمکی، به موارد زیر نیاز دارید:
- پیکربندی جستجو
- یک فایل XML که برخی تنظیمات را برای کادر محاورهای یا ویجت جستجو پیکربندی میکند. این فایل شامل تنظیماتی برای ویژگیهایی مانند جستجوی صوتی، پیشنهاد جستجو و متن راهنما برای کادر جستجو است.
- یک فعالیت قابل جستجو
Activityکه عبارت جستجو را دریافت میکند، دادههای شما را جستجو میکند و نتایج جستجو را نمایش میدهد.- رابط جستجو، که توسط یکی از موارد زیر ارائه میشود:
- کادر محاورهای جستجو
- به طور پیشفرض، کادر جستجو پنهان است. وقتی تابع
onSearchRequested()را فراخوانی میکنید و کاربر دکمه جستجو را لمس میکند، کادر جستجو در بالای صفحه ظاهر میشود.- یک ویجت
SearchView- استفاده از ویجت جستجو به شما امکان میدهد کادر جستجو را در هر جایی از فعالیت خود، از جمله به عنوان نمای اکشن در نوار برنامه، قرار دهید.
- یک ویجت
ادامهی این سند به شما نشان میدهد که چگونه پیکربندی جستجو و فعالیت قابل جستجو را ایجاد کنید و چگونه یک رابط جستجو را با کادر محاورهای جستجو یا ویجت جستجو پیادهسازی کنید.
ایجاد پیکربندی قابل جستجو
اولین چیزی که نیاز دارید یک فایل XML به نام پیکربندی جستجو است. این فایل جنبههای خاصی از رابط کاربری کادر محاورهای یا ویجت جستجو را پیکربندی میکند و نحوه رفتار ویژگیهایی مانند پیشنهادات و جستجوی صوتی را تعریف میکند. این فایل به طور سنتی searchable.xml نام دارد و باید در دایرکتوری res/xml/ project ذخیره شود.
فایل پیکربندی جستجو باید شامل عنصر <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 در برنامه شماست که جستجوها را بر اساس یک رشته پرسوجو انجام میدهد و نتایج جستجو را ارائه میدهد.
وقتی کاربر در کادر محاورهای یا ویجت جستجو، جستجویی انجام میدهد، سیستم activity قابل جستجو (searchable activity) شما را آغاز میکند و کوئری جستجو را در یک Intent با اکشن ACTION_SEARCH به آن تحویل میدهد. activity قابل جستجوی شما، کوئری را از QUERY extra مربوط به intent بازیابی میکند، سپس دادههای شما را جستجو کرده و نتایج را ارائه میدهد.
از آنجا که میتوانید کادر محاورهای یا ویجت جستجو را در هر اکتیویتی دیگری در برنامه خود قرار دهید، سیستم باید بداند کدام اکتیویتی، اکتیویتی قابل جستجو شماست تا بتواند به درستی عبارت جستجو را ارائه دهد. بنابراین، ابتدا اکتیویتی قابل جستجو خود را در فایل مانیفست اندروید تعریف کنید.
یک فعالیت قابل جستجو اعلام کنید
اگر از قبل فعالیتی ندارید، یک Activity ایجاد کنید که جستجوها را انجام داده و نتایج را ارائه دهد. هنوز نیازی به پیادهسازی قابلیت جستجو ندارید - فقط یک Activity ایجاد کنید که بتوانید آن را در manifest تعریف کنید. درون عنصر <activity> در manifest، موارد زیر را انجام دهید:
- اکتیویتی را طوری تعریف کنید که قصد
ACTION_SEARCHرا در یک عنصر<intent-filter>بپذیرد. - پیکربندی جستجو را برای استفاده در عنصر
<meta-data>مشخص کنید.
این در مثال زیر نشان داده شده است:
<application ... > < activity android:name=".SearchableActivity&quo<t; > intent-filt<er> action android:name="android.intent.ac<tion.SEARCH" /> < /intent-filter> meta-data android:name="android.app.searchable" < android:resourc<e="@xml/searchable"/> /activity> ... /application>
عنصر <meta-data> باید شامل ویژگی android:name با مقدار "android.app.searchable" و ویژگی android:resource با ارجاع به فایل پیکربندی searchable باشد. در مثال قبلی، به فایل res/xml/searchable.xml اشاره دارد.
انجام جستجو
پس از اینکه اکتیویتی قابل جستجو را در مانیفست تعریف کردید، برای انجام جستجو در اکتیویتی قابل جستجو، این مراحل را دنبال کنید:
دریافت استعلام
وقتی کاربری از طریق کادر محاورهای جستجو یا ویجت جستجو میکند، سیستم activity قابل جستجو را شروع میکند و یک ACTION_SEARCH intent به آن ارسال میکند. این intent شامل عبارت جستجو در رشته QUERY اضافی است. هنگام شروع activity، این intent را بررسی کنید و رشته را استخراج کنید. برای مثال، در اینجا نحوه دریافت عبارت جستجو هنگام شروع activity قابل جستجو آورده شده است:
کاتلین
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- میتواند جستجوی قویتری را در دادههای متنی ارائه دهد و نتایج را به طور قابل توجهی سریعتر تولید کند. برای اطلاعات در مورد FTS3 به sqlite.org و برای اطلاعات در مورد SQLite در اندروید به کلاسSQLiteDatabaseمراجعه کنید. - اگر دادههای شما به صورت آنلاین ذخیره میشوند، ممکن است عملکرد جستجوی درک شده توسط اتصال داده کاربر مختل شود. شاید بخواهید تا زمان بازگشت جستجوی خود، یک نشانگر پیشرفت نمایش دهید. برای مرجع APIهای شبکه و
ProgressBarمربوط به نحوه نمایش نشانگر پیشرفت، بهandroid.netمراجعه کنید.
نتایج را ارائه دهید
صرف نظر از اینکه دادههای شما کجا هستند و چگونه آنها را جستجو میکنید، توصیه میکنیم نتایج جستجو را با استفاده از یک Adapter به activity قابل جستجوی خود برگردانید. به این ترتیب، میتوانید تمام نتایج جستجو را در یک RecyclerView ارائه دهید. اگر دادههای شما از یک کوئری پایگاه داده SQLite میآیند، میتوانید نتایج خود را با استفاده از CursorAdapter در یک RecyclerView اعمال کنید. اگر دادههای شما با فرمت متفاوتی میآیند، میتوانید یک افزونه از BaseAdapter ایجاد کنید.
یک Adapter هر آیتم از مجموعهای از دادهها را به یک شیء View متصل میکند. وقتی Adapter به یک RecyclerView اعمال میشود، هر قطعه داده به عنوان یک نمای جداگانه در لیست درج میشود. Adapter فقط یک رابط است، بنابراین پیادهسازیهایی مانند CursorAdapter - برای اتصال دادهها از یک Cursor - مورد نیاز است. اگر هیچ یک از پیادهسازیهای موجود برای دادههای شما کار نمیکند، میتوانید پیادهسازی خودتان را از BaseAdapter پیادهسازی کنید.
از کادر محاورهای جستجو استفاده کنید
کادر جستجوی جستجو، یک کادر جستجوی شناور در بالای صفحه نمایش میدهد که آیکون برنامه در سمت چپ آن قرار دارد. کادر جستجوی جستجو میتواند همزمان با تایپ کاربر، پیشنهادات جستجو را ارائه دهد. هنگامی که کاربر جستجویی را انجام میدهد، سیستم عبارت جستجو را به یک activity قابل جستجو ارسال میکند که جستجو را انجام میدهد.
به طور پیشفرض، کادر جستجو تا زمانی که کاربر آن را فعال نکند، پنهان است. برنامه شما میتواند با فراخوانی 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&quo<t; > intent-filt<er> action android:name="android.intent.ac<tion.SEARCH" /> < /intent-filter> meta-data android:name="android.app.searchable" < android:reso<urce="@xml/searchable"/> /activity> !-- This activity enables the search dialo>g to <initiate searches in the SearchableActivity.< -- activity android:name=".OtherActivity" ... > !-- Ena<ble the search dialog to send searches to SearchableActivity. --> meta-data android:name="androi>d.app<.default_searchable<" android:value=".SearchableActivity" / /activity> ... /application>
از آنجایی که OtherActivity اکنون شامل یک عنصر <meta-data> برای اعلام اینکه کدام فعالیت قابل جستجو برای جستجوها استفاده شود، میباشد، این فعالیت، کادر محاورهای جستجو را فعال میکند. اگرچه کاربر در این فعالیت است، اما متد onSearchRequested() کادر محاورهای جستجو را فعال میکند. هنگامی که کاربر جستجو را انجام میدهد، سیستم SearchableActivity شروع کرده و هدف ACTION_SEARCH به آن تحویل میدهد.
اگر میخواهید هر اکتیویتی در برنامه شما، کادر محاورهای جستجو را ارائه دهد، به جای هر <activity> ، عنصر <meta-data> قبلی را به عنوان فرزند عنصر <application> وارد کنید. به این ترتیب، هر اکتیویتی مقدار را به ارث میبرد، کادر محاورهای جستجو را ارائه میدهد و جستجوها را به همان اکتیویتی قابل جستجو تحویل میدهد. اگر چندین اکتیویتی قابل جستجو دارید، میتوانید با قرار دادن یک تعریف <meta-data> متفاوت در داخل هر اکتیویتی، فعالیت پیشفرض قابل جستجو را لغو کنید.
با فعال شدن کادر محاورهای جستجو برای فعالیتهای شما، برنامه شما آماده انجام جستجوها است.
فراخوانی کادر محاورهای جستجو
اگرچه برخی از دستگاهها یک دکمه جستجوی اختصاصی ارائه میدهند، اما رفتار این دکمه ممکن است بین دستگاهها متفاوت باشد و بسیاری از دستگاهها اصلاً دکمه جستجو ارائه نمیدهند. بنابراین هنگام استفاده از کادر محاورهای جستجو، باید یک دکمه جستجو در رابط کاربری خود ارائه دهید که با فراخوانی onSearchRequested() کادر محاورهای جستجو را فعال کند.
برای مثال، یک دکمه جستجو در منوی گزینهها یا طرح رابط کاربری خود اضافه کنید که onSearchRequested() را فراخوانی کند.
همچنین میتوانید قابلیت "type-to-search" را فعال کنید، که با شروع تایپ کاربر روی صفحه کلید، کادر جستجو را فعال میکند. کلیدهای فشرده شده در کادر جستجو درج میشوند. میتوانید با فراخوانی setDefaultKeyMode یا DEFAULT_KEYS_SEARCH_LOCAL در طول متد onCreate() در activity خود، قابلیت type-to-search را در activity خود فعال کنید.
تأثیر کادر محاورهای جستجو بر چرخه حیات فعالیت شما
کادر محاورهای جستجو، یک 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()دریافت میکند و یک نمونه جدید از اکتیویتی به بالای پشته اکتیویتی آورده میشود. اکنون دو نمونه از اکتیویتی قابل جستجوی شما در پشته اکتیویتی وجود دارد، بنابراین ضربه زدن روی دکمه Back شما را به نمونه قبلی اکتیویتی قابل جستجو برمیگرداند، به جای اینکه از اکتیویتی قابل جستجو خارج شوید. - اگر
android:launchModeروی"singleTop"تنظیم کنید، آنگاه activity قابل جستجو، هدفACTION_SEARCHرا با فراخوانیonNewIntent(Intent)دریافت میکند و هدف جدیدACTION_SEARCHرا ارسال میکند. برای مثال، در اینجا نحوه مدیریت این مورد را نشان میدهیم که در آن حالت راهاندازی activity قابل جستجو"singleTop"است:کاتلین
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) } } }
جاوا
@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()همان intent ای را که باonCreate()دریافت میشود، برمیگرداند. به همین دلیل است که بایدsetIntent(Intent)درونonNewIntent(Intent)فراخوانی کنید: تا intent ذخیره شده توسط اکتیویتی در صورت فراخوانیgetIntent()در آینده بهروزرسانی شود.
سناریوی دوم، استفاده از حالت راهاندازی "singleTop" ، معمولاً ترجیح داده میشود، زیرا پس از انجام جستجو، کاربر ممکن است جستجوهای اضافی انجام دهد و شما نمیخواهید برنامه شما چندین نمونه از activity قابل جستجو ایجاد کند. توصیه میکنیم activity قابل جستجوی خود را در مانیفست برنامه روی حالت راهاندازی "singleTop" تنظیم کنید، همانطور که در مثال زیر نشان داده شده است:
<activity android:name=".SearchableActivity" android:launchMode="si<ngleTop" > <intent-filter> action android:name="androi<d.intent.action.SEAR<CH" /> /intent-filter> meta-data android:name="android.app.searchable&quo<t; android:resource="@xml/searchable"/> /activity>
دادههای زمینه جستجو را ارسال کنید
در برخی موارد، میتوانید اصلاحات لازم را در کوئری جستجو درون اکتیویتی قابل جستجو برای هر جستجوی انجام شده انجام دهید. با این حال، اگر میخواهید معیارهای جستجوی خود را بر اساس اکتیویتی که کاربر از آن جستجو را انجام میدهد، اصلاح کنید، میتوانید دادههای اضافی را در intent که سیستم به اکتیویتی قابل جستجوی شما ارسال میکند، ارائه دهید. میتوانید دادههای اضافی را در APP_DATA Bundle که در intent ACTION_SEARCH گنجانده شده است، ارسال کنید.
برای ارسال این نوع دادهها به activity قابل جستجو، متد onSearchRequested() را برای activity که کاربر میتواند از طریق آن جستجو انجام دهد، override کنید، یک 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; }
برگرداندن مقدار true نشان میدهد که شما با موفقیت این رویداد فراخوانی را مدیریت کردهاید و تابع startSearch() را برای فعال کردن کادر محاورهای جستجو فراخوانی کردهاید. پس از ارسال درخواست توسط کاربر، این درخواست به همراه دادههایی که اضافه میکنید به activity قابل جستجوی شما تحویل داده میشود. میتوانید دادههای اضافی را از 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); }
استفاده از ویجت جستجو
شکل ۱. ویجت SearchView به عنوان یک نمای عملیاتی در نوار برنامه.
ویجت جستجو همان عملکرد کادر محاورهای جستجو را ارائه میدهد. این ویجت وقتی کاربر جستجویی را انجام میدهد، فعالیت مربوطه را آغاز میکند و میتواند پیشنهادهای جستجو را ارائه دهد و جستجوی صوتی انجام دهد. اگر قرار دادن ویجت جستجو در نوار برنامه برای شما امکانپذیر نیست، میتوانید ویجت جستجو را در جایی از طرحبندی فعالیت خود قرار دهید.
پیکربندی ابزارک جستجو
پس از ایجاد پیکربندی جستجو و یک فعالیت قابل جستجو ، با فراخوانی تابع setSearchableInfo() و ارسال شیء SearchableInfo که نشاندهنده پیکربندی قابل جستجوی شماست، جستجوی کمکی را برای هر SearchView فعال کنید.
شما میتوانید با فراخوانی تابع getSearchableInfo() در SearchManager به SearchableInfo ارجاع دهید.
برای مثال، اگر از 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; }
ویجت جستجو اکنون پیکربندی شده است و سیستم، درخواستهای جستجو را به فعالیت جستجوی شما ارسال میکند. همچنین میتوانید پیشنهادهای جستجو را برای ویجت جستجو فعال کنید.
برای اطلاعات بیشتر در مورد نماهای اکشن در نوار برنامه، به بخش «استفاده از نماهای اکشن و ارائه دهندگان اکشن» مراجعه کنید.
سایر ویژگیهای ویجت جستجو
ویجت SearchView چند ویژگی اضافی که ممکن است بخواهید را ارائه میدهد:
- یک دکمه ارسال
- به طور پیشفرض، هیچ دکمهای برای ارسال یک عبارت جستجو وجود ندارد، بنابراین کاربر باید کلید Return را روی صفحه کلید فشار دهد تا جستجو را آغاز کند. میتوانید با فراخوانی
setSubmitButtonEnabled(true)یک دکمه "ارسال" اضافه کنید. - اصلاح پرسوجو برای پیشنهادهای جستجو
- وقتی پیشنهادهای جستجو را فعال میکنید، معمولاً انتظار دارید کاربران یک پیشنهاد را انتخاب کنند، اما ممکن است بخواهند عبارت جستجوی پیشنهادی را نیز اصلاح کنند. میتوانید با فراخوانی
setQueryRefinementEnabled(true)یک دکمه در کنار هر پیشنهاد اضافه کنید که پیشنهاد را در کادر جستجو برای اصلاح توسط کاربر وارد کند. - امکان تغییر وضعیت نمایش کادر جستجو
- به طور پیشفرض، ویجت جستجو "آیکوندار" است، به این معنی که فقط با یک آیکون جستجو - یک ذرهبین - نمایش داده میشود. وقتی کاربر روی آیکون ضربه میزند، این آیکون برای نمایش کادر جستجو باز میشود. همانطور که در مثال قبلی نشان داده شد، میتوانید با فراخوانی
setIconifiedByDefault(false)کادر جستجو را به طور پیشفرض نمایش دهید. همچنین میتوانید با فراخوانیsetIconified()ظاهر ویجت جستجو را تغییر دهید.
چندین API دیگر در کلاس SearchView وجود دارد که به شما امکان سفارشیسازی ویجت جستجو را میدهند. با این حال، اکثر آنها فقط زمانی استفاده میشوند که خودتان تمام ورودیهای کاربر را مدیریت کنید، به جای اینکه از سیستم اندروید برای ارائه درخواستهای جستجو و نمایش پیشنهادات جستجو استفاده کنید.
از ویجت و پنجره گفتگو همزمان استفاده کنید
اگر ویجت جستجو را به عنوان یک نمای اکشن در نوار برنامه قرار دهید و در صورت وجود فضای کافی - با تنظیم android:showAsAction="ifRoom" - آن را طوری تنظیم کنید که در نوار برنامه ظاهر شود، ممکن است ویجت جستجو به عنوان یک نمای اکشن ظاهر نشود. در عوض، یک آیتم منو ممکن است در منوی سرریز ظاهر شود. به عنوان مثال، وقتی برنامه شما روی صفحه نمایش کوچکتری اجرا میشود، ممکن است فضای کافی در نوار برنامه برای نمایش ویجت جستجو به همراه سایر آیتمهای اکشن یا عناصر ناوبری وجود نداشته باشد، بنابراین آیتم منو در منوی سرریز ظاهر میشود. وقتی در منوی سرریز قرار میگیرد، مانند یک آیتم منوی معمولی عمل میکند و نمای اکشن - یعنی ویجت جستجو - را نمایش نمیدهد.
برای مدیریت این وضعیت، آیتم منویی که ویجت جستجو را به آن متصل میکنید، باید وقتی کاربر آن را از منوی سرریز انتخاب میکند، کادر محاورهای جستجو را فعال کند. برای انجام این کار، متد onOptionsItemSelected() را برای مدیریت آیتم منوی "جستجو" پیادهسازی کنید و با فراخوانی onSearchRequested() کادر محاورهای جستجو را باز کنید.
برای اطلاعات بیشتر در مورد نحوه عملکرد موارد موجود در نوار برنامه و نحوه مدیریت این وضعیت، به افزودن نوار برنامه مراجعه کنید.
اضافه کردن جستجوی صوتی
شما میتوانید با اضافه کردن ویژگی android:voiceSearchMode به پیکربندی قابل جستجو، قابلیت جستجوی صوتی را به کادر محاورهای یا ویجت جستجوی خود اضافه کنید. این کار یک دکمه جستجوی صوتی اضافه میکند که یک پیام صوتی را اجرا میکند. وقتی کاربر صحبت خود را تمام کرد، عبارت جستجوی رونویسی شده به activity قابل جستجوی شما ارسال میشود.
این در مثال زیر نشان داده شده است:
<?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:voiceS<earchMode="showVoiceSearchButton|launchRecognizer" > /searchable>
مقدار showVoiceSearchButton برای فعال کردن جستجوی صوتی مورد نیاز است. مقدار دوم، launchRecognizer ، مشخص میکند که دکمه جستجوی صوتی باید یک تشخیصدهنده را اجرا کند که متن رونویسی شده را به فعالیت قابل جستجو بازگرداند.
شما میتوانید ویژگیهای اضافی برای مشخص کردن رفتار جستجوی صوتی، مانند زبان مورد انتظار و حداکثر تعداد نتایج قابل نمایش، ارائه دهید. برای اطلاعات بیشتر در مورد ویژگیهای موجود، به مرجع پیکربندی جستجو مراجعه کنید.
افزودن پیشنهادهای جستجو
هم کادر محاورهای جستجو و هم ویجت جستجو میتوانند با کمک سیستم اندروید، همزمان با تایپ کاربر، پیشنهادهای جستجو ارائه دهند. سیستم، فهرست پیشنهادها را مدیریت میکند و رویداد انتخاب یک پیشنهاد توسط کاربر را مدیریت میکند.
شما میتوانید دو نوع پیشنهاد جستجو ارائه دهید:
- پیشنهادات جستجوی پرس و جوهای اخیر
- این پیشنهادات کلماتی هستند که کاربر قبلاً به عنوان عبارات جستجو در برنامه شما استفاده کرده است. برای اطلاعات بیشتر به افزودن پیشنهادات جستجوی سفارشی مراجعه کنید.
- پیشنهادهای جستجوی سفارشی
- اینها پیشنهادهای جستجویی هستند که شما از منبع داده خودتان ارائه میدهید تا به کاربران کمک کنید فوراً املای صحیح یا مورد مورد نظر خود را انتخاب کنند. برای اطلاعات بیشتر به افزودن پیشنهادهای جستجوی سفارشی مراجعه کنید.