Dodawanie niestandardowych sugestii wyszukiwania

Wypróbuj Compose

Jetpack Compose to zalecany zestaw narzędzi interfejsu na Androida. Dowiedz się, jak dodać funkcję wyszukiwania w Compose.

Pasek wyszukiwania →

Gdy użytkownik korzysta z okna wyszukiwania lub widżetu wyszukiwania na Androidzie, możesz wyświetlać niestandardowe sugestie wyszukiwania utworzone na podstawie danych z aplikacji. Jeśli na przykład Twoja aplikacja to słownik, możesz sugerować słowa z niego, które pasują do tekstu wpisanego w polu wyszukiwania, zanim użytkownik skończy wpisywać zapytanie. Te sugestie są przydatne, ponieważ skutecznie przewidują, czego szuka użytkownik, i zapewniają do tego natychmiastowy dostęp. Ilustracja 1 przedstawia przykład okna wyszukiwania z niestandardowymi sugestiami.

Po podaniu niestandardowych sugestii możesz też udostępnić je w Szybkim polu wyszukiwania w całym systemie, zapewniając dostęp do swoich treści spoza aplikacji.

Zanim dodasz niestandardowe sugestie, wdróż w aplikacji okno wyszukiwania na Androidzie lub widżet wyszukiwania. Więcej informacji znajdziesz w sekcjach Tworzenie interfejsu wyszukiwania i Dostawcy treści.

Podstawy

Rysunek 1. Zrzut ekranu okna wyszukiwania z niestandardowymi sugestiami wyszukiwania.

Gdy użytkownik wybierze niestandardową sugestię, system wyśle do Twojej aktywności z możliwością wyszukiwania zdarzenie Intent. W przeciwieństwie do zwykłego zapytania, które wysyła intencję z działaniemACTION_SEARCHACTION_VIEW, możesz zdefiniować własne sugestie, aby używać działaniaACTION_VIEW lub dowolnego innego działania związanego z intencją, a także uwzględniać dane istotne dla wybranej sugestii. W przykładzie ze słownikiem, gdy użytkownik wybierze sugestię, aplikacja może od razu otworzyć definicję tego słowa, zamiast wyszukiwać w słowniku pasujące hasła.

Aby podać niestandardowe sugestie:

• Zaimplementuj podstawową aktywność z możliwością wyszukiwania zgodnie z opisem w sekcji Tworzenie interfejsu wyszukiwania.
• Zmodyfikuj konfigurację wyszukiwania, dodając informacje o dostawcy treści, który udostępnia niestandardowe sugestie.
• Utwórz tabelę, np. w SQLiteDatabase, z sugestiami i sformatuj ją, dodając wymagane kolumny.
• Utwórz dostawcę treści, który ma dostęp do tabeli sugestii, i zadeklaruj go w pliku manifestu.
• Zadeklaruj typ Intent, który ma być wysyłany, gdy użytkownik wybierze sugestię, w tym działanie niestandardowe i dane niestandardowe.

Podobnie jak w przypadku okna wyszukiwania, system Android wyświetla też sugestie wyszukiwania. Musisz mieć dostawcę treści, od którego system może pobierać sugestie. Przeczytaj artykuł Dostawcy treści, aby dowiedzieć się, jak utworzyć dostawcę treści.

Gdy system stwierdzi, że Twoja aktywność jest wyszukiwalna i wyświetli sugestie wyszukiwania, po wpisaniu przez użytkownika zapytania nastąpi ta procedura:

1. System pobiera tekst zapytania, czyli wszystko, co zostało do tej pory wpisane, i wysyła zapytanie do dostawcy treści, który zarządza Twoimi sugestiami.
2. Dostawca treści zwraca Cursor, który wskazuje wszystkie sugestie powiązane z tekstem zapytania.
3. System wyświetli listę sugestii podanych przez Cursor.

Gdy wyświetlą się sugestie niestandardowe, może się zdarzyć:

