सर्च इंटरफ़ेस बनाना

Compose को आज़माएं

Android के लिए, Jetpack Compose को यूज़र इंटरफ़ेस (यूआई) टूलकिट के तौर पर इस्तेमाल करने का सुझाव दिया जाता है. Compose में खोज की सुविधा जोड़ने का तरीका जानें.

Search bar →

जब आपको अपने ऐप्लिकेशन में खोज की सुविधा जोड़नी हो, तो Android आपकी मदद करता है. इसके लिए, आपको उपयोगकर्ता इंटरफ़ेस लागू करना होता है. इसके लिए, गतिविधि विंडो के सबसे ऊपर दिखने वाला खोज डायलॉग या खोज विजेट इस्तेमाल किया जा सकता है. खोज विजेट को अपने लेआउट में डाला जा सकता है. खोज डायलॉग और विजेट, दोनों ही उपयोगकर्ता की खोज क्वेरी को आपके ऐप्लिकेशन में किसी खास गतिविधि तक पहुंचा सकते हैं. इस तरह, उपयोगकर्ता किसी भी ऐसी गतिविधि से खोज शुरू कर सकता है जहां खोज डायलॉग या विजेट उपलब्ध है. इसके बाद, सिस्टम खोज करने और नतीजे दिखाने के लिए सही गतिविधि शुरू करता है.

खोज डायलॉग और विजेट के लिए उपलब्ध अन्य सुविधाओं में ये शामिल हैं:

• बोलकर खोजें
• हाल ही की क्वेरी के आधार पर खोज के सुझाव
• खोज के ऐसे सुझाव जो आपके ऐप्लिकेशन के डेटा में मौजूद असल नतीजों से मेल खाते हों

इस दस्तावेज़ में, अपने ऐप्लिकेशन को सेट अप करने का तरीका बताया गया है. इससे आपको एक ऐसा सर्च इंटरफ़ेस मिलेगा जिसमें Android सिस्टम, सर्च क्वेरी के नतीजे दिखाने में आपकी मदद करेगा. इसके लिए, सर्च डायलॉग या सर्च विजेट का इस्तेमाल किया जा सकता है.

इसी विषय से जुड़े लिंक:

• Material Design आइकॉन

बुनियादी बातें

शुरू करने से पहले, यह तय करें कि आपको खोज के लिए इंटरफ़ेस, खोज वाले डायलॉग या खोज वाले विजेट का इस्तेमाल करके लागू करना है. ये दोनों ही प्लैटफ़ॉर्म, खोज से जुड़ी एक जैसी सुविधाएं देते हैं. हालांकि, इन्हें इस्तेमाल करने का तरीका थोड़ा अलग होता है:

• खोज डायलॉग एक यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट है. इसे Android सिस्टम कंट्रोल करता है. उपयोगकर्ता के चालू करने पर, खोज वाला डायलॉग बॉक्स, गतिविधि के सबसे ऊपर दिखता है.

  Android सिस्टम, खोज वाले डायलॉग बॉक्स में मौजूद सभी इवेंट को कंट्रोल करता है. जब उपयोगकर्ता कोई क्वेरी सबमिट करता है, तो सिस्टम उस क्वेरी को उस ऐक्टिविटी को भेजता है जिसे आपने खोजों को हैंडल करने के लिए तय किया है. उपयोगकर्ता के टाइप करते समय, डायलॉग बॉक्स में खोज के सुझाव भी दिख सकते हैं.

• खोज विजेट, SearchView का एक इंस्टेंस है. इसे अपने लेआउट में कहीं भी रखा जा सकता है. डिफ़ॉल्ट रूप से, खोज विजेट एक स्टैंडर्ड EditText विजेट की तरह काम करता है और कुछ नहीं करता. हालांकि, इसे इस तरह कॉन्फ़िगर किया जा सकता है कि Android सिस्टम, सभी इनपुट इवेंट को हैंडल करे, क्वेरी को सही गतिविधि तक पहुंचाए, और खोज के सुझाव दे. यह खोज डायलॉग की तरह ही काम करता है.

