پیکربندی جستجو

روش نوشتن را امتحان کنید

Jetpack Compose ابزار رابط کاربری پیشنهادی برای اندروید است. یاد بگیرید که چگونه قابلیت جستجو را در Compose اضافه کنید.

نوار جستجو →

برای پیاده‌سازی جستجو با کمک سیستم اندروید - یعنی ارسال درخواست‌های جستجو به یک اکتیویتی و ارائه پیشنهادات جستجو - برنامه شما باید پیکربندی جستجو را در قالب یک فایل XML ارائه دهد.

این صفحه، فایل پیکربندی جستجو را از نظر نحو و کاربرد آن شرح می‌دهد. برای اطلاعات بیشتر در مورد نحوه پیاده‌سازی ویژگی‌های جستجو برای برنامه خود، به ایجاد یک رابط جستجو مراجعه کنید.

محل فایل:

res/xml/ filename .xml
اندروید از نام فایل به عنوان شناسه منبع استفاده می‌کند.

نحو:

<?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:label

منبع رشته‌ای . (الزامی.) نام برنامه شما. باید با نامی که برای ویژگی android:label عنصر مانیفست <activity> یا <application> شما اعمال شده است، یکسان باشد. این برچسب فقط زمانی برای کاربر قابل مشاهده است که android:includeInGlobalSearch را روی "true" تنظیم کنید، که در این صورت، این برچسب برای شناسایی برنامه شما به عنوان یک مورد قابل جستجو در تنظیمات جستجوی سیستم استفاده می‌شود.

android:hint

منبع رشته‌ای . (توصیه می‌شود.) متنی که در فیلد متن جستجو، زمانی که متنی وارد نشده است، نمایش داده می‌شود. این متن به کاربر در مورد محتوای قابل جستجو، راهنمایی ارائه می‌دهد. برای سازگاری با سایر برنامه‌های اندروید، رشته android:hint به صورت "جستجو <content-or-product> " قالب‌بندی کنید. به عنوان مثال، "جستجوی آهنگ‌ها و هنرمندان" یا "جستجوی یوتیوب".

android:searchMode

کلمه کلیدی . حالت‌های اضافی که نمایش جستجو را کنترل می‌کنند، تنظیم می‌کند. حالت‌های موجود، نحوه بازنویسی متن جستجو را هنگام دریافت فوکوس توسط یک پیشنهاد سفارشی تعریف می‌کنند. مقادیر حالت زیر پذیرفته می‌شوند:

ارزش	توضیحات
"queryRewriteFromData"	از مقدار ستون SUGGEST_COLUMN_INTENT_DATA برای بازنویسی متن پرس‌وجو استفاده کنید. این فقط زمانی باید استفاده شود که مقادیر موجود در SUGGEST_COLUMN_INTENT_DATA برای بررسی و ویرایش کاربر، مانند URLهای HTTP، مناسب باشند.
"queryRewriteFromText"	از مقدار ستون SUGGEST_COLUMN_TEXT_1 برای بازنویسی متن پرس‌وجو استفاده کنید.

برای اطلاعات بیشتر، به مستندات مربوط به بازنویسی متن جستجو در بخش «افزودن پیشنهادات جستجوی سفارشی» مراجعه کنید.

android:searchButtonText

منبع رشته‌ای . متنی که در دکمه‌ای که جستجو را اجرا می‌کند نمایش داده می‌شود. به طور پیش‌فرض، دکمه یک آیکون جستجو (یک ذره‌بین) را نشان می‌دهد که برای بین‌المللی‌سازی ایده‌آل است. بنابراین از این ویژگی برای تغییر دکمه استفاده نکنید، مگر اینکه رفتار آن چیزی غیر از جستجو باشد، مانند درخواست URL در یک مرورگر وب.

android:inputType

کلمه کلیدی . نوع روش ورودی مورد استفاده، مانند نوع صفحه کلید نرم افزاری را تعریف می‌کند. برای اکثر جستجوها، که در آنها متن آزاد انتظار می‌رود، به این ویژگی نیازی ندارید. برای لیستی از مقادیر مناسب برای این ویژگی، به inputType مراجعه کنید.

android:imeOptions

