הוספת הצעות לחיפוש בהתאמה אישית

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

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

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

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

איור 1. צילום מסך של תיבת דו-שיח של חיפוש עם הצעות לחיפוש בהתאמה אישית.

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

כדי לספק הצעות בהתאמה אישית, מבצעים את השלבים הבאים:

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

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

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

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

אחרי שההצעות בהתאמה אישית יוצגו, יכול להיות שזה מה שיקרה:

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

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

כדי להוסיף תמיכה בהצעות מותאמות אישית, android:searchSuggestAuthority אל רכיב <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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

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

יצירת ספק תוכן

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

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

פרטים על יצירת ספק תוכן להצעות מותאמות אישית בסעיפים הבאים:

טיפול בשאילתת ההצעה

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

יצירה של טבלת הצעות

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

טיפול בשאילתת ההצעה

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

הנה סיכום של הפרמטרים שהמערכת מעבירה אמצעי התשלום query(), מופיע לפי הסדר:

uri

תמיד יש תוכן Uri, בפורמט הבא ככה:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

ברירת המחדל היא שהמערכת תעביר את ה-URI הזה ותצרף את השאילתה שליחת טקסט:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

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

החלק optional.suggest.path כלול רק ה-URI, אם תגדירו נתיב כזה בקובץ התצורה שמשמש לחיפוש המאפיין android:searchSuggestPath. יש צורך רק אם אתם משתמשים באותו ספק תוכן למספר פעילויות שאפשר לחפש. אם המיקום במקרה כזה, צריך להבהיר את המקור של שאילתת ההצעה.

projection

תמיד אפס.

selection

הערך שצוין בandroid:searchSuggestSelection של קובץ התצורה לחיפוש, או null אם לא להצהיר על המאפיין android:searchSuggestSelection. נדון בנושא זה בהרחבה.

selectionArgs

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

sortOrder

תמיד אפס.

המערכת יכולה לשלוח לכם את הטקסט של שאילתת החיפוש בשתי דרכים. שיטת ברירת המחדל היא שטקסט השאילתה ייכלל כנתיב האחרון של ה-URI של התוכן שהועבר הפרמטר uri. אבל אם כוללים ערך בחירה android:searchSuggestSelection של ההגדרה האישית שלך שניתנת לחיפוש אז הטקסט של השאילתה עובר במקום זאת בתור הרכיב הראשון מערך מחרוזת selectionArgs. שתי האפשרויות האלה מתוארות הבא.

אחזור השאילתה ב-URI

כברירת מחדל, השאילתה מצורפת כקטע האחרון של uri פרמטר — אובייקט Uri. כדי לאחזר את טקסט השאילתה בתוך מקרה, שימוש getLastPathSegment(), כפי שאפשר לראות בדוגמה הבאה:

val query: String = uri.lastPathSegment.toLowerCase()

String query = uri.getLastPathSegment().toLowerCase();

הפעולה הזו מחזירה את הקטע האחרון של ה-Uri, שהוא השאילתה טקסט שהמשתמש מזין.

הצגת השאילתה בארגומנטים של הבחירה

במקום להשתמש ב-URI, אולי כדאי יותר query() כדי לקבל את כל מה שצריך כדי לבצע שאפשר לחפש, ואולי תרצו גם את selection selectionArgs כדי להעביר את הערכים המתאימים. כאן גודל אות, צריך להוסיף את המאפיין android:searchSuggestSelection הגדרה שאפשר לחפש באמצעות מחרוזת הבחירה של SQLite. בבחירה מחרוזת, כוללים סימן שאלה (?) בתור placeholder שאילתת החיפוש. המערכת קוראת ל-query() כשמחרוזת הבחירה היא הפרמטר selection ושאילתת החיפוש כרכיב הראשון במערך selectionArgs.

לדוגמה, כך אפשר ליצור המאפיין android:searchSuggestSelection כדי ליצור טקסט מלא הצהרת חיפוש:

<?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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

עם ההגדרות האישיות האלה, ה-method query() מספקת את selection כפרמטר "word MATCH ?", הפרמטר selectionArgs כשאילתת החיפוש. כשמעבירים את הערכים האלה אל SQLite query() בתור הארגומנטים התואמים שלהם, הם מסונתזים יחד – כלומר סימן השאלה יוחלף בטקסט של השאילתה. אם המיקום מקבלים שאילתות של הצעות באופן הזה וצריך להוסיף לשאילתה תווים כלליים לחיפוש טקסט, מוסיפים או מוסיפים להם תחילית לפרמטר selectionArgs, כי הערך הזה מוקף במירכאות ומוכנס במקום סימן השאלה.

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

יצירה של טבלת הצעות

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

המערכת מבינה כמה עמודות, אבל צריך רק שתיים מהן:

_ID

מזהה שורה ייחודי של מספר שלם לכל הצעה. המערכת דורשת את זה כדי להציג הצעות ListView

SUGGEST_COLUMN_TEXT_1

המחרוזת שמוצגת כהצעה.

כל העמודות הבאות הן אופציונליות. רובם מוזכרים בפירוט רב יותר בקטעים הבאים.

SUGGEST_COLUMN_TEXT_2

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

SUGGEST_COLUMN_ICON_1

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

SUGGEST_COLUMN_ICON_2

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

SUGGEST_COLUMN_INTENT_ACTION

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

SUGGEST_COLUMN_INTENT_DATA

מחרוזת URI של נתונים. אם העמודה הזו קיימת ומכילה ערך בשורה הזו נעשה שימוש בנתונים האלה ליצירת הכוונה של ההצעה. אם הרכיב אינו מוגדר, הנתונים נלקחים שדה android:searchSuggestIntentData בחיפוש הגדרה אישית. אם לא צוין מקור, שדה הנתונים של ה-Intent יהיה null. אם הנתונים זהים בכל ההצעות, או שניתן לתאר אותם באמצעות חלק קבוע ומזהה ספציפי, עדיף לציין באמצעות android:searchSuggestIntentData והשמטה עמודה.

SUGGEST_COLUMN_INTENT_DATA_ID

מחרוזת נתיב של URI. אם העמודה הזו קיימת ומכילה ערך שורה ואז "/" והערך הזה מתווסף לשדה הנתונים ב-Intent. יש להשתמש באפשרות הזו רק אם שדה הנתונים שצוין על ידי מאפיין android:searchSuggestIntentData בחיפוש כבר מוגדר למחרוזת בסיס מתאימה.

SUGGEST_COLUMN_INTENT_EXTRA_DATA

נתונים שרירותיים. אם העמודה הזו קיימת ומכילה ערך בשורה נתונה, אלה הנתונים הנוספים שמשמשים ליצירת הכוונה של ההצעה. אם לא צוין ערך, שדה הנתונים הנוספים של ה-Intent יהיה null. העמודה הזו מאפשרת מספקות נתונים נוספים שכלולים של Intent EXTRA_DATA_KEY מקש.

SUGGEST_COLUMN_QUERY

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

SUGGEST_COLUMN_SHORTCUT_ID

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

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

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

המידע לגבי רוב העמודות האלה מפורט בסעיפים הבאים.

הצהרה על כוונה לקבל הצעות

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

הצהרה על פעולת הכוונה

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

תלוי אם רוצים שכל ההצעות יתבססו על אותה פעולת Intent, אפשר להגדיר את הפעולה בשתי דרכים:

• שימוש במאפיין android:searchSuggestIntentAction של קובץ תצורה זמין לחיפוש כדי להגדיר את הפעולה עבור כל ההצעות, כמו שמוצגת בדוגמה הבאה:

  <?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"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW" >
  </searchable>
  

• יש להשתמש בעמודה SUGGEST_COLUMN_INTENT_ACTION כדי להגדיר פעולה לגבי הצעות בודדות. כדי לעשות את זה, מוסיפים עמודה אחת (SUGGEST_COLUMN_INTENT_ACTION) לטבלת ההצעות ולכל הצעה, המקום בה את הפעולה שבה צריך להשתמש, כמו "android.intent.action.VIEW".

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

הצהרה על נתוני Intent

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

אפשר להגדיר את הנתונים שנכללים מתוך Intent בשתי דרכים:

• להגדיר את הנתונים לכל הצעה בתוך עמודה SUGGEST_COLUMN_INTENT_DATA בטבלת ההצעות.

  מספקים את כל הנתונים הנחוצים לכל כוונה בהצעות טבלה באמצעות הכללת העמודה SUGGEST_COLUMN_INTENT_DATA ואז לאכלס אותה בנתונים ייחודיים לכל שורה. הנתונים מהעמודה הזו מצורף ל-Intent בדיוק כמו שמגדירים אותו בעמודה הזו. אפשר ואז מאחזרים אותו באמצעות getData() או getDataString().

