דף זה תורגם על ידי Cloud Translation API.

יצירת ממשק חיפוש

כשיתאים לך להוסיף פונקציונליות חיפוש לאפליקציה, מערכת Android עוזרת לך להטמיע את ממשק המשתמש באמצעות תיבת דו-שיח של חיפוש שמופיעה בחלק העליון של המסך. של חלון הפעילות או ווידג'ט החיפוש שאפשר להוסיף לפריסה. גם תיבת הדו-שיח של החיפוש וגם הווידג'ט יכולים להציג את שאילתת החיפוש של המשתמש פעילות ספציפית באפליקציה שלכם. כך המשתמש יכול להתחיל חיפוש מכל פעילות שבה תיבת הדו-שיח או הווידג'ט של החיפוש זמינים, והמערכת מתחילה לבצע את החיפוש המתאים ולהציג תוצאות.

תכונות נוספות שזמינות לתיבת הדו-שיח ולווידג'ט של החיפוש כוללות:

חיפוש קולי
הצעות חיפוש על סמך שאילתות אחרונות
הצעות חיפוש שתואמות לתוצאות בפועל בנתוני האפליקציה

במסמך הזה מוסבר איך להגדיר את האפליקציה כדי לספק ממשק חיפוש שמקבלת סיוע ממערכת Android כדי להציג שאילתות חיפוש, בתיבת הדו-שיח של החיפוש או בווידג'ט החיפוש.

מקורות מידע שקשורים לנושא:

סמלים של עיצוב חדשני (Material Design)

העקרונות הבסיסיים

לפני שמתחילים, צריך להחליט אם להטמיע את ממשק החיפוש באמצעות תיבת הדו-שיח של החיפוש או ווידג'ט החיפוש. הם מספקים את אותו חיפוש אבל בדרכים מעט שונות:

תיבת הדו-שיח של החיפוש היא רכיב בממשק המשתמש שנשלט על ידי במערכת Android. כאשר המשתמש מופעל, תיבת הדו-שיח של החיפוש מופיעה ב בחלק העליון של הפעילות.
מערכת Android שולטת בכל האירועים בתיבת הדו-שיח של החיפוש. כאשר כאשר משתמש שולח שאילתה, המערכת מספקת את השאילתה לפעילות שאתם מגדירים לטיפול בחיפושים. בתיבת הדו-שיח יש גם אפשרות לחפש בזמן שהמשתמש מקליד.
ווידג'ט החיפוש הוא מופע של SearchView שיש לך אפשרות בכל מקום בפריסה שלכם. כברירת מחדל, ווידג'ט החיפוש פועל כמו רגילה EditText הווידג'ט הזה לא עושה דבר, אבל ניתן להגדיר אותו כך שה-Android שמטפלת בכל אירועי הקלט, מספקת שאילתות פעילות ומספקת הצעות לחיפוש - בדיוק כמו בחיפוש

הערה: המסמך הזה מתמקד באופן שבו ניתן לשלב את ווידג'ט החיפוש עם את המערכת להטמעת חיפוש בסיוע. אבל אפשר גם לטפל בכל קלט של משתמשים בווידג'ט החיפוש בעצמך, באמצעות שיטות שונות של קריאה חוזרת מאזינים. אם אתם רוצים לטפל בקלט של משתמשים בעצמכם, כדאי לקרוא את קובץ העזר מסמך בשביל SearchView והממשקים הפנימיים שלו.

כשהמשתמש מבצע חיפוש מתיבת הדו-שיח של החיפוש או מווידג'ט חיפוש, המערכת יוצרת Intent והקבוצה ששומר בה את שאילתת המשתמש. לאחר מכן המערכת מתחילה את הפעילות הצהרה על טיפול בחיפושים — "הפעילות הניתנת לחיפוש" — והצגה את הכוונה. כדי להגדיר את האפליקציה לחיפוש בסיוע מהסוג הזה, צריך הבאים:

הגדרות חיפוש: קובץ XML שקובע כמה הגדרות לווידג'ט או לתיבת הדו-שיח של החיפוש. המסמך כולל הגדרות של תכונות כמו חיפוש קולי, הצעות לחיפוש, ורמז לטקסט עבור תיבת החיפוש.
פעילות שאפשר לחפש בה: Activity שמקבל את שאילתת החיפוש, מחפש בנתונים שלכם ומציג את החיפוש תוצאות.
ממשק חיפוש, שמסופק על ידי אחד מהגורמים הבאים:

בהמשך המסמך מוסבר איך ליצור את הגדרות החיפוש ולבצע חיפוש של הפעילות, ואיך ליישם ממשק חיפוש עם של תיבת דו-שיח לחיפוש או ווידג'ט חיפוש.

יצירת הגדרות שאפשר לחפש

הדבר הראשון שאתם צריכים הוא קובץ XML שנקרא הגדרות חיפוש. היא מגדירה היבטים מסוימים של ממשק המשתמש בתיבת הדו-שיח או בווידג'ט של החיפוש, ומגדירה איך תכונות כמו הצעות וחיפוש קולי. בדרך כלל, הקובץ הזה בשם searchable.xml וצריך לשמור אותו בקובץ res/xml/ של פרויקט.

הערה: המערכת משתמשת בקובץ הזה כדי ליצור SearchableInfo לאובייקט. אין לך אפשרות ליצור את האובייקט הזה בעצמך בזמן ריצה. עליך להצהיר על הגדרות החיפוש ב-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, שמספק מחרוזת רמז בחיפוש לפני שמשתמשים מזינים שאילתה. הרמז חשוב כי הוא מספק רמזים חשובים למשתמשים לגבי מה שהם יכולים לחפש.

טיפ: כדי לשמור על עקביות עם אפליקציות אחרות ל-Android, צריך להזין את המחרוזת בפורמט הבא: android:hint בתור 'חיפוש <content-or-product>'. לדוגמה, "חיפוש שירים ואומנים" או 'חיפוש ב-YouTube'.

הרכיב <searchable> מקבל כמה מאפיינים אחרים. עם זאת, אין צורך ברוב המאפיינים עד שמוסיפים תכונות כמו הצעות לחיפוש וגם חיפוש קולי. לקבלת מידע מפורט על חיפוש בקובץ התצורה של החיפוש, הגדרות חיפוש מסמך עזר.

יצירת פעילות שניתן לחפש

פעילות שניתנת לחיפוש היא Activity באפליקציה שלך שמבצעת ביצועים חיפוש לפי מחרוזת שאילתה ולהציג את תוצאות החיפוש.

כשהמשתמש מבצע חיפוש בתיבת הדו-שיח או בווידג'ט של החיפוש, המערכת מתחיל את הפעילות המחפשת את הפעילות שלך ומציג אותה כשאילתת חיפוש Intent עם ACTION_SEARCH פעולה. הפעילות שניתנת לחיפוש מאחזרת את השאילתה QUERY נוסף, מחפש את הנתונים ומציג את התוצאות.

מכיוון שאפשר לכלול את תיבת הדו-שיח או את הווידג'ט של החיפוש בכל פעילות אחרת ב- באפליקציה, המערכת צריכה לדעת איזו פעילות היא הפעילות שבה אפשר לחפש, כדי שיוכל לספק כראוי את שאילתת החיפוש. קודם כול, מצהירים על מידת החיפוש פעילות בקובץ המניפסט של Android.

הצהרה על פעילות הניתנת לחיפוש

אם עדיין אין לך חשבון, עליך ליצור Activity שפועל חיפוש והצגת תוצאות. אין צורך להטמיע את תכונת החיפוש פונקציונליות בלבד - פשוט צרו פעילות שעליה תוכלו להצהיר . בתוך המניפסט <activity> בצעו את הפעולות הבאות:

צריך להצהיר על הפעילות כדי לאשר את Intent ACTION_SEARCH ב <intent-filter> לרכיב מסוים.
מציינים את תצורת החיפוש שבה רוצים להשתמש <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 חדש.

