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

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

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

اصول اولیه

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

پیشنهادات پرس و جو اخیر جستجوهای ذخیره شده هستند. وقتی کاربر پیشنهادی را انتخاب می‌کند، فعالیت قابل جستجوی شما یک هدف ACTION_SEARCH با پیشنهاد به عنوان عبارت جستجویی که فعالیت قابل جستجوی شما قبلاً انجام می‌دهد، دریافت می‌کند.

برای ارائه پیشنهادات سؤالات اخیر، باید:

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

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

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

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

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

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

کلاس SearchRecentSuggestionsProvider که برای ارائه دهنده محتوای خود گسترش می دهید به طور خودکار کار را در مراحل قبل انجام می دهد، بنابراین کد کمی برای نوشتن وجود دارد.

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

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

به عنوان مثال، در اینجا پیاده سازی کاملی از یک ارائه دهنده محتوا برای پیشنهادات درخواست اخیر آمده است:

class MySuggestionProvider : SearchRecentSuggestionsProvider() {
    init {
        setupSuggestions(AUTHORITY, MODE)
    }

    companion object {
        const val AUTHORITY = "com.example.MySuggestionProvider"
        const val MODE: Int = SearchRecentSuggestionsProvider.DATABASE_MODE_QUERIES
    }
}

public class MySuggestionProvider extends SearchRecentSuggestionsProvider {
    public final static String AUTHORITY = "com.example.MySuggestionProvider";
    public final static int MODE = DATABASE_MODE_QUERIES;

    public MySuggestionProvider() {
        setupSuggestions(AUTHORITY, MODE);
    }
}

فراخوانی به setupSuggestions() نام مرجع جستجو و حالت پایگاه داده را ارسال می کند. مرجع جستجو می تواند هر رشته منحصر به فردی باشد، اما بهترین روش استفاده از یک نام کاملاً واجد شرایط برای ارائه دهنده محتوای خود است، مانند نام بسته به دنبال نام کلاس ارائه دهنده. به عنوان مثال، "com.example.MySuggestionProvider" .

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

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

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

<application>
    <provider android:name=".MySuggestionProvider"
              android:authorities="com.example.MySuggestionProvider" />
    ...
</application>

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

برای پیکربندی سیستم برای استفاده از ارائه‌دهنده پیشنهادات خود، ویژگی‌های android:searchSuggestAuthority و android:searchSuggestSelection را به عنصر <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.MySuggestionProvider"
    android:searchSuggestSelection=" ?" >
</searchable>

مقدار android:searchSuggestAuthority باید یک نام کاملاً واجد شرایط برای ارائه‌دهنده محتوای شما باشد که دقیقاً با مرجع استفاده شده در ارائه‌دهنده محتوا مطابقت داشته باشد، مانند "com.example.MySuggestionProvider" در مثال‌های قبل.

مقدار android:searchSuggestSelection باید یک علامت سوال باشد که قبل از آن یک فاصله وجود داشته باشد: " ?" . این یک مکان نگهدار برای آرگومان انتخاب SQLite است و به طور خودکار با متن درخواست وارد شده توسط کاربر جایگزین می شود.

کوئری ها را ذخیره کنید

برای پر کردن مجموعه جستجوهای اخیر خود، هر درخواست دریافت شده توسط فعالیت قابل جستجوی خود را به SearchRecentSuggestionsProvider خود اضافه کنید. برای انجام این کار، یک نمونه از SearchRecentSuggestions ایجاد کنید و هر بار که فعالیت قابل جستجوی شما درخواستی را دریافت می کند، saveRecentQuery() فراخوانی کنید. به عنوان مثال، در اینجا نحوه ذخیره پرس و جو در طول متد onCreate() در فعالیت خود آورده شده است:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            SearchRecentSuggestions(this, MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE)
                    .saveRecentQuery(query, null)
        }
    }
}

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent  = getIntent();

    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        String query = intent.getStringExtra(SearchManager.QUERY);
        SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
                MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
        suggestions.saveRecentQuery(query, null);
    }
}

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

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

داده های پیشنهاد را پاک کنید

برای محافظت از حریم خصوصی کاربر، همیشه راهی را برای کاربر فراهم کنید تا پیشنهادات درخواست اخیر را پاک کند. برای پاک کردن تاریخچه پرس و جو، clearHistory() را فراخوانی کنید. به عنوان مثال:

SearchRecentSuggestions(this, HelloSuggestionsProvider.AUTHORITY, HelloSuggestionsProvider.MODE)
        .clearHistory()

SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
        HelloSuggestionProvider.AUTHORITY, HelloSuggestionProvider.MODE);
suggestions.clearHistory();

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