هنگام استفاده از گفتگوی جستجوی Android یا ویجت جستجو، میتوانید پیشنهادهای جستجوی سفارشی را ارائه دهید که از دادههای موجود در برنامه شما ایجاد میشوند. به عنوان مثال، اگر برنامه شما یک فرهنگ لغت است، می توانید کلماتی را از فرهنگ لغت پیشنهاد دهید که با متن وارد شده در قسمت جستجو مطابقت دارند قبل از اینکه کاربر وارد کردن درخواست خود را تمام کند. این پیشنهادات ارزشمند هستند زیرا می توانند به طور موثر خواسته های کاربر را پیش بینی کنند و دسترسی فوری به آن را فراهم کنند. شکل 1 نمونه ای از گفتگوی جستجو با پیشنهادات سفارشی را نشان می دهد.
پس از ارائه پیشنهادات سفارشی، میتوانید آنها را نیز در جعبه جستجوی سریع سیستم در دسترس قرار دهید و امکان دسترسی به محتوای خود را از خارج از برنامه خود فراهم کنید.
قبل از اینکه پیشنهادهای سفارشی اضافه کنید، گفتگوی جستجوی Android یا ویجت جستجو برای جستجوها را در برنامه خود پیاده کنید. به ایجاد رابط جستجو و ارائه دهندگان محتوا مراجعه کنید.
اصول اولیه
![](https://developer.android.com/static/images/search/search-suggest-custom.png?hl=fa)
شکل 1. تصویر صفحه گفتگوی جستجو با پیشنهادهای جستجوی سفارشی.
هنگامی که کاربر یک پیشنهاد سفارشی را انتخاب می کند، سیستم یک Intent
به فعالیت قابل جستجوی شما ارسال می کند. برخلاف یک عبارت جستجوی معمولی که یک intent را با عملکرد ACTION_SEARCH
ارسال میکند، میتوانید در عوض پیشنهادهای سفارشی خود را برای استفاده از ACTION_VIEW
- یا هر اقدام قصد دیگری - تعریف کنید و همچنین دادههایی را که به پیشنهاد انتخابشده مرتبط هستند را شامل کنید. در مثال فرهنگ لغت، زمانی که کاربر پیشنهادی را انتخاب میکند، برنامه میتواند به جای جستجو در فرهنگ لغت برای موارد منطبق، بلافاصله تعریف آن کلمه را باز کند.
برای ارائه پیشنهادات سفارشی، مراحل زیر را انجام دهید:
- همانطور که در ایجاد رابط جستجو توضیح داده شده است، یک فعالیت قابل جستجو اولیه را اجرا کنید.
- پیکربندی قابل جستجو را با اطلاعات مربوط به ارائهدهنده محتوا که پیشنهادات سفارشی ارائه میکند، تغییر دهید.
- یک جدول، مانند
SQLiteDatabase
، برای پیشنهادات خود بسازید و جدول را با ستون های مورد نیاز قالب بندی کنید. - یک ارائه دهنده محتوا ایجاد کنید که به جدول پیشنهادات شما دسترسی داشته باشد و ارائه دهنده را در مانیفست خود اعلام کنید.
- زمانی که کاربر پیشنهادی را انتخاب میکند، نوع
Intent
ارسالی را اعلام کنید، از جمله یک اقدام سفارشی و دادههای سفارشی.
همانطور که سیستم اندروید گفتگوی جستجو را نمایش می دهد، پیشنهادات جستجوی شما را نیز نمایش می دهد. شما به یک ارائه دهنده محتوا نیاز دارید که سیستم بتواند پیشنهادات شما را از آن بازیابی کند. ارائه دهندگان محتوا را بخوانید تا نحوه ایجاد یک ارائه دهنده محتوا را بیاموزید.
هنگامی که سیستم تشخیص می دهد که فعالیت شما قابل جستجو است و پیشنهادات جستجو را ارائه می دهد، زمانی که کاربر یک درخواست را وارد می کند، مراحل زیر انجام می شود:
- این سیستم متن درخواست جستجو را می گیرد - یعنی هر آنچه که تاکنون وارد شده است - و یک پرس و جو را برای ارائه دهنده محتوای شما انجام می دهد که پیشنهادات شما را مدیریت می کند.
- ارائهدهنده محتوای شما
Cursor
برمیگرداند که به همه پیشنهادهایی که با متن عبارت جستجو مرتبط هستند اشاره میکند. - سیستم لیستی از پیشنهادات ارائه شده توسط
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
ارائه کنید تا هر بار که میانبر نمایش داده میشود، پیشنهاد دوباره برای نسخه جدید درخواست شود. میانبر به سرعت با دادههایی که اخیراً در دسترس است نمایش داده میشود تا زمانی که درخواست تازهسازی بازگردد، در این مرحله پیشنهاد با اطلاعات جدید تازهسازی میشود. درخواست تازهسازی با یک مسیر URISUGGEST_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
نیازی ندارید.
درباره رتبه بندی پیشنهاد جعبه جستجوی سریع
هنگامی که پیشنهادات جستجوی برنامه خود را در جعبه جستجوی سریع در دسترس قرار دادید، رتبه بندی جعبه جستجوی سریع تعیین می کند که چگونه پیشنهادات برای یک درخواست خاص به کاربر ارائه می شود. این ممکن است بستگی به این دارد که چند برنامه دیگر برای آن جستجو نتایج داشته باشند و کاربر چقدر نتایج شما را در مقایسه با برنامه های دیگر انتخاب می کند. هیچ تضمینی در مورد اینکه پیشنهادات شما چگونه رتبه بندی می شوند یا اینکه آیا پیشنهادات برنامه شما اصلاً برای یک جستار مشخص نشان داده می شوند وجود ندارد. به طور کلی، ارائه نتایج با کیفیت، احتمال اینکه پیشنهادات برنامه شما در موقعیت برجسته ارائه شود را افزایش می دهد و برنامه هایی که پیشنهادات با کیفیت پایین ارائه می کنند، به احتمال زیاد در رتبه های پایین تر قرار می گیرند یا نمایش داده نمی شوند.