הגדרות חיפוש

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

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

elements:‎

<searchable>

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

מאפיינים:

android:label

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

android:hint

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

android:searchMode

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

ערך	תיאור
"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

‫

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

android:searchSuggestPath

‫

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

android:searchSuggestSelection

‫

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

android:searchSuggestIntentAction

‫

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

android:searchSuggestIntentData

‫

String. נתוני הכוונה שיוגדרו כברירת מחדל לשימוש כשמשתמש מקיש על הצעה מותאמת אישית לחיפוש. אם לא מבטלים את ההצעה שנבחרה באמצעות העמודה 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

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

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

android:voiceLanguageModel

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

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

מידע נוסף זמין במאמר EXTRA_LANGUAGE_MODEL.

android:voicePromptText

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

android:voiceLanguage

‫

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

android:voiceMaxResults

‫

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

<actionkey>

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

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

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

מאפיינים:

android:keycode

‫

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

android:queryActionMsg

‫

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

android:suggestActionMsg

‫

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

android:suggestActionMsgColumn

‫

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