जब उपयोगकर्ता, खोज वाले डायलॉग या खोज वाले विजेट से कोई खोज करता है, तो सिस्टम एक Intent बनाता है और उसमें उपयोगकर्ता की क्वेरी सेव करता है. इसके बाद, सिस्टम उस गतिविधि को शुरू करता है जिसे आपने खोजों को हैंडल करने के लिए तय किया है. इसे "खोजे जा सकने वाले गतिविधि" कहा जाता है. साथ ही, यह गतिविधि इंटेंट को डिलीवर करती है. इस तरह की खोज के लिए अपने ऐप्लिकेशन को सेट अप करने के लिए, आपको इन चीज़ों की ज़रूरत होगी:

खोज का कॉन्फ़िगरेशन

यह एक XML फ़ाइल है. यह खोज डायलॉग या विजेट के लिए कुछ सेटिंग कॉन्फ़िगर करती है. इसमें बोलकर खोजने, खोज के सुझाव पाने, और खोज बॉक्स के लिए हिंट टेक्स्ट जैसी सुविधाओं की सेटिंग शामिल होती हैं.

खोजने लायक गतिविधि

Activity को सर्च क्वेरी मिलती है. इसके बाद, वह आपके डेटा में खोज करता है और खोज के नतीजे दिखाता है.

सर्च इंटरफ़ेस, जो इनमें से किसी एक के ज़रिए उपलब्ध कराया जाता है:

सर्च डायलॉग

डिफ़ॉल्ट रूप से, खोज वाला डायलॉग बॉक्स छिपा होता है. जब कोई उपयोगकर्ता आपके खोजें बटन पर टैप करता है, तब स्क्रीन पर सबसे ऊपर onSearchRequested() दिखता है.

SearchView विजेट

सर्च विजेट का इस्तेमाल करके, सर्च बॉक्स को अपनी गतिविधि में कहीं भी रखा जा सकता है. इसमें ऐप्लिकेशन बार में ऐक्शन व्यू के तौर पर सर्च बॉक्स को रखना भी शामिल है.

इस दस्तावेज़ के बाकी हिस्से में, खोज कॉन्फ़िगरेशन और खोजे जा सकने वाले डेटा को बनाने का तरीका बताया गया है. साथ ही, इसमें खोज डायलॉग या खोज विजेट की मदद से, खोज इंटरफ़ेस को लागू करने का तरीका भी बताया गया है.

खोजे जा सकने वाले कॉन्फ़िगरेशन बनाना

इसके लिए, आपको खोज कॉन्फ़िगरेशन नाम की एक्सएमएल फ़ाइल की ज़रूरत होगी. यह खोज वाले डायलॉग बॉक्स या विजेट के कुछ यूज़र इंटरफ़ेस (यूआई) पहलुओं को कॉन्फ़िगर करता है. साथ ही, यह तय करता है कि सुझाव और वॉइस सर्च जैसी सुविधाएं कैसे काम करती हैं. इस फ़ाइल का नाम आम तौर पर 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 एक्स्ट्रा से क्वेरी वापस लाती है. इसके बाद, आपके डेटा में खोज करती है और नतीजे दिखाती है.

आपके पास अपने ऐप्लिकेशन की किसी भी गतिविधि में, खोज डायलॉग या विजेट शामिल करने का विकल्प होता है. इसलिए, सिस्टम को यह पता होना चाहिए कि खोज की जा सकने वाली गतिविधि कौनसी है, ताकि वह खोज क्वेरी को सही तरीके से डिलीवर कर सके. इसलिए, सबसे पहले Android मेनिफ़ेस्ट फ़ाइल में, खोजे जा सकने वाले ऐप्लिकेशन का एलान करें.

खोजे जा सकने वाली गतिविधि का एलान करना