• Jeśli użytkownik wpisze kolejną literę lub w jakikolwiek sposób zmieni zapytanie, poprzednie kroki zostaną powtórzone, a lista sugestii zostanie odpowiednio zaktualizowana.
• Jeśli użytkownik przeprowadzi wyszukiwanie, sugestie zostaną zignorowane, a wyszukiwanie zostanie przekazane do aktywności z możliwością wyszukiwania za pomocą zwykłego intencji ACTION_SEARCH.
• Jeśli użytkownik wybierze sugestię, do aktywności z możliwością wyszukiwania zostanie wysłany zamiar zawierający działanie niestandardowe i dane niestandardowe, aby aplikacja mogła otworzyć sugerowane treści.

Zmień konfigurację możliwości wyszukiwania

Aby dodać obsługę niestandardowych sugestii, dodaj atrybut android:searchSuggestAuthority do elementu <searchable> w pliku konfiguracyjnym z możliwością wyszukiwania, jak pokazano 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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

W zależności od rodzaju intencji, którą przypisujesz do każdej sugestii, oraz sposobu formatowania zapytań do dostawcy treści możesz potrzebować dodatkowych atrybutów. Pozostałe atrybuty opcjonalne zostały omówione w kolejnych sekcjach.

Tworzenie dostawcy treści

Aby utworzyć dostawcę treści dla niestandardowych sugestii, najpierw zapoznaj się z sekcją Dostawcy treści, w której znajdziesz informacje o tym, jak to zrobić. Dostawca treści dla niestandardowych sugestii jest podobny do każdego innego dostawcy treści. W przypadku każdej sugestii musisz jednak podać odpowiedni wiersz w pliku Cursor, który musi zawierać określone kolumny, które system rozumie i wykorzystuje do formatowania sugestii.

Gdy użytkownik wpisze tekst w oknie wyszukiwania lub widżecie wyszukiwania, system wysyła do dostawcy treści zapytanie o sugestie, wywołując funkcję query() za każdym razem, gdy użytkownik wpisze literę. W implementacji query() dostawca treści musi przeszukać dane sugestii i zwrócić Cursor, który wskazuje wiersze uznane za dobre sugestie.

Szczegóły tworzenia dostawcy treści dla niestandardowych sugestii znajdziesz w 2 sekcjach poniżej:

Obsługa zapytania o sugestię

Sposób, w jaki system wysyła żądania do dostawcy treści, i jak je obsługiwać.

Tworzenie tabeli sugestii

Jak zdefiniować kolumny, których system oczekuje w Cursor zwracanych z każdym zapytaniem.

Obsługa zapytania dotyczącego sugestii

Gdy system prosi dostawcę treści o sugestie, wywołuje metodę query() dostawcy treści. Zaimplementuj tę metodę, aby wyszukiwać dane sugestii i zwracać Cursor wskazujące sugestie, które uznasz za istotne.

Oto podsumowanie parametrów, które system przekazuje do Twojej metody query(), w kolejności ich występowania:

uri

Zawsze treść Uri sformatowana w ten sposób:

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

Domyślnie system przekazuje ten identyfikator URI i dołącza do niego tekst zapytania:

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

Tekst zapytania na końcu jest zakodowany zgodnie z regułami kodowania URI, więc przed wyszukiwaniem może być konieczne jego dekodowanie.

Część optional.suggest.path jest uwzględniana w identyfikatorze URI tylko wtedy, gdy ustawisz taką ścieżkę w pliku konfiguracyjnym z możliwością wyszukiwania za pomocą atrybutu android:searchSuggestPath. Jest to konieczne tylko wtedy, gdy używasz tego samego dostawcy treści w przypadku wielu działań, które można wyszukiwać. W takim przypadku rozróżnij źródło zapytania sugestii.

projection

Zawsze wartość null.

selection

Wartość podana w atrybucie android:searchSuggestSelection pliku konfiguracyjnego z możliwością wyszukiwania lub wartość null, jeśli nie zadeklarujesz atrybutu android:searchSuggestSelection. Więcej informacji znajdziesz w następnej sekcji.

selectionArgs

