پیشنهادات جستجوی سفارشی را اضافه کنید

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

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

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

اصول اولیه

شکل 1. تصویر صفحه گفتگوی جستجو با پیشنهادهای جستجوی سفارشی.

هنگامی که کاربر یک پیشنهاد سفارشی را انتخاب می کند، سیستم یک Intent به فعالیت قابل جستجوی شما ارسال می کند. برخلاف یک عبارت جستجوی معمولی که یک intent را با عملکرد ACTION_SEARCH ارسال می‌کند، می‌توانید در عوض پیشنهادهای سفارشی خود را برای استفاده از ACTION_VIEW - یا هر اقدام قصد دیگری - تعریف کنید و همچنین داده‌هایی را که به پیشنهاد انتخاب‌شده مرتبط هستند را شامل کنید. در مثال فرهنگ لغت، زمانی که کاربر پیشنهادی را انتخاب می‌کند، برنامه می‌تواند به جای جستجو در فرهنگ لغت برای موارد منطبق، بلافاصله تعریف آن کلمه را باز کند.

برای ارائه پیشنهادات سفارشی، مراحل زیر را انجام دهید:

• همانطور که در ایجاد رابط جستجو توضیح داده شده است، یک فعالیت قابل جستجو اولیه را اجرا کنید.
• پیکربندی قابل جستجو را با اطلاعات مربوط به ارائه‌دهنده محتوا که پیشنهادات سفارشی ارائه می‌کند، تغییر دهید.
• یک جدول، مانند SQLiteDatabase ، برای پیشنهادات خود بسازید و جدول را با ستون های مورد نیاز قالب بندی کنید.
• یک ارائه دهنده محتوا ایجاد کنید که به جدول پیشنهادات شما دسترسی داشته باشد و ارائه دهنده را در مانیفست خود اعلام کنید.
• زمانی که کاربر پیشنهادی را انتخاب می‌کند، نوع Intent ارسالی را اعلام کنید، از جمله یک اقدام سفارشی و داده‌های سفارشی.

همانطور که سیستم اندروید گفتگوی جستجو را نمایش می دهد، پیشنهادات جستجوی شما را نیز نمایش می دهد. شما به یک ارائه دهنده محتوا نیاز دارید که سیستم بتواند پیشنهادات شما را از آن بازیابی کند. ارائه دهندگان محتوا را بخوانید تا نحوه ایجاد یک ارائه دهنده محتوا را بیاموزید.

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

1. این سیستم متن درخواست جستجو را می گیرد - یعنی هر آنچه که تاکنون وارد شده است - و یک پرس و جو را برای ارائه دهنده محتوای شما انجام می دهد که پیشنهادات شما را مدیریت می کند.
2. ارائه‌دهنده محتوای شما Cursor برمی‌گرداند که به همه پیشنهادهایی که با متن عبارت جستجو مرتبط هستند اشاره می‌کند.
3. سیستم لیستی از پیشنهادات ارائه شده توسط Cursor را نمایش می دهد.

پس از نمایش پیشنهادات سفارشی، ممکن است موارد زیر رخ دهد:

• اگر کاربر حرف دیگری را وارد کند یا به هر نحوی پرس و جو را تغییر دهد، مراحل قبل تکرار می شود و لیست پیشنهادات متناسب با آن به روز می شود.
• اگر کاربر جستجو را اجرا کند، پیشنهادات نادیده گرفته می‌شوند و جستجو با استفاده از هدف معمولی ACTION_SEARCH به فعالیت قابل جستجوی شما تحویل داده می‌شود.
• اگر کاربر پیشنهادی را انتخاب کند، یک هدف به فعالیت قابل جستجوی شما ارسال می‌شود که حاوی یک اقدام سفارشی و داده‌های سفارشی است تا برنامه شما بتواند محتوای پیشنهادی را باز کند.

پیکربندی قابل جستجو را تغییر دهید

برای افزودن پشتیبانی از پیشنهادات سفارشی، همانطور که در مثال زیر نشان داده شده است، ویژگی android:searchSuggestAuthority را به عنصر <searchable> در فایل پیکربندی قابل جستجو اضافه کنید:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

بسته به نوع هدفی که به هر پیشنهاد و نحوه قالب بندی درخواست ها برای ارائه دهنده محتوای خود می خواهید، ممکن است به ویژگی های اضافی نیاز داشته باشید. سایر ویژگی های اختیاری در بخش های زیر مورد بحث قرار می گیرند.