अगर आपके पास पहले से कोई ऐसा Activity नहीं है जो खोज करता हो और नतीजे दिखाता हो, तो एक Activity बनाएं. आपको अभी खोज करने की सुविधा लागू करने की ज़रूरत नहीं है. बस एक ऐसी गतिविधि बनाएं जिसे मेनिफ़ेस्ट में शामिल किया जा सके. मेनिफ़ेस्ट के <activity> एलिमेंट में, ये काम करें:

1. <intent-filter> एलिमेंट में ACTION_SEARCH इंटेंट को स्वीकार करने के लिए, गतिविधि का एलान करें.
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 डेटाबेस में सेव है, तो टेक्स्ट डेटा में बेहतर तरीके से खोजने के लिए, LIKE क्वेरी के बजाय FTS3 का इस्तेमाल करके फ़ुल-टेक्स्ट खोज की जा सकती है. इससे नतीजे भी काफ़ी तेज़ी से मिलते हैं. Android पर SQLite के बारे में जानकारी पाने के लिए, SQLiteDatabase क्लास के बारे में जानकारी पाने के लिए, sqlite.org पर जाएं.
• अगर आपका डेटा ऑनलाइन सेव किया जाता है, तो खोज की परफ़ॉर्मेंस पर उपयोगकर्ता के डेटा कनेक्शन का असर पड़ सकता है. खोज के नतीजे दिखने तक, प्रोग्रेस इंडिकेटर दिखाया जा सकता है. नेटवर्क एपीआई के रेफ़रंस के लिए, android.net देखें. साथ ही, प्रोग्रेस इंडिकेटर दिखाने के तरीके के बारे में जानकारी के लिए, ProgressBar देखें.

नतीजे दिखाना

आपका डेटा कहां सेव है और उसे कैसे खोजा जाता है, इससे कोई फ़र्क़ नहीं पड़ता. हमारा सुझाव है कि आप खोजे जा सकने वाले डेटा से खोज के नतीजे पाने के लिए, Adapter का इस्तेमाल करें. इस तरह, खोज के सभी नतीजों को RecyclerView में दिखाया जा सकता है. अगर आपका डेटा, SQLite डेटाबेस क्वेरी से आता है, तो RecyclerView का इस्तेमाल करके, अपने नतीजों को CursorAdapter पर लागू किया जा सकता है. अगर आपका डेटा किसी दूसरे फ़ॉर्मैट में है, तो BaseAdapter का एक्सटेंशन बनाया जा सकता है.

Adapter, डेटा के सेट में मौजूद हर आइटम को View ऑब्जेक्ट में बाइंड करता है. जब Adapter को RecyclerView पर लागू किया जाता है, तो डेटा का हर हिस्सा सूची में अलग-अलग व्यू के तौर पर डाला जाता है. Adapter सिर्फ़ एक इंटरफ़ेस है. इसलिए, CursorAdapter जैसे इंप्लिमेंटेशन की ज़रूरत होती है. इसका इस्तेमाल Cursor से डेटा बाइंड करने के लिए किया जाता है. अगर मौजूदा लागू करने के तरीकों में से कोई भी तरीका आपके डेटा के लिए काम नहीं करता है, तो BaseAdapter से अपना तरीका लागू किया जा सकता है.

सर्च डायलॉग का इस्तेमाल करना

खोज डायलॉग, स्क्रीन पर सबसे ऊपर एक फ़्लोटिंग सर्च बॉक्स दिखाता है. इसमें बाईं ओर ऐप्लिकेशन का आइकॉन होता है. उपयोगकर्ता के टाइप करते समय, खोज डायलॉग में खोज के सुझाव दिए जा सकते हैं. जब उपयोगकर्ता कोई खोज करता है, तो सिस्टम खोज क्वेरी को खोजे जा सकने वाली गतिविधि पर भेजता है. यह गतिविधि खोज करती है.

डिफ़ॉल्ट रूप से, खोज वाला डायलॉग हमेशा छिपा रहता है. उपयोगकर्ता के इसे चालू करने पर ही यह दिखता है. आपका ऐप्लिकेशन, onSearchRequested() को कॉल करके खोज डायलॉग को चालू कर सकता है. हालांकि, यह तरीका तब तक काम नहीं करता, जब तक गतिविधि के लिए खोज डायलॉग चालू नहीं किया जाता.