Zawiera zapytanie jako pierwszy i jedyny element tablicy, jeśli w konfiguracji wyszukiwania zadeklarujesz atrybut android:searchSuggestSelection. Jeśli nie zadeklarujesz android:searchSuggestSelection, ten parametr będzie miał wartość null. Więcej informacji znajdziesz w następnej sekcji.

sortOrder

Zawsze wartość null.

System może wysłać tekst zapytania na 2 sposoby. Domyślnie tekst zapytania jest uwzględniany jako ostatnia ścieżka identyfikatora URI treści przekazywanego w parametrze uri. Jeśli jednak uwzględnisz wartość wyboru w atrybucie android:searchSuggestSelection konfiguracji wyszukiwania, tekst zapytania zostanie przekazany jako pierwszy element tablicy ciągów znaków selectionArgs. Te 2 opcje opisano poniżej.

Pobieranie zapytania w Uri

Domyślnie zapytanie jest dołączane jako ostatni segment parametru uri, czyli obiektu Uri. Aby w tym przypadku pobrać tekst zapytania, użyj getLastPathSegment(), jak w tym przykładzie:

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

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

Zwraca to ostatni segment Uri, czyli tekst zapytania wprowadzony przez użytkownika.

Pobieranie zapytania w argumentach wyboru

Zamiast używać URI, może być bardziej sensowne, aby metoda query() otrzymywała wszystko, czego potrzebuje do wyszukiwania, a parametry selection i selectionArgs zawierały odpowiednie wartości. W tym przypadku dodaj atrybut android:searchSuggestSelection do konfiguracji z możliwością wyszukiwania za pomocą ciągu wyboru SQLite. W ciągu znaków wyboru umieść znak zapytania (?) jako symbol zastępczy rzeczywistego zapytania. System wywołuje funkcję query() z ciągiem wyboru jako parametrem selection i zapytaniem jako pierwszym elementem tablicy selectionArgs.

Oto przykład, jak możesz utworzyć atrybut android:searchSuggestSelection, aby utworzyć pełnotekstowe wyrażenie wyszukiwania:

<?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>

W tej konfiguracji metoda query() przekazuje parametr selection jako "word MATCH ?", a parametr selectionArgs jako zapytanie. Gdy przekażesz je do metody SQLite jako odpowiednie argumenty, zostaną one zsyntetyzowane, co oznacza, że znak zapytania zostanie zastąpiony tekstem zapytania.query() Jeśli otrzymujesz w ten sposób zapytania z sugestiami i musisz dodać do tekstu zapytania symbole wieloznaczne, dołącz je do parametru selectionArgs lub dodaj je przed nim, ponieważ ta wartość jest ujęta w cudzysłów i wstawiana w miejsce znaku zapytania.

Kolejny atrybut w poprzednim przykładzie to android:searchSuggestIntentAction, który definiuje działanie związane z intencją wysyłane z każdą intencją, gdy użytkownik wybierze sugestię. Więcej informacji znajdziesz w sekcji Deklarowanie intencji dotyczącej sugestii.

Tworzenie tabeli sugestii

Gdy zwracasz sugestie do systemu za pomocą znaku Cursor, system oczekuje w każdym wierszu określonych kolumn. Niezależnie od tego, czy dane sugestii są przechowywane w bazie danych SQLite na urządzeniu, w bazie danych na serwerze internetowym czy w innym formacie na urządzeniu lub w internecie, sformatuj sugestie jako wiersze w tabeli i wyświetl je za pomocą znaku Cursor.

System rozpoznaje kilka kolumn, ale tylko 2 z nich są wymagane:

_ID

Unikalny identyfikator wiersza w postaci liczby całkowitej dla każdej sugestii. System wymaga tego, aby wyświetlać sugestie w ListView.

SUGGEST_COLUMN_TEXT_1

Ciąg znaków, który jest prezentowany jako sugestia.

Wszystkie te kolumny są opcjonalne. Większość z nich omówimy szczegółowo w kolejnych sekcjach.

SUGGEST_COLUMN_TEXT_2

