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

امتحان کردن روش Compose
Jetpack Compose جعبه‌ابزار واسط کاربر توصیه‌شده برای Android است. با نحوه افزودن عملکرد جستجو در Compose آشنا شوید.
نوار جستجو ←

برای پیاده‌سازی جستجو با کمک سیستم 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 را به‌صورت «جستجوی <محتوا یا محصول>» قالب‌بندی کنید. برای مثال، «جستجوی آهنگ‌ها و هنرمندان» یا «جستجوی YouTube».
android:searchMode
کلیدواژه. حالت‌های اضافی را که ارائه جستجو را کنترل می‌کند تنظیم می‌کند. حالت‌های دردسترس تعیین می‌کنند که وقتی پیشنهاد سفارشی فوکوس را دریافت می‌کند، نوشتار پُرسمان چگونه باید بازنویسی شود. مقادیر حالت زیر پذیرفته می‌شوند:
مقدارشرح
"queryRewriteFromData" از مقدار ستون SUGGEST_COLUMN_INTENT_DATA برای بازنویسی نوشتار پُرسمان استفاده کنید. این فقط زمانی باید استفاده شود که مقادیر موجود در SUGGEST_COLUMN_INTENT_DATA برای بازرسی و ویرایش کاربر مناسب باشد، مانند URIهای HTTP.
"queryRewriteFromText" از مقدار ستون SUGGEST_COLUMN_TEXT_1 برای بازنویسی نوشتار پُرسمان استفاده کنید.

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

android:searchButtonText
منبع رشته. نوشتاری که در دکمه اجرای جستجو نمایش داده می‌شود. به‌طور پیش‌فرض، دکمه نماد جستجو (ذره‌بین) را نشان می‌دهد که برای بین‌المللی‌سازی ایده‌آل است. بنابراین از این مشخصه برای تغییر دکمه استفاده نکنید، مگراینکه رفتار چیزی غیراز جستجو باشد، مثلاً درخواست نشانی وب در مرورگر وب.
android:inputType
کلیدواژه. نوع روش ورودی مورداستفاده را تعریف می‌کند، مثلاً نوع صفحه‌کلید نرم‌افزاری. برای اکثر جستجوها که در آن‌ها نوشتار قالب آزاد انتظار می‌رود، به این مشخصه نیاز ندارید. برای مشاهده فهرست مقادیر مناسب برای این مشخصه، به inputType مراجعه کنید.
android:imeOptions
کلیدواژه. گزینه‌های بیشتری برای روش ورودی ارائه می‌دهد. برای اکثر جستجوها، که در آن‌ها نوشتار قالب آزاد انتظار می‌رود، به این مشخصه نیاز ندارید. IME پیش‌فرض actionSearch است که به‌جای بازگشت نورد در صفحه‌کلید نرم‌افزاری، دکمه «جستجو» را ارائه می‌دهد. برای مشاهده فهرست مقادیر مناسب برای این مشخصه، به imeOptions مراجعه کنید.

مشخصه‌های پیشنهاد جستجو

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


android:searchSuggestAuthority
رشته. (برای ارائه پیشنهادهای جستجو لازم است.) این مقدار باید با رشته مرجع ارائه‌شده در مشخصه android:authorities عنصر <provider> مانیفست Android مطابقت داشته باشد.
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
عدد صحیح. حداقل تعداد نویسه‌های لازم برای راه‌اندازی جستجوی پیشنهاد. این کار فقط تضمین می‌کند که سیستم برای هر چیزی کوتاه‌تر از آستانه، از ارائه‌دهنده محتوای شما پُرسمان نمی‌کند. مقدار پیش‌فرض ۰ است.

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

مشخصه‌های «چارگوش جستجوی سریع»

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


android:includeInGlobalSearch
بولی. (برای ارائه پیشنهادهای جستجو در «چارگوش جستجوی سریع» لازم است.) اگر می‌خواهید پیشنهادهایتان در «چارگوش جستجوی سریع» که به‌طور سراسری دردسترس است گنجانده شود، روی "true" تنظیم کنید. کاربر باید همچنان برنامه شما را به‌عنوان موردی قابل‌جستجو در تنظیمات جستجوی سیستم فعال کند تا پیشنهادهای شما در «چارگوش جستجوی سریع» نشان داده شود.
android:searchSettingsDescription
منبع رشته. شرح کوتاهی از پیشنهادهای جستجویی که به «چارگوش جستجوی سریع» ارائه می‌دهید ارائه می‌کند، که در ورودی موارد قابل‌جستجو برای برنامه‌تان نمایش داده می‌شود. توضیحات شما باید به‌طور خلاصه محتوای قابل‌جستجو را توصیف کند. برای مثال، «هنرمندان، آلبوم‌ها، و قطعه‌ها» برای برنامه موسیقی، یا «یادداشت‌های ذخیره‌شده» برای برنامه دفترچه یادداشت.
android:queryAfterZeroResults
بولی. اگر می‌خواهید ارائه‌دهنده محتوایتان برای اَبَرمجموعه‌های پُرسمان‌هایی که قبلاً هیچ نتیجه‌ای برنگردانده‌اند فراخوانده شود، روی "true" تنظیم کنید. برای مثال، اگر ارائه‌دهنده محتوای شما برای «bo» صفر نتیجه برگرداند، باید برای «bob» دوباره پرسمان شود. اگر روی "false" تنظیم شود، اَبَرمجموعه‌ها برای یک جلسه نادیده گرفته می‌شوند—«bob» درخواست مجدد را فراخوانی نمی‌کند. این فقط برای طول عمر کادر گفتگوی جستجو یا طول عمر فعالیت هنگام استفاده از ابزاره جستجو باقی می‌ماند. وقتی کادر گفتگوی جستجو یا فعالیت دوباره باز می‌شود، «bo» دوباره ارائه‌دهنده محتوای شما را پُرسمان می‌کند. مقدار پیش‌فرض نادرست است.

مشخصه‌های جستجوی گفتاری

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