הערה: <intent-filter> לא צריך <category> עם ערך של DEFAULT - שבדרך כלל מופיע ב-<activity> - מכיוון שהמערכת מספקת את הערך ACTION_SEARCH את כוונת הרכישה באופן מפורש, באמצעות שם הרכיב שלו.

חיפוש

אחרי שמצהירים במניפסט על הפעילות הניתנת לחיפוש, צריך לפעול לפי לביצוע חיפוש בפעילות הניתנת לחיפוש:

מקבלים את השאילתה.
חיפוש בנתונים.
מציגים את התוצאות.

קבלת השאילתה

כשמשתמש מבצע חיפוש מתיבת הדו-שיח או מהווידג'ט של החיפוש, המערכת מתחיל את הפעילות הניתנת לחיפוש ושולח לה ACTION_SEARCH בכוונה טובה. Intent זה נושא את שאילתת החיפוש במחרוזת QUERY. נוסף. צריך לבדוק את הכוונה הזו כשהפעילות מתחילה ולחלץ את המחרוזת. לדוגמה, כך אפשר לקבל את שאילתת החיפוש בזמן חיפוש תחילת הפעילות:

Kotlin

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

Java

@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 תמיד נכללת עם Intent מסוג ACTION_SEARCH. בדוגמה שלמעלה, השאילתה אוחזרה והועברה לשיטת doMySearch() מקומית שבה פעולת החיפוש בפועל הושלמה.

חיפוש בנתונים

תהליך האחסון והחיפוש של הנתונים הוא ייחודי לאפליקציה שלכם. אפשר לאחסן את הנתונים שלכם ולחפש אותם בדרכים רבות, והמסמך הזה לא מראה לכם איך. כדאי להביא בחשבון את האופן שבו אתם מאחסנים את הנתונים ומחפשים אותם בהקשר של הצרכים שלכם והנתונים שלכם הפורמט. אפשר ליישם את הטיפים הבאים:

אם הנתונים מאוחסנים במסד נתונים של SQLite במכשיר, חיפוש טקסט מלא – באמצעות FTS3, במקום LIKE שאילתה שמאפשרת חיפוש יעיל יותר בנתוני טקסט, תשיגו תוצאות מהר יותר משמעותית. צפייה sqlite.org עבור מידע על FTS3 SQLiteDatabase למידע על SQLite ב-Android.
אם הנתונים שלכם מאוחסנים באינטרנט, יכול להיות שביצועי החיפוש בפועל נחסמה על ידי חבילת הגלישה של המשתמש. יכול להיות שתרצו להציג עד שהחיפוש יחזור. צפייה android.net לעיון בממשקי API של רשתות ProgressBar לקבלת מידע על הצגת אינדיקטור התקדמות.

הצגת התוצאות

בלי קשר למיקום של הנתונים ולאופן החיפוש שלהם, אנחנו ממליצים אתם מחזירים תוצאות חיפוש לפעילות הניתנת לחיפוש באמצעות Adapter הזה אפשר להציג את כל תוצאות החיפוש RecyclerView אם הנתונים מגיעים משאילתה במסד הנתונים של SQLite, אפשר להחיל את התוצאות על RecyclerView באמצעות CursorAdapter. אם הנתונים מגיעים בפורמט אחר, אפשר ליצור תוסף של 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 בכוונה טובה.

הערה: הפעילות עצמה שניתנת לחיפוש מספקת את תיבת הדו-שיח של החיפוש באמצעות כברירת מחדל, לכן לא צריך להוסיף את ההצהרה SearchableActivity

אם רוצים שכל פעילות באפליקציה תציג את תיבת הדו-שיח של החיפוש, מזינים רכיב <meta-data> הקודם כצאצא של <application> במקום כל <activity>. כך כל פעילות יורשת את הערך, מספקת את תיבת הדו-שיח של החיפוש ומציגה חיפושים אותה פעילות שניתן לחפש. אם יש לכם פעילויות מרובות שניתן לחפש, תוכלו לשנות את פעילות ברירת המחדל לחיפוש על ידי הצבת הצהרה <meta-data> בתוך פעילויות נפרדות.

כשתיבת הדו-שיח של החיפוש מופעלת עכשיו עבור הפעילויות שלך, האפליקציה מוכנה לבצע חיפושים.