Ciąg znaków. Jeśli plik Cursor zawiera tę kolumnę, wszystkie sugestie są podawane w formacie dwuwierszowym. Ciąg znaków w tej kolumnie jest wyświetlany jako drugi, mniejszy wiersz tekstu pod głównym tekstem sugestii. Może mieć wartość null lub być puste, aby wskazywać brak tekstu dodatkowego.

SUGGEST_COLUMN_ICON_1

Ciąg identyfikatora URI zasobu do rysowania, treści lub pliku. Jeśli Twój plik Cursor zawiera tę kolumnę, wszystkie sugestie są podawane w formacie ikona plus tekst, a ikona jest wyświetlana po lewej stronie. Może to być wartość null lub zero, co oznacza brak ikony w tym wierszu.

SUGGEST_COLUMN_ICON_2

Ciąg identyfikatora URI zasobu do rysowania, treści lub pliku. Jeśli Twój plik Cursor zawiera tę kolumnę, wszystkie sugestie są podawane w formacie ikona + tekst, a ikona znajduje się po prawej stronie. Może to być wartość null lub zero, co oznacza brak ikony w tym wierszu.

SUGGEST_COLUMN_INTENT_ACTION

Ciąg działania intencji. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, podczas tworzenia intencji sugestii używane jest zdefiniowane tutaj działanie. Jeśli element nie jest podany, działanie jest podejmowane na podstawie pola android:searchSuggestIntentAction w konfiguracji wyszukiwania. Jeśli działanie jest takie samo w przypadku wszystkich sugestii, bardziej efektywne jest określenie działania za pomocą tagu android:searchSuggestIntentAction i pominięcie tej kolumny.

SUGGEST_COLUMN_INTENT_DATA

Ciąg identyfikatora URI danych. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, te dane są używane podczas tworzenia intencji sugestii. Jeśli element nie zostanie podany, dane zostaną pobrane z pola android:searchSuggestIntentData w konfiguracji wyszukiwania. Jeśli nie podano żadnego źródła, pole danych intencji ma wartość null. Jeśli dane są takie same dla wszystkich sugestii lub można je opisać za pomocą stałej części i konkretnego identyfikatora, bardziej efektywne jest określenie ich za pomocą tagu android:searchSuggestIntentData i pominięcie tej kolumny.

SUGGEST_COLUMN_INTENT_DATA_ID

Ciąg ścieżki URI. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, do pola danych w intencji dodawany jest znak „/” i ta wartość. Używaj tego tylko wtedy, gdy pole danych określone przez atrybut android:searchSuggestIntentData w konfiguracji z możliwością wyszukiwania jest już ustawione na odpowiedni ciąg podstawowy.

SUGGEST_COLUMN_INTENT_EXTRA_DATA

Dowolne dane. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, są to dodatkowe dane używane podczas tworzenia intencji sugestii. Jeśli nie zostanie podany, dodatkowe pole danych intencji będzie miało wartość null. Ta kolumna umożliwia sugestiom dostarczanie dodatkowych danych, które są uwzględniane jako dodatkowe informacje w EXTRA_DATA_KEYkluczu intencji.

SUGGEST_COLUMN_QUERY

Jeśli ta kolumna istnieje, a ten element występuje w danym wierszu, są to dane używane podczas tworzenia zapytania sugestii, które są dołączane jako dodatkowe w QUERYkluczu intencji.QUERY Jest wymagany, jeśli działanie sugestii to ACTION_SEARCH, ale w innych przypadkach jest opcjonalny.

SUGGEST_COLUMN_SHORTCUT_ID

Używane tylko podczas wyświetlania sugestii w polu szybkiego wyszukiwania. Ta kolumna określa, czy sugestia wyszukiwania musi być przechowywana jako skrót i czy musi być weryfikowana. Skróty są zwykle tworzone, gdy użytkownik kliknie sugestię w polu szybkiego wyszukiwania. Jeśli go brakuje, wynik jest zapisywany jako skrót i nigdy nie jest odświeżany. Jeśli ustawisz wartość SUGGEST_NEVER_MAKE_SHORTCUT, wynik nie zostanie zapisany jako skrót. W przeciwnym razie identyfikator skrótu jest używany do sprawdzenia aktualnej sugestii za pomocą SUGGEST_URI_PATH_SHORTCUT.

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