یک ارائه دهنده محتوا ایجاد کنید

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

هنگامی که کاربر متنی را در گفتگوی جستجو یا ویجت جستجو وارد می کند، سیستم با فراخوانی query() هر بار که یک حرف وارد می شود، از ارائه دهنده محتوای شما برای پیشنهادات درخواست می کند. در اجرای query() ارائه‌دهنده محتوای شما باید داده‌های پیشنهادی شما را جستجو کند و Cursor را برگرداند که به ردیف‌هایی اشاره می‌کند که تشخیص می‌دهد پیشنهادهای خوبی هستند.

جزئیات در مورد ایجاد یک ارائه دهنده محتوا برای پیشنهادات سفارشی در دو بخش زیر مورد بحث قرار گرفته است:

به درخواست پیشنهاد رسیدگی کنید

نحوه ارسال درخواست‌ها توسط سیستم به ارائه‌دهنده محتوای شما و نحوه رسیدگی به آنها.

یک جدول پیشنهادی بسازید

نحوه تعریف ستون هایی که سیستم انتظار دارد در Cursor با هر کوئری بازگردانده شود.

به درخواست پیشنهاد رسیدگی کنید

هنگامی که سیستم از ارائه دهنده محتوای شما پیشنهاداتی را درخواست می کند، متد query() ارائه دهنده محتوای شما را فراخوانی می کند. این روش را برای جستجوی داده‌های پیشنهادی خود اجرا کنید و یک Cursor به پیشنهادهایی که به نظر شما مرتبط می‌دانید اشاره می‌کند.

در اینجا خلاصه ای از پارامترهایی است که سیستم به متد query() شما ارسال می کند، که به ترتیب فهرست شده اند:

uri

همیشه یک محتوا Uri ، با قالب بندی زیر:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

رفتار پیش فرض این است که سیستم این URI را ارسال کند و متن پرس و جو را به آن اضافه کند:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

متن پرس و جو در انتها با استفاده از قوانین رمزگذاری URI کدگذاری می شود، بنابراین ممکن است لازم باشد قبل از انجام جستجو آن را رمزگشایی کنید.

بخش optional.suggest.path تنها در صورتی در URI گنجانده می شود که چنین مسیری را در فایل پیکربندی قابل جستجو خود با ویژگی android:searchSuggestPath تنظیم کنید. تنها زمانی لازم است که از یک ارائه دهنده محتوا برای چندین فعالیت قابل جستجو استفاده کنید. اگر اینطور است، منبع پرس و جو پیشنهاد را رفع ابهام کنید.

projection

همیشه پوچ.

selection

مقدار ارائه شده در ویژگی android:searchSuggestSelection فایل پیکربندی قابل جستجوی شما، یا اگر ویژگی android:searchSuggestSelection اعلان نکنید، عددی است که مشخص می شود. بخش بعدی بیشتر به این موضوع می پردازد.

selectionArgs

اگر مشخصه android:searchSuggestSelection در پیکربندی قابل جستجو خود اعلام کنید، عبارت جستجو را به عنوان اولین و تنها عنصر آرایه شامل می شود. اگر android:searchSuggestSelection اعلام نکنید، این پارامتر null است. بخش بعدی بیشتر به این موضوع می پردازد.

sortOrder

همیشه پوچ.

این سیستم می تواند متن درخواست جستجو را به دو صورت برای شما ارسال کند. راه پیش فرض این است که متن پرس و جو به عنوان آخرین مسیر URI محتوا در پارامتر uri قرار می گیرد. با این حال، اگر یک مقدار انتخاب را در ویژگی android:searchSuggestSelection پیکربندی قابل جستجو خود وارد کنید، متن پرس و جو در عوض به عنوان اولین عنصر آرایه رشته selectionArgs منتقل می شود. این دو گزینه در ادامه توضیح داده شده است.

درخواست را در Uri دریافت کنید

به طور پیش فرض، پرس و جو به عنوان آخرین بخش از پارامتر uri - یک شی Uri - اضافه می شود. برای بازیابی متن query در این مورد، از getLastPathSegment() استفاده کنید، همانطور که در مثال زیر نشان داده شده است:

val query: String = uri.lastPathSegment.toLowerCase()

String query = uri.getLastPathSegment().toLowerCase();

این آخرین بخش از Uri را برمی گرداند، که متن درخواستی است که کاربر وارد می کند.

پرس و جو را در آرگومان های انتخاب دریافت کنید

