إضافة اقتراحات بحث مخصّص

عند استخدام مربّع حوار "بحث Google" أو تطبيق "بحث Google" المصغّر، يمكنك تقديم اقتراحات البحث المخصّصة التي يتم إنشاؤها من البيانات في تطبيقك. على سبيل المثال: إذا كان تطبيقك قاموسًا، فيمكنك اقتراح كلمات من القاموس مطابقة النص الذي تم إدخاله في حقل البحث قبل أن ينتهي المستخدم من إدخال استعلامهم. هذه الاقتراحات قيّمة لأنها يمكنها التنبؤ بفعالية لما يريده المستخدم وتوفير إمكانية الوصول الفوري إليه. يوضح الشكل 1 مثالاً لمربع حوار بحث يتضمن اقتراحات مخصصة.

بعد تقديم اقتراحات مخصّصة، يمكنك أيضًا إتاحتها للمستخدمين مربع البحث السريع على مستوى النظام، والذي يوفر الدخول إلى المحتوى من خارج التطبيق.

قبل إضافة اقتراحات مخصصة، نفذ مربع حوار بحث Android أو تطبيق "بحث Google" المصغّر لعمليات البحث في تطبيقك راجع إنشاء واجهة بحث المحتوى Google.

الأساسيات

الشكل 1. لقطة شاشة لمربع حوار بحث يتضمّن اقتراحات البحث المخصصة.

عندما يختار المستخدم اقتراحًا مخصّصًا، يرسل النظام في Intent نشاطًا قابلاً للبحث. على عكس طلب البحث العادي الذي يرسل مقصدًا باستخدام ACTION_SEARCH إجراء، يمكنك بدلاً من ذلك تحديد اقتراحاتك المخصّصة ACTION_VIEW—أو أي إجراء غرض آخر - وتضمين البيانات أيضًا ذات الصلة الاقتراح المحدد. في مثال القاموس، عندما يحدد المستخدم يمكن للتطبيق فتح تعريف تلك الكلمة على الفور، بدلاً من البحث في القاموس عن التطابقات.

لتقديم اقتراحات مخصّصة، اتّبِع الخطوات التالية:

  • تنفيذ نشاط أساسي للبحث، كما هو موضح في أنشئ واجهة بحث.
  • تعديل الإعدادات القابلة للبحث باستخدام معلومات عن المحتوى الذي يقدّم اقتراحات مخصّصة.
  • يمكنك إنشاء جدول، كما هو الحال في SQLiteDatabase, لاقتراحاتك وتنسيق الجدول بالأعمدة المطلوبة.
  • إنشاء محتوى الذي يمكنه الوصول إلى جدول الاقتراحات ويعلن في البيان.
  • يُرجى تحديد نوع Intent الذي سيتم إرساله عندما يختار المستخدم اقتراح، بما في ذلك إجراء مخصّص وبيانات مخصّصة

مثلما يعرض نظام Android مربع حوار البحث، فإنه يعرض أيضًا اقتراحات البحث. تحتاج إلى موفّر محتوى يمكن للنظام من خلاله لاسترداد اقتراحاتك. القراءة موفّرو المحتوى لمعرفة كيفية إنشاء موفّر محتوى.

عندما يحدد النظام أن نشاطك قابل للبحث ويوفر اقتراحات البحث، يتم تنفيذ الإجراء التالي عندما يُدخل المستخدم استعلام:

  1. يأخذ النظام نص طلب البحث، بمعنى أي نص يتم إدخاله إلى الآن، ثم يسأل موفر المحتوى الذي يدير الاقتراحات.
  2. يعرض موفّر المحتوى Cursor يشير إلى كل الاقتراحات ذات الصلة بطلب البحث النص.
  3. يعرض النظام قائمة الاقتراحات التي يقدمها 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()، بالترتيب:

  1. 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. من الضروري فقط إذا تستخدم نفس مزود المحتوى مع العديد من الأنشطة القابلة للبحث. في حال حذف هذه هي الحالة، وضح مصدر استعلام الاقتراح.

  2. projection
    خالية دائمًا.
  3. selection
    القيمة المقدّمة في android:searchSuggestSelection محددة لملف التكوين القابل للبحث، أو خالية إذا لم تعريف السمة android:searchSuggestSelection. تشير رسالة الأشكال البيانية يناقش القسم التالي هذا الأمر بشكل أكبر.
  4. selectionArgs
    تحتوي على طلب البحث كالعنصر الأول والوحيد في المصفوفة إذا تشير إلى السمة android:searchSuggestSelection في التهيئة القابلة للبحث. في حال عدم الإفصاح android:searchSuggestSelection، تكون هذه المعلمة فارغة. ويناقش القسم التالي هذا الأمر بمزيد من التفصيل.
  5. 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" لطلب البحث. اقتراح إعادة الاستعلام عن نسخة جديدة في كل مرة نتائج البحث. يتم عرض الاختصار بسرعة مع أي بيانات أكثر أهمية متاحة مؤخرًا إلى أن يعرض طلب إعادة التحميل، عند هذه النقطة يتم تحديث الاقتراح بالمعلومات الجديدة. استعلام التحديث هو يتم إرساله إلى موفّر المحتوى مع مسار عنوان URI SUGGEST_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".

معلومات عن ترتيب اقتراحات مربّع البحث السريع

بعد إتاحة اقتراحات البحث للتطبيق في مربّع البحث السريع، يحدد ترتيب مربع البحث السريع كيفية ظهور الاقتراحات في المستخدم لطلب بحث معين. قد يعتمد ذلك على عدد التطبيقات الأخرى التي تحتوي على النتائج لطلب البحث هذا وعدد المرات التي حدد فيها المستخدم نتائجك مقارنةً وتلك الواردة من التطبيقات الأخرى. ليس هناك ما يضمن مستوى عرض اقتراحاتك الترتيب أو ما إذا كانت اقتراحات تطبيقك تظهر مطلقًا لطلب بحث معيّن. ضِمن بشكلٍ عام، يزيد تقديم نتائج عالية الجودة من احتمالية ويتم تقديم الاقتراحات في موضع بارز، والتطبيقات التي توفّر ويزيد ترتيب الاقتراحات منخفضة الجودة في ترتيب أدنى أو ألا يتم عرضها.