Używane tylko podczas wyświetlania sugestii w polu szybkiego wyszukiwania. Ta kolumna określa, że zamiast ikony z SUGGEST_COLUMN_ICON_2 podczas odświeżania skrótu tej sugestii w polu szybkiego wyszukiwania musi być wyświetlany spinner.

Większość tych kolumn omówimy w dalszej części tego artykułu.

Deklarowanie intencji dotyczącej sugestii

Gdy użytkownik wybierze sugestię z listy, która pojawi się pod oknem wyszukiwania lub widżetem, system wyśle niestandardowy Intent do Twojej aktywności, w której można wyszukiwać. Musisz zdefiniować działanie i dane dla intencji.

Deklarowanie działania intencji

Najczęstszym działaniem związanym z intencją w przypadku sugestii niestandardowej jest ACTION_VIEW. Jest ono odpowiednie, gdy chcesz coś otworzyć, np. definicję słowa, dane kontaktowe osoby lub stronę internetową. Działanie związane z intencją może być jednak dowolnym innym działaniem i może się różnić w przypadku poszczególnych sugestii.

W zależności od tego, czy chcesz, aby wszystkie sugestie używały tego samego działania związanego z intencją, możesz zdefiniować działanie na 2 sposoby:

• Użyj atrybutu android:searchSuggestIntentAction w pliku konfiguracyjnym z możliwością wyszukiwania, aby zdefiniować działanie dla wszystkich sugestii, jak pokazano 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"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW" >
  </searchable>

• W kolumnie SUGGEST_COLUMN_INTENT_ACTION możesz określić działanie dla poszczególnych sugestii. Aby to zrobić, dodaj do tabeli sugestii kolumnę SUGGEST_COLUMN_INTENT_ACTION i w przypadku każdej sugestii umieść w niej działanie, którego chcesz użyć, np. "android.intent.action.VIEW".

Możesz też połączyć te 2 techniki. Możesz na przykład dodać atrybut android:searchSuggestIntentAction z działaniem, które ma być domyślnie używane we wszystkich sugestiach, a następnie zastąpić to działanie w przypadku niektórych sugestii, deklarując inne działanie w kolumnie SUGGEST_COLUMN_INTENT_ACTION. Jeśli nie podasz wartości w kolumnie SUGGEST_COLUMN_INTENT_ACTION, zostanie użyty zamiar podany w atrybucie android:searchSuggestIntentAction.

Deklarowanie danych o intencjach

Gdy użytkownik wybierze sugestię, Twoja aktywność, którą można przeszukiwać, otrzyma intencję z określonym przez Ciebie działaniem – jak opisano w poprzedniej sekcji – ale intencja musi też zawierać dane, aby Twoja aktywność mogła rozpoznać, która sugestia została wybrana. Dane muszą być unikalne dla każdej sugestii, np. identyfikator wiersza sugestii w tabeli SQLite. Po otrzymaniu intencji możesz pobrać dołączone dane za pomocą funkcji getData() lub getDataString().

Dane dołączone do intencji możesz zdefiniować na 2 sposoby:

• Określ dane dla każdej sugestii w kolumnie SUGGEST_COLUMN_INTENT_DATA tabeli sugestii.

  W tabeli sugestii podaj wszystkie niezbędne informacje o danych dla każdego zamiaru, wstawiając kolumnę SUGGEST_COLUMN_INTENT_DATA, a następnie wypełniając ją unikalnymi danymi w każdym wierszu. Dane z tej kolumny są dołączane do intencji dokładnie tak, jak zdefiniujesz je w tej kolumnie. Możesz go wtedy odzyskać za pomocą getData() lub getDataString().

