כשמשתמשים בווידג'ט החיפוש או בתיבת הדו-שיח של החיפוש ב-Android, אפשר לספק הצעות לחיפוש בהתאמה אישית שנוצרות מנתונים באפליקציה. לדוגמה, אם האפליקציה היא מילון, אפשר להציע מילים מהמילון להתאים לטקסט שהוזן בשדה החיפוש לפני שהמשתמש מסיים להזין השאילתה שלהם. ההצעות האלה מועילות כי הן יכולות לחזות ביעילות את מה שהמשתמש רוצה ולספק גישה מיידית אליו. איור 1 מציג דוגמה של תיבת דו-שיח של חיפוש עם הצעות מותאמות אישית.
אחרי שתספקו הצעות מותאמות אישית, תוכלו גם להפוך אותן לזמינות של תיבת החיפוש המהיר ברמת המערכת, המספקת גישה לתוכן אפליקציה.
לפני שמוסיפים הצעות מותאמות אישית, מטמיעים את תיבת הדו-שיח של חיפוש ב-Android או ווידג'ט החיפוש לחיפושים באפליקציה. ראו יצירה ממשק חיפוש תוכן ספקים.
העקרונות הבסיסיים
![](https://developer.android.com/static/images/search/search-suggest-custom.png?authuser=2&hl=he)
איור 1. צילום מסך של תיבת דו-שיח של חיפוש עם הצעות לחיפוש בהתאמה אישית.
כשהמשתמש בוחר בהצעה בהתאמה אישית, המערכת שולחת
Intent
אל
פעילות הניתנת לחיפוש. בניגוד לשאילתת חיפוש רגילה ששולחת אובייקט Intent עם
ACTION_SEARCH
תוכלו להגדיר במקום זאת את ההצעות המותאמות אישית שבהן תשתמשו
ACTION_VIEW
- או
כל פעולת Intent אחרת — וגם לכלול נתונים שרלוונטיים
ההצעה שנבחרה. במילון שבדוגמה, כאשר משתמש בוחר
הצעה, האפליקציה תוכל לפתוח מיד את ההגדרה של אותה מילה, במקום זאת
של חיפוש במילון אחר התאמות.
כדי לספק הצעות בהתאמה אישית, מבצעים את השלבים הבאים:
- ליישם פעילות בסיסית בחיפוש, כפי שמתואר ב יוצרים ממשק חיפוש.
- שנה את התצורה שניתנת לחיפוש באמצעות מידע על התוכן ספק שמספק הצעות מותאמות אישית.
- ליצור טבלה, למשל
SQLiteDatabase
, כדי לקבל את ההצעות ולעצב את הטבלה עם העמודות הנדרשות. - יצירת תוכן ספק שיש לו גישה לטבלת ההצעות שלך ומצהיר על במניפסט.
- להצהיר על סוג ה
Intent
שיישלח כשהמשתמש יבחר הצעה, כולל פעולה מותאמת אישית ונתונים מותאמים אישית.
בדיוק כמו שמערכת Android מציגה את תיבת הדו-שיח של החיפוש, היא מציגה גם את הצעות לחיפוש. אתה צריך ספק תוכן שממנו המערכת תוכל לאחזר את ההצעות שלכם. נקראו ספקי תוכן ככה יוצרים ספק תוכן.
כאשר המערכת מזהה שהפעילות שלכם ניתנת לחיפוש ומספקת בהצעות לחיפוש, ההליך הבא מתרחש כשהמשתמש מזין שאילתה:
- המערכת לוקחת את הטקסט של שאילתת החיפוש – כלומר, מה שהוזן עד כה — ושולח שאילתה לספק התוכן שמנהל את הצעות.
- ספק התוכן שלך מחזיר
Cursor
שמצביעה על כל ההצעות שרלוונטיות לשאילתת החיפוש טקסט. - המערכת מציגה את רשימת ההצעות שסופקו על ידי
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()
,
כפי שאפשר לראות בדוגמה הבאה:
Kotlin
val query: String = uri.lastPathSegment.toLowerCase()
Java
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()
קריאה חוזרת:
Kotlin
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) } }
Java
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
.
מידע על דירוג ההצעות של תיבת החיפוש המהיר
ברגע שהצעות החיפוש של האפליקציה יהיו זמינות ל'תיבת החיפוש המהיר', הדירוג של תיבת החיפוש המהיר קובע איך ההצעות יוצגו עבור שאילתה מסוימת. זה עשוי להיות תלוי בכמה אפליקציות אחרות תוצאות לשאילתה הזו והתדירות שבה המשתמש בוחר את התוצאות בהשוואה מאפליקציות אחרות. אין כל ערובה לגבי אופן הפעולה של ההצעות שלך בדירוג או אם הצעות האפליקציה מוצגות בעקבות שאילתה נתונה. לחשבון באופן כללי, הצגת תוצאות איכותיות מגבירה את הסבירות ההצעות מוצגות במיקום בולט, ואפליקציות שמספקות להצעות באיכות נמוכה יש סיכוי גבוה יותר לקבל דירוג נמוך או לא להופיע.