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

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

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

نوار جستجو ←

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

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

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

اصول اولیه

شکل ۱. نماگرفتی از کادر گفتگوی جستجو با پیشنهادهای جستجوی سفارشی.

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

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

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

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

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

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

توجه: SUGGEST_URI_PATH_QUERY رشته تحت‌اللفظی ارائه‌شده در URI نیست؛ بلکه یک ثابت است. اگر لازم است به این مسیر ارجاع دهید، از آن استفاده کنید.

projection

همیشه تهی است.

selection

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

selectionArgs

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

sortOrder

همیشه تهی است.

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

دریافت پُرسمان در Uri

به‌طور پیش‌فرض، پُرسمان به‌عنوان آخرین بخش پارامتر uri (یک شیء Uri) اضافه می‌شود. برای بازیابی نوشتار پُرسمان در این مورد، از 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 را به‌عنوان پُرسمان جستجو ارائه می‌دهد. وقتی این‌ها را به‌عنوان آرگومان‌های مربوطه به روش SQLite query() ارسال می‌کنید، باهم ترکیب می‌شوند—یعنی علامت سؤال با نوشتار پُرسمان جایگزین می‌شود. اگر از این طریق پُرسمان‌های پیشنهادی دریافت می‌کنید و لازم است نویسه‌های عام به نوشتار پُرسمان اضافه کنید، آن‌ها را به پارامتر selectionArgs پیشوند یا پسوند کنید، زیرا این مقدار در گیومه قرار می‌گیرد و به‌جای علامت سؤال درج می‌شود.

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

نکته: اگر نمی‌خواهید عبارت انتخاب را در مشخصه android:searchSuggestSelection تعریف کنید، اما همچنان می‌خواهید نوشتار پُرسمان را در پارامتر selectionArgs دریافت کنید، مقدار غیرتهی برای مشخصه android:searchSuggestSelection ارائه دهید. این کار باعث می‌شود پُرسمان در selectionArgs ارسال شود و می‌توانید پارامتر selection را نادیده بگیرید. به‌این‌ترتیب، می‌توانید به‌جای آن، عبارت انتخاب واقعی را در سطح پایین‌تری تعریف کنید تا ارائه‌دهنده محتوای شما مجبور نباشد آن را مدیریت کند.

ساختن جدول پیشنهاد

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

توجه: اگر پیشنهادهای جستجوی شما در قالب جدول (مثلاً جدول SQLite) بااستفاده از ستون‌های موردنیاز سیستم ذخیره نشده است، می‌توانید داده‌های پیشنهادی خود را برای موارد منطبق جستجو کنید و سپس آن‌ها را در هر درخواست در جدول لازم قالب‌بندی کنید. برای انجام این کار، بااستفاده از نام‌های ستون الزامی، MatrixCursor ایجاد کنید و سپس بااستفاده از addRow(Object[])، برای هر پیشنهاد یک ردیف اضافه کنید. محصول نهایی را از روش query() ارائه‌دهنده محتوایتان برگردانید.

سیستم چندین ستون را درک می‌کند، اما فقط دو ستون از آن‌ها الزامی است:

_ID

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

SUGGEST_COLUMN_TEXT_1

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

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

SUGGEST_COLUMN_TEXT_2

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

SUGGEST_COLUMN_ICON_1

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

SUGGEST_COLUMN_ICON_2

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

SUGGEST_COLUMN_INTENT_ACTION

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

SUGGEST_COLUMN_INTENT_DATA

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

SUGGEST_COLUMN_INTENT_DATA_ID

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

SUGGEST_COLUMN_INTENT_EXTRA_DATA

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

SUGGEST_COLUMN_QUERY

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

SUGGEST_COLUMN_SHORTCUT_ID

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

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

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

درباره اکثر این ستون‌ها در بخش‌های زیر بیشتر بحث شده است.

اعلام قصد برای پیشنهادها

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

توجه: اگر مشخصه android:searchSuggestIntentAction را در پیکربندی قابل‌جستجو قرار ندهید، باید برای هر پیشنهاد، مقداری را در ستون SUGGEST_COLUMN_INTENT_ACTION قرار دهید، درغیراین‌صورت قصد ناموفق خواهد بود.

اعلام کردن داده‌های هدف

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

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

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

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

  نکته: معمولاً استفاده از شناسه ردیف جدول به‌عنوان داده قصد آسان‌تر است، زیرا همیشه یکتا است. ساده‌ترین راه برای انجام این کار استفاده از نام ستون SUGGEST_COLUMN_INTENT_DATA به‌عنوان نام مستعار برای ستون شناسه ردیف است.
• یک 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 را با getData() بازیابی کنید.

افزودن داده‌های بیشتر

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

مدیریت قصد

پس‌از ارائه پیشنهادهای جستجوی سفارشی با هدف‌های سفارشی، به فعالیت قابل‌جستجو نیاز دارید تا وقتی کاربر پیشنهادی را انتخاب می‌کند، این هدف‌ها را مدیریت کند. این کار علاوه‌بر رسیدگی به هدف ACTION_SEARCH است که فعالیت قابل‌جستجوی شما درحال‌حاضر انجام می‌دهد. در اینجا مثالی از نحوه مدیریت هدف‌ها درطول فراخوانی برگشتی 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);
}

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

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

بازنویسی نوشتار پُرسمان

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

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

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

نمایش پیشنهادهای جستجو در «چارگوش جستجوی سریع»

وقتی برنامه‌تان را برای ارائه پیشنهادهای جستجوی سفارشی پیکربندی کردید، دردسترس قرار دادن آن‌ها برای «چارگوش جستجوی سریع» که به‌طور سراسری قابل‌دسترسی است به‌آسانی اصلاح پیکربندی قابل‌جستجویتان برای گنجاندن android:includeInGlobalSearch با مقدار "true" است.

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

<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 نیاز ندارید.

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

درباره رتبه‌بندی پیشنهادهای «چارگوش جستجوی سریع»

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