הפעלה של תיבת הדו-שיח של החיפוש

למרות במכשירים מסוימים יש לחצן חיפוש ייעודי, ההתנהגות של עשוי להשתנות בין מכשירים, ומכשירים רבים לא מספקים חיפוש בכלל. לכן, כשמשתמשים בתיבת הדו-שיח של החיפוש, צריך להוסיף לחצן חיפוש בממשק המשתמש שמפעיל את תיבת הדו-שיח של החיפוש באמצעות onSearchRequested()

לדוגמה, הוסף לחצן חיפוש תפריט האפשרויות או הפריסה של ממשק המשתמש שנקרא onSearchRequested().

אפשר גם להפעיל את האפשרות 'סוג לחיפוש' חדשה, שמפעילה את של תיבת הדו-שיח של החיפוש, כשהמשתמש מתחיל להקליד במקלדת. ההקשות הן מוכנסת לתיבת הדו-שיח של החיפוש. אפשר להפעיל את התכונה 'הקלדה לחיפוש' בפעילות שלך על ידי התקשרות setDefaultKeyMode — או DEFAULT_KEYS_SEARCH_LOCAL - במהלך של הפעילות שלך onCreate() .

ההשפעה של תיבת הדו-שיח של החיפוש על מחזור החיים של הפעילות

תיבת הדו-שיח של החיפוש היא Dialog צף בחלק העליון של המסך. הוא לא גורם לשינוי במקבץ הפעילויות, לכן כשתיבת הדו-שיח של החיפוש מופיעה, לא קיימות שיטות במחזור חיים, כמו onPause() – הם שנקראה. הפעילות מתבטלת בגלל ההתמקדות בקלט, תיבת החיפוש.

כדי לקבל התראה כשתיבת הדו-שיח של החיפוש מופעלת, צריך לבטל את אמצעי תשלום אחד (onSearchRequested()). כשהמערכת קוראת לשיטה הזו, הוא סימן לכך שהפעילות מאבדת את המיקוד לתיבת הדו-שיח של החיפוש, לכן אפשר לבצע כל עבודה שמתאימה לאירוע, כמו להשהות משחק. אלא אם אתם מעבירים הקשר חיפוש נתונים – כמו שהסברנו בקטע אחר במסמך הזה – צריך לסיים את באמצעות קריאה להטמעה של מחלקה-על:

Kotlin

override fun onSearchRequested(): Boolean {
    pauseSomeStuff()
    return super.onSearchRequested()
}

Java

@Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}

אם המשתמש מבטל את החיפוש על ידי הקשה על הלחצן 'הקודם', תיבת הדו-שיח של החיפוש נסגרת והפעילות חוזרת להתמקד בקלט. אפשר להירשם כדי לקבל הודעות כשתיבת הדו-שיח של החיפוש נסגרת עם setOnDismissListener(), setOnCancelListener(), או לשניהם. צריך רק לרשום את OnDismissListener, מפני שהוא נקרא בכל פעם שתיבת הדו-שיח של החיפוש נסגרת. OnCancelListener מתייחסת רק לאירועים שבהם המשתמש יוצא באופן מפורש מתיבת הדו-שיח של החיפוש, לכן היא לא מופעלת בעת ביצוע חיפוש. כשהחיפוש מתבצע, תיבת הדו-שיח של החיפוש נעלמת באופן אוטומטי.

אם הפעילות הנוכחית אינה הפעילות הניתנת לחיפוש, אירועי מחזור חיים של פעילות מופעלים כשהמשתמש מבצע חיפוש – הפעילות הנוכחית מקבלת onPause(), כפי שמתואר בחלק מבוא ל פעילויות. עם זאת, אם הפעילות הנוכחית היא הפעילות שניתנת לחיפוש, מתרחש אחד משני דברים:

כברירת מחדל, הפעילות הניתנת לחיפוש מקבלת Intent מסוג ACTION_SEARCH עם קריאה ל-onCreate(), ומופע חדש של הפעילות מופיע בראש הפעילות סטאק. כעת יש שני מופעים של הפעילות הניתנת לחיפוש מקבץ פעילויות, כך שהקשה על לחצן 'הקודם' תחזיר אותך של הפעילות הניתנת לחיפוש, במקום לצאת פעילות.

אם מגדירים את android:launchMode לערך "singleTop", הפעילות הניתנת לחיפוש מקבלת את ה-Intent ACTION_SEARCH עם קריאה אל onNewIntent(Intent), העברת 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() הפונקציה מחזירה את אותה Intent שמתקבלת עם onCreate(). לכן צריך להתקשר setIntent(Intent) בתוך onNewIntent(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, כלומר כלולה ב-Intent ACTION_SEARCH.

כדי להעביר נתונים מהסוג הזה לפעילות שמתבצעת בה חיפוש, צריך לשנות את השיטה onSearchRequested() לפעילות שממנה המשתמש יכול לבצע חיפוש, ליצור Bundle עם הנתונים הנוספים לשלוח קריאה startSearch() כדי להפעיל את תיבת הדו-שיח של החיפוש. לדוגמה:

Kotlin

override fun onSearchRequested(): Boolean {
    val appData = Bundle().apply {
        putBoolean(JARGON, true)
    }
    startSearch(null, false, appData, false)
    return true
}

Java

@Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }

ההחזרה True מציינת שאירוע הקריאה החוזרת (callback) טופל בהצלחה קוראים לפונקציה startSearch() כדי להפעיל את תיבת הדו-שיח של החיפוש. אחרי שהמשתמש שולח שאילתה, והוא מועבר לפעילות הניתנת לחיפוש יחד עם הנתונים שמוסיפים. אפשר לחלץ את הנתונים הנוספים מהשדה APP_DATA Bundle כדי לצמצם את החיפוש, כמו בדוגמה הבאה:

Kotlin

val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false

Java

Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}

זהירות: אף פעם אל תקראו לשיטה startSearch() מחוץ לארגון שיטת הקריאה החוזרת (callback) של onSearchRequested(). כדי להפעיל את החיפוש בתיבת הדו-שיח שלך בפעילות, לקרוא תמיד ל-onSearchRequested(). אחרת, לא תתבצע התקשרות אל onSearchRequested() ו התאמות אישיות - כמו הוספת appData בדוגמה הקודמת - חסרים.

איך משתמשים בווידג'ט החיפוש

תמונה שרואים בה תצוגת חיפוש בסרגל העליון של האפליקציה

איור 1. הווידג'ט SearchViewבתור תצוגת פעולה בסרגל האפליקציה.

ווידג'ט החיפוש מספק את אותה פונקציונליות שיש בתיבת הדו-שיח של החיפוש. הוא מתחילה את הפעילות המתאימה כשהמשתמש מבצע חיפוש, והוא יכול להציג הצעות לחיפוש ולבצע חיפוש קולי. אם היא לא זמינה עבור כדי להציב את ווידג'ט החיפוש בסרגל האפליקציות, אפשר במקום זאת להציב את הווידג'ט במקום כלשהו בפריסת הפעילות שלכם.

הגדרה של ווידג'ט החיפוש

אחרי שיוצרים הגדרות חיפוש פעילות הניתנת לחיפוש, הפעלת חיפוש בסיוע לכל SearchView באמצעות setSearchableInfo() ומעבירים אליו את האובייקט SearchableInfo שמייצג את תצורה ניתנת לחיפוש.

אפשר לקבל הפניה אל SearchableInfo בטלפון getSearchableInfo() על SearchManager.

לדוגמה, אם משתמשים ב-SearchView כתצוגה של פעולה מסרגל האפליקציות, מפעילים את הווידג'ט במהלך onCreateOptionsMenu() קריאה חוזרת, כפי שמוצג בדוגמה הבאה:

Kotlin

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
}

Java

@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;
}

ווידג'ט החיפוש מוגדר עכשיו והמערכת מציגה שאילתות חיפוש לפעילות הניתנת לחיפוש. אפשר גם להפעיל הצעות חיפוש לווידג'ט החיפוש.

