הגדרות חיפוש

כדאי לנסות את הדרך של כתיבת אימייל

‫Jetpack Compose היא ערכת הכלים המומלצת לבניית ממשק משתמש ל-Android. כך מוסיפים פונקציית חיפוש בכלי הכתיבה.

סרגל החיפוש ←

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

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

מיקום הקובץ:

‫

res/xml/filename.xml
ב-Android, שם הקובץ משמש כמזהה המשאב.

תחביר:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>

רכיבים:

<searchable>

הגדרת כל תצורות החיפוש שמשמשות את מערכת Android כדי לספק חיפוש בעזרת AI.

מאפיינים:

android:label

משאב מחרוזות. (חובה) השם של האפליקציה. השם הזה צריך להיות זהה לשם שמופיע במאפיין android:label של אלמנט המניפסט <activity> או <application>. התווית הזו גלויה למשתמש רק כשמגדירים את הערך של android:includeInGlobalSearch ל-"true". במקרה כזה, התווית הזו משמשת לזיהוי האפליקציה שלכם כפריט שאפשר לחפש בהגדרות החיפוש של המערכת.

android:hint

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

android:searchMode

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

ערך	תיאור
"queryRewriteFromData"	משתמשים בערך מהעמודה SUGGEST_COLUMN_INTENT_DATA כדי לשכתב את הטקסט של שאילתת החיפוש. אפשר להשתמש בערכים האלה רק אם הערכים ב-SUGGEST_COLUMN_INTENT_DATA מתאימים לבדיקה ולעריכה על ידי המשתמש, כמו מזהי URI של HTTP.
"queryRewriteFromText"	משתמשים בערך מהעמודה SUGGEST_COLUMN_TEXT_1 כדי לשכתב את טקסט השאילתה.

מידע נוסף זמין במאמר הוספת הצעות מותאמות אישית לחיפוש.

android:searchButtonText

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

android:inputType

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

android:imeOptions

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

מאפיינים של הצעות לחיפוש

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

android:searchSuggestAuthority

מחרוזת. (חובה כדי לספק הצעות לחיפוש). הערך הזה צריך להיות זהה למחרוזת הסמכות שצוינה במאפיין android:authorities של רכיב מניפסט Android <provider>.

android:searchSuggestPath

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

android:searchSuggestSelection

מחרוזת. הערך הזה מועבר לפונקציית השאילתה כפרמטר selection. בדרך כלל זהו משפט WHERE במסד הנתונים, והוא חייב להכיל סימן שאלה אחד כמחזיק מקום למחרוזת השאילתה בפועל שהוזנה על ידי המשתמש – לדוגמה, "query=?". עם זאת, אפשר גם להשתמש בכל ערך שאינו null כדי להפעיל את השליחה של טקסט השאילתה באמצעות הפרמטר selectionArgs, ואז להתעלם מהפרמטר selection).

android:searchSuggestIntentAction

מחרוזת. פעולת ברירת המחדל של הכוונה שתשמש כשמשתמש מקיש על הצעה מותאמת אישית לחיפוש – כמו "android.intent.action.VIEW". אם הערך הזה לא מוחלף על ידי ההצעה שנבחרה באמצעות העמודה SUGGEST_COLUMN_INTENT_ACTION, הערך מוצב בשדה הפעולה של Intent כשהמשתמש מקיש על הצעה.

android:searchSuggestIntentData

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

android:searchSuggestThreshold

‫

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

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

מאפיינים של תיבת חיפוש מהיר

כדי שהצעות החיפוש המותאמות אישית יהיו זמינות בתיבת החיפוש המהיר, צריך להשתמש בחלק מהמאפיינים הבאים של <searchable>:

android:includeInGlobalSearch

בוליאני. (חובה כדי לספק הצעות לחיפוש בתיבת החיפוש המהיר). מגדירים את הערך "true" אם רוצים שההצעות ייכללו בתיבת החיפוש המהיר שנגישה בכל העולם. המשתמש עדיין צריך להפעיל את האפליקציה כפריט שאפשר לחפש בהגדרות החיפוש של המערכת כדי שההצעות שלכם יופיעו בתיבת החיפוש המהיר.

android:searchSettingsDescription

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

android:queryAfterZeroResults

בוליאני. מגדירים את הערך ל-"true" אם רוצים שהספק של התוכן יופעל עבור קבוצות-על של שאילתות שהחזירו בעבר אפס תוצאות. לדוגמה, אם ספק התוכן מחזיר אפס תוצאות עבור המחרוזת 'bo', צריך לשלוח שוב שאילתה עבור המחרוזת 'bob'. אם הערך הוא "false", המערכת מתעלמת מקבוצות-על במהלך סשן יחיד – המערכת לא תבצע שאילתה חוזרת עבור 'bob'. ההגדרה הזו תקפה רק למשך הזמן שתיבת הדו-שיח של החיפוש פתוחה, או למשך הזמן שהווידג'ט של החיפוש פעיל. כשפותחים מחדש את תיבת הדו-שיח או את הפעילות של החיפוש, השאילתות של 'bo' מופנות שוב לספק התוכן. ערך ברירת המחדל הוא false.