• Podziel adres URI danych na 2 części: część wspólną dla wszystkich sugestii i część unikalną dla każdej sugestii. Umieść te części w atrybucie android:searchSuggestintentData konfiguracji umożliwiającej wyszukiwanie i w kolumnie SUGGEST_COLUMN_INTENT_DATA_ID tabeli sugestii.

  Przykład poniżej pokazuje, jak zadeklarować część identyfikatora URI, która jest wspólna dla wszystkich sugestii, w atrybucie android:searchSuggestIntentData konfigurowalnego elementu wyszukiwania:

    <?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>
    

  W kolumnie SUGGEST_COLUMN_INTENT_DATA_ID tabeli sugestii podaj ścieżkę końcową każdej sugestii, czyli jej unikalną część. Gdy użytkownik wybierze sugestię, system pobierze ciąg znaków z kolumny android:searchSuggestIntentData, doda ukośnik (/), a następnie doda odpowiednią wartość z kolumny SUGGEST_COLUMN_INTENT_DATA_ID, aby utworzyć pełny identyfikator URI treści. Następnie możesz pobrać Uri za pomocą polecenia getData().

Dodawanie większej ilości danych

Jeśli chcesz przekazać więcej informacji o swoim zamiarze, możesz dodać kolejną kolumnę tabeli, np. SUGGEST_COLUMN_INTENT_EXTRA_DATA, w której możesz przechowywać dodatkowe informacje o sugestii. Dane zapisane w tej kolumnie są umieszczane w EXTRA_DATA_KEY dodatkowego pakietu intencji.

Obsługa intencji

Po udostępnieniu niestandardowych sugestii wyszukiwania z niestandardowymi zamiarami musisz sprawić, aby Twoja aktywność, którą można przeszukiwać, obsługiwała te zamiary, gdy użytkownik wybierze sugestię. Oprócz tego musisz obsługiwać ACTION_SEARCHintencję, co już robisz w przypadku aktywności, którą można wyszukiwać. Oto przykład obsługi intencji w wywołaniu zwrotnym onCreate() aktywności:

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);
}

W tym przykładzie działanie intencji to ACTION_VIEW, a dane zawierają pełny identyfikator URI wskazujący sugerowany element, który został utworzony przez ciąg android:searchSuggestIntentData i kolumnę SUGGEST_COLUMN_INTENT_DATA_ID. Identyfikator URI jest następnie przekazywany do lokalnej metody showResult(), która wysyła do dostawcy treści zapytanie o element określony przez identyfikator URI.

Przepisz tekst zapytania

Domyślnie, jeśli użytkownik porusza się po liście sugestii za pomocą elementów sterujących kierunkiem, np. trackballa lub pada kierunkowego, tekst zapytania nie jest aktualizowany. Możesz jednak tymczasowo zastąpić tekst zapytania użytkownika w polu tekstowym zapytaniem pasującym do sugerowanej odpowiedzi. Dzięki temu użytkownik widzi sugerowane zapytanie i może wybrać pole wyszukiwania oraz edytować zapytanie przed wysłaniem go jako wyszukiwania.

Tekst zapytania możesz napisać ponownie na te sposoby:

• Dodaj do konfigurowalnego atrybutu android:searchMode wartość "queryRewriteFromText". W tym przypadku do zmiany tekstu zapytania używane są treści z kolumny SUGGEST_COLUMN_TEXT_1 sugestii.
• Dodaj atrybut android:searchMode do konfiguracji searchable\ z wartością "queryRewriteFromData". W tym przypadku treść z kolumny SUGGEST_COLUMN_INTENT_DATA sugestii jest używana do przepisania tekstu zapytania. Używaj tej funkcji tylko w przypadku identyfikatorów URI lub innych formatów danych, które mają być widoczne dla użytkownika, np. adresów URL HTTP. Nie używaj wewnętrznych schematów identyfikatorów URI do przepisywania zapytania w ten sposób.
• W kolumnie SUGGEST_COLUMN_QUERY tabeli sugestii podaj unikalny ciąg tekstowy zapytania. Jeśli ta kolumna jest obecna i zawiera wartość dla bieżącej sugestii, jest używana do przepisania tekstu zapytania i zastąpienia jednej z poprzednich implementacji.

