Tworzenie interfejsu wyszukiwania

Gdy uznasz, że chcesz dodać do swojej aplikacji funkcję wyszukiwania, Android pomoże Ci zaimplementować interfejs z oknem wyszukiwania wyświetlanym u góry okna aktywności lub z widżetem wyszukiwania, który możesz wstawić do układu strony. Zarówno okno wyszukiwania, jak i widżet mogą kierować zapytanie użytkownika do określonej aktywności w aplikacji. W ten sposób użytkownik może rozpocząć wyszukiwanie z dowolnego miejsca, w którym dostępne jest okno wyszukiwania lub widżet, a system uruchamia odpowiednie działanie w celu przeprowadzenia wyszukiwania i prezentowania wyników.

Inne funkcje dostępne dla okna wyszukiwania i widżetu to:

  • Wyszukiwanie głosowe
  • Sugestie wyszukiwania na podstawie ostatnich zapytań
  • Sugestie wyszukiwania pasujące do rzeczywistych wyników w danych aplikacji

W tym dokumencie opisujemy, jak skonfigurować aplikację tak, aby interfejs wyszukiwania, który za pomocą okna wyszukiwania lub widżetu wyszukiwania był obsługiwany przez system Android, był wspierany przez system Android.

Przydatne materiały

Podstawy

Zanim zaczniesz, zdecyduj, czy chcesz zaimplementować interfejs wyszukiwania, używając okna wyszukiwania czy widżetu wyszukiwania. Udostępniają te same funkcje wyszukiwania, ale nieco inne:

  • Okno wyszukiwania to komponent UI sterowany przez system Android. Jeśli użytkownik aktywuje tę opcję, u góry aktywności pojawi się okno wyszukiwania.

    System Android kontroluje wszystkie zdarzenia w oknie wyszukiwania. Gdy użytkownik przesyła zapytanie, system dostarcza je do działania, które określisz na potrzeby wyszukiwania. Okno może też zawierać sugestie wyszukiwania, gdy użytkownik wpisuje tekst.

  • Widżet wyszukiwania to wystąpienie elementu SearchView, który możesz umieścić w dowolnym miejscu układu. Domyślnie widżet wyszukiwania działa jak standardowy widżet EditText i nie wykonuje żadnego działania, ale możesz go skonfigurować tak, aby system Android obsługiwał wszystkie zdarzenia wejściowe, wysyłał zapytania do odpowiednich działań oraz udostępniał sugestie wyszukiwania – tak jak okno wyszukiwania.

Gdy użytkownik przeprowadza wyszukiwanie w oknie wyszukiwania lub w widżecie wyszukiwania, system tworzy element Intent i zapisuje w nim zapytanie użytkownika. Następnie system uruchamia działanie, które deklarujesz jako obsługę wyszukiwań, czyli „aktywność dostępną dla wyszukiwarki”, i realizuje intencję. Aby skonfigurować aplikację pod kątem tego rodzaju wspomaganego wyszukiwania, potrzebujesz:

  • Konfiguracja wyszukiwania
    Plik XML służący do konfigurowania niektórych ustawień okna wyszukiwania lub widżetu. Obejmuje ona ustawienia takich funkcji jak wyszukiwanie głosowe, sugestie wyszukiwania i tekst podpowiedzi w polu wyszukiwania.
  • aktywność, którą można wyszukać;
    Activity, który odbiera zapytanie, przeszukuje Twoje dane i wyświetla wyniki wyszukiwania.
  • Interfejs wyszukiwania udostępniany przez jeden z tych elementów:
    • Okno wyszukiwania
      Okno wyszukiwania jest domyślnie ukryte. Pojawia się u góry ekranu, gdy wywołujesz onSearchRequested(), gdy użytkownik kliknie przycisk Szukaj.
    • Widżet SearchView
      Używając widżetu wyszukiwania, możesz umieścić pole wyszukiwania w dowolnym miejscu w aktywności, np. w widoku działań na pasku aplikacji.