• פיצול URI של נתונים לשני חלקים: החלק המשותף לכל ההצעות ואת החלק הייחודי של כל הצעה. מציבים את החלקים האלה ב מאפיין android:searchSuggestintentData של החיפוש והעמודה SUGGEST_COLUMN_INTENT_DATA_ID של בטבלת ההצעות, בהתאמה.

  הדוגמה הבאה מראה איך להצהיר על החלק מה-URI שמשותף לכל ההצעות מאפיין android:searchSuggestIntentData של המודעות שלך שניתנות לחיפוש תצורה:

    <?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"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:searchSuggestIntentData="content://com.example/datatable" >
    </searchable>
    

  כלול את הנתיב הסופי לכל הצעה — החלק הייחודי - ב- העמודה SUGGEST_COLUMN_INTENT_DATA_ID של ההצעות טבלה. כשהמשתמש בוחר בהצעה, המערכת לוקחת את המחרוזת מ: android:searchSuggestIntentData, הוספה של קו נטוי (/), ואז מוסיף את הערך המתאים עמודה SUGGEST_COLUMN_INTENT_DATA_ID ליצירת תוכן שלם URI. לאחר מכן אפשר לאחזר את Uri באמצעות getData().

הוספת עוד נתונים

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

הכוונה גם לכוונה

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

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

בדוגמה הזו, פעולת ה-Intent היא ACTION_VIEW והנתונים כולל URI מלא שמצביע אל הפריט המוצע, כפי שמסונתז באמצעות מחרוזת android:searchSuggestIntentData ו עמודה SUGGEST_COLUMN_INTENT_DATA_ID. לאחר מכן ה-URI מעביר שיטה showResult() מקומית ששולחת שאילתה אל ספק התוכן שצוין על ידי ה-URI.

שכתוב טקסט השאילתה

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

אפשר לשכתב את טקסט השאילתה בדרכים הבאות:

• הוספת המאפיין android:searchMode לחיפוש עם הערך "queryRewriteFromText". כאן הפנייה, התוכן מהSUGGEST_COLUMN_TEXT_1 של ההצעה משמשת לשכתוב טקסט השאילתה.
• הוספת המאפיין android:searchMode לחיפוש עם הערך "queryRewriteFromData". כאן הוא התוכן מההצעה העמודה SUGGEST_COLUMN_INTENT_DATA משמשת לשכתוב השאילתה טקסט. יש להשתמש במאפיין הזה רק עם מזהי URI או פורמטים אחרים של נתונים שמיועדים להיות גלויות למשתמש, כמו כתובות URL מסוג HTTP. אל תשתמשו בסכימות URI פנימיות כדי לשכתב את השאילתה באופן הזה.
• מזינים מחרוזת טקסט ייחודית של השאילתה עמודה SUGGEST_COLUMN_QUERY בטבלת ההצעות. אם קיימת ומכילה ערך להצעה הנוכחית, היא ששימש לשכתוב הטקסט של השאילתה ולשינוי אחד מהמשפטים הקודמים בפועל.

חשיפת הצעות לחיפוש לתיבת החיפוש המהיר

ברגע שהגדרתם את האפליקציה שלכם כך שתספקו הצעות חיפוש מותאמות אישית, כך לתיבת החיפוש המהיר שנגישה בכל העולם קל לבצע שינויים את התצורה שניתנת לחיפוש כדי לכלול android:includeInGlobalSearch עם הערך "true".

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

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

בדוגמה הזו, הספק מגביל את גישת הקריאה והכתיבה לתוכן. הרכיב <path-permission> מתקן את ההגבלה בכך הענקת גישת קריאה לתוכן בתוך "/search_suggest_query" קידומת של נתיב כשההרשאה "android.permission.GLOBAL_SEARCH" קיים. פעולה זו מעניקה גישה לתיבת החיפוש המהיר, כך שתוכל לשלוח שאילתות על התוכן שלך כדי לקבל הצעות.

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

הפעלת הצעות במכשיר

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

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

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

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

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

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

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

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

• אפשר להפוך את תיבת החיפוש המהיר לשאילתה מחדש של ספק התוכן כדי לקבל של קיצור הדרך להצעה.

  בעמודה SUGGEST_COLUMN_SHORTCUT_ID מציינים ערך עבור את ההצעה לבקש שאילתה מחדש לגבי גרסה חדשה בכל פעם שקיצור הדרך מוצגת. קיצור הדרך מוצג במהירות עם הנתונים החשובים ביותר עד ששאילתת הרענון תחזור, ובשלב זה ההצעה מתעדכנת עם המידע החדש. שאילתת הרענון היא נשלח לספק התוכן עם נתיב URI של SUGGEST_URI_PATH_SHORTCUT — במקום SUGGEST_URI_PATH_QUERY.

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

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

• מניעת העתקת ההצעה לקיצור דרך.

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

• להחיל את התנהגות ברירת המחדל של מקשי הקיצור.

  יש להשאיר את השדה SUGGEST_COLUMN_SHORTCUT_ID ריק בכל אחד מהשדות שלא משתנה ושניתן לשמור אותה מקש קיצור.

אם אף אחת מההצעות לא תשתנה, אין צורך עמודה SUGGEST_COLUMN_SHORTCUT_ID.

מידע על דירוג ההצעות של תיבת החיפוש המהיר

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