إعدادات البحث

لتنفيذ البحث بمساعدة نظام Android - أي عرض طلبات البحث لأحد الأنشطة وتقديم اقتراحات البحث - يجب أن يوفر تطبيقك تهيئة بحث في شكل ملف XML.

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

موقع الملف:

res/xml/filename.xml
يستخدم Android اسم الملف كرقم تعريف المورد.

بناء الجملة:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>

العناصر:

<searchable>

يحدد هذا الإعداد جميع عمليات ضبط البحث التي يستخدمها نظام Android لتوفير البحث المدعوم.

السمات:

android:label

مورد السلسلة. (يجب ملء هذا الحقل.) اسم تطبيقك ويجب أن يكون مطابقًا الاسم المطبّق على السمة android:label في عنصر البيان <activity> أو <application>. لا يظهر هذا التصنيف للمستخدم إلا عند ضبط android:includeInGlobalSearch على "true". وفي هذه الحالة، يتم استخدام هذا التصنيف للتعرّف على تطبيقك كعنصر يمكن البحث عنه في إعدادات البحث الخاصة بالنظام.

android:hint

مورد السلسلة. (يُنصح به.) النص الذي سيتم عرضه في حقل نص البحث عند عدم إدخال أي نص. وهي تقدّم تلميحًا للمستخدم بشأن المحتوى القابل للبحث. للحفاظ على الاتساق مع تطبيقات Android الأخرى، يجب تنسيق سلسلة android:hint على النحو التالي: "البحث <content-or-product>"، على سبيل المثال، "البحث عن أغانٍ وفنّانين" أو "البحث في YouTube".

android:searchMode

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

القيمة	الوصف
"queryRewriteFromData"	استخدِم القيمة من العمود SUGGEST_COLUMN_INTENT_DATA لإعادة كتابة نص طلب البحث. ولا يجب استخدام هذه السمة إلا عندما تكون القيم في SUGGEST_COLUMN_INTENT_DATA مناسبة لفحصها وتعديلها من قِبل المستخدم، مثل معرّفات الموارد المنتظمة (URI) لبروتوكول HTTP.
"queryRewriteFromText"	استخدِم القيمة من العمود SUGGEST_COLUMN_TEXT_1 لإعادة كتابة نص طلب البحث.

لمزيد من المعلومات، راجِع المستندات المتعلّقة بإعادة كتابة نص طلب البحث في إضافة اقتراحات بحث مخصّصة.

android:searchButtonText

مورد السلسلة. النص المطلوب عرضه في الزر الذي ينفذ عملية البحث. بشكل افتراضي، يعرض الزر رمز بحث (عدسة مكبرة)، وهي مثالية للتدويل. لذلك، لا تستخدم هذه السمة لتغيير الزر إلا إذا كان السلوك شيئًا آخر غير البحث، مثل طلب عنوان URL في متصفح ويب.

android:inputType

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

android:imeOptions

الكلمة الرئيسية: يقدم خيارات إضافية لأسلوب الإدخال. لست بحاجة إلى هذه السمة في معظم عمليات البحث التي يُتوقّع فيها استخدام نص ذي تصميم مرن. أداة IME التلقائية هي actionSearch، الذي يوفر زر "البحث" بدلاً من حرف الرجوع في لوحة المفاتيح الإلكترونية. راجِع imeOptions للاطّلاع على قائمة بالقيم المناسبة لهذه السمة.

سمات اقتراحات البحث

إذا حددت موفِّر محتوى لإنشاء اقتراحات البحث، يجب تحديد سمات إضافية تؤدي إلى إعداد الاتصالات مع موفِّر المحتوى. عند تقديم اقتراحات البحث، يجب أن تتوفّر بعض سمات <searchable> التالية:

android:searchSuggestAuthority

سلسلة: (مطلوب لتقديم اقتراحات البحث.) يجب أن تتطابق هذه القيمة مع سلسلة المرجع المقدمة في السمة android:authorities لعنصر بيان Android <provider>.

android:searchSuggestPath

سلسلة: يُستخدم هذا المسار كجزء من طلب بحث الاقتراحات Uri، بعد البادئة والمرجع وقبل مسار الاقتراحات العادية. هذا الإجراء مطلوب فقط إذا كان لديك موفّر محتوى واحد يُصدر أنواعًا مختلفة من الاقتراحات، مثل أنواع بيانات مختلفة، وتحتاج إلى طريقة لتمييز طلبات البحث الخاصة بالاقتراحات عند تلقّيها.

android:searchSuggestSelection

سلسلة: ويتم تمرير هذه القيمة إلى دالة طلب البحث باعتبارها المَعلَمة selection. عادةً ما تكون عبارة WHERE هي عبارة WHERE لقاعدة البيانات، ويجب أن تحتوي على علامة استفهام واحدة كعنصر نائب لسلسلة طلب البحث الفعلية التي يُدخلها المستخدم، مثل "query=?". مع ذلك، يمكنك أيضًا استخدام أي قيمة غير فارغة لبدء تسليم نص طلب البحث باستخدام مَعلمة selectionArgs، ثمّ تجاهل المَعلمة selection).

android:searchSuggestIntentAction

سلسلة: هو إجراء الغرض التلقائي الذي سيتم استخدامه عندما ينقر المستخدم على اقتراح بحث مخصّص، مثل "android.intent.action.VIEW". إذا لم يتم تجاوز هذه القيمة من خلال الاقتراح المحدّد باستخدام عمود SUGGEST_COLUMN_INTENT_ACTION، يتم وضع القيمة في حقل الإجراء في Intent عندما ينقر المستخدم على أحد الاقتراحات.

android:searchSuggestIntentData

سلسلة: هي بيانات الغرض التلقائية التي سيتم استخدامها عندما ينقر المستخدم على اقتراح بحث مخصّص. إذا لم يتم تجاوز هذه القيمة بالاقتراح المحدّد، من خلال عمود SUGGEST_COLUMN_INTENT_DATA، يتم وضع هذه القيمة في حقل البيانات في Intent عندما ينقر المستخدم على اقتراحًا.

android:searchSuggestThreshold

عدد صحيح. تمثّل هذه السمة الحد الأدنى لعدد الأحرف اللازمة لبدء البحث عن اقتراح. ويضمن ذلك فقط أنّ النظام لن يطلب من موفّر المحتوى البحث عن أيّ محتوى أقصر من الحدّ الأدنى. القيمة التلقائية هي 0.

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

سمات مربع البحث السريع

لإتاحة اقتراحات البحث المخصص لمربع البحث السريع، ستحتاج إلى بعض سمات <searchable> التالية:

android:includeInGlobalSearch

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

android:searchSettingsDescription

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

android:queryAfterZeroResults

منطقية اضبط القيمة على "true" إذا كنت تريد استدعاء موفّر المحتوى للمجموعات الرئيسية من طلبات البحث التي لم تعرض في السابق أي نتائج. على سبيل المثال، إذا لم يعرض موفِّر المحتوى أي نتائج لكلمة "bo"، يجب طلبه بدلاً من "bob". أمّا في حال ضبط السياسة على "false"، فسيتم تجاهل السمات المميزة لجلسة واحدة، ولا يستدعي "bob" طلب بحث. يستمر هذا الإجراء فقط طوال مدة استخدام مربّع حوار البحث أو مدة النشاط عند استخدام تطبيق "بحث Google" المصغّر. عند إعادة فتح مربع حوار البحث أو النشاط، ترسل "bo" طلبًا إلى موفّر المحتوى مرة أخرى. وتكون القيمة الافتراضية false (خطأ).

سمات البحث الصوتي

لتفعيل البحث الصوتي، يجب استخدام بعض سمات <searchable> التالية:

android:voiceSearchMode

الكلمة الرئيسية: (مطلوب لتوفير إمكانات البحث الصوتي). لتفعيل البحث الصوتي، مع وضع محدد للبحث الصوتي. قد لا يوفّر الجهاز ميزة البحث الصوتي، وفي هذه الحالة لن يكون لهذه العلامات أي تأثير. يتم قبول قيم الوضع التالية:

القيمة	الوصف
"showVoiceSearchButton"	عرض زر بحث صوتي إذا كان البحث الصوتي متوفرًا على الجهاز. في حال ضبطها، يجب ضبط "launchWebSearch" أو "launchRecognizer" أيضًا، مفصولاً بشرطة رأسية (|).
"launchWebSearch"	ينقل زر البحث الصوتي المستخدم مباشرةً إلى نشاط بحث صوتي مضمَّن في الويب. ولا تستخدم معظم التطبيقات هذه العلامة، لأنّها تنقل المستخدم بعيدًا عن النشاط الذي تم استدعاء البحث فيه.
"launchRecognizer"	ينقل زر البحث الصوتي المستخدم مباشرةً إلى نشاط التسجيل الصوتي المضمّن. يطلب هذا النشاط من المستخدم التحدّث وتحويل النص المنطوق إلى نص وإعادة توجيه نص طلب البحث الناتج إلى النشاط القابل للبحث، كما لو كان المستخدم قد كتبه في واجهة مستخدم البحث ونقر على زر البحث.

android:voiceLanguageModel

الكلمة الرئيسية: نموذج اللغة الذي يجب استخدامه بواسطة نظام التعرّف على الصوت. يتم قبول القيم التالية:

القيمة	الوصف
"free_form"	يمكنك استخدام ميزة التعرّف على الكلام الحرة لإملاء الاستعلامات. تم تحسين هذا في المقام الأول لللغة الإنجليزية. وهذا هو الخيار التلقائي.
"web_search"	استخدام التعرف على عبارة بحث الويب مع العبارات الأقصر التي تشبه عبارات البحث. وهو متوفّر بلغات أكثر من "free_form".

يمكنك الاطّلاع على EXTRA_LANGUAGE_MODEL للحصول على مزيد من المعلومات.

android:voicePromptText

مورد السلسلة. رسالة إضافية يتم عرضها في مربّع حوار الإدخال الصوتي.

android:voiceLanguage

سلسلة: اللغة المحكية المتوقعة، ويتم التعبير عنها بقيمة السلسلة لثابت في Locale، مثل "de" للّغة الألمانية أو "fr" للّغة الفرنسية. تكون هذه السمة مطلوبة فقط إذا كانت مختلفة عن القيمة الحالية لـ Locale.getDefault().

android:voiceMaxResults

عدد صحيح. لضبط الحد الأقصى لعدد النتائج التي يتم عرضها، بما في ذلك نتيجة "أفضل"، والتي يتم تقديمها دائمًا على أنها طلب البحث الأساسي للنية ACTION_SEARCH. يجب أن تكون القيمة 1 أو أكبر. استخدِم EXTRA_RESULTS للحصول على النتائج من النية. وفي حال عدم توفيرها، تختار أداة التعرُّف عدد النتائج التي يتم عرضها.

<actionkey>

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

لا تتوفّر جميع مفاتيح الإجراءات على كل جهاز، ولا يمكن تجاهل جميع المفاتيح بهذه الطريقة. على سبيل المثال، لا يمكن إلغاء المفتاح "Home" (الصفحة الرئيسية) ويجب أن يعود دائمًا إلى الشاشة الرئيسية. تأكَّد أيضًا من عدم تحديد مفتاح إجراء للمفتاح المطلوب لكتابة طلب بحث. ويحصر ذلك استخدام مفاتيح الإجراءات المتاحة والمعقولة في زر الاتصال وزر القائمة.

ملاحظة: لا يمكن اكتشاف مفاتيح الإجراءات بشكل عام، لذا لا تقدِّمها كميزة أساسية للمستخدم.

ويجب تحديد android:keycode لتحديد المفتاح وسمة واحدة على الأقل من السمات الثلاث الأخرى لتحديد إجراء البحث.

السمات:

android:keycode

سلسلة: (يجب ملء هذا الحقل.) رمز مفتاح من KeyEvent يمثّل مفتاح الإجراء الذي تريد الردّ عليه، مثلاً "KEYCODE_CALL". تتم إضافة هذه القيمة إلى الغرض ACTION_SEARCH الذي تم تمريره إلى نشاطك القابل للبحث. لفحص رمز المفتاح، استخدِم getIntExtra(SearchManager.ACTION_KEY). لا تتوافق بعض المفاتيح مع إجراء بحث معيّن، لأنّ العديد منها يُستخدم للكتابة أو التنقل أو وظائف النظام.

android:queryActionMsg

سلسلة: رسالة إجراء يتم إرسالها إذا تم الضغط على مفتاح الإجراء أثناء إدخال المستخدم لنص طلب البحث. تتم إضافة هذه البيانات إلى الغرض ACTION_SEARCH الذي يرسله النظام إلى نشاطك القابل للبحث. ولفحص السلسلة، استخدِم getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

سلسلة: رسالة إجراء يتم إرسالها إذا تم الضغط على مفتاح الإجراء أثناء التركيز على اقتراح. تُضاف هذه السمة إلى الغرض من إرسال النظام إلى نشاطك الذي يمكن البحث فيه، وذلك باستخدام الإجراء الذي تحدّده للاقتراح. لفحص السلسلة، استخدِم السمة getStringExtra(SearchManager.ACTION_MSG). يجب استخدام هذا فقط إذا كانت جميع اقتراحاتك تتوافق مع مفتاح الإجراء هذا. إذا لم تتمكّن كل الاقتراحات من معالجة مفتاح الإجراء نفسه، عليك استخدام سمة android:suggestActionMsgColumn التالية بدلاً من ذلك.

android:suggestActionMsgColumn

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

أولاً، يجب تحديد عمود في موفِّر المحتوى لكل اقتراح من أجل تقديم رسالة إجراء له، ثم توفير اسم العمود في هذه السمة. يفحص النظام مؤشر الاقتراح، باستخدام السلسلة المقدَّمة هنا، لاختيار عمود رسالة الإجراء، ثم يختار سلسلة رسالة الإجراء من المؤشر. تتم إضافة هذه السلسلة إلى الغرض الذي يمرّره النظام إلى نشاطك القابل للبحث، وذلك باستخدام الإجراء الذي تحدّده لتقديم الاقتراحات. ولفحص السلسلة، استخدِم getStringExtra(SearchManager.ACTION_MSG). في حال عدم توفّر بيانات الاقتراح المحدّد، يتم تجاهل مفتاح الإجراء.

مثلا:

تم حفظ ملف XML في res/xml/searchable.xml:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>