הגדרות חיפוש

ליישם חיפוש בעזרת מערכת 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 משתמשת כדי לספק חיפוש בסיוע.

מאפיינים:

android:label

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

android:hint

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

android:searchMode

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

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

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

android:searchButtonText

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

android:inputType

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

android:imeOptions

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

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

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

android:searchSuggestAuthority

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

android:searchSuggestPath

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

android:searchSuggestSelection

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

android:searchSuggestIntentAction

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

android:searchSuggestIntentData

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

android:searchSuggestThreshold

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

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

android:voiceMaxResults

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

<actionkey>

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

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

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

מאפיינים:

android:keycode

מחרוזת. (חובה). קוד מפתח מ- KeyEvent שמייצג מקש הפעולה שרוצים להגיב עליו, לדוגמה "KEYCODE_CALL". הזה נוסף 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>