کلمه کلیدی . گزینه‌های اضافی برای روش ورودی ارائه می‌دهد. برای اکثر جستجوها، که در آنها متن آزاد انتظار می‌رود، به این ویژگی نیازی ندارید. IME پیش‌فرض actionSearch است که دکمه "جستجو" را به جای بازگشت به ابتدای صفحه کلید ارائه می‌دهد. برای لیستی از مقادیر مناسب برای این ویژگی، به imeOptions مراجعه کنید.

ویژگی‌های پیشنهاد جستجو

اگر یک ارائه‌دهنده محتوا را برای تولید پیشنهادهای جستجو تعریف می‌کنید، باید ویژگی‌های اضافی را تعریف کنید که ارتباطات با ارائه‌دهنده محتوا را پیکربندی می‌کنند. هنگام ارائه پیشنهادهای جستجو، به برخی از ویژگی‌های <searchable> زیر نیاز دارید:

android:searchSuggestAuthority

رشته . (برای ارائه پیشنهادات جستجو الزامی است.) این مقدار باید با رشته اعتبار ارائه شده در ویژگی android:authorities از عنصر <provider> مانیفست اندروید مطابقت داشته باشد.

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 است.

برای اطلاعات بیشتر در مورد ویژگی‌های فوق برای پیشنهادات جستجو، به مستندات مربوط به افزودن پیشنهادات جستجوی سفارشی و افزودن پیشنهادات سفارشی مراجعه کنید.

ویژگی‌های کادر جستجوی سریع

برای اینکه پیشنهادات جستجوی سفارشی شما در کادر جستجوی سریع در دسترس قرار گیرد، به برخی از ویژگی‌های <searchable> زیر نیاز دارید:

android:includeInGlobalSearch

بولی . (برای ارائه پیشنهادات جستجو در کادر جستجوی سریع الزامی است.) اگر می‌خواهید پیشنهادات شما در کادر جستجوی سریع که به صورت سراسری قابل دسترسی است، گنجانده شود، آن را روی "true" تنظیم کنید. کاربر همچنان باید برنامه شما را به عنوان یک مورد قابل جستجو در تنظیمات جستجوی سیستم فعال کند تا پیشنهادات شما در کادر جستجوی سریع نمایش داده شود.

android:searchSettingsDescription

منبع رشته‌ای . شرح مختصری از پیشنهادات جستجویی که شما به کادر جستجوی سریع ارائه می‌دهید، ارائه می‌دهد که در ورودی موارد قابل جستجو برای برنامه شما نمایش داده می‌شود. شرح شما باید به طور خلاصه محتوای قابل جستجو را توصیف کند. به عنوان مثال، "هنرمندان، آلبوم‌ها و آهنگ‌ها" برای یک برنامه موسیقی یا "یادداشت‌های ذخیره شده" برای یک برنامه دفترچه یادداشت.

android:queryAfterZeroResults

بولی . اگر می‌خواهید ارائه‌دهنده محتوای شما برای مجموعه‌های بزرگ پرس‌وجوهایی که قبلاً هیچ نتیجه‌ای برنمی‌گردانند، فراخوانی شود، آن را روی "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

رشته . زبان گفتاری مورد انتظار، که به صورت مقدار رشته‌ای یک ثابت در Locale بیان می‌شود، مانند "de" برای آلمانی یا "fr" برای فرانسوی. این فقط در صورتی مورد نیاز است که با مقدار فعلی Locale.getDefault() متفاوت باشد.

android:voiceMaxResults

عدد صحیح . حداکثر تعداد نتایج قابل بازگشت، از جمله "بهترین" نتیجه را که همیشه به عنوان پرس و جوی اصلی ACTION_SEARCH intent ارائه می‌شود، تعیین می‌کند. باید ۱ یا بیشتر باشد. EXTRA_RESULTS برای دریافت نتایج از intent استفاده کنید. در صورت عدم ارائه، تشخیص دهنده تعداد نتایج قابل بازگشت را انتخاب می‌کند.

<actionkey>

یک کلید و رفتار دستگاه را برای یک عمل جستجو تعریف می‌کند. یک عمل جستجو، بر اساس عبارت جستجو یا پیشنهاد مورد نظر فعلی، با ضربه زدن روی یک دکمه روی دستگاه، رفتار خاصی را ارائه می‌دهد. به عنوان مثال، برنامه مخاطبین یک عمل جستجو را برای شروع یک تماس تلفنی با پیشنهاد مخاطب مورد نظر فعلی هنگام ضربه زدن روی دکمه تماس فراهم می‌کند.

