دمج ميزات بحث Android في تطبيقك
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تجربة طريقة "الكتابة"
Jetpack Compose هي مجموعة أدوات واجهة المستخدم التي يُنصح باستخدامها على Android. تعرَّف على كيفية إضافة وظيفة البحث في "إنشاء".
البحث هو إحدى الميزات الأساسية للمستخدمين على Android. يجب أن يتمكّن المستخدمون من البحث عن أي بيانات متاحة لهم، سواء كان المحتوى مخزّنًا على الجهاز أو على الإنترنت. للمساعدة في توفير تجربة بحث متسقة للمستخدمين، يوفّر نظام التشغيل Android إطار عمل للبحث يساعدك في تنفيذ وظيفة البحث في تطبيقك.
الشكل 1. مربّع حوار بحث يتضمّن اقتراحات بحث مخصّصة
يتيح إطار عمل البحث طريقتَين لإدخال طلب البحث: مربّع حوار البحث في أعلى الشاشة أو أداة بحث مصغّرة (SearchView) يمكنك تضمينها في تصميم نشاطك. في كلتا الحالتين، يساعد نظام التشغيل Android في تنفيذ البحث من خلال إرسال طلبات البحث إلى نشاط معيّن ينفّذ عمليات البحث. يمكنك أيضًا تفعيل مربّع حوار البحث أو التطبيق المصغّر لتقديم اقتراحات البحث أثناء كتابة المستخدم. يعرض الشكل 1 مثالاً على مربّع حوار البحث مع اقتراحات بحث اختيارية.
بعد إعداد مربّع حوار البحث أو أداة البحث، يمكنك إجراء ما يلي:
- فعِّل ميزة "البحث الصوتي".
- تقديم اقتراحات البحث استنادًا إلى طلبات البحث الأخيرة التي أجراها المستخدِمون
- قدِّم اقتراحات بحث مخصّصة تتطابق مع النتائج الفعلية في بيانات تطبيقك.
- عرض اقتراحات البحث في تطبيقك في "مربّع البحث السريع" على مستوى النظام
ملاحظة: لا يوفّر إطار عمل البحث واجهات برمجة تطبيقات للبحث في بياناتك. لإجراء عملية بحث، عليك استخدام واجهات برمجة التطبيقات المناسبة لبياناتك. على سبيل المثال، إذا كانت بياناتك مخزّنة في قاعدة بيانات SQLite، استخدِم واجهات برمجة التطبيقات لإجراء عمليات البحث.android.database.sqlite
بالإضافة إلى ذلك، ليس هناك ما يضمن توفير الجهاز لزر مخصّص للبحث يستدعي واجهة البحث في تطبيقك. عند استخدام مربّع حوار البحث أو واجهة مخصّصة، عليك توفير زر بحث في واجهة المستخدم يفعّل واجهة البحث. لمزيد من المعلومات، يُرجى الاطّلاع على استدعاء مربّع حوار البحث.
توضّح لك الصفحات التالية كيفية استخدام إطار عمل Android لتنفيذ البحث:
- إنشاء واجهة بحث
- كيفية إعداد تطبيقك لاستخدام مربّع حوار البحث أو أداة البحث
- إضافة اقتراحات
لطلبات البحث الأخيرة
- كيفية تقديم اقتراحات استنادًا إلى طلبات البحث المستخدَمة سابقًا
- إضافة اقتراحات مخصّصة
- كيفية تقديم اقتراحات استنادًا إلى بيانات مخصّصة من تطبيقك وعرضها
في "مربع البحث السريع" على مستوى النظام
- الإعدادات القابلة للبحث
- مستند مرجعي لملف الإعداد القابل للبحث تتضمّن المستندات الأخرى أيضًا مناقشة لملف الإعدادات من حيث السلوكيات المحدّدة.
حماية خصوصية المستخدم
عند تنفيذ ميزة البحث في تطبيقك، اتّخِذ خطوات لحماية خصوصية المستخدم. يرى العديد من المستخدمين أنّ أنشطتهم على هواتفهم، بما في ذلك عمليات البحث، هي معلومات خاصة. للحفاظ على خصوصية المستخدمين، يجب الالتزام بالمبادئ التالية:
- عدم إرسال معلومات شخصية إلى الخوادم، وفي حال الضرورة، عدم تسجيلها
المعلومات الشخصية هي أي معلومات يمكن أن تحدّد هوية المستخدمين، مثل أسمائهم أو عناوين بريدهم الإلكتروني أو معلومات الفوترة أو أي بيانات أخرى يمكن ربطها بشكل معقول بهذه المعلومات. إذا كان تطبيقك يتيح البحث بمساعدة خادم، تجنَّب إرسال معلومات شخصية مع طلبات البحث. على سبيل المثال، إذا كنت تبحث عن أنشطة تجارية بالقرب من رمز بريدي، لا تحتاج إلى إرسال رقم تعريف المستخدم أيضًا، بل أرسِل الرمز البريدي فقط إلى الخادم. إذا كان عليك إرسال معلومات شخصية، تجنَّب تسجيلها. إذا كان عليك تسجيلها، احرص على حماية هذه البيانات
بعناية فائقة وامحها في أقرب وقت ممكن.
- توفير طريقة للمستخدمين لمحو سجلّ البحث
يساعد إطار عمل البحث تطبيقك في تقديم اقتراحات خاصة بالسياق أثناء كتابة المستخدم. في بعض الأحيان، تستند هذه الاقتراحات إلى عمليات البحث السابقة أو الإجراءات الأخرى التي اتّخذها المستخدم في جلسة سابقة. قد لا يريد المستخدم أن تظهر عمليات البحث السابقة لمستخدمي الأجهزة الآخرين. إذا كان تطبيقك يقدّم اقتراحات يمكن أن تكشف عن أنشطة البحث السابقة، عليك توفير طريقة للمستخدم لمحو سجلّ البحث. إذا كنت تستخدم SearchRecentSuggestions،
يمكنك استدعاء الطريقة
clearHistory(). إذا كنت تنفّذ اقتراحات مخصّصة، عليك توفير طريقة مشابهة "لمحو السجلّ" في مقدّم المحتوى يمكن للمستخدم تنفيذها.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-08-26 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-26 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["Try the Compose way \nJetpack Compose is the recommended UI toolkit for Android. Learn how to add search functionality in Compose. \n[Search bar →](/develop/ui/compose/components/search-bar) \n\nSearch is a core user feature on Android. Users must be able\nto search any data that is available to them, whether the content is located on the device or\nthe internet. To help create a consistent search experience for users, Android provides a\nsearch framework that helps you implement search for your application. \n\n**Figure 1.** A search dialog with custom\nsearch suggestions.\n\nThe search framework offers two modes of search input: a search dialog at the top of the\nscreen or a search widget ([SearchView](/reference/android/widget/SearchView)) that you can embed in your activity\nlayout. In either case, the Android system assists your search implementation by\ndelivering search queries to a specific activity that performs searches. You can also enable\nthe search dialog or widget to provide search suggestions as the user types. Figure 1 shows an\nexample of the search dialog with optional search suggestions.\n\nOnce you set up either the search dialog or the search widget, you can do the following:\n\n- Enable voice search.\n- Provide search suggestions based on recent user queries.\n- Provide custom search suggestions that match actual results in your application data.\n- Offer your application's search suggestions in the system-wide Quick Search Box.\n\n**Note** : The search framework does *not* provide APIs to\nsearch your data. To perform a search, you need to use APIs appropriate for your data. For example,\nif your data is stored in an SQLite database, use the [android.database.sqlite](/reference/android/database/sqlite/package-summary)\nAPIs to perform searches.\n\n\u003cbr /\u003e\n\n\nAlso, there is no guarantee that a device provides a dedicated SEARCH button that invokes the\nsearch interface in your application. When using the search dialog or a custom interface, you\nmust provide a search button in your UI that activates the search interface. For more\ninformation, see [Invoke the search\ndialog](/develop/ui/views/search/search-dialog#InvokingTheSearchDialog).\n\nThe following pages show you how to use Android's framework to implement search:\n\n**[Create a search interface](/develop/ui/views/search/search-dialog)**\n: How to set up your application to use the search dialog or search widget.\n\n**[Add recent query\nsuggestions](/develop/ui/views/search/adding-recent-query-suggestions)**\n: How to provide suggestions based on queries previously used.\n\n**[Add custom suggestions](/develop/ui/views/search/adding-custom-suggestions)**\n: How to provide suggestions based on custom data from your application and offer them\n in the system-wide Quick Search Box.\n\n**[Searchable configuration](/develop/ui/views/search/searchable-config)**\n: A reference document for the searchable configuration file. The other\n documents also discuss the configuration file in terms of specific behaviors.\n\nProtect user privacy\n\nWhen you implement search in your application, take steps to protect the user's\nprivacy. Many users consider their activities on their phone---including searches---to\nbe private information. To protect users' privacy, abide by the following\nprinciples:\n\n- **Don't send personal information to servers‐and if you must, don't log it.**\n\n Personal information is any information that can personally identify your users, such as their\n names, email addresses, billing information, or other data that can be reasonably linked to such\n information. If your application implements search with the assistance of a server, avoid sending\n personal information along with the search queries. For example, if you are searching for businesses\n near a ZIP code,\n you don't need to send the user ID as well; send only the ZIP code to the server. If you must\n send personal information, avoid logging it. If you must log it, protect that data\n very carefully and erase it as soon as possible.\n- **Provide users with a way to clear their search history.**\n\n The search framework helps your application provide context-specific suggestions while the user\n types. Sometimes these\n suggestions are based on previous searches or other actions taken by the user in an earlier\n session. A user might not want previous searches to be revealed to other device users. If your\n application provides suggestions that\n can reveal previous search activities, implement a way for the user to clear their\n search history. If you are using [SearchRecentSuggestions](/reference/android/provider/SearchRecentSuggestions),\n you can call the\n [clearHistory()](/reference/android/provider/SearchRecentSuggestions#clearHistory())\n method. If you are implementing custom suggestions, you need to provide a similar \"clear history\"\n method in your content provider that the user can execute."]]