Udostępnianie sugestii wyszukiwania w oknie szybkiego wyszukiwania

Po skonfigurowaniu aplikacji tak, aby udostępniała niestandardowe sugestie wyszukiwania, udostępnienie ich w globalnie dostępnym polu szybkiego wyszukiwania jest tak proste, jak zmodyfikowanie konfiguracji wyszukiwania, aby zawierała element android:includeInGlobalSearch z wartością "true".

Dodatkowe działania są konieczne tylko wtedy, gdy dostawca treści wymaga uprawnień do odczytu. W takim przypadku musisz dodać element <path-permission>, aby dostawca przyznał Szybkiemu polu wyszukiwania dostęp do odczytu Twojego dostawcy treści, jak pokazano w tym przykładzie:

<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>

W tym przykładzie dostawca ogranicza dostęp do treści do odczytu i zapisu. Element <path-permission> zmienia ograniczenie, przyznając dostęp do odczytu treści w "/search_suggest_query" prefiksie ścieżki, gdy istnieje uprawnienie "android.permission.GLOBAL_SEARCH". Umożliwia to dostęp do pola szybkiego wyszukiwania, dzięki czemu może ono wysyłać do dostawcy treści zapytania o sugestie.

Jeśli dostawca treści nie wymusza uprawnień do odczytu, pole szybkiego wyszukiwania odczytuje je domyślnie.

Włączanie sugestii na urządzeniu

Domyślnie aplikacje nie mogą wyświetlać sugestii w polu szybkiego wyszukiwania, nawet jeśli są do tego skonfigurowane. Użytkownik decyduje, czy uwzględniać sugestie z aplikacji w polu szybkiego wyszukiwania. W tym celu otwiera Elementy, które można przeszukiwać w sekcji Ustawienia > Wyszukiwanie i włącza aplikację jako element, który można przeszukiwać.

Każda aplikacja dostępna w Szybkim polu wyszukiwania ma wpis na stronie ustawień Elementy do wyszukiwania. Wpis zawiera nazwę aplikacji i krótki opis treści, które można w niej wyszukiwać i które są dostępne jako sugestie w polu szybkiego wyszukiwania. Aby zdefiniować tekst opisu aplikacji, w której można wyszukiwać, dodaj atrybut android:searchSettingsDescription do konfiguracji aplikacji, w której można wyszukiwać, jak pokazano 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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

Ciąg znaków dla android:searchSettingsDescription powinien być jak najkrótszy i określać, jakie treści można wyszukiwać. Na przykład „Wykonawcy, albumy i utwory” w przypadku aplikacji muzycznej lub „Zapisane notatki” w przypadku aplikacji do robienia notatek. Podanie tego opisu jest ważne, aby użytkownik wiedział, jakie sugestie są wyświetlane. Zawsze uwzględniaj ten atrybut, gdy atrybut android:includeInGlobalSearch ma wartość „true”.

Użytkownik musi otworzyć menu ustawień, aby włączyć sugestie wyszukiwania w Twojej aplikacji. Jeśli wyszukiwanie jest ważnym aspektem Twojej aplikacji, zastanów się, jak przekazać tę informację użytkownikom. Możesz na przykład wyświetlić notatkę przy pierwszym uruchomieniu aplikacji przez użytkownika, która wyjaśnia, jak włączyć sugestie wyszukiwania w Szybkim polu wyszukiwania.

Zarządzanie skrótami sugestii w polu szybkiego wyszukiwania

Sugestie, które użytkownik wybierze w polu szybkiego wyszukiwania, mogą być automatycznie przekształcane w skróty. Są to sugestie, które system kopiuje od dostawcy treści, aby mieć do nich szybki dostęp bez konieczności ponownego wysyłania zapytań do dostawcy.

