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

تجربة طريقة "الكتابة"

‫Jetpack Compose هي مجموعة أدوات واجهة المستخدم التي يُنصح باستخدامها على Android. تعرَّف على كيفية إضافة وظيفة البحث في "إنشاء".

شريط البحث →

لتنفيذ البحث بمساعدة من نظام 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

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

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

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

android:searchSuggestAuthority

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

android:searchSuggestPath

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

android:searchSuggestSelection

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

android:searchSuggestIntentAction

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

android:searchSuggestIntentData

String. تمثّل هذه السمة بيانات الهدف التلقائية التي سيتم استخدامها عندما ينقر المستخدم على اقتراح بحث مخصّص. إذا لم يتم تجاهل هذه القيمة من خلال الاقتراح المحدّد (عبر العمود SUGGEST_COLUMN_INTENT_DATA)، يتم وضع هذه القيمة في حقل البيانات الخاص بـ Intent عندما ينقر المستخدم على اقتراح.

android:searchSuggestThreshold

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

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

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

لإتاحة اقتراحات البحث المخصّصة في &quot;مربّع البحث السريع&quot;، يجب أن تتضمّن بعض <searchable> السمات التالية:

android:includeInGlobalSearch

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

android:searchSettingsDescription

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

android:queryAfterZeroResults

Boolean: اضبط القيمة على "true" إذا أردت أن يتم استدعاء موفّر المحتوى الخاص بك للحصول على مجموعات فرعية من طلبات البحث التي لم تعرض أي نتائج سابقًا. على سبيل المثال، إذا لم يعرض مقدّم المحتوى أي نتائج للبحث عن "bo"، يجب إعادة البحث عن "bob". إذا تم ضبطها على "false"، سيتم تجاهل المجموعات الفرعية لجلسة واحدة، ولن يؤدي البحث عن "bob" إلى إعادة طلب البحث. ويستمر ذلك فقط طوال مدة ظهور مربّع حوار البحث أو طوال مدة النشاط عند استخدام أداة البحث. عند إعادة فتح مربّع حوار البحث أو النشاط، يُرسل "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

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

android:voiceMaxResults

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

<actionkey>

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

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

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

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

السمات:

android:keycode

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

android:queryActionMsg

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

android:suggestActionMsg

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

android:suggestActionMsgColumn

String. اسم العمود في موفّر المحتوى الذي يحدّد رسالة الإجراء لمفتاح الإجراء هذا، والتي سيتم إرسالها إذا ضغط المستخدم على مفتاح الإجراء أثناء التركيز على اقتراح. تتيح لك هذه السمة التحكّم في مفتاح الإجراء على أساس اقتراح تلو الآخر، لأنّه بدلاً من استخدام السمة 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>