W dalszej części tego dokumentu dowiesz się, jak utworzyć konfigurację wyszukiwania i aktywność związaną z możliwością wyszukiwania oraz jak wdrożyć interfejs wyszukiwania za pomocą okna wyszukiwania lub widżetu wyszukiwania.

Utwórz konfigurację, którą można przeszukiwać

Pierwszą rzeczą, której potrzebujesz, jest plik XML o nazwie konfiguracja wyszukiwania. Konfiguruje on niektóre aspekty interfejsu okna wyszukiwania lub widżetu oraz określa sposób działania takich funkcji jak sugestie i wyszukiwanie głosowe. Tradycyjnie ten plik ma nazwę searchable.xml i trzeba go zapisać w katalogu projektu res/xml/.

Plik konfiguracji wyszukiwania musi zawierać element <searchable> jako węzeł główny oraz określać co najmniej 1 atrybut, jak w tym przykładzie:

<?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" >
</searchable>

Atrybut android:label jest jedynym wymaganym atrybutem. Wskazuje zasób tekstowy, którym musi być nazwa aplikacji. Ta etykieta nie będzie widoczna dla użytkownika, dopóki nie włączysz sugestii wyszukiwania dla Okna szybkiego wyszukiwania. Będzie ona widoczna na liście elementów dostępnych do przeszukiwania w ustawieniach systemowych.

Chociaż nie jest to wymagane, zalecamy, aby zawsze stosować atrybut android:hint, który zawiera ciąg podpowiedzi w polu wyszukiwania, zanim użytkownicy wprowadzą zapytanie. Wskazówka jest ważna, ponieważ informuje użytkowników, co mogą wyszukać.

Element <searchable> akceptuje kilka innych atrybutów. Jednak większość atrybutów nie jest potrzebna, dopóki nie dodasz funkcji takich jak sugestie wyszukiwania i wyszukiwanie głosowe. Szczegółowe informacje o pliku konfiguracji wyszukiwania znajdziesz w dokumencie referencyjnym konfiguracji wyszukiwania.

Utwórz aktywność, którą można przeszukiwać

Aktywność dostępna do przeszukiwania to funkcja Activity w aplikacji, która wykonuje wyszukiwania na podstawie ciągu zapytania i wyświetla wyniki.

Gdy użytkownik przeprowadza wyszukiwanie w oknie wyszukiwania lub w widżecie wyszukiwania, system rozpoczyna działanie umożliwiające wyszukiwanie i dostarcza je w funkcji Intent z działaniem ACTION_SEARCH. Aktywność związana z wyszukiwaniem pobiera zapytanie z dodatkowego komponentu QUERY intencji, a potem przeszukuje Twoje dane i prezentuje wyniki.

Okno wyszukiwania lub widżet możesz dołączyć do dowolnego innego działania w aplikacji, dlatego system musi wiedzieć, która aktywność jest aktywnością do przeszukiwania, aby prawidłowo podać zapytanie. Najpierw zadeklaruj aktywność możliwą do wyszukania w pliku manifestu Androida.

Deklarowanie aktywności dostępnej dla wyszukiwarki

Jeśli jeszcze go nie masz, utwórz Activity, który będzie przeprowadzać wyszukiwanie i prezentować wyniki. Nie musisz jeszcze wdrażać funkcji wyszukiwania – wystarczy utworzyć działanie, które można zadeklarować w pliku manifestu. W elemencie <activity> pliku manifestu wykonaj te czynności:

  1. Zadeklaruj aktywność, aby zaakceptować intencję ACTION_SEARCH w elemencie <intent-filter>.
  2. Określ konfigurację wyszukiwania, której chcesz użyć w elemencie <meta-data>.

Widać to w tym przykładzie:

<application ... >
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>
    ...
</application>

