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

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

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

android:imeOptions

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

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

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

android:searchSuggestAuthority

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

android:searchSuggestPath

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

android:searchSuggestSelection

سلسلة: يتم تمرير هذه القيمة إلى دالة طلب البحث كمعلمة selection. عادةً ما يكون هذا عبارة 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

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

android:queryAfterZeroResults

منطقي. يمكنك ضبط القيمة على "true" إذا أردت ضبط الخدمة على موفّر المحتوى. تم استدعاءه للمجموعات الرئيسية من الاستعلامات التي كانت تعرض نتائج صفرية في السابق. على سبيل المثال، إذا لا يعرض موفر المحتوى أي نتائج لـ "bo"، يجب طلبها عن "bob". في حال حذف يتم ضبطها على "false"، ويتم تجاهل المجموعات الرئيسية لجلسة واحدة—"bob" لا يستدعي إعادة استعلام. ويبقى هذا الأمر صالحًا فقط خلال عمر مربّع حوار البحث أو مدة النشاط عند استخدام تطبيق "بحث Google" المصغّر عندما تتم إعادة فتح النشاط أو مربع حوار البحث، "بو" إلى مزود المحتوى لديك مرة أخرى. وتكون القيمة الافتراضية 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 الاستعلام الأساسي لـ intent. يجب أن تكون القيمة 1 أو أكبر. استخدام EXTRA_RESULTS للحصول على النتائج من الغرض. إذا لم تتوفر، تختار أداة التعرّف عدد النتائج التي يتم عرضها.

<actionkey>

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

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

يجب تحديد 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>