הערה: אם אתם רוצים לטפל בעצמכם בכל הקלט של המשתמשים, אתם יכולים לעשות זאת באמצעות כמה שיטות קריאה חוזרת (callback) ו-event listener. מידע נוסף זמין במאמר מסמכי עזר של SearchView והממשקים הפנימיים שלו.

למידע נוסף על צפיות בפעולות בסרגל האפליקציה: משתמשים בתצוגות פעולה ובפעולות לביצוע ספקים.

תכונות אחרות לווידג'ט החיפוש

הווידג'ט SearchView מספק כמה תכונות נוספות יכול להיות:

לחצן שליחה: כברירת מחדל, אין לחצן לשליחת שאילתת חיפוש, לכן המשתמש צריך מקישים על מקש Return במקלדת כדי להתחיל חיפוש. שלך יכול להוסיף 'הגשה' לחצן בהתקשרות setSubmitButtonEnabled(true)
חידוד שאילתה להצעות חיפוש: כשמפעילים הצעות לחיפוש, בדרך כלל מצפה מהמשתמשים לבחור את ההצעה הזו, אבל הם עשויים גם לצמצם את שאילתת החיפוש המוצעת. אפשר להוסיף לחצן לצד כל הצעה שמוסיפה את ההצעה בתיבת החיפוש לחידוד על ידי המשתמש על ידי התקשרות setQueryRefinementEnabled(true)
יכולת להחליף את מצב החשיפה של תיבת החיפוש: כברירת מחדל, ווידג'ט החיפוש "מסמל", כלומר שמיוצג רק על ידי סמל חיפוש — זכוכית מגדלת. מתרחב אל להציג את תיבת החיפוש כשהמשתמש מקיש על הסמל. כפי שמוצג למעלה לדוגמה, אפשר להציג את תיבת החיפוש כברירת מחדל באמצעות setIconifiedByDefault(false) אפשר גם לשנות את המראה של ווידג'ט החיפוש באמצעות התקשרות setIconified()

יש כמה ממשקי API אחרים במחלקה SearchView שמאפשרים להתאים אישית את ווידג'ט החיפוש. עם זאת, רובם משמשים רק כאשר תטפלו בכל הקלט של המשתמשים בעצמכם, במקום להשתמש במערכת Android כדי שאילתות חיפוש ולהציג הצעות לחיפוש.

משתמשים בווידג'ט וגם בתיבת הדו-שיח

אם מוסיפים את ווידג'ט החיפוש בסרגל האפליקציות Action view (צפייה בפעולה) והפעלה יופיע בסרגל האפליקציות אם יש מקום - באמצעות ההגדרה 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, מציין לחצן החיפוש הקולי חייב להפעיל מזהה שמחזיר את הערך תומלל טקסט לפעילות שניתן לחפש.

תוכלו לספק מאפיינים נוספים כדי לציין את התנהגות החיפוש הקולי, כמו השפה הצפויה והמספר המקסימלי של התוצאות שיחזרו. צפייה מידע נוסף על הגדרות חיפוש על המאפיינים הזמינים.

הוספת הצעות לחיפוש

גם תיבת הדו-שיח של החיפוש וגם ווידג'ט החיפוש יכולים לספק הצעות לחיפוש כמו שהמשתמש מקליד, בעזרת מערכת Android. המערכת מנהלת רשימת ההצעות והטיפול באירוע כשהמשתמש בוחר הצעה חדשה.

אפשר לספק שני סוגים של הצעות לחיפוש:

הצעות אחרונות לחיפוש שאילתות: ההצעות האלה הן מילים שהמשתמש השתמש בהן בעבר כחיפוש באפליקציה שלכם. ראה הוספה הצעות לחיפוש מותאם אישית לקבלת מידע נוסף.
הצעות לחיפוש בהתאמה אישית: אלה הצעות לחיפוש שאתה מספק ממקור הנתונים שלך כדי לעזור למשתמשים לבחור מיד את האיות או הפריט הנכון שהם מחפשים עבור. ראו הוספת חיפוש מותאם אישית הצעות למידע נוסף.