به جای استفاده از URI، ممکن است منطقی‌تر باشد که متد query() شما همه چیزهایی را که برای انجام جستجوی نیاز دارد دریافت کند، و ممکن است بخواهید پارامترهای selection و selectionArgs مقادیر مناسب را داشته باشند. در این مورد، ویژگی android:searchSuggestSelection را با رشته انتخابی SQLite به پیکربندی قابل جستجو خود اضافه کنید. در رشته انتخاب، یک علامت سوال ( ? ) را به عنوان یک مکان برای عبارت جستجوی واقعی قرار دهید. سیستم query() با رشته انتخاب به عنوان پارامتر selection و پرس و جو جستجو به عنوان اولین عنصر در آرایه selectionArgs فراخوانی می کند.

به عنوان مثال، در اینجا نحوه ایجاد ویژگی android:searchSuggestSelection برای ایجاد یک عبارت جستجوی متن کامل آمده است:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

با این پیکربندی، متد query() شما پارامتر selection را به صورت "word MATCH ?" و پارامتر selectionArgs به عنوان عبارت جستجو. هنگامی که اینها را به یک متد query() SQLite می‌دهید، به عنوان آرگومانهای مربوطه، با هم ترکیب می‌شوند - به این معنی که علامت سوال با متن query جایگزین می‌شود. اگر درخواست‌های پیشنهادی را از این طریق دریافت می‌کنید و نیاز به اضافه کردن حروف عام به متن پرس و جو دارید، آنها را به پارامتر selectionArgs اضافه یا پیشوند کنید، زیرا این مقدار در گیومه پیچیده شده و به جای علامت سؤال درج می‌شود.

یکی دیگر از ویژگی‌های مثال قبل android:searchSuggestIntentAction است که هنگام انتخاب پیشنهادی توسط کاربر، اقدام قصد ارسال با هر intent را مشخص می‌کند. این موضوع در بخش اعلام قصد برای پیشنهادات بیشتر مورد بحث قرار گرفته است.

یک جدول پیشنهادی بسازید

وقتی پیشنهادات را با Cursor به سیستم برمی‌گردانید، سیستم انتظار ستون‌های خاصی را در هر ردیف دارد. صرف نظر از اینکه داده های پیشنهادی خود را در یک پایگاه داده SQLite در دستگاه ذخیره می کنید، یک پایگاه داده در یک وب سرور یا قالب دیگری در دستگاه یا وب، پیشنهادات را به صورت ردیف هایی در یک جدول قالب بندی کرده و آنها را با Cursor ارائه دهید.

سیستم چندین ستون را درک می کند، اما تنها دو مورد از آنها مورد نیاز است:

_ID

شناسه ردیف عدد صحیح منحصر به فرد برای هر پیشنهاد. سیستم برای ارائه پیشنهادات در ListView به این نیاز دارد.

SUGGEST_COLUMN_TEXT_1

رشته ای که به عنوان پیشنهاد ارائه می شود.

ستون های زیر همگی اختیاری هستند. بیشتر در بخش های بعدی بیشتر مورد بحث قرار می گیرد.

SUGGEST_COLUMN_TEXT_2

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

SUGGEST_COLUMN_ICON_1

یک رشته URI منبع، محتوا یا فایل قابل ترسیم. اگر Cursor شما شامل این ستون است، همه پیشنهادات در قالب نماد به اضافه متن با نماد قابل ترسیم در سمت چپ ارائه می‌شوند. این می تواند تهی یا صفر باشد تا نشان دهد هیچ نمادی در این ردیف وجود ندارد.

SUGGEST_COLUMN_ICON_2

یک رشته URI منبع، محتوا یا فایل قابل ترسیم. اگر Cursor شما شامل این ستون است، همه پیشنهادات در قالب نماد به اضافه متن با نماد در سمت راست ارائه می‌شوند. این می تواند تهی یا صفر باشد تا نشان دهد هیچ نمادی در این ردیف وجود ندارد.

SUGGEST_COLUMN_INTENT_ACTION

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

SUGGEST_COLUMN_INTENT_DATA

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

SUGGEST_COLUMN_INTENT_DATA_ID

یک رشته مسیر URI. اگر این ستون وجود داشته باشد و حاوی یک مقدار در ردیف داده شده باشد، "/" و این مقدار به فیلد داده در intent اضافه می شود. فقط در صورتی از این استفاده کنید که فیلد داده مشخص شده توسط ویژگی android:searchSuggestIntentData در پیکربندی قابل جستجو از قبل روی یک رشته پایه مناسب تنظیم شده باشد.