खोज डायलॉग को खोज करने की अनुमति देने के लिए, सिस्टम को यह बताएं कि खोज डायलॉग से कौनसी खोज क्वेरी मिलनी चाहिए. उदाहरण के लिए, खोजे जा सकने वाले गतिविधि पैरामीटर बनाने के बारे में ऊपर दिए गए सेक्शन में, SearchableActivity नाम की खोजे जा सकने वाले गतिविधि पैरामीटर बनाया गया है. अगर आपको OtherActivity नाम की कोई अलग गतिविधि चाहिए, ताकि वह खोज डायलॉग दिखा सके और खोजों को SearchableActivity तक पहुंचा सके, तो मेनिफ़ेस्ट में यह एलान करें कि OtherActivity, खोज डायलॉग के लिए इस्तेमाल की जाने वाली खोज गतिविधि है.SearchableActivity

किसी गतिविधि के खोज डायलॉग के लिए, खोजे जा सकने वाले कॉन्टेंट का एलान करने के लिए, उस गतिविधि के <activity> एलिमेंट में <meta-data> एलिमेंट जोड़ें. <meta-data> एलिमेंट में, android:value एट्रिब्यूट शामिल होना चाहिए. यह एट्रिब्यूट, खोजे जा सकने वाले गतिविधि के क्लास का नाम तय करता है. साथ ही, इसमें android:name एट्रिब्यूट शामिल होना चाहिए, जिसकी वैल्यू "android.app.default_searchable" हो.

उदाहरण के लिए, यहां खोजे जा सकने वाले ऐप्लिकेशन, SearchableActivity, और दूसरे ऐप्लिकेशन, OtherActivity, दोनों के लिए एलान दिया गया है. 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() को कॉल करके खोज डायलॉग को चालू करता है.

उदाहरण के लिए, अपने विकल्प मेन्यू या यूज़र इंटरफ़ेस (यूआई) लेआउट में एक खोज बटन जोड़ें. यह बटन 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" के तौर पर सेट किया गया है:

  Kotlin

  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)
          }
      }
  }

  Java

  @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() के साथ मिला था. इसलिए, आपको onNewIntent(Intent) के अंदर setIntent(Intent) को कॉल करना होगा, ताकि गतिविधि से सेव किया गया इंटेंट अपडेट हो जाए. ऐसा तब होगा, जब आपने आने वाले समय में getIntent() को कॉल किया हो.

"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>

खोज के कॉन्टेक्स्ट का डेटा पास करना

कुछ मामलों में, हर खोज के लिए, खोजे जा सकने वाले डेटा में मौजूद खोज क्वेरी में ज़रूरी बदलाव किए जा सकते हैं. हालांकि, अगर आपको खोज के लिए इस्तेमाल की जाने वाली शर्तों को बेहतर बनाना है, तो इसके लिए आपको उस गतिविधि के आधार पर शर्तें तय करनी होंगी जिसके लिए उपयोगकर्ता खोज कर रहा है. इसके लिए, आपको उस इंटेंट में अतिरिक्त डेटा देना होगा जिसे सिस्टम, खोज की जा सकने वाली गतिविधि के लिए भेजता है. APP_DATA Bundle में अतिरिक्त डेटा पास किया जा सकता है. यह 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;
 }

सही वैल्यू का मतलब है कि आपने इस कॉलबैक इवेंट को मैनेज कर लिया है. साथ ही, खोज डायलॉग को चालू करने के लिए 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);
}

Search विजेट का इस्तेमाल करना

पहली इमेज. ऐप्लिकेशन बार में, SearchViewविजेट को ऐक्शन व्यू के तौर पर दिखाया गया है.

