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

وقتی آماده اضافه کردن قابلیت جستجو به برنامه خود هستید، Android به شما کمک می‌کند رابط کاربری را با یک گفتگوی جستجو که در بالای پنجره فعالیت ظاهر می‌شود یا یک ویجت جستجو که می‌توانید در طرح‌بندی خود وارد کنید، پیاده‌سازی کنید. هم گفتگوی جستجو و هم ویجت می توانند درخواست جستجوی کاربر را به یک فعالیت خاص در برنامه شما تحویل دهند. به این ترتیب کاربر می تواند از هر فعالیتی که گفتگو یا ویجت جستجو در دسترس است، جستجو را آغاز کند و سیستم فعالیت مناسب را برای انجام جستجو و ارائه نتایج آغاز می کند.

سایر ویژگی های موجود برای گفتگو و ویجت جستجو عبارتند از:

• جستجوی صوتی
• پیشنهادات جستجو بر اساس جستارهای اخیر
• جستجوی پیشنهادهایی که با نتایج واقعی در داده‌های برنامه شما مطابقت دارند

این سند نحوه راه‌اندازی برنامه خود را برای ارائه یک رابط جستجو که توسط سیستم Android برای ارائه عبارت‌های جستجو کمک می‌کند، با استفاده از گفتگوی جستجو یا ویجت جستجو نشان می‌دهد.

منابع مرتبط:

• نمادهای طراحی متریال

اصول اولیه

قبل از شروع، تصمیم بگیرید که آیا می خواهید رابط جستجوی خود را با استفاده از گفتگوی جستجو یا ویجت جستجو پیاده سازی کنید. آنها همان ویژگی های جستجو را ارائه می دهند، اما به روش های کمی متفاوت:

• گفتگوی جستجو یک جزء رابط کاربری است که توسط سیستم Android کنترل می شود. هنگامی که توسط کاربر فعال می شود، گفتگوی جستجو در بالای فعالیت ظاهر می شود.

  سیستم Android همه رویدادها را در گفتگوی جستجو کنترل می کند. هنگامی که کاربر یک پرس و جو ارسال می کند، سیستم پرس و جو را به فعالیتی که شما برای رسیدگی به جستجوها مشخص کرده اید تحویل می دهد. گفتگو همچنین می تواند پیشنهادات جستجو را در حین تایپ کاربر ارائه دهد.

• ویجت جستجو نمونه ای از SearchView است که می توانید آن را در هر نقطه از طرح بندی خود قرار دهید. به‌طور پیش‌فرض، ویجت جستجو مانند یک ویجت استاندارد EditText عمل می‌کند و کاری انجام نمی‌دهد، اما می‌توانید آن را به گونه‌ای پیکربندی کنید که سیستم Android تمام رویدادهای ورودی را مدیریت کند، پرس‌و‌جوها را به فعالیت مناسب تحویل دهد و پیشنهادات جستجو را ارائه دهد - درست مانند جستجو. گفتگو

هنگامی که کاربر جستجویی را از گفتگوی جستجو یا ویجت جستجو انجام می دهد، سیستم یک Intent ایجاد می کند و درخواست کاربر را در آن ذخیره می کند. سپس سیستم فعالیتی را که شما اعلام می‌کنید برای انجام جستجوها آغاز می‌کند - "فعالیت قابل جستجو" - و هدف را به آن تحویل می‌دهد. برای تنظیم برنامه خود برای این نوع جستجوی کمکی، به موارد زیر نیاز دارید:

یک پیکربندی جستجو

یک فایل XML که برخی تنظیمات را برای گفتگو یا ویجت جستجو پیکربندی می کند. این شامل تنظیماتی برای ویژگی‌هایی مانند جستجوی صوتی، پیشنهاد جستجو، و متن راهنمایی برای کادر جستجو است.

یک فعالیت قابل جستجو

Activity که عبارت جستجو را دریافت می کند، داده های شما را جستجو می کند و نتایج جستجو را نمایش می دهد.

یک رابط جستجو، ارائه شده توسط یکی از موارد زیر:

گفتگوی جستجو

به طور پیش فرض، گفتگوی جستجو پنهان است. هنگامی که کاربر onSearchRequested onSearchRequested() را می‌زند، در بالای صفحه ظاهر می‌شود.

ویجت SearchView

استفاده از ویجت جستجو به شما امکان می دهد کادر جستجو را در هر نقطه از فعالیت خود قرار دهید، از جمله به عنوان نمای کنشی در نوار برنامه.

بقیه این سند به شما نشان می دهد که چگونه پیکربندی جستجو و فعالیت قابل جستجو را ایجاد کنید و چگونه رابط جستجو را با گفتگوی جستجو یا ویجت جستجو پیاده سازی کنید.

یک پیکربندی قابل جستجو ایجاد کنید

اولین چیزی که نیاز دارید یک فایل XML به نام پیکربندی جستجو است. جنبه های UI خاصی از گفتگو یا ویجت جستجو را پیکربندی می کند و نحوه عملکرد ویژگی هایی مانند پیشنهادات و جستجوی صوتی را مشخص می کند. این فایل به طور سنتی 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 اضافی intent بازیابی می کند، سپس داده های شما را جستجو می کند و نتایج را ارائه می دهد.

از آنجایی که می‌توانید گفتگو یا ویجت جستجو را در هر فعالیت دیگری در برنامه خود بگنجانید، سیستم باید بداند که فعالیت قابل جستجوی شما کدام است تا بتواند به درستی درخواست جستجو را ارائه دهد. بنابراین، ابتدا فعالیت قابل جستجوی خود را در فایل مانیفست اندروید اعلام کنید.

فعالیت قابل جستجو را اعلام کنید

اگر قبلاً ندارید، یک 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 - می‌تواند جستجوی قوی‌تری در میان داده‌های متنی ارائه دهد و نتایج را به‌طور قابل توجهی سریع‌تر تولید کند. برای اطلاعات در مورد FTS3 و کلاس SQLiteDatabase برای اطلاعات در مورد SQLite در اندروید به sqlite.org مراجعه کنید.
• اگر داده‌های شما به صورت آنلاین ذخیره می‌شوند، ممکن است عملکرد جستجوی درک شده توسط اتصال داده کاربر مهار شود. ممکن است بخواهید یک نشانگر پیشرفت نمایش دهید تا زمانی که جستجوی شما برگردد. برای اطلاعات در مورد نحوه نمایش نشانگر پیشرفت، به android.net مراجعه کنید تا مرجع APIهای شبکه و ProgressBar را ببینید.

نتایج را ارائه دهید

صرف نظر از اینکه داده های شما در کجا زندگی می کنند و چگونه آنها را جستجو می کنید، توصیه می کنیم نتایج جستجو را با یک Adapter به فعالیت قابل جستجوی خود برگردانید. به این ترتیب، می توانید تمام نتایج جستجو را در یک RecyclerView ارائه کنید. اگر داده‌های شما از یک جستجوی پایگاه داده SQLite می‌آید، می‌توانید نتایج خود را با استفاده از CursorAdapter روی RecyclerView اعمال کنید. اگر داده‌های شما با فرمت متفاوتی ارائه می‌شوند، می‌توانید پسوندی برای BaseAdapter ایجاد کنید.

یک Adapter هر آیتم را از مجموعه ای از داده ها به یک شی View متصل می کند. هنگامی که Adapter بر روی RecyclerView اعمال می شود، هر قطعه داده به عنوان یک نمای جداگانه در لیست درج می شود. Adapter فقط یک رابط است، بنابراین پیاده سازی هایی مانند CursorAdapter - برای اتصال داده ها از یک Cursor - مورد نیاز است. اگر هیچ یک از پیاده‌سازی‌های موجود برای داده‌های شما کار نمی‌کند، می‌توانید پیاده‌سازی خود را از BaseAdapter پیاده‌سازی کنید.

از گفتگوی جستجو استفاده کنید

