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

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

ویژگی ها:

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 برای بازنویسی متن thebquery استفاده کنید. این فقط زمانی باید استفاده شود که مقادیر موجود در SUGGEST_COLUMN_INTENT_DATA برای بازرسی و ویرایش کاربر مناسب باشند، مانند HTTP URI.
"queryRewriteFromText"	از مقدار ستون SUGGEST_COLUMN_TEXT_1 برای بازنویسی متن درخواست استفاده کنید.

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

android:searchButtonText

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

android:inputType

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

android:imeOptions

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

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

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

android:searchSuggestAuthority

رشته . (برای ارائه پیشنهادات جستجو ضروری است.) این مقدار باید با رشته مرجع ارائه شده در android:authorities عنصر Android manifest <provider> مطابقت داشته باشد.

android:searchSuggestPath

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

android:searchSuggestSelection

رشته . این مقدار به عنوان پارامتر selection به تابع query شما منتقل می شود. معمولاً این یک عبارت 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

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

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

<actionkey>

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

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

شما باید 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>