Element <meta-data> musi zawierać atrybut android:name o wartości "android.app.searchable" oraz atrybut android:resource z odniesieniem do możliwego do wyszukiwania pliku konfiguracji. W poprzednim przykładzie odnosi się ona do pliku res/xml/searchable.xml.

Przeprowadź wyszukiwanie

Gdy zadeklarujesz w manifeście aktywność, którą chcesz wyszukać, wykonaj tę procedurę, aby przeprowadzić wyszukiwanie w aktywności możliwej do wyszukania:

  1. Odbiór zapytania.
  2. Wyszukiwanie danych.
  3. Zaprezentuj wyniki.

Odbieranie zapytania

Gdy użytkownik przeprowadza wyszukiwanie w oknie wyszukiwania lub w widżecie wyszukiwania, system uruchamia działanie umożliwiające wyszukiwanie i wysyła intencję ACTION_SEARCH. Ta intencja umieszcza wyszukiwane hasło w dodatkowym ciągu znaków QUERY. Poszukaj tej intencji po rozpoczęciu działania i wyodrębnij ciąg znaków. Na przykład w ten sposób możesz uzyskać zapytanie, gdy rozpocznie się działanie dostępne dla wyszukiwarki:

Kotlin

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

    // Verify the action and get the query.
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

Java

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

    // Get the intent, verify the action, and get the query.
    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

Ciąg QUERY jest zawsze dołączany do intencji ACTION_SEARCH. W poprzednim przykładzie zapytanie jest pobierane i przekazywane do lokalnej metody doMySearch(), gdzie następuje rzeczywista operacja wyszukiwania.

Wyszukiwanie danych

Proces przechowywania i wyszukiwania danych różni się w zależności od konkretnej aplikacji. Dane możesz przechowywać i przeszukiwać na wiele sposobów, a w tym dokumencie nie pokazaliśmy, jak to zrobić. Zastanów się, jak przechowujesz i przeszukujesz dane pod kątem swoich potrzeb i formatu danych. Oto kilka wskazówek, które możesz zastosować:

  • Jeśli dane są przechowywane w bazie danych SQLite na urządzeniu, wyszukiwanie pełnotekstowe – za pomocą FTS3 zamiast zapytania LIKE – może zapewnić dokładniejsze wyszukiwanie danych tekstowych i znacznie szybciej generować wyniki. Na stronie sqlite.org znajdziesz informacje o FTS3 i klasie SQLiteDatabase, gdzie znajdziesz informacje na temat SQLite na Androida.
  • Jeśli Twoje dane są przechowywane online, wydajność wyszukiwania może być utrudniona przez połączenie transmisji danych użytkownika. Do czasu przywrócenia wyszukiwania może być wyświetlany wskaźnik postępu. Na stronie android.net znajdziesz informacje o interfejsach API sieci, a na ProgressBar – o tym, jak wyświetlać wskaźnik postępu.

Zaprezentuj wyniki

Niezależnie od tego, gdzie znajdują się dane i jak je wyszukujesz, zalecamy zwracanie wyników wyszukiwania do aktywności, którą można wyszukać za pomocą funkcji Adapter. Dzięki temu wszystkie wyniki wyszukiwania możesz wyświetlić w polu RecyclerView. Jeśli dane pochodzą z zapytania do bazy danych SQLite, możesz zastosować wyniki do RecyclerView za pomocą CursorAdapter. Jeśli dane są dostępne w innym formacie, możesz utworzyć rozszerzenie BaseAdapter.

Adapter wiąże każdy element ze zbioru danych w obiekcie View. Po zastosowaniu elementu Adapter do listy RecyclerView każdy fragment danych jest wstawiany na listę jako pojedynczy widok. Adapter to tylko interfejs, więc potrzebne są wdrożenia takie jak CursorAdapter, które pozwalają powiązać dane z Cursor. Jeśli żadna z dotychczasowych implementacji nie działa w przypadku Twoich danych, możesz wdrożyć własną z poziomu BaseAdapter.