SUGGEST_COLUMN_INTENT_EXTRA_DATA

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

SUGGEST_COLUMN_QUERY

اگر این ستون وجود داشته باشد و این عنصر در ردیف داده شده وجود داشته باشد، این داده‌ای است که هنگام تشکیل پرس و جو پیشنهاد استفاده می‌شود و به عنوان یک اضافی در کلید QUERY intent گنجانده می‌شود. اگر اقدام پیشنهاد ACTION_SEARCH باشد، لازم است، اما در غیر این صورت اختیاری است.

SUGGEST_COLUMN_SHORTCUT_ID

فقط هنگام ارائه پیشنهادات برای جعبه جستجوی سریع استفاده می شود. این ستون نشان می دهد که آیا یک پیشنهاد جستجو باید به عنوان یک میانبر ذخیره شود و آیا باید تأیید شود یا خیر. میانبرها معمولاً زمانی ایجاد می شوند که کاربر روی پیشنهادی از جعبه جستجوی سریع ضربه می زند. در صورت عدم وجود، نتیجه به عنوان میانبر ذخیره می شود و هرگز بازخوانی نمی شود. اگر روی SUGGEST_NEVER_MAKE_SHORTCUT تنظیم شود، نتیجه به عنوان میانبر ذخیره نمی شود. در غیر این صورت، شناسه میانبر برای بررسی مجدد پیشنهاد به‌روز با استفاده از SUGGEST_URI_PATH_SHORTCUT استفاده می‌شود.

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

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

بیشتر این ستون ها در بخش های بعدی بیشتر مورد بحث قرار می گیرند.

قصد خود را برای پیشنهادات اعلام کنید

هنگامی که کاربر پیشنهادی را از لیستی که در زیر گفتگو یا ویجت جستجو ظاهر می شود انتخاب می کند، سیستم یک Intent سفارشی را به فعالیت قابل جستجوی شما ارسال می کند. شما باید اقدام و داده را برای intent تعریف کنید.

عمل قصد را اعلام کنید

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

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

• همانطور که در مثال زیر نشان داده شده است، از ویژگی android:searchSuggestIntentAction فایل پیکربندی قابل جستجو خود برای تعریف عملکرد برای همه پیشنهادات استفاده کنید:

  <?xml version="1.0" encoding="utf-8"?>
  <searchable xmlns:android="http://schemas.android.com/apk/res/android"
      android:label="@string/app_label"
      android:hint="@string/search_hint"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW" >
  </searchable>
  

• از ستون SUGGEST_COLUMN_INTENT_ACTION برای تعریف کنش برای پیشنهادهای فردی استفاده کنید. برای انجام این کار، ستون SUGGEST_COLUMN_INTENT_ACTION را به جدول پیشنهادات خود اضافه کنید و برای هر پیشنهاد، عملکرد مورد استفاده را در آن قرار دهید - مانند "android.intent.action.VIEW" .

شما همچنین می توانید این دو تکنیک را با هم ترکیب کنید. به عنوان مثال، می‌توانید ویژگی android:searchSuggestIntentAction با یک عملکرد به‌صورت پیش‌فرض برای استفاده با همه پیشنهادها اضافه کنید، سپس با اعلام یک عملکرد متفاوت در ستون SUGGEST_COLUMN_INTENT_ACTION ، این عملکرد را برای برخی از پیشنهادات لغو کنید. اگر مقداری را در ستون SUGGEST_COLUMN_INTENT_ACTION وارد نکنید، از هدف ارائه شده در ویژگی android:searchSuggestIntentAction استفاده می‌شود.

داده های قصد را اعلام کنید

هنگامی که کاربر پیشنهادی را انتخاب می‌کند، فعالیت قابل جستجوی شما با عملکردی که تعریف کرده‌اید، هدف را دریافت می‌کند - همانطور که در بخش قبل بحث شد - اما این هدف همچنین باید داده‌هایی را برای فعالیت شما داشته باشد تا مشخص کند کدام پیشنهاد انتخاب شده است. به طور خاص، داده ها باید برای هر پیشنهاد منحصر به فرد باشند، مانند شناسه ردیف برای پیشنهاد در جدول SQLite شما. هنگامی که intent دریافت شد، می توانید داده های پیوست شده را با getData() یا getDataString() بازیابی کنید.

