عند استخدام مربّع حوار "بحث Google" أو تطبيق "بحث Google" المصغّر، يمكنك تقديم اقتراحات البحث المخصّصة التي يتم إنشاؤها من البيانات في تطبيقك. على سبيل المثال: إذا كان تطبيقك قاموسًا، فيمكنك اقتراح كلمات من القاموس مطابقة النص الذي تم إدخاله في حقل البحث قبل أن ينتهي المستخدم من إدخال استعلامهم. هذه الاقتراحات قيّمة لأنها يمكنها التنبؤ بفعالية لما يريده المستخدم وتوفير إمكانية الوصول الفوري إليه. يوضح الشكل 1 مثالاً لمربع حوار بحث يتضمن اقتراحات مخصصة.
بعد تقديم اقتراحات مخصّصة، يمكنك أيضًا إتاحتها للمستخدمين مربع البحث السريع على مستوى النظام، والذي يوفر الدخول إلى المحتوى من خارج التطبيق.
قبل إضافة اقتراحات مخصصة، نفذ مربع حوار بحث Android أو تطبيق "بحث Google" المصغّر لعمليات البحث في تطبيقك راجع إنشاء واجهة بحث المحتوى Google.
الأساسيات
![](https://developer.android.com/static/images/search/search-suggest-custom.png?authuser=19&hl=ar)
الشكل 1. لقطة شاشة لمربع حوار بحث يتضمّن اقتراحات البحث المخصصة.
عندما يختار المستخدم اقتراحًا مخصّصًا، يرسل النظام
في Intent
نشاطًا قابلاً للبحث. على عكس طلب البحث العادي الذي يرسل مقصدًا باستخدام
ACTION_SEARCH
إجراء، يمكنك بدلاً من ذلك تحديد اقتراحاتك المخصّصة
ACTION_VIEW
—أو
أي إجراء غرض آخر - وتضمين البيانات أيضًا ذات الصلة
الاقتراح المحدد. في مثال القاموس، عندما يحدد المستخدم
يمكن للتطبيق فتح تعريف تلك الكلمة على الفور، بدلاً من
البحث في القاموس عن التطابقات.
لتقديم اقتراحات مخصّصة، اتّبِع الخطوات التالية:
- تنفيذ نشاط أساسي للبحث، كما هو موضح في أنشئ واجهة بحث.
- تعديل الإعدادات القابلة للبحث باستخدام معلومات عن المحتوى الذي يقدّم اقتراحات مخصّصة.
- يمكنك إنشاء جدول، كما هو الحال في
SQLiteDatabase
, لاقتراحاتك وتنسيق الجدول بالأعمدة المطلوبة. - إنشاء محتوى الذي يمكنه الوصول إلى جدول الاقتراحات ويعلن في البيان.
- يُرجى تحديد نوع
Intent
الذي سيتم إرساله عندما يختار المستخدم اقتراح، بما في ذلك إجراء مخصّص وبيانات مخصّصة
مثلما يعرض نظام Android مربع حوار البحث، فإنه يعرض أيضًا اقتراحات البحث. تحتاج إلى موفّر محتوى يمكن للنظام من خلاله لاسترداد اقتراحاتك. القراءة موفّرو المحتوى لمعرفة كيفية إنشاء موفّر محتوى.
عندما يحدد النظام أن نشاطك قابل للبحث ويوفر اقتراحات البحث، يتم تنفيذ الإجراء التالي عندما يُدخل المستخدم استعلام:
- يأخذ النظام نص طلب البحث، بمعنى أي نص يتم إدخاله إلى الآن، ثم يسأل موفر المحتوى الذي يدير الاقتراحات.
- يعرض موفّر المحتوى
Cursor
يشير إلى كل الاقتراحات ذات الصلة بطلب البحث النص. - يعرض النظام قائمة الاقتراحات التي يقدمها
Cursor
وبعد عرض الاقتراحات المخصّصة، قد يحدث ما يلي:
- إذا أدخل المستخدم حرفًا آخر أو غير طلب البحث بأي شكل من الأشكال، تتكرر الخطوات السابقة ويتم تحديث قائمة الاقتراحات وفقًا لذلك.
- إذا قام المستخدم بإجراء البحث، فسيتم تجاهل الاقتراحات
إلى نشاطك القابل للبحث باستخدام طريقة
هدف واحد (
ACTION_SEARCH
). - إذا اختار المستخدم اقتراحًا، يتم إرسال هدف إلى نشاط يتضمن إجراء مخصص وبيانات مخصصة حتى يتمكن التطبيق من فتح المحتوى المقترح.
تعديل الإعدادات القابلة للبحث
لإتاحة اقتراحات مخصّصة، أضِف
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
محددة لملف التكوين القابل للبحث، أو خالية إذا لم تعريف السمةandroid:searchSuggestSelection
. تشير رسالة الأشكال البيانية يناقش القسم التالي هذا الأمر بشكل أكبر.selectionArgs
- تحتوي على طلب البحث كالعنصر الأول والوحيد في المصفوفة إذا تشير إلى السمة
android:searchSuggestSelection
في التهيئة القابلة للبحث. في حال عدم الإفصاحandroid:searchSuggestSelection
، تكون هذه المعلمة فارغة. ويناقش القسم التالي هذا الأمر بمزيد من التفصيل.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. في الجزء المحدّد
سلسلة، قم بتضمين علامة الاستفهام (?) كعنصر نائب للعنصر الفعلي
استعلام البحث. يستدعي النظام 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>
باستخدام هذه الإعدادات، توفِّر طريقة query()
المعلمة selection
على أنها "word MATCH ?"
المعلمة selectionArgs
كطلب بحث. عندما تقوم بتمريرها إلى
لغة SQLite
query()
وطريقة، كوسيطات خاصة بها، فيتم تجميعها
معًا - بمعنى أنه يتم استبدال علامة الاستفهام بنص الاستعلام. في حال حذف
تتلقى استعلامات اقتراحات بهذه الطريقة وتحتاج إلى إضافة أحرف بدل إلى طلب البحث
أو إلحاقها أو البادئة بها إلى المعلمة selectionArgs
، لأن
يتم التفاف هذه القيمة بين علامتي اقتباس وإدراجها بدلاً من علامة الاستفهام.
هناك سمة أخرى في المثال السابق وهي
android:searchSuggestIntentAction
، الذي يحدد إجراء الهدف
يتم إرسالها مع كل هدف عندما يختار المستخدم اقتراحًا. تمت مناقشة هذا
كما ورد في الإعلان عن نية
قسم الاقتراحات
إنشاء جدول اقتراحات
عند عرض الاقتراحات إلى النظام باستخدام Cursor
،
النظام أعمدة محددة في كل صف. بغض النظر عما إذا كنت تخزّن
بيانات الاقتراحات في قاعدة بيانات SQLite على الجهاز، قاعدة بيانات على الويب
أو أي تنسيق آخر على الجهاز أو الويب، يمكنه تنسيق الاقتراحات في شكل صفوف.
في جدول وتقديم Cursor
.
يتعرف النظام على عدة أعمدة، ولكن لا يلزم سوى اثنتين منها:
_ID
- رقم تعريف فريد لصف عدد صحيح لكل اقتراح. يتطلب النظام تنفيذ هذا الإجراء من أجل
تقديم الاقتراحات في
ListView
SUGGEST_COLUMN_TEXT_1
- السلسلة المقدَّمة كاقتراح
الأعمدة التالية كلها اختيارية. تتم مناقشة معظمها بشكل أكبر في الأقسام التالية.
SUGGEST_COLUMN_TEXT_2
- سلسلة إذا كانت "
Cursor
" تتضمّن هذا العمود، سيتم يتم تقديم الاقتراحات في تنسيق من سطرين. السلسلة في هذا العمود هي يتم عرضه كسطر نص ثانٍ أصغر حجمًا أسفل الاقتراح الأساسي النص. يمكن أن يكون صفرًا أو فارغًا للإشارة إلى عدم وجود نص ثانوي. SUGGEST_COLUMN_ICON_1
- مصدر أو محتوى أو سلسلة معرّف موارد منتظم (URI) لملف قابل للرسم إذا كان
يتضمن
Cursor
هذا العمود، ثم يتم تقديم جميع الاقتراحات بتنسيق رمز زائد مع النص مع الأيقونة القابلة للرسم على الجانب الأيسر. هذا النمط يمكن أن يكون صفرًا أو صفرًا للإشارة إلى عدم وجود أيقونة في هذا الصف. SUGGEST_COLUMN_ICON_2
- مصدر أو محتوى أو سلسلة معرّف موارد منتظم (URI) لملف قابل للرسم إذا كان
يتضمن
Cursor
هذا العمود، ثم يتم تقديم جميع الاقتراحات بتنسيق رمز زائد مع النص مع الأيقونة على الجانب الأيمن. يمكن أن تظهر فائدة هذا بوضوح أكبر "فارغ" أو "صفر" للإشارة إلى عدم وجود رمز في هذا الصف. SUGGEST_COLUMN_INTENT_ACTION
- سلسلة إجراء intent إذا كان هذا العمود موجودًا ويحتوي على قيمة
صف معين، يُستخدم الإجراء المحدد هنا عند صياغة اقتراح
والنية. فإذا لم يتوفر هذا العنصر، يتم اتخاذ الإجراء من
الحقل
android:searchSuggestIntentAction
في صفحة البحث التكوين. إذا كان الإجراء هو نفسه لكل الاقتراحات، فمن الأفضل فعالاً لتحديد الإجراء باستخدامandroid:searchSuggestIntentAction
واحذف هذا العمود. SUGGEST_COLUMN_INTENT_DATA
- سلسلة معرف موارد منتظم (URI) للبيانات إذا كان هذا العمود موجودًا ويحتوي على قيمة
صف، تُستخدم هذه البيانات عند تكوين هدف الاقتراح. إذا لم يكن العنصر
لم يتم توفيره، تكون البيانات مأخوذة من
الحقل
android:searchSuggestIntentData
في صفحة البحث التكوين. إذا لم يتم تقديم أي من المصدرين، فسيتم خالية. إذا كانت بياناتك متطابقة لجميع الاقتراحات أو يمكن وصفها باستخدام جزء ثابت ومعرف محدد، يكون من الأكثر فعالية تحديده استخدامandroid:searchSuggestIntentData
وحذف هذا . SUGGEST_COLUMN_INTENT_DATA_ID
- سلسلة مسار معرّف الموارد المنتظم (URI) إذا كان هذا العمود موجودًا ويحتوي على قيمة
الصف، ثم "/" ويتم إلحاق هذه القيمة بحقل البيانات في الغرض.
لا تستخدم هذا إلا إذا كان حقل البيانات المحدد بواسطة
السمة
android:searchSuggestIntentData
في السمة القابلة للبحث سبق أن تم ضبط الإعدادات على سلسلة أساسية مناسبة. SUGGEST_COLUMN_INTENT_EXTRA_DATA
- البيانات العشوائية: إذا كان هذا العمود موجودًا ويحتوي على قيمة في صف معين،
هذه هي البيانات الإضافية المستخدمة عند صياغة الغرض من الاقتراح.
إذا لم يتم توفير حقل البيانات الإضافية في intent، يكون حقل البيانات فارغًا. يتيح هذا العمود
توفر الاقتراحات بيانات إضافية يتم تضمينها كقيمة إضافية في
intent's
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
مخصّصًا إلى
نشاطًا قابلاً للبحث. يجب تحديد الإجراء والبيانات للغرض.
إعلان الإجراء المطلوب
الإجراء الأكثر شيوعًا لاقتراح مخصّص هو
ACTION_VIEW
، وهو أمر مناسب عندما تريد فتح محتوى،
مثل تعريف كلمة أو معلومات الاتصال بشخص ما أو صفحة ويب.
ومع ذلك، يمكن أن يكون الإجراء المقصود أي إجراء آخر ويمكن أن يختلف حسب كل إجراء.
اقتراحنا.
واعتمادًا على ما إذا كنت تريد أن تستخدم جميع الاقتراحات الإجراء المقصود نفسه، يمكنك تعريف الإجراء بطريقتين:
- استخدِم السمة
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
، ثم الغرض
المقدّمة في السمة android:searchSuggestIntentAction
استخدام البيانات المختلفة.
تعريف بيانات الغرض
عندما يختار المستخدم اقتراحًا، يتلقى نشاطك القابل للبحث
النية بالإجراء الذي تحدده - كما تمت مناقشته في المقالة السابقة
- ولكن يجب أن يتضمن القصد أيضًا بيانات لنشاطك لتحديد
الاقتراح الذي يتم اختياره. وعلى وجه التحديد، يجب أن تكون البيانات شيئًا فريدًا
لكل اقتراح، مثل معرف الصف للاقتراح في جدول SQLite.
عند استلام الغرض، يمكنك استرداد البيانات المرفقة باستخدام
getData()
أو
getDataString()
يمكنك تحديد البيانات المضمنة في الغرض بطريقتين:
- حدد البيانات لكل اقتراح داخل
عمود واحد (
SUGGEST_COLUMN_INTENT_DATA
) من جدول الاقتراحات.تقديم جميع معلومات البيانات اللازمة لكل هدف في الاقتراحات عن طريق تضمين عمود
SUGGEST_COLUMN_INTENT_DATA
ثم تعبئتها ببيانات فريدة لكل صف. البيانات من هذا العمود يرتبط بالغرض تمامًا كما حدَّدته في هذا العمود. يمكنك ثم استردادها باستخدام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); }
في هذا المثال، الإجراء المطلوب هو ACTION_VIEW
والبيانات
عنوان URI كامل يشير إلى العنصر المقترح، كما تم تركيبه بواسطة
سلسلة android:searchSuggestIntentData
عمود "SUGGEST_COLUMN_INTENT_DATA_ID
". بعد ذلك يمر عنوان URI إلى
طريقة showResult()
المحلية التي تطلب من موفّر المحتوى البحث عن
العنصر المحدد من قِبل عنوان URI.
إعادة كتابة نص طلب البحث
بشكل افتراضي، إذا كان المستخدم يتنقل عبر قائمة الاقتراحات باستخدام عناصر التحكم في الاتجاهات، كما هو الحال باستخدام كرة التعقب أو لوحة الاتجاهات، فإن نص الاستعلام تحديث. ومع ذلك، يمكنك إعادة كتابة نص استعلام المستخدم مؤقتًا كما يظهر في مربع النص باستخدام استعلام يطابق الاقتراح محل التركيز. وهذا يتيح المستخدم مشاهدة طلب البحث المقترح، ويمكنه تحديد مربع البحث وتعديل الاستعلام قبل إرسالها كبحث.
يمكنك إعادة كتابة نص الاستعلام بالطرق التالية:
- إضافة السمة
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>
للجهة المقدِّمة لمنحه ميزة Quick
الإذن بالاطّلاع على مربّع البحث في موفّر المحتوى على النحو الموضّح في ما يلي
مثال:
<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
صحيحة.
لأنّه يجب على المستخدم الانتقال إلى قائمة الإعدادات لتفعيل اقتراحات البحث في تطبيقك، إذا كان البحث جانبًا مهمًا في تطبيقك، ففكر في كيفية نقل ذلك إلى المستخدمين. على سبيل المثال، يمكنك تقديم ملاحظة في المرة الأولى يشغِّل المستخدم التطبيق الذي يشرح كيفية تفعيل اقتراحات البحث مربع البحث.
إدارة اختصارات اقتراحات مربع البحث السريع
يمكن تلقائيًا اختيار الاقتراحات التي يختارها المستخدم من "مربّع البحث السريع". وتحويلها إلى اختصارات. هذه هي الاقتراحات التي ينسخها النظام من تقديم المحتوى ليتمكّن من الوصول إلى الاقتراح بسرعة بدون الحاجة إلى إعادة الاستعلام من موفر المحتوى.
يتم تفعيل هذا الإعداد تلقائيًا لجميع الاقتراحات التي تم استردادها بواسطة ميزة "البحث السريع".
Box، ولكن إذا كانت بيانات الاقتراح تتغير بمرور الوقت، فيمكنك طلب ذلك
تحديث الاختصارات. على سبيل المثال، إذا كانت اقتراحاتك تشير إلى الإعلانات الديناميكية
البيانات، مثل حالة تواجد جهة اتصال، ثم تطلب أن تتم
تحديث الاختصارات عند عرضها للمستخدم. للقيام بذلك، قم بتضمين
SUGGEST_COLUMN_SHORTCUT_ID
في جدول الاقتراحات. يمكنك استخدام
هذا العمود لضبط سلوك الاختصار لكل اقتراح في إحدى
الطرق التالية:
اجعل مربع البحث السريع يعيد استعلام موفر المحتوى لديك للحصول على إصدار اختصار الاقتراح.
أدخِل قيمة في عمود "
SUGGEST_COLUMN_SHORTCUT_ID
" لطلب البحث. اقتراح إعادة الاستعلام عن نسخة جديدة في كل مرة نتائج البحث. يتم عرض الاختصار بسرعة مع أي بيانات أكثر أهمية متاحة مؤخرًا إلى أن يعرض طلب إعادة التحميل، عند هذه النقطة يتم تحديث الاقتراح بالمعلومات الجديدة. استعلام التحديث هو يتم إرساله إلى موفّر المحتوى مع مسار عنوان URISUGGEST_URI_PATH_SHORTCUT
— بدلاً منSUGGEST_URI_PATH_QUERY
اجعل قيمة
Cursor
التي ترجعها تحتوي على اقتراح واحد باستخدام نفس أعمدة الاقتراح الأصلي أو تكون فارغة، مما يشير إلى أن لم يعد الاختصار صالحًا، وفي هذه الحالة سيختفي الاقتراح وتتم إزالة الاختصار.إذا كان أحد الاقتراحات يشير إلى البيانات التي قد تستغرق وقتًا أطول في إعادة التحميل، مثل تحديث معتمد على الشبكة، يمكنك أيضًا إضافة عمود واحد (
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
) إلى جدول اقتراحات بالقيمة "صحيح" لعرض مؤشر سريان العمل الرمز الأيمن إلى أن تكتمل عملية إعادة التحميل. أي قيمة غير صحيحة مؤشر سريان العملتمنع مطلقًا نسخ الاقتراح إلى اختصار.
أدخل القيمة
SUGGEST_NEVER_MAKE_SHORTCUT
في عمودSUGGEST_COLUMN_SHORTCUT_ID
. في هذه الحالة، لا يتم نسخ الاقتراح إلى الاختصار أبدًا. يعد ذلك ضروريًا فقط إذا تمامًا لا تريد أن يظهر الاقتراح المنسوخ سابقًا. إذا كنت على توفير قيمة عادية للعمود، ثم اختصار الاقتراح فقط حتى يتم عرض استعلام التحديث.السماح بتطبيق سلوك الاختصار التلقائي.
يُرجى إبقاء قيمة
SUGGEST_COLUMN_SHORTCUT_ID
فارغة لكل اقتراح لا يتغير ويمكن حفظه الاختصار.
إذا لم تتغير أي من اقتراحاتك على الإطلاق، فلن تحتاج إلى
عمود "SUGGEST_COLUMN_SHORTCUT_ID
".
معلومات عن ترتيب اقتراحات مربّع البحث السريع
بعد إتاحة اقتراحات البحث للتطبيق في مربّع البحث السريع، يحدد ترتيب مربع البحث السريع كيفية ظهور الاقتراحات في المستخدم لطلب بحث معين. قد يعتمد ذلك على عدد التطبيقات الأخرى التي تحتوي على النتائج لطلب البحث هذا وعدد المرات التي حدد فيها المستخدم نتائجك مقارنةً وتلك الواردة من التطبيقات الأخرى. ليس هناك ما يضمن مستوى عرض اقتراحاتك الترتيب أو ما إذا كانت اقتراحات تطبيقك تظهر مطلقًا لطلب بحث معيّن. ضِمن بشكلٍ عام، يزيد تقديم نتائج عالية الجودة من احتمالية ويتم تقديم الاقتراحات في موضع بارز، والتطبيقات التي توفّر ويزيد ترتيب الاقتراحات منخفضة الجودة في ترتيب أدنى أو ألا يتم عرضها.