מאפיינים של חיפוש קולי

כדי להפעיל חיפוש קולי, צריך להוסיף חלק מהמאפיינים הבאים <searchable>:

android:voiceSearchMode

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

ערך	תיאור
"showVoiceSearchButton"	הצגת לחצן חיפוש קולי, אם החיפוש הקולי זמין במכשיר. אם המדיניות הזו מוגדרת, צריך להגדיר גם את "launchWebSearch" או את "launchRecognizer", ולהפריד ביניהם באמצעות התו של הקו האנכי (|).
"launchWebSearch"	לחיצה על הכפתור מעבירה את המשתמש ישירות לפעילות חיפוש קולי מובנית באינטרנט. רוב האפליקציות לא משתמשות בדגל הזה, כי הוא מוציא את המשתמש מהפעילות שבה הופעל החיפוש.
"launchRecognizer"	לחיצה על לחצן החיפוש הקולי מעבירה את המשתמש ישירות לפעילות מובנית של הקלטת קול. הפעילות הזו גורמת למשתמש לדבר, מתמללת את הטקסט המדובר ומעבירה את טקסט השאילתה שנוצר לפעילות שאפשר לחפש בה, בדיוק כמו אם המשתמש הקליד את הטקסט בממשק המשתמש של החיפוש והקיש על לחצן החיפוש.

android:voiceLanguageModel

מילת מפתח. מודל השפה שבו מערכת זיהוי הקול צריכה להשתמש. הערכים הקבילים הם:

ערך	תיאור
"free_form"	שימוש בזיהוי דיבור חופשי להכתבת שאילתות. האופטימיזציה מתבצעת בעיקר לאנגלית. זוהי ברירת המחדל.
"web_search"	להשתמש בזיהוי של מונחי חיפוש באינטרנט לביטויים קצרים יותר, כמו חיפוש. התכונה הזו זמינה ביותר שפות מאשר "free_form".

מידע נוסף זמין בכתובת EXTRA_LANGUAGE_MODEL.

android:voicePromptText

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

android:voiceLanguage

מחרוזת. השפה המדוברת הצפויה, שמוצגת כערך המחרוזת של קבוע ב-Locale, כמו "de" לגרמנית או "fr" לצרפתית. השדה הזה נדרש רק אם הוא שונה מהערך הנוכחי של Locale.getDefault().

android:voiceMaxResults

‫

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

<actionkey>

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

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

כדי להגדיר את המפתח, צריך להגדיר את android:keycode ולפחות אחד משלושת המאפיינים האחרים כדי להגדיר את פעולת החיפוש.

מאפיינים:

android:keycode

מחרוזת. (חובה) קוד מקש מ-KeyEvent שמייצג את מקש הפעולה שרוצים להגיב לו – לדוגמה, "KEYCODE_CALL". הקוד הזה מתווסף ל-Intent ACTION_SEARCH שמועבר לפעילות שניתן לחפש בה. כדי לבדוק את קוד המפתח, משתמשים ב-getIntExtra(SearchManager.ACTION_KEY). לא כל המקשים נתמכים בפעולת חיפוש, כי רבים מהם משמשים להקלדה, לניווט או לפונקציות מערכת.

android:queryActionMsg

מחרוזת. הודעת פעולה שתישלח אם מקש הפעולה יילחץ בזמן שהמשתמש מזין טקסט של שאילתה. המידע הזה מתווסף לACTION_SEARCH הכוונה שהמערכת מעבירה לפעילות שניתן לחפש בה. כדי לבדוק את המחרוזת, משתמשים ב-getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

מחרוזת. הודעת פעולה שתישלח אם מקש הפעולה יילחץ בזמן שההצעה נמצאת במיקוד. ההצעה הזו מתווספת לכוונה שהמערכת מעבירה לפעילות שניתן לחפש בה – באמצעות הפעולה שאתם מגדירים להצעה. כדי לבדוק את המחרוזת, משתמשים ב-getStringExtra(SearchManager.ACTION_MSG). אפשר להשתמש בקיצור הדרך הזה רק אם כל ההצעות תומכות במקש הפעולה הזה. אם לא כל ההצעות יכולות לטפל באותו מקש פעולה, צריך להשתמש במאפיין android:suggestActionMsgColumn הבא.

android:suggestActionMsgColumn

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

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

דוגמא:

קובץ ה-XML ‏

נשמר במיקום res/xml/searchable.xml:

<?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:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>