شما می توانید داده های موجود با هدف را به دو روش تعریف کنید:

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

  با گنجاندن ستون SUGGEST_COLUMN_INTENT_DATA و سپس پر کردن آن با داده های منحصر به فرد برای هر ردیف، تمام اطلاعات داده های لازم را برای هر هدف در جدول پیشنهادات ارائه دهید. داده های این ستون دقیقاً همانطور که در این ستون تعریف کرده اید به intent پیوست می شود. سپس می توانید آن را با getData() یا getDataString() بازیابی کنید.

• یک URI داده را به دو قسمت تقسیم کنید: بخش مشترک برای همه پیشنهادات و بخشی منحصر به فرد برای هر پیشنهاد. این قسمت ها را به ترتیب در android:searchSuggestintentData پیکربندی قابل جستجو و ستون SUGGEST_COLUMN_INTENT_DATA_ID جدول پیشنهادات خود قرار دهید.

  مثال زیر نشان می دهد که چگونه می توان قطعه URI را که در همه پیشنهادات موجود در ویژگی android:searchSuggestIntentData پیکربندی قابل جستجو شما مشترک است، اعلام کرد:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:searchSuggestIntentData="content://com.example/datatable" >
    </searchable>
    

  مسیر نهایی هر پیشنهاد - بخش منحصر به فرد - را در ستون SUGGEST_COLUMN_INTENT_DATA_ID جدول پیشنهادات خود وارد کنید. هنگامی که کاربر پیشنهادی را انتخاب می کند، سیستم رشته را از android:searchSuggestIntentData می گیرد، یک اسلش ( / ) اضافه می کند و سپس مقدار مربوطه را از ستون SUGGEST_COLUMN_INTENT_DATA_ID اضافه می کند تا یک URI محتوای کامل را تشکیل دهد. سپس می توانید Uri را با getData() بازیابی کنید.

داده های بیشتری اضافه کنید

اگر می‌خواهید اطلاعات بیشتری را با هدف خود بیان کنید، می‌توانید ستون جدول دیگری مانند SUGGEST_COLUMN_INTENT_EXTRA_DATA اضافه کنید که می‌تواند اطلاعات بیشتری درباره پیشنهاد ذخیره کند. داده های ذخیره شده در این ستون در EXTRA_DATA_KEY بسته اضافی intent قرار می گیرد.

به نیت رسیدگی کنید

پس از ارائه پیشنهادهای جستجوی سفارشی با اهداف سفارشی، به فعالیت قابل جستجوی خود نیاز دارید تا زمانی که کاربر پیشنهادی را انتخاب می کند، این اهداف را مدیریت کنید. این علاوه بر مدیریت هدف ACTION_SEARCH است، که فعالیت قابل جستجوی شما از قبل انجام می‌دهد. در اینجا مثالی از نحوه مدیریت intent ها در حین پاسخ به تماس onCreate() در فعالیت خود آورده شده است:

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

در این مثال، کنش intent ACTION_VIEW است و داده ها یک URI کامل دارند که به آیتم پیشنهادی اشاره می کند، همانطور که توسط android:searchSuggestIntentData و ستون SUGGEST_COLUMN_INTENT_DATA_ID ترکیب شده است. سپس URI به متد محلی showResult() می‌رود که از ارائه‌دهنده محتوا برای آیتم مشخص‌شده توسط URI درخواست می‌کند.

متن پرس و جو را بازنویسی کنید

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

می توانید متن پرس و جو را به روش های زیر بازنویسی کنید:

• ویژگی android:searchMode را با مقدار "queryRewriteFromText" به پیکربندی قابل جستجو خود اضافه کنید. در این مورد، محتوای ستون SUGGEST_COLUMN_TEXT_1 پیشنهاد برای بازنویسی متن درخواست استفاده می‌شود.
• ویژگی android:searchMode را با مقدار "queryRewriteFromData" به پیکربندی قابل جستجو خود اضافه کنید. در این مورد، محتوای ستون SUGGEST_COLUMN_INTENT_DATA پیشنهاد برای بازنویسی متن درخواست استفاده می‌شود. این را فقط با URI یا سایر قالب‌های داده‌ای که برای کاربر قابل مشاهده هستند، مانند URL‌های HTTP استفاده کنید. از طرح های URI داخلی برای بازنویسی پرس و جو به این روش استفاده نکنید.
• یک رشته متن درخواستی منحصر به فرد در ستون SUGGEST_COLUMN_QUERY جدول پیشنهادات خود ارائه دهید. اگر این ستون وجود داشته باشد و حاوی مقداری برای پیشنهاد فعلی باشد، برای بازنویسی متن پرس و جو و لغو هر یک از پیاده سازی های قبلی استفاده می شود.

پیشنهادات جستجو را در جعبه جستجوی سریع قرار دهید

هنگامی که برنامه خود را برای ارائه پیشنهادهای جستجوی سفارشی پیکربندی می‌کنید، در دسترس قرار دادن آنها در جعبه جستجوی سریع قابل دسترسی جهانی به آسانی تغییر پیکربندی قابل جستجو برای گنجاندن android:includeInGlobalSearch با مقدار "true" .

تنها سناریویی که در آن کار اضافی لازم است، زمانی است که ارائه‌دهنده محتوای شما اجازه خواندن درخواست می‌کند. در آن صورت، باید یک عنصر <path-permission> را برای ارائه دهنده اضافه کنید تا به ارائه دهنده محتوای شما دسترسی خواندن Quick Search Box را بدهد، همانطور که در مثال زیر نشان داده شده است:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

در این مثال، ارائه دهنده دسترسی خواندن و نوشتن به محتوا را محدود می کند. عنصر <path-permission> با اعطای دسترسی خواندن به محتوای داخل پیشوند مسیر "/search_suggest_query" هنگامی که مجوز "android.permission.GLOBAL_SEARCH" وجود دارد، محدودیت را اصلاح می کند. این امکان دسترسی به جعبه جستجوی سریع را فراهم می کند تا بتواند از ارائه دهنده محتوای شما برای پیشنهادات درخواست کند.

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

فعال کردن پیشنهادات در یک دستگاه

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

هر برنامه ای که در جعبه جستجوی سریع موجود است، یک ورودی در صفحه تنظیمات موارد قابل جستجو دارد. ورودی شامل نام برنامه و شرح کوتاهی از محتوای قابل جستجو از برنامه است و برای پیشنهادات در جعبه جستجوی سریع در دسترس است. برای تعریف متن توضیحات برای برنامه قابل جستجو خود، همانطور که در مثال زیر نشان داده شده است، ویژگی android:searchSettingsDescription به پیکربندی قابل جستجو خود اضافه کنید:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

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

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

میانبرهای پیشنهاد جعبه جستجوی سریع را مدیریت کنید

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

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

• جعبه جستجوی سریع را برای نسخه جدیدی از میانبر پیشنهاد، دوباره از ارائه دهنده محتوای خود درخواست کنید.

  مقداری را در ستون SUGGEST_COLUMN_SHORTCUT_ID ارائه کنید تا هر بار که میانبر نمایش داده می‌شود، پیشنهاد دوباره برای نسخه جدید درخواست شود. میانبر به سرعت با داده‌هایی که اخیراً در دسترس است نمایش داده می‌شود تا زمانی که درخواست تازه‌سازی بازگردد، در این مرحله پیشنهاد با اطلاعات جدید تازه‌سازی می‌شود. درخواست تازه‌سازی با یک مسیر URI SUGGEST_URI_PATH_SHORTCUT - به‌جای SUGGEST_URI_PATH_QUERY به ارائه‌دهنده محتوای شما ارسال می‌شود.

  Cursor که برمی‌گردانید حاوی یک پیشنهاد با استفاده از همان ستون‌های پیشنهاد اصلی باشد یا خالی باشد، که نشان می‌دهد میانبر دیگر معتبر نیست—در این صورت، پیشنهاد ناپدید می‌شود و میانبر حذف می‌شود.

  اگر پیشنهادی به داده‌هایی اشاره دارد که ممکن است بازخوانی آنها بیشتر طول بکشد، مانند بازخوانی مبتنی بر شبکه، همچنین می‌توانید ستون SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING را با مقدار true به جدول پیشنهادات خود اضافه کنید تا یک چرخش پیشرفت برای نماد سمت راست نشان داده شود تا زمانی که رفرش کامل شد هر مقداری غیر از true، چرخش پیشرفت را نشان نمی دهد.

• اصلاً از کپی شدن پیشنهاد در میانبر جلوگیری کنید.

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

• اجازه دهید رفتار میانبر پیش فرض اعمال شود.

  برای هر پیشنهادی که تغییر نمی کند و می تواند به عنوان میانبر ذخیره شود، SUGGEST_COLUMN_SHORTCUT_ID را خالی بگذارید.

اگر هیچ یک از پیشنهادات شما تغییر نکرد، به ستون SUGGEST_COLUMN_SHORTCUT_ID نیازی ندارید.

درباره رتبه بندی پیشنهاد جعبه جستجوی سریع

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