Korzystanie z okna wyszukiwania

U góry ekranu okno wyszukiwania zawiera pływające pole wyszukiwania, a po lewej stronie znajduje się ikona aplikacji. Okno wyszukiwania może wyświetlać sugestie wyszukiwania podczas wpisywania. Gdy użytkownik przeprowadza wyszukiwanie, system wysyła zapytanie do działania, które można wyszukać.

Okno wyszukiwania jest domyślnie ukryte, dopóki użytkownik go nie aktywuje. Aplikacja może aktywować okno wyszukiwania, wywołując metodę onSearchRequested(). Jednak ta metoda nie będzie działać, dopóki dla aktywności nie włączysz okna wyszukiwania.

Aby umożliwić przeprowadzanie wyszukiwań w oknie wyszukiwania, wskaż systemowi, która aktywność związana z wyszukiwaniem musi otrzymywać zapytania z okna wyszukiwania. Na przykład w poprzedniej sekcji o tworzeniu aktywności z możliwością wyszukiwania tworzona jest aktywność, którą można przeszukiwać o nazwie SearchableActivity. Jeśli chcesz utworzyć osobną aktywność, np. OtherActivity, aby wyświetlić okno wyszukiwania i przekazać wyszukiwania do usługi SearchableActivity, zadeklaruj w pliku manifestu, że SearchableActivity jest aktywnością, której można użyć do przeszukiwania w oknie wyszukiwania w OtherActivity.

Aby zadeklarować aktywność do przeszukiwania w oknie wyszukiwania aktywności, dodaj element <meta-data> w elemencie <activity> odpowiedniej aktywności. Element <meta-data> musi zawierać atrybut android:value, który określa nazwę klasy działania możliwego do wyszukiwania, oraz atrybut android:name o wartości "android.app.default_searchable".

Oto przykładowa deklaracja aktywności dostępnej do przeszukiwania (SearchableActivity), jak i innej aktywności (OtherActivity), która używa funkcji SearchableActivity do przeprowadzania wyszukiwań wykonywanych w oknie wyszukiwania:

<application ... >
    <!-- This is the searchable activity; it performs searches. -->
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>

    <!-- This activity enables the search dialog to initiate searches
         in the SearchableActivity. -->
    <activity android:name=".OtherActivity" ... >
        <!-- Enable the search dialog to send searches to SearchableActivity. -->
        <meta-data android:name="android.app.default_searchable"
                   android:value=".SearchableActivity" />
    </activity>
    ...
</application>

Ponieważ OtherActivity zawiera teraz element <meta-data> służący do deklarowania, której aktywności związanej z wyszukiwaniem ma być używana do wyszukiwania, działanie to włącza okno wyszukiwania. Chociaż użytkownik bierze udział w tej aktywności, metoda onSearchRequested() aktywuje okno wyszukiwania. Gdy użytkownik przeprowadza wyszukiwanie, system uruchamia SearchableActivity i dostarcza go intencją ACTION_SEARCH.

Jeśli chcesz, aby każda aktywność w aplikacji wyświetlała okno wyszukiwania, wstaw poprzedni element <meta-data> jako element podrzędny elementu <application> zamiast każdego elementu <activity>. W ten sposób każda aktywność dziedziczy wartość, udostępnia okno wyszukiwania i udostępnia wyszukiwania w ramach tej samej aktywności, którą można przeszukiwać. Jeśli masz wiele aktywności, które można przeszukiwać, możesz zastąpić domyślną, którą można przeszukiwać, umieszczając w poszczególnych aktywnościach inną deklarację <meta-data>.

Gdy okno wyszukiwania jest włączone dla aktywności, aplikacja jest gotowa do wyszukiwania.

Wywołaj okno wyszukiwania