सर्च विजेट में, सर्च डायलॉग बॉक्स जैसी ही सुविधाएं होती हैं. जब उपयोगकर्ता कोई खोज करता है, तो यह सही गतिविधि शुरू करता है. साथ ही, यह खोज के सुझाव दे सकता है और बोलकर खोजने की सुविधा का इस्तेमाल कर सकता है. अगर आपके पास ऐप्लिकेशन बार में खोज विजेट जोड़ने का विकल्प नहीं है, तो खोज विजेट को गतिविधि लेआउट में कहीं भी जोड़ा जा सकता है.

Search विजेट को कॉन्फ़िगर करना

खोज कॉन्फ़िगरेशन और खोजने लायक गतिविधि बनाने के बाद, हर SearchView के लिए खोज में मदद करने वाली सुविधा चालू करें. इसके लिए, setSearchableInfo() को कॉल करें और उसे SearchableInfo ऑब्जेक्ट पास करें. यह ऑब्जेक्ट, आपके खोजने लायक कॉन्फ़िगरेशन को दिखाता है.

SearchManager पर getSearchableInfo() को कॉल करके, 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;
}

अब खोज विजेट कॉन्फ़िगर हो गया है. साथ ही, सिस्टम खोज क्वेरी को आपकी खोजे जा सकने वाली गतिविधि तक पहुंचाता है. सर्च विजेट के लिए, खोज के सुझाव भी चालू किए जा सकते हैं.

ऐप्लिकेशन बार में ऐक्शन व्यू के बारे में ज़्यादा जानने के लिए, ऐक्शन व्यू और ऐक्शन उपलब्ध कराने वाली कंपनी का इस्तेमाल करना लेख पढ़ें.

Search विजेट की अन्य सुविधाएं

SearchView विजेट में कुछ अतिरिक्त सुविधाएं मिलती हैं. इनका इस्तेमाल किया जा सकता है:

सबमिट बटन

खोज क्वेरी सबमिट करने के लिए, डिफ़ॉल्ट रूप से कोई बटन नहीं होता. इसलिए, खोज शुरू करने के लिए उपयोगकर्ता को कीबोर्ड पर Return कुंजी दबानी होती है. setSubmitButtonEnabled(true) को कॉल करके, "सबमिट करें" बटन जोड़ा जा सकता है.

खोज से जुड़े सुझावों के लिए क्वेरी को बेहतर बनाना

खोज के सुझाव देने की सुविधा चालू करने पर, आम तौर पर आपको लगता है कि उपयोगकर्ता कोई सुझाव चुनेंगे. हालांकि, वे सुझाई गई खोज क्वेरी को बेहतर बनाना भी चाहें. हर सुझाव के साथ एक बटन जोड़ा जा सकता है. इससे उपयोगकर्ता को setQueryRefinementEnabled(true) को कॉल करके, खोज बॉक्स में सुझाव डालने की सुविधा मिलती है.

खोज बॉक्स के दिखने की सेटिंग को टॉगल करने की सुविधा

डिफ़ॉल्ट रूप से, खोज विजेट को "आइकॉन के तौर पर दिखाया जाता है." इसका मतलब है कि इसे सिर्फ़ खोज आइकॉन—मैग्नीफ़ाइंग ग्लास के तौर पर दिखाया जाता है. जब उपयोगकर्ता इस आइकॉन पर टैप करता है, तो यह बड़ा हो जाता है और खोज बॉक्स दिखता है. ऊपर दिए गए उदाहरण में दिखाया गया है कि setIconifiedByDefault(false) को कॉल करके, खोज बॉक्स को डिफ़ॉल्ट रूप से दिखाया जा सकता है. setIconified() को कॉल करके, खोज विजेट के दिखने की सुविधा को टॉगल भी किया जा सकता है.

SearchView क्लास में कई अन्य एपीआई भी हैं. इनकी मदद से, खोज विजेट को अपनी पसंद के मुताबिक बनाया जा सकता है. हालांकि, इनमें से ज़्यादातर का इस्तेमाल सिर्फ़ तब किया जाता है, जब आपको उपयोगकर्ता के सभी इनपुट खुद मैनेज करने हों. इसके बजाय, Android सिस्टम का इस्तेमाल करके खोज क्वेरी डिलीवर करने और खोज के सुझाव दिखाने के लिए किया जाता है.