گفتگوی جستجو یک کادر جستجوی شناور را در بالای صفحه با نماد برنامه در سمت چپ ارائه می دهد. گفتگوی جستجو می تواند پیشنهادات جستجو را به عنوان کاربر ارائه دهد. هنگامی که کاربر یک جستجو را اجرا می کند، سیستم عبارت جستجو را به یک فعالیت قابل جستجو ارسال می کند که جستجو را انجام می دهد.

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

اگر می‌خواهید هر فعالیت در برنامه شما گفتگوی جستجو را ارائه دهد، به جای هر <activity> عنصر <meta-data> قبلی را به عنوان فرزند عنصر <application> وارد کنید. به این ترتیب، هر فعالیت مقدار را به ارث می برد، گفتگوی جستجو را ارائه می دهد و جستجوها را به همان فعالیت قابل جستجو تحویل می دهد. اگر چندین فعالیت قابل جستجو دارید، می توانید با قرار دادن یک اعلان <meta-data> متفاوت در داخل فعالیت های فردی، فعالیت قابل جستجوی پیش فرض را لغو کنید.

با فعال شدن کادر گفتگوی جستجو برای فعالیت‌های شما، برنامه شما آماده انجام جستجو است.

گفتگوی جستجو را فراخوانی کنید

اگرچه برخی از دستگاه‌ها یک دکمه جستجوی اختصاصی ارائه می‌کنند، اما رفتار دکمه ممکن است بین دستگاه‌ها متفاوت باشد و بسیاری از دستگاه‌ها اصلاً دکمه جستجو را ارائه نمی‌کنند. بنابراین هنگام استفاده از گفتگوی جستجو، باید یک دکمه جستجو در رابط کاربری خود ارائه دهید که با فراخوانی onSearchRequested() گفتگوی جستجو را فعال می کند.

برای مثال، یک دکمه جستجو را در منوی گزینه‌ها یا طرح‌بندی UI خود اضافه کنید که 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" است، در اینجا آمده است:

  کاتلین

  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() همان قصدی را که با onCreate() دریافت می‌شود، برمی‌گرداند. به همین دلیل است که شما باید setIntent(Intent) در داخل onNewIntent(Intent) فراخوانی کنید تا در صورت فراخوانی getIntent() در آینده، intent ذخیره شده توسط اکتیویتی به روز شود.

سناریوی دوم، با استفاده از حالت راه‌اندازی "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>

داده های زمینه جستجو را ارسال کنید

در برخی موارد، می‌توانید برای هر جستجوی انجام شده اصلاحات لازم را در عبارت جستجو در فعالیت قابل جستجو انجام دهید. با این حال، اگر می‌خواهید معیارهای جستجوی خود را بر اساس فعالیتی که کاربر از آن جستجو می‌کند، اصلاح کنید، می‌توانید داده‌های اضافی را با هدفی که سیستم به فعالیت قابل جستجوی شما ارسال می‌کند، ارائه دهید. می‌توانید داده‌های اضافی را در Bundle APP_DATA ، که در هدف 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;
 }

برگرداندن 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);
}

از ویجت جستجو استفاده کنید

شکل 1. ویجت SearchView به عنوان نمای اقدام در نوار برنامه.

ویجت جستجو همان عملکرد گفتگوی جستجو را ارائه می دهد. هنگامی که کاربر جستجویی را انجام می دهد، فعالیت مناسب را شروع می کند و می تواند پیشنهادات جستجو را ارائه دهد و جستجوی صوتی را انجام دهد. اگر گزینه ای برای شما نیست که ویجت جستجو را در نوار برنامه قرار دهید، می توانید ویجت جستجو را در جایی از طرح فعالیت خود قرار دهید.

ویجت جستجو را پیکربندی کنید

پس از ایجاد یک پیکربندی جستجو و یک فعالیت قابل جستجو ، جستجوی کمکی را برای هر SearchView با فراخوانی setSearchableInfo() و ارسال شی SearchableInfo که نمایانگر پیکربندی قابل جستجوی شما است، فعال کنید.

با فراخوانی 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) یک دکمه «submit» اضافه کنید.

اصلاح پرس و جو برای پیشنهادات جستجو

وقتی پیشنهادات جستجو را فعال می‌کنید، معمولاً از کاربران انتظار دارید که پیشنهادی را انتخاب کنند، اما ممکن است بخواهند عبارت جستجوی پیشنهادی را اصلاح کنند. می‌توانید در کنار هر پیشنهاد یک دکمه اضافه کنید که با فراخوانی setQueryRefinementEnabled(true) پیشنهاد را برای اصلاح توسط کاربر در کادر جستجو قرار می‌دهد.

قابلیت تغییر حالت نمای جعبه جستجو

به‌طور پیش‌فرض، ویجت جستجو "iconified" است، به این معنی که فقط با یک نماد جستجو - یک ذره‌بین نمایش داده می‌شود. هنگامی که کاربر روی نماد ضربه می زند، جعبه جستجو را بزرگ می کند. همانطور که در مثال قبل نشان داده شد، می توانید با فراخوانی setIconifiedByDefault(false) کادر جستجو را به طور پیش فرض نشان دهید. همچنین می توانید با فراخوانی setIconified() ظاهر ویجت جستجو را تغییر دهید.

چندین API دیگر در کلاس SearchView وجود دارد که به شما امکان می دهد ویجت جستجو را سفارشی کنید. با این حال، بیشتر آنها تنها زمانی استفاده می‌شوند که به جای استفاده از سیستم Android برای ارائه عبارت‌های جستجو و نمایش پیشنهادات جستجو، همه ورودی‌های کاربر را خودتان مدیریت کنید.

هم از ویجت و هم از دیالوگ استفاده کنید

اگر ویجت جستجو را در نوار برنامه به‌عنوان نمای اقدام وارد کنید و در صورت وجود فضا، آن را فعال کنید تا در نوار برنامه ظاهر شود - با تنظیم android:showAsAction="ifRoom" - ممکن است ویجت جستجو به‌عنوان یک نمای اقدام ظاهر نشود. در عوض، ممکن است یک آیتم منو در منوی سرریز ظاهر شود. به عنوان مثال، وقتی برنامه شما روی صفحه نمایش کوچکتری اجرا می شود، ممکن است فضای کافی در نوار برنامه برای نمایش ویجت جستجو به همراه سایر موارد اقدام یا عناصر ناوبری وجود نداشته باشد، بنابراین آیتم منو در عوض در منوی سرریز ظاهر می شود. هنگامی که آیتم در منوی سرریز قرار می گیرد، مانند یک آیتم منو معمولی عمل می کند و نمای عمل - یعنی ویجت جستجو را نشان نمی دهد.

برای رسیدگی به این وضعیت، آیتم منویی که ویجت جستجو را به آن متصل می‌کنید، باید زمانی که کاربر آن را از منوی سرریز انتخاب می‌کند، گفتگوی جستجو را فعال کند. برای انجام این کار، onOptionsItemSelected() را برای مدیریت آیتم منوی "Search" پیاده سازی کنید و با فراخوانی 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، پیشنهادهای جستجو را به هنگام تایپ کاربر ارائه دهند. این سیستم لیست پیشنهادات را مدیریت می کند و زمانی که کاربر پیشنهادی را انتخاب می کند، رویداد را مدیریت می کند.

شما می توانید دو نوع پیشنهاد جستجو ارائه دهید:

پیشنهادهای جستجوی اخیر

این پیشنهادها کلماتی هستند که کاربر قبلاً به عنوان عبارت جستجو در برنامه شما استفاده می کرد. برای اطلاعات بیشتر به افزودن پیشنهادهای جستجوی سفارشی مراجعه کنید.

پیشنهادات جستجوی سفارشی

اینها پیشنهادات جستجویی هستند که از منبع داده خود ارائه می کنید تا به کاربران کمک کند فوراً املا یا موردی را که جستجو می کنند صحیح انتخاب کنند. برای اطلاعات بیشتر به افزودن پیشنهادهای جستجوی سفارشی مراجعه کنید.