Domyślnie ta opcja jest włączona w przypadku wszystkich sugestii pobieranych przez pole szybkiego wyszukiwania, ale jeśli dane sugestii zmieniają się z czasem, możesz poprosić o odświeżenie skrótów. Jeśli na przykład sugestie odnoszą się do danych dynamicznych, takich jak stan obecności kontaktu, poproś o odświeżenie skrótów sugestii, gdy są one wyświetlane użytkownikowi. Aby to zrobić, dodaj do tabeli sugestii znak SUGGEST_COLUMN_SHORTCUT_ID. W tej kolumnie możesz skonfigurować działanie skrótu dla każdej sugestii na jeden z tych sposobów:

• Spraw, aby pole szybkiego wyszukiwania ponownie wysłało zapytanie do dostawcy treści o nową wersję skrótu do sugestii.

  W kolumnie SUGGEST_COLUMN_SHORTCUT_ID podaj wartość, aby za każdym razem, gdy wyświetlane jest skrót, ponownie wysyłać zapytanie o sugestię w celu uzyskania jej najnowszej wersji. Skrót wyświetla się szybko z najnowszymi dostępnymi danymi, dopóki nie zostanie zwrócone zapytanie o odświeżenie. W tym momencie sugestia jest odświeżana o nowe informacje. Zapytanie o odświeżenie jest wysyłane do dostawcy treści ze ścieżką URI SUGGEST_URI_PATH_SHORTCUT zamiast SUGGEST_URI_PATH_QUERY.

  Zwracany przez Ciebie element Cursor powinien zawierać 1 sugestię z tymi samymi kolumnami co oryginalna sugestia lub być pusty, co oznacza, że skrót nie jest już ważny. W takim przypadku sugestia znika, a skrót zostaje usunięty.

  Jeśli sugestia odnosi się do danych, których odświeżanie może trwać dłużej, np. odświeżanie oparte na sieci, możesz też dodać do tabeli sugestii kolumnę SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING z wartością „true”, aby wyświetlać ikonę postępu odświeżania po prawej stronie, dopóki odświeżanie się nie zakończy. Każda wartość inna niż true nie wyświetla wskaźnika postępu.

• Uniemożliwia skopiowanie sugestii do skrótu.

  Podaj wartość SUGGEST_NEVER_MAKE_SHORTCUT w kolumnie SUGGEST_COLUMN_SHORTCUT_ID. W takim przypadku sugestia nigdy nie jest kopiowana do skrótu. Jest to konieczne tylko wtedy, gdy nie chcesz, aby wcześniej skopiowana sugestia się wyświetlała. Jeśli podasz normalną wartość w kolumnie, skrót sugestii będzie się wyświetlać tylko do momentu, gdy zapytanie odświeżania zwróci wynik.

• Zastosuj domyślne działanie skrótu.

  Pozostaw puste pole SUGGEST_COLUMN_SHORTCUT_ID przy każdej sugestii, która nie ulega zmianie i może zostać zapisana jako skrót.

Jeśli żadna z Twoich sugestii nigdy się nie zmienia, nie potrzebujesz kolumnySUGGEST_COLUMN_SHORTCUT_ID.

Informacje o rankingu sugestii w oknie szybkiego wyszukiwania

Gdy udostępnisz sugestie wyszukiwania aplikacji w Szybkim polu wyszukiwania, ranking Szybkiego pola wyszukiwania określi, jak sugestie będą wyświetlane użytkownikowi w przypadku danego zapytania. Może to zależeć od tego, ile innych aplikacji ma wyniki dla danego zapytania i jak często użytkownik wybiera Twoje wyniki w porównaniu z wynikami innych aplikacji. Nie ma gwarancji, jak Twoje sugestie będą klasyfikowane ani czy sugestie dotyczące Twojej aplikacji będą w ogóle wyświetlane w przypadku danego zapytania. Ogólnie rzecz biorąc, dostarczanie wyników wysokiej jakości zwiększa prawdopodobieństwo, że sugestie Twojej aplikacji będą wyświetlane na widocznym miejscu. Aplikacje, które dostarczają sugestie niskiej jakości, są częściej klasyfikowane niżej lub nie są wyświetlane.