विजेट और डायलॉग, दोनों का इस्तेमाल करना

अगर आपने खोज विजेट को ऐप्लिकेशन बार में ऐक्शन व्यू के तौर पर डाला है और आपने इसे ऐप्लिकेशन बार में दिखने की अनुमति दी है, तो हो सकता है कि खोज विजेट, ऐक्शन व्यू के तौर पर न दिखे. इसके लिए, आपको android:showAsAction="ifRoom" सेट करना होगा. इसके बजाय, मेन्यू आइटम ओवरफ़्लो मेन्यू में दिख सकता है. उदाहरण के लिए, जब आपका ऐप्लिकेशन किसी छोटी स्क्रीन पर चलता है, तो हो सकता है कि ऐप्लिकेशन बार में, खोज विजेट को अन्य कार्रवाई आइटम या नेविगेशन एलिमेंट के साथ दिखाने के लिए, जगह न हो. इसलिए, मेन्यू आइटम ओवरफ़्लो मेन्यू में दिखता है. ओवरफ़्लो मेन्यू में रखने पर, यह आइटम सामान्य मेन्यू आइटम की तरह काम करता है. साथ ही, इसमें ऐक्शन व्यू यानी खोज करने वाला विजेट नहीं दिखता.

इस स्थिति को मैनेज करने के लिए, जिस मेन्यू आइटम में आपने खोज विजेट अटैच किया है उसे उपयोगकर्ता के ओवरफ़्लो मेन्यू से चुनने पर, खोज डायलॉग को चालू करना होगा. इसके लिए, "खोजें" मेन्यू आइटम को हैंडल करने के लिए onOptionsItemSelected() लागू करें. साथ ही, 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, यह तय करती है कि वॉइस सर्च बटन को एक recognizer लॉन्च करना होगा. यह recognizer, खोजे जा सकने वाले टेक्स्ट को ट्रांसक्रिप्ट किए गए टेक्स्ट के तौर पर दिखाता है.

बोलकर खोजने की सुविधा के बारे में ज़्यादा जानकारी देने के लिए, अतिरिक्त एट्रिब्यूट दिए जा सकते हैं. जैसे, अनुमानित भाषा और ज़्यादा से ज़्यादा नतीजे दिखाने की संख्या. उपलब्ध एट्रिब्यूट के बारे में ज़्यादा जानकारी के लिए, खोज कॉन्फ़िगरेशन का रेफ़रंस देखें.

खोज से जुड़े सुझाव जोड़ना

Android सिस्टम की मदद से, खोज के लिए उपलब्ध डायलॉग और विजेट, दोनों में ही उपयोगकर्ता के टाइप करते समय खोज के सुझाव दिख सकते हैं. सिस्टम, सुझावों की सूची को मैनेज करता है. साथ ही, जब उपयोगकर्ता कोई सुझाव चुनता है, तब सिस्टम उस इवेंट को हैंडल करता है.

खोज के लिए दो तरह के सुझाव दिए जा सकते हैं:

हाल ही में की गई क्वेरी के खोज सुझाव

ये सुझाव ऐसे शब्द होते हैं जिनका इस्तेमाल उपयोगकर्ता ने पहले आपके ऐप्लिकेशन में खोज क्वेरी के तौर पर किया था. ज़्यादा जानकारी के लिए, खोज के लिए कस्टम सुझाव जोड़ना लेख पढ़ें.

कस्टम सर्च से जुड़े सुझाव

ये खोज के ऐसे सुझाव होते हैं जिन्हें आपने अपने डेटा सोर्स से उपलब्ध कराया है. इनकी मदद से, उपयोगकर्ता तुरंत सही स्पेलिंग चुन सकते हैं या उस आइटम को चुन सकते हैं जिसे वे खोज रहे हैं. ज़्यादा जानकारी के लिए, कस्टम सर्च के सुझाव जोड़ना लेख पढ़ें.