همه کلیدهای عملیاتی در هر دستگاهی موجود نیستند و همه کلیدها را نمی‌توان به این روش لغو کرد. برای مثال، کلید "خانه" را نمی‌توان لغو کرد و همیشه باید به صفحه اصلی برگردد. همچنین، مطمئن شوید که برای کلیدی که برای تایپ یک عبارت جستجو لازم است، کلید عملیاتی تعریف نکنید. این کار کلیدهای عملیاتی موجود و معقول را به دکمه تماس و دکمه منو محدود می‌کند.

توجه: کلیدهای عملیاتی معمولاً قابل کشف نیستند، بنابراین آنها را به عنوان یک ویژگی اصلی برای کاربر ارائه ندهید.

شما باید android:keycode برای تعریف کلید و حداقل یکی از سه ویژگی دیگر را برای تعریف عملیات جستجو تعریف کنید.

ویژگی‌ها:

android:keycode

String . (الزامی.) یک کد کلید از KeyEvent که نشان دهنده کلید عملیاتی است که می‌خواهید به آن پاسخ دهید - برای مثال، "KEYCODE_CALL" . این به ACTION_SEARCH intent که به activity قابل جستجوی شما ارسال می‌شود، اضافه می‌شود. برای بررسی کد کلید، getIntExtra(SearchManager.ACTION_KEY) استفاده کنید. همه کلیدها برای یک عمل جستجو پشتیبانی نمی‌شوند، زیرا بسیاری از آنها برای تایپ، پیمایش یا عملکردهای سیستم استفاده می‌شوند.

android:queryActionMsg

رشته . یک پیام عملیاتی که در صورت فشردن کلید عملیاتی هنگام وارد کردن متن جستجو توسط کاربر، ارسال می‌شود. این پیام به ACTION_SEARCH intent که سیستم به activity قابل جستجوی شما ارسال می‌کند، اضافه می‌شود. برای بررسی رشته، getStringExtra(SearchManager.ACTION_MSG) استفاده کنید.

android:suggestActionMsg

رشته . یک پیام عملیاتی که در صورت فشردن کلید عملیاتی در حین فوکوس روی یک پیشنهاد، ارسال می‌شود. این به هدفی که سیستم به فعالیت قابل جستجوی شما منتقل می‌کند اضافه می‌شود - با استفاده از عملیاتی که برای پیشنهاد تعریف می‌کنید. برای بررسی رشته، getStringExtra(SearchManager.ACTION_MSG) استفاده کنید. این فقط باید در صورتی استفاده شود که همه پیشنهادات شما از این کلید عملیاتی پشتیبانی کنند. اگر همه پیشنهادات نمی‌توانند کلید عملیاتی یکسانی را مدیریت کنند، باید از ویژگی android:suggestActionMsgColumn زیر استفاده کنید.

android:suggestActionMsgColumn

String . نام ستونی در ارائه‌دهنده محتوای شما که پیام عملیاتی را برای این کلید عملیاتی تعریف می‌کند، که در صورت فشردن کلید عملیاتی توسط کاربر در حالی که یک پیشنهاد در حال فوکوس است، ارسال می‌شود. این ویژگی به شما امکان می‌دهد کلید عملیاتی را بر اساس پیشنهاد به پیشنهاد کنترل کنید، زیرا به جای استفاده از ویژگی android:suggestActionMsg برای تعریف پیام عملیاتی برای همه پیشنهادها، هر ورودی در ارائه‌دهنده محتوای شما پیام عملیاتی خود را ارائه می‌دهد.

ابتدا، باید در ارائه‌دهنده محتوای خود، ستونی را برای هر پیشنهاد تعریف کنید تا برای آن یک پیام عملیاتی ارائه دهد، سپس نام آن ستون را در این ویژگی وارد کنید. سیستم با استفاده از رشته‌ای که در اینجا ارائه شده است، به مکان‌نمای پیشنهاد شما نگاه می‌کند تا ستون پیام عملیاتی شما را انتخاب کند و سپس رشته پیام عملیاتی را از مکان‌نما انتخاب می‌کند. آن رشته به intent اضافه می‌شود که سیستم با استفاده از عملیاتی که برای پیشنهادات تعریف می‌کنید، به activity قابل جستجوی شما ارسال می‌کند. برای بررسی رشته، 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>