Chociaż niektóre urządzenia mają specjalny przycisk wyszukiwania, jego działanie może się różnić w zależności od urządzenia, a wiele z nich w ogóle nie ma przycisku wyszukiwania. Jeśli używasz okna wyszukiwania, musisz umieścić w interfejsie przycisk wyszukiwania, który aktywuje okno wyszukiwania przez wywołanie onSearchRequested().

Na przykład dodaj w menu opcji lub w układzie interfejsu przycisk wyszukiwania wywołujący onSearchRequested().

Możesz też włączyć funkcję „Wpisz, aby wyszukać”, która aktywuje okno wyszukiwania, gdy użytkownik zacznie pisać na klawiaturze. Kombinacje klawiszy pojawią się w oknie wyszukiwania. Możesz włączyć w swojej aktywności funkcję wpisania, aby wyszukać, wywołując metodę setDefaultKeyMode lub DEFAULT_KEYS_SEARCH_LOCAL podczas korzystania z metody onCreate().

Wpływ okna wyszukiwania na cykl aktywności

Okno wyszukiwania to Dialog unoszący się u góry ekranu. Nie powoduje to żadnych zmian w stosie aktywności, więc po wyświetleniu okna wyszukiwania nie są wywoływane żadne metody cyklu życia, np. onPause(). Aktywność nie będzie już zaznaczona, ponieważ zaznaczone będzie okno wyszukiwania.

Jeśli chcesz otrzymać powiadomienie po aktywowaniu okna wyszukiwania, zastąp metodę onSearchRequested(). Gdy system wywoła tę metodę, oznacza to, że aktywność nie jest już zaznaczona w oknie wyszukiwania. Dzięki temu możesz wykonać dowolną czynność odpowiednią dla zdarzenia, np. wstrzymać grę. Jeśli nie przesyłasz danych kontekstowych wyszukiwania – omówione w innej sekcji tego dokumentu – zakończ tę metodę, wywołując implementację klasy nadrzędnej:

Kotlin

override fun onSearchRequested(): Boolean {
    pauseSomeStuff()
    return super.onSearchRequested()
}

Java

@Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}

Jeśli użytkownik anuluje wyszukiwanie, klikając przycisk Wstecz, okno wyszukiwania zostanie zamknięte, a aktywność odzyska zaznaczenie. Możesz zarejestrować się, aby otrzymywać powiadomienia, gdy okno wyszukiwania zostanie zamknięte za pomocą setOnDismissListener(), setOnCancelListener() lub obu tych metod. Wystarczy, że zarejestrujesz OnDismissListener, ponieważ jest on wywoływany przy każdym zamknięciu okna wyszukiwania. Element OnCancelListener odnosi się tylko do zdarzeń, w których użytkownik jawnie opuszcza okno wyszukiwania, więc nie jest wywoływany przy wyszukiwaniu. Po przeprowadzeniu wyszukiwania okno wyszukiwania automatycznie znika.

Jeśli bieżące działanie nie jest działaniem dostępnym do przeszukiwania, normalne zdarzenia cyklu życia aktywności są wywoływane, gdy użytkownik przeprowadza wyszukiwanie – bieżąca aktywność otrzymuje onPause(). Jak to opisano we wprowadzeniu do aktywności. Jeśli jednak bieżąca aktywność jest możliwością wyszukiwania, zachodzi jedna z dwóch sytuacji:

  • Domyślnie działanie możliwe do wyszukania otrzymuje intencję ACTION_SEARCH z wywołaniem onCreate(), a nowe wystąpienie tego działania jest umieszczane na początku stosu aktywności. Teraz w stosie działań dostępne są 2 instancje aktywności, którą można przeszukiwać, więc naciśnięcie przycisku Wstecz spowoduje powrót do poprzedniego wystąpienia aktywności, którą można przeszukiwać, bez zamykania jej.
  • Jeśli ustawisz android:launchMode na "singleTop", aktywność, którą można przeszukiwać, otrzyma intencję ACTION_SEARCH z wywołaniem onNewIntent(Intent), przekazując nową intencję ACTION_SEARCH. Oto jak możesz rozwiązać ten problem, w którym tryb uruchamiania aktywności, którą można wyszukać, to "singleTop":

    Kotlin

    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.search)
    handleIntent(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    handleIntent(intent)
}

private fun handleIntent(intent: Intent) {
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

    Java

    @Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);
    handleIntent(getIntent());
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
    handleIntent(intent);
}

private void handleIntent(Intent intent) {
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

    W porównaniu z przykładowym kodem w sekcji poświęconej wykonywaniu wyszukiwania cały kod obsługujący intencję wyszukiwania znajduje się teraz w metodzie handleIntent(), dzięki czemu mogą go wykonać zarówno onCreate(), jak i onNewIntent().

    Gdy system wywołuje funkcję onNewIntent(Intent), działanie nie jest uruchamiane ponownie, więc metoda getIntent() zwraca tę samą intencję, która została otrzymywana z metodą onCreate(). Dlatego musisz wywołać metodę setIntent(Intent)inside onNewIntent(Intent): aby intencja zapisana przez aktywność została zaktualizowana na wypadek, gdyby w przyszłości wywołano metodę getIntent().

Zazwyczaj preferowany jest drugi scenariusz, w którym używany jest tryb uruchamiania "singleTop", ponieważ po zakończeniu wyszukiwania użytkownik może przeprowadzić dodatkowe wyszukiwania i nie chcesz, aby aplikacja generowała wiele wystąpień takiej aktywności. Zalecamy ustawienie działania możliwego do wyszukania w trybie uruchamiania "singleTop" w manifeście aplikacji, jak pokazano w tym przykładzie:

<activity android:name=".SearchableActivity"
          android:launchMode="singleTop" >
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    <meta-data
          android:name="android.app.searchable"
          android:resource="@xml/searchable"/>
  </activity>

Przekazywanie danych kontekstowych wyszukiwania

W niektórych przypadkach możesz wprowadzić odpowiednie doprecyzowanie zapytania w ramach działania funkcji wyszukiwania dla każdego wyszukiwania. Jeśli jednak chcesz zawęzić kryteria wyszukiwania na podstawie działań, które użytkownik wykonuje w wyszukiwarce, możesz podać dodatkowe dane w intencji, którą system wysyła do aktywności dostępnej do przeszukiwania. Dodatkowe dane możesz przekazywać w funkcji APP_DATA Bundle, która jest zawarta w intencji ACTION_SEARCH.

Aby przekazać tego rodzaju dane do aktywności związanej z wyszukiwaniem, zastąp metodę onSearchRequested() w przypadku działania, z którego użytkownik może przeprowadzić wyszukiwanie, utwórz obiekt Bundle z dodatkowymi danymi i wywołaj metodę startSearch(), aby aktywować okno wyszukiwania. Na przykład:

Kotlin

override fun onSearchRequested(): Boolean {
    val appData = Bundle().apply {
        putBoolean(JARGON, true)
    }
    startSearch(null, false, appData, false)
    return true
}

Java

@Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }

Zwracanie wartości „true” oznacza, że udało Ci się obsłużyć to zdarzenie wywołania zwrotnego i wywołać funkcję startSearch(), aby aktywować okno wyszukiwania. Gdy użytkownik prześle zapytanie, jest ono dostarczane do aktywności, którą można wyszukać, razem z dodanymi przez Ciebie danymi. Aby zawęzić wyszukiwanie, możesz wyodrębnić dodatkowe dane z APP_DATA Bundle, jak pokazano w tym przykładzie:

Kotlin

val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false

Java

Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}

Używanie widżetu wyszukiwania

Obraz przedstawiający widok wyszukiwania na górnym pasku aplikacji

Rysunek 1. SearchViewwidżet jako widok działań na pasku aplikacji.

Widżet wyszukiwania oferuje te same funkcje co okno wyszukiwania. Uruchamia odpowiednie działanie, gdy użytkownik przeprowadza wyszukiwanie, i może podać sugestie wyszukiwania oraz przeprowadzić wyszukiwanie głosowe. Jeśli nie możesz umieścić widżetu wyszukiwania na pasku aplikacji, możesz umieścić go w dowolnym miejscu w układzie aktywności.

Konfigurowanie widżetu wyszukiwania

Po utworzeniu konfiguracji wyszukiwania i aktywności związanej z wyszukiwaniem włącz wspomagane wyszukiwanie w przypadku każdego elementu SearchView, wywołując jego metodę setSearchableInfo() i przekazując mu obiekt SearchableInfo, który reprezentuje Twoją konfigurację do przeszukiwania.

Aby uzyskać odniesienie do tego zasobu (SearchableInfo), zadzwoń pod numer getSearchableInfo()SearchManager.

Jeśli na przykład używasz SearchView jako widoku działań na pasku aplikacji, włącz widżet podczas wywołania zwrotnego onCreateOptionsMenu(), jak pokazano w tym przykładzie:

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    // Inflate the options menu from XML.
    val inflater = menuInflater
    inflater.inflate(R.menu.options_menu, menu)

    // Get the SearchView and set the searchable configuration.
    val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
    (menu.findItem(R.id.menu_search).actionView as SearchView).apply {
        // Assumes current activity is the searchable activity.
        setSearchableInfo(searchManager.getSearchableInfo(componentName))
        setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default.
    }

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the options menu from XML.
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options_menu, menu);

    // Get the SearchView and set the searchable configuration.
    SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE);
    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
    // Assumes current activity is the searchable activity.
    searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName()));
    searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default.

    return true;
}

Widżet wyszukiwania jest teraz skonfigurowany i system dostarcza wyszukiwane hasła do aktywności związanej z wyszukiwaniem. Możesz też włączyć sugestie wyszukiwania dla widżetu wyszukiwania.

Więcej informacji o widokach działań na pasku aplikacji znajdziesz w artykule o korzystaniu z widoków działań i dostawców działań.

Inne funkcje widżetu wyszukiwania

Widżet SearchView udostępnia kilka dodatkowych funkcji, które mogą być przydatne:

Przycisk przesyłania
Domyślnie nie ma przycisku umożliwiającego przesłanie zapytania, więc aby rozpocząć wyszukiwanie, użytkownik musi nacisnąć klawisz Return na klawiaturze. Możesz dodać przycisk „Prześlij”, wywołując setSubmitButtonEnabled(true).
Zawężenie zapytania dotyczącego sugestii wyszukiwania
Po włączeniu sugestii wyszukiwania zwykle oczekujesz, że użytkownicy wybiorą sugestię, ale być może będą chcieli doprecyzować zapytanie. Obok każdej sugestii możesz dodać przycisk, który wstawia ją w polu wyszukiwania w celu zawężenia wyników, wywołując funkcję setQueryRefinementEnabled(true).
Możliwość przełączania widoczności pola wyszukiwania
Domyślnie widżet wyszukiwania jest oznaczony ikoną ikony, co oznacza, że reprezentuje go tylko ikona wyszukiwania – lupa. Po kliknięciu ikony przez użytkownika wyświetla się pole wyszukiwania. Jak pokazano w poprzednim przykładzie, możesz domyślnie wyświetlać pole wyszukiwania, wywołując setIconifiedByDefault(false). Możesz też przełączyć wygląd widżetu wyszukiwania, wywołując setIconified().

Klasa SearchView ma kilka innych interfejsów API, które umożliwiają dostosowywanie widżetu wyszukiwania. Większość z nich jest jednak używana tylko wtedy, gdy samodzielnie obsługujesz dane wejściowe wszystkich użytkowników, a nie przez system Android do generowania zapytań i wyświetlania sugestii wyszukiwania.

Używanie zarówno widżetu, jak i okna

Jeśli wstawisz widżet wyszukiwania na pasku aplikacji jako widok działań i włączysz jego pojawianie się na pasku aplikacji, o ile jest na nim wolne miejsce, ustaw wartość android:showAsAction="ifRoom", wówczas widżet wyszukiwania może nie wyświetlać się jako widok działań. Zamiast tego pozycja menu może się wyświetlić w rozszerzonym menu. Jeśli na przykład aplikacja działa na mniejszym ekranie, na pasku aplikacji może być za mało miejsca na wyświetlenie widżetu wyszukiwania wraz z innymi działaniami lub elementami nawigacyjnymi, dlatego ta pozycja pojawia się w rozszerzonym menu. Po umieszczeniu w rozszerzonym menu element działa jak zwykły element menu i nie wyświetla widoku czynności, czyli widżet wyszukiwania.

W tej sytuacji element menu, do którego chcesz dołączyć widżet wyszukiwania, musi aktywować okno wyszukiwania, gdy użytkownik wybierze go z rozszerzonego menu. W tym celu zaimplementuj funkcję onOptionsItemSelected(), aby obsługiwać pozycję menu „Szukaj”, i otwórz okno wyszukiwania, wywołując metodę onSearchRequested().

Więcej informacji o tym, jak działają elementy na pasku aplikacji i jak radzić sobie w takiej sytuacji, znajdziesz w artykule Dodawanie paska aplikacji.

Dodaj wyszukiwanie głosowe

Możesz dodać funkcję wyszukiwania głosowego do okna wyszukiwania lub widżetu, dodając atrybut android:voiceSearchMode do konfiguracji wyszukiwania. Spowoduje to dodanie przycisku wyszukiwania głosowego, który będzie uruchamiać potwierdzenie głosowe. Gdy użytkownik skończy mówić, transkrypcja zapytania zostanie wysłana do Twojej aktywności możliwej do wyszukiwania.

Widać to w tym przykładzie:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:voiceSearchMode="showVoiceSearchButton|launchRecognizer" >
</searchable>

Wartość showVoiceSearchButton jest wymagana do włączenia wyszukiwania głosowego. Druga wartość (launchRecognizer) określa, że przycisk wyszukiwania głosowego musi uruchamiać narzędzie do rozpoznawania treści, które zwraca transkrypcję tekstu do aktywności, którą można przeszukiwać.

Możesz podać dodatkowe atrybuty, by określić działanie wyszukiwania głosowego, takie jak oczekiwany język czy maksymalną liczbę zwracanych wyników. Więcej informacji o dostępnych atrybutach znajdziesz w dokumentacji konfiguracji wyszukiwania.

Dodaj sugestie wyszukiwania

Zarówno okno wyszukiwania, jak i widżet wyszukiwania mogą dostarczać podpowiedzi wyszukiwania podczas wpisywania zapytania przez użytkownika, korzystając z systemu Android. Gdy użytkownik wybierze sugestię, system zarządza listą sugestii i obsługuje zdarzenie.

Możesz podać 2 rodzaje sugestii wyszukiwania:

Ostatnie sugestie wyszukiwania zapytań
Te sugestie to słowa, których użytkownik wcześniej używał jako zapytania w Twojej aplikacji. Więcej informacji znajdziesz w artykule Dodawanie niestandardowych sugestii wyszukiwania.
Niestandardowe sugestie wyszukiwania
Są to sugestie wyszukiwania podane przez Ciebie z Twojego własnego źródła danych, aby pomóc użytkownikom szybko wybrać prawidłową pisownię lub wyszukiwane hasło. Więcej informacji znajdziesz w artykule Dodawanie niestandardowych sugestii wyszukiwania.