Dodawanie niestandardowych sugestii wyszukiwania

Gdy używasz okna wyszukiwania na Androidzie lub widżetu wyszukiwania, możesz podawać niestandardowe sugestie wyszukiwania, które są tworzone na podstawie danych w aplikacji. Jeśli na przykład aplikacja jest słownikiem, możesz sugerować w słowniku słowa pasujące do tekstu wpisanego w polu wyszukiwania, zanim użytkownik zakończy zapytanie. Sugestie te są cenne, ponieważ pozwalają skutecznie przewidywać, czego chce użytkownik, i zapewniać natychmiastowy dostęp do tych podpowiedzi. Rysunek 1 przedstawia przykład okna wyszukiwania z niestandardowymi sugestiami.

Po podaniu spersonalizowanych sugestii możesz je także udostępnić w całym systemie Okno szybkiego wyszukiwania, co zapewni dostęp do Twoich treści spoza aplikacji.

Zanim dodasz niestandardowe sugestie, zaimplementuj okno wyszukiwania na Androidzie lub widżet wyszukiwania do wyszukiwania w aplikacji. Zobacz 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 możliwej do wyszukiwania zdarzenie Intent. W odróżnieniu od normalnego zapytania, które wysyła intencję działaniem ACTION_SEARCH, możesz zamiast tego zdefiniować niestandardowe sugestie użycia atrybutu ACTION_VIEW lub dowolnego innego działania dotyczącego zamiaru, a także uwzględnić dane związane z wybraną sugestią. W przykładzie ze słownikiem, gdy użytkownik wybierze sugestię, aplikacja może natychmiast otworzyć definicję tego słowa, zamiast szukać dopasowań w słowniku.

Aby wyświetlić niestandardowe sugestie, wykonaj te czynności:

  • Zaimplementuj podstawowe działanie umożliwiające wyszukiwanie, zgodnie z opisem w sekcji Tworzenie interfejsu wyszukiwania.
  • Zmodyfikuj konfigurację możliwości wyszukiwania, korzystając z informacji o dostawcy treści, który udostępnia niestandardowe sugestie.
  • Utwórz tabelę, na przykład w SQLiteDatabase, na sugestie i sformatuj tabelę za pomocą wymaganych kolumn.
  • Utwórz dostawcę treści, który ma dostęp do tabeli sugestii, i zadeklaruj go w pliku manifestu.
  • Zadeklaruj typ elementu Intent, który ma być wysyłany, gdy użytkownik wybierze sugestię, w tym działanie niestandardowe i dane niestandardowe.

System Android wyświetla okno wyszukiwania, a oprócz tego wyświetla też sugestie wyszukiwania. Potrzebujesz dostawcy treści, od którego system może pobrać sugestie. Aby dowiedzieć się, jak utworzyć dostawcę treści, przeczytaj artykuł o dostawcach treści.

Jeśli system wykryje, że Twoją aktywność można wyszukiwać, i zaproponuje sugestie wyszukiwania, po wpisaniu zapytania przez użytkownika ma miejsce taka procedura:

  1. System pobiera tekst zapytania (czyli dowolne wprowadzone do tej pory hasło) i wysyła zapytanie do dostawcy treści, który zarządza sugestiami.
  2. Dostawca treści zwraca właściwość Cursor, która wskazuje wszystkie sugestie, które mają związek z treścią wyszukiwanego hasła.
  3. System wyświetli listę sugestii podanych przez funkcję Cursor.

Po wyświetleniu niestandardowych sugestii mogą wystąpić takie sytuacje:

  • Jeśli użytkownik wpisze kolejną literę lub w jakikolwiek sposób zmieni zapytanie, poprzednie kroki powtarzają się, a lista sugestii zostanie odpowiednio zaktualizowana.
  • Jeśli użytkownik wykona wyszukiwanie, sugestie zostaną zignorowane, a wyszukiwanie zostanie dostarczone w ramach aktywności, którą można przeszukiwać z użyciem zwykłej intencji ACTION_SEARCH.
  • Jeśli użytkownik wybierze sugestię, do działania, który można wyszukać, zostanie wysłana intencja zawierająca działanie niestandardowe i dane niestandardowe, dzięki którym aplikacja będzie mogła otworzyć sugerowane treści.

Modyfikowanie konfiguracji możliwości wyszukiwania

Aby dodać obsługę niestandardowych sugestii, dodaj atrybut android:searchSuggestAuthority do elementu <searchable> w pliku konfiguracji, który można przeszukiwać, w sposób podany 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 typu intencji dołączonej do każdej sugestii i sposobu formatowania zapytań w dostawcy treści możesz potrzebować dodatkowych atrybutów. Pozostałe atrybuty opcjonalne zostały omówione w kolejnych sekcjach.

Utwórz dostawcę treści

Jeśli chcesz utworzyć dostawcę niestandardowych sugestii, przeczytaj artykuł o dostawcach treści. Znajdziesz tam informacje o tym, jak to zrobić. Dostawca treści do niestandardowych sugestii jest podobny do każdego innego dostawcy treści. W przypadku każdej podanej sugestii odpowiedni wiersz w elemencie Cursor musi jednak zawierać określone kolumny rozpoznawane przez system i używane do ich formatowania.

Gdy użytkownik wpisuje tekst w oknie wyszukiwania lub w widżecie wyszukiwania, system wysyła zapytanie do dostawcy treści o sugestie, wywołując query() przy każdym wpisywaniu litery. W Twojej implementacji funkcji query() dostawca treści musi przeszukać dane sugestii i zwrócić wartość Cursor wskazującą wiersze, które uzna za dobre sugestie.

Szczegółowe informacje o tworzeniu dostawcy treści na potrzeby niestandardowych sugestii znajdziesz w 2 sekcjach:

Obsługa zapytania dotyczącego sugestii
W jaki sposób system wysyła żądania do dostawcy treści i jak je obsługiwać.
Tworzenie tabeli sugestii
Jak zdefiniować kolumny, które system spodziewa się w polu Cursor zwracanym przy każdym zapytaniu.

Obsługa zapytania sugestii

Gdy system żąda sugestii od dostawcy treści, wywołuje metodę query() tego dostawcy. Zastosuj tę metodę, aby wyszukiwać dane dotyczące sugestii i zwracać wartość Cursor wskazującą sugestie, które uważasz za istotne.

Oto podsumowanie parametrów, które system przekazuje do metody query(), w kolejności:

  1. uri

    Zawsze jest to Uri w takim formacie:

    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 kodowany za pomocą reguł kodowania URI, więc przed przeprowadzeniem wyszukiwania może być konieczne jego zdekodowanie.

    Część optional.suggest.path jest zawarta w identyfikatorze URI tylko wtedy, gdy ustawisz taką ścieżkę w pliku konfiguracji, który można przeszukiwać za pomocą atrybutu android:searchSuggestPath. Jest to konieczne tylko wtedy, gdy korzystasz z tego samego dostawcy treści na potrzeby wielu działań, które można wyszukać. Jeśli tak jest, określ źródło zapytania.

  2. projection
    Zawsze ma wartość null.
  3. selection
    Wartość podana w atrybucie android:searchSuggestSelection w dostępnym do przeszukiwania pliku konfiguracji lub wartość null, jeśli nie zadeklarujesz atrybutu android:searchSuggestSelection. Szczegółowo omawiamy to w tej sekcji.
  4. selectionArgs
    Zawiera wyszukiwane hasło jako pierwszy i jedyny element tablicy, jeśli zadeklarujesz atrybut android:searchSuggestSelection w konfiguracji, którą można przeszukiwać. Jeśli nie zadeklarujesz parametru android:searchSuggestSelection, ten parametr będzie miał wartość null. Szczegółowo omawiamy to w tej sekcji.
  5. sortOrder
    Zawsze ma wartość null.

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

Pobieranie zapytania z identyfikatora URI

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

Kotlin

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

Java

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

Zwraca ostatni segment parametru Uri, który jest tekstem zapytania wpisanym przez użytkownika.

Pobierz zapytanie z argumentów wyboru

Zamiast korzystać z identyfikatora URI, metoda query() może otrzymywać wszystko, czego potrzebuje do wyszukiwania. Możesz też zdecydować, że parametry selection i selectionArgs będą przekazywać odpowiednie wartości. W takim przypadku dodaj atrybut android:searchSuggestSelection do konfiguracji możliwej do wyszukiwania za pomocą ciągu wyboru SQLite. W ciągu wyboru umieść znak zapytania (?) jako zmienną dla rzeczywistego zapytania. System wywołuje funkcję query(), podając ciąg wyboru jako parametr selection, a wyszukiwane hasło jako pierwszy element tablicy selectionArgs.

Atrybut android:searchSuggestSelection pozwala na przykład utworzyć instrukcję wyszukiwania pełnotekstową:

<?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 przypadku tej konfiguracji metoda query() dostarcza parametr selection jako "word MATCH ?", a parametr selectionArgs jako zapytanie. Po przekazaniu ich do metody SQLite query() jako odpowiednich argumentów są one syntetyczne, co oznacza, że znak zapytania jest zastępowany tekstem zapytania. Jeśli otrzymujesz w ten sposób zapytania podpowiedzi i chcesz dodać symbole wieloznaczne do tekstu zapytania, dołącz je do parametru selectionArgs lub umieść przed nimi prefiks, ponieważ ta wartość jest ujęta w cudzysłów i wstawiona zamiast znaku zapytania.

Kolejnym atrybutem w poprzednim przykładzie jest android:searchSuggestIntentAction, który określa działanie intencji wysyłane z każdą intencją, gdy użytkownik wybierze sugestię. Zostało to omówione dokładniej w sekcji Deklarowanie intencji w związku z sugestiami.

Tworzenie tabeli sugestii

Gdy zwracasz sugestie do systemu z atrybutem Cursor, system oczekuje w każdym wierszu określonych kolumn. Niezależnie od tego, czy przechowujesz sugestie w bazie danych SQLite na urządzeniu, w bazie danych na serwerze WWW, czy w innym formacie na urządzeniu lub w internecie, sformatuj sugestie jako wiersze w tabeli i przedstaw je za pomocą funkcji Cursor.

System rozpoznaje kilka kolumn, ale wymagane są tylko dwie:

_ID
Unikalny identyfikator wiersza liczby całkowitej dla każdej sugestii. System wymaga tego, aby wyświetlać sugestie w elemencie ListView.
SUGGEST_COLUMN_TEXT_1
Ciąg tekstowy przedstawiony jako sugestia.

Poniższe kolumny są opcjonalne. Większość z nich zostanie omówiona w dalszej części tego artykułu.

SUGGEST_COLUMN_TEXT_2
Ciąg znaków. Jeśli Cursor zawiera tę kolumnę, wszystkie sugestie są wyświetlane w formacie dwuwierszowym. Ciąg w tej kolumnie jest wyświetlany jako drugi, mniejszy wiersz tekstu pod główną sugestią. Pole może mieć wartość null lub być puste, by oznaczać brak dodatkowego tekstu.
SUGGEST_COLUMN_ICON_1
Możliwy do rysowania ciąg tekstowy zasobu, treści lub identyfikatora URI pliku. Jeśli Cursor zawiera tę kolumnę, wszystkie sugestie są podawane w formacie ikona z tekstem i ikona, którą można przeciągnąć po lewej stronie. Wartość może być równa null lub 0 oznacza brak ikony w tym wierszu.
SUGGEST_COLUMN_ICON_2
Możliwy do rysowania ciąg tekstowy zasobu, treści lub identyfikatora URI pliku. Jeśli Cursor zawiera tę kolumnę, wszystkie sugestie są podawane w formacie ikona plus tekst z ikoną po prawej stronie. Wartość null lub 0 oznacza brak ikony w tym wierszu.
SUGGEST_COLUMN_INTENT_ACTION
Ciąg znaków działania intencji. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, przy tworzeniu intencji sugestii używane jest zdefiniowane tutaj działanie. Jeśli ten element nie zostanie podany, działanie zostanie wykonane z pola android:searchSuggestIntentAction w konfiguracji, którą można przeszukiwać. Jeśli działanie jest takie samo w przypadku wszystkich sugestii, lepiej jest określić działanie za pomocą właściwości android:searchSuggestIntentAction i pominąć tę kolumnę.
SUGGEST_COLUMN_INTENT_DATA
Ciąg URI danych. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, te dane zostaną użyte podczas tworzenia intencji sugestii. Jeśli ten element nie zostanie podany, dane zostaną pobrane z pola android:searchSuggestIntentData w konfiguracji, którą można przeszukiwać. Jeśli nie podano żadnego z źródeł, pole danych intencji ma wartość null. Jeśli dane są takie same we wszystkich sugestiach lub można je opisać za pomocą stałej części i określonego identyfikatora, lepiej jest określić je za pomocą właściwości android:searchSuggestIntentData i pominąć tę kolumnę.
SUGGEST_COLUMN_INTENT_DATA_ID
Ciąg znaków ścieżki URI. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, w polu danych w intencji znajduje się znak „/”, a ta wartość jest dodawana do pola danych. Używaj go tylko wtedy, gdy pole danych określone przez atrybut android:searchSuggestIntentData w konfiguracji umożliwiającej wyszukiwanie jest już ustawione na odpowiedni ciąg podstawowy.
SUGGEST_COLUMN_INTENT_EXTRA_DATA
Dane dowolne. Jeśli ta kolumna istnieje i zawiera wartość w danym wierszu, są to dodatkowe dane używane do tworzenia intencji sugestii. Jeśli nie podano, dodatkowe pole danych intencji ma wartość null. Ta kolumna umożliwia sugestie podawanie dodatkowych danych, które są uwzględniane jako dodatkowe dane w kluczu EXTRA_DATA_KEY 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, umieszczone jako dodatkowe informacje w kluczu QUERY intencji. Jest ona wymagana, jeśli działaniem sugestii jest ACTION_SEARCH. W przeciwnym razie jest ona opcjonalna.
SUGGEST_COLUMN_SHORTCUT_ID
Używane tylko podczas podawania sugestii dla Okna szybkiego wyszukiwania. Ta kolumna wskazuje, czy sugestia wyszukiwania musi być przechowywana jako skrót i czy musi zostać zweryfikowana. Skróty powstają zwykle wtedy, gdy użytkownik kliknie sugestię w oknie szybkiego wyszukiwania. Jeśli go nie znajdziesz, wynik będzie przechowywany jako skrót i nigdy nie będzie odświeżany. Jeśli zasada ma wartość SUGGEST_NEVER_MAKE_SHORTCUT, wynik nie jest przechowywany jako skrót. W przeciwnym razie identyfikator skrótu służy do sprawdzania, czy dostępna jest aktualna sugestia dotycząca funkcji SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
Używane tylko podczas podawania sugestii dla Okna szybkiego wyszukiwania. Ta kolumna określa, że w czasie, gdy skrót tej sugestii w oknie szybkiego wyszukiwania ma być odświeżany, zamiast ikony z SUGGEST_COLUMN_ICON_2 musi być wyświetlany wskaźnik postępu.

Większość z nich jest szczegółowo omówiona w kolejnych sekcjach.

Deklarowanie intencji związanych z sugestiami

Gdy użytkownik wybierze sugestię z listy, która pojawia się w oknie wyszukiwania lub w widżecie, system wyśle niestandardowy element Intent do Twojej aktywności możliwej do wyszukiwania. Musisz zdefiniować działanie i dane intencji.

Deklarowanie działania intencji

Najczęściej stosowanym działaniem intencji w przypadku sugestii niestandardowych jest ACTION_VIEW. Jest to odpowiednie rozwiązanie, gdy chcesz coś otworzyć, np. definicję słowa, informacje kontaktowe lub stronę internetową. Działaniem intencji może być jednak dowolne inne działanie, które może się różnić w zależności od sugestii.

W zależności od tego, czy wszystkie sugestie mają korzystać z tego samego działania intencji, możesz zdefiniować to działanie na 2 sposoby:

  • Użyj atrybutu android:searchSuggestIntentAction w pliku konfiguracji, który można przeszukiwać, aby określić 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>
  • Aby określić działania dla poszczególnych sugestii, użyj kolumny SUGGEST_COLUMN_INTENT_ACTION. Aby to zrobić, dodaj kolumnę SUGGEST_COLUMN_INTENT_ACTION do tabeli sugestii i w przypadku każdej sugestii umieść w niej działanie, które ma zostać użyte, np. "android.intent.action.VIEW".

Możesz też połączyć te 2 metody. Możesz na przykład uwzględnić atrybut android:searchSuggestIntentAction z działaniem, które będzie domyślnie używane ze wszystkimi sugestiami, 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żyta intencja podana w atrybucie android:searchSuggestIntentAction.

Deklarowanie danych intencji

Gdy użytkownik wybierze sugestię, działanie dostępne do przeszukiwania otrzymuje intencję ze zdefiniowanym przez Ciebie działaniem – co omówiliśmy w poprzedniej sekcji – ale intencja musi też zawierać dane dotyczące Twojego działania, aby można było zidentyfikować sugestię, która zostanie wybrana. Dane muszą być niepowtarzalne w przypadku każdej sugestii, np. identyfikator wiersza sugestii w tabeli SQLite. Po otrzymaniu intencji możesz pobrać załączone dane za pomocą funkcji getData() lub getDataString().

Dane uwzględnione w intencji możesz definiować na 2 sposoby:

  • Zdefiniuj dane dla każdej sugestii w kolumnie SUGGEST_COLUMN_INTENT_DATA tabeli sugestii.

    Podaj wszystkie niezbędne informacje o każdej intencji w tabeli sugestii, uwzględniając kolumnę SUGGEST_COLUMN_INTENT_DATA, a następnie wypełniając ją unikalnymi danymi dla każdego wiersza. Dane z tej kolumny są dołączone do intencji dokładnie w takiej postaci, w jakiej zostały zdefiniowane w tej kolumnie. Możesz go pobrać za pomocą usługi getData() lub getDataString().

  • Fragment identyfikatora URI danych na 2 części: część wspólna dla wszystkich sugestii oraz część unikalna dla każdej sugestii. Umieść te części odpowiednio w atrybucie android:searchSuggestintentData konfiguracji możliwej do wyszukiwania i w kolumnie SUGGEST_COLUMN_INTENT_DATA_ID tabeli sugestii.

    Z przykładu poniżej dowiesz się, jak zadeklarować fragment identyfikatora URI, który jest wspólny dla wszystkich sugestii w atrybucie android:searchSuggestIntentData konfiguracji 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>

    Podaj końcową ścieżkę każdej sugestii (unikalną część) w kolumnie SUGGEST_COLUMN_INTENT_DATA_ID w tabeli sugestii. Gdy użytkownik wybiera sugestię, system pobiera ciąg znaków z tabeli android:searchSuggestIntentData, dodaje ukośnik (/), a następnie dodaje 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ą getData().

Dodaj więcej danych

Jeśli chcesz podać więcej informacji, możesz dodać kolejną kolumnę tabeli, np. SUGGEST_COLUMN_INTENT_EXTRA_DATA, która może zawierać dodatkowe informacje o sugestii. Dane zapisane w tej kolumnie są umieszczane w elemencie EXTRA_DATA_KEY dodatkowego pakietu intencji.

Obsługa intencji

Gdy przekażesz niestandardowe sugestie wyszukiwania z intencjami niestandardowymi, Twoja aktywność związana z funkcją wyszukiwania musi obsługiwać te intencje, gdy użytkownik wybierze sugestię. Stanowi to uzupełnienie intencji ACTION_SEARCH, co już robi Twoja aktywność związana z wyszukiwaniem. Oto przykład obsługi intencji podczas wywołania zwrotnego onCreate() aktywności:

Kotlin

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

Java

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 na sugerowany element, zsyntetyzowany za pomocą ciągu znaków android:searchSuggestIntentData i kolumny SUGGEST_COLUMN_INTENT_DATA_ID. Identyfikator URI przekazuje go do lokalnej metody showResult(), która wysyła zapytanie do dostawcy treści w przypadku elementu określonego przez identyfikator URI.

Przeredaguj treść zapytania

Domyślnie, gdy użytkownik porusza się po liście sugestii za pomocą elementów sterujących kierunkowych, takich jak kulka lub pad kierunkowy, tekst zapytania nie jest aktualizowany. Można jednak tymczasowo zmienić treść zapytania użytkownika w takiej postaci, w jakiej wyświetla się w polu tekstowym, z zapytaniem pasującym do wybranej sugestii. Dzięki temu użytkownik widzi sugerowane zapytanie i może zaznaczyć pole wyszukiwania i edytować zapytanie przed wysłaniem go jako wyszukiwania.

Tekst zapytania możesz zmienić na kilka sposobów:

  • Dodaj atrybut android:searchMode do konfiguracji, którą można przeszukiwać, za pomocą wartości "queryRewriteFromText". W tym przypadku zawartość kolumny SUGGEST_COLUMN_TEXT_1 sugestii jest używana do przepisywania tekstu zapytania.
  • Dodaj atrybut android:searchMode do konfiguracji oferowanej do wyszukiwania, podając wartość "queryRewriteFromData". W tym przypadku zawartość kolumny SUGGEST_COLUMN_INTENT_DATA sugestii jest używana do przepisywania tekstu zapytania. Tej opcji należy używać tylko w przypadku identyfikatorów URI lub innych formatów danych, które mają być widoczne dla użytkownika, takich jak adresy URL HTTP. Nie używaj wewnętrznych schematów URI do przepisywania zapytań w ten sposób.
  • Podaj unikalny ciąg tekstowy zapytania w kolumnie SUGGEST_COLUMN_QUERY tabeli sugestii. Jeśli ta kolumna jest obecna i zawiera wartość bieżącej sugestii, będzie ona służyć do przepisywania tekstu zapytania i zastąpienia jednej z poprzednich implementacji.

Udostępnij sugestie wyszukiwania w Oknie szybkiego wyszukiwania

Gdy skonfigurujesz aplikację pod kątem wyświetlania niestandardowych sugestii wyszukiwania, udostępnienie ich w dostępnym globalnie Oknie szybkiego wyszukiwania jest proste – wystarczy zmodyfikować konfigurację wyszukiwania, dodając do niej android:includeInGlobalSearch z wartością "true".

Jedyny scenariusz, w którym wymagana jest dodatkowa praca, to gdy dostawca treści wymaga uprawnień do odczytu. W takim przypadku musisz dodać element <path-permission>, który pozwoli dostawcy przyznać mu dostęp do odczytu Okna szybkiego wyszukiwania, jak pokazano w poniższym 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 uprawnienia do odczytu i zapisu treści. Element <path-permission> zmienia ograniczenie, przyznając uprawnienia do odczytu treści w prefiksie ścieżki "/search_suggest_query", gdy występuje uprawnienie "android.permission.GLOBAL_SEARCH". Daje to dostęp do Okna szybkiego wyszukiwania, dzięki czemu może ono wysyłać zapytania do dostawcy treści w celu uzyskania sugestii.

Jeśli Twój dostawca treści nie wymusza uprawnień do odczytu, Okno szybkiego wyszukiwania będzie je domyślnie odczytywać.

Włączanie sugestii na urządzeniu

Domyślnie aplikacje nie wyświetlają sugestii w oknie szybkiego wyszukiwania, nawet jeśli są tak skonfigurowane. Użytkownik może zdecydować, czy chce uwzględniać sugestie z Twojej aplikacji w oknie szybkiego wyszukiwania. Aby to zrobić, otwórz Elementy do przeszukiwania (Ustawienia > Szukaj) i włącz aplikację jako element, który można wyszukać.

Każda aplikacja dostępna dla Okna szybkiego wyszukiwania ma wpis na stronie ustawień Elementy do przeszukiwania. Wpis zawiera nazwę aplikacji i krótki opis zawartości, którą można wyszukać w aplikacji oraz udostępnia sugestie w oknie szybkiego wyszukiwania. Aby określić tekst opisu aplikacji do przeszukiwania, dodaj do jej konfiguracji atrybut android:searchSettingsDescription w sposób podany 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>

Postaraj się, by ciąg android:searchSettingsDescription był jak najbardziej zwięzły i określał treść, którą można wyszukać. Może to być na przykład „Wykonawcy, albumy i utwory” w przypadku aplikacji muzycznej lub „Zapisane notatki” w przypadku aplikacji do notatników. Podanie tego opisu jest ważne, ponieważ dzięki temu użytkownik wie, jakie sugestie są podane. Zawsze uwzględniaj ten atrybut, gdy android:includeInGlobalSearch ma wartość prawda.

Aby włączyć sugestie wyszukiwania dla aplikacji, użytkownik musi otworzyć menu ustawień, dlatego jeśli wyszukiwanie jest ważnym aspektem aplikacji, zastanów się, jak przekazać te informacje użytkownikom. Na przykład przy pierwszym uruchomieniu aplikacji przez użytkownika możesz dodać wyjaśnienie, jak włączyć sugestie wyszukiwania dla Okna szybkiego wyszukiwania.

Zarządzanie skrótami sugestii Okna szybkiego wyszukiwania

Sugestie, które użytkownik wybiera w Oknie szybkiego wyszukiwania, mogą być automatycznie tworzone w skróty. Są to sugestie, które system kopiuje od dostawcy treści, aby mógł szybko uzyskać do nich dostęp bez konieczności ponownego wysyłania zapytań do dostawcy treści.

Domyślnie ta opcja jest włączona dla wszystkich sugestii pobieranych przez Okno szybkiego wyszukiwania, ale jeśli dane sugestii w przyszłości się zmienią, możesz poprosić o odświeżenie skrótów. Jeśli np. sugestie odnoszą się do danych dynamicznych, takich jak stan obecności kontaktu, poproś o odświeżenie skrótów wyświetlanych użytkownikowi. Aby to zrobić, uwzględnij SUGGEST_COLUMN_SHORTCUT_ID w tabeli sugestii. Możesz użyć tej kolumny, aby skonfigurować działanie skrótu dla każdej sugestii na jeden z tych sposobów:

  • Okno szybkiego wyszukiwania ponownie wyśle zapytanie do dostawcy treści w celu pobrania nowej wersji skrótu sugestii.

    Podaj wartość w kolumnie SUGGEST_COLUMN_SHORTCUT_ID, aby sugestia była ponawiana za każdym razem, gdy wyświetlany jest skrót. Skrót szybko wyświetla się z najnowszymi dostępnymi danymi, dopóki zapytanie nie zostanie odświeżone. Sugestia zostanie wtedy odświeżona o nowe informacje. Zapytanie odświeżania jest wysyłane do dostawcy treści ze ścieżką URI SUGGEST_URI_PATH_SHORTCUT, a nie SUGGEST_URI_PATH_QUERY.

    Zwracany wynik Cursor powinien zawierać 1 sugestię, która korzysta z tych samych kolumn co pierwotna sugestia, lub być pusta, co oznacza, że skrót jest już nieważny. W takim przypadku sugestia zniknie, a skrót zostanie usunięty.

    Jeśli sugestia dotyczy danych, których odświeżanie może trwać dłużej, np. odświeżania na podstawie sieci, możesz też dodać do tabeli sugestii kolumnę SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING z wartością prawda. Spowoduje to wyświetlanie wskaźnika postępu dla ikony po prawej stronie do czasu zakończenia odświeżania. Wartości inne niż true nie pokazują wskaźnika postępu.

  • Uniemożliwienie skopiowania sugestii do skrótu.

    Podaj wartość SUGGEST_NEVER_MAKE_SHORTCUT w kolumnie SUGGEST_COLUMN_SHORTCUT_ID. W tym przypadku sugestia nigdy nie jest kopiowana do skrótu. Jest to konieczne tylko wtedy, gdy absolutnie nie chcesz, by wyświetliła się skopiowana wcześniej sugestia. Jeśli podasz normalną wartość tej kolumny, skrót sugestii będzie widoczny tylko do momentu zwrócenia zapytania dotyczącego odświeżania.

  • Zezwól na domyślne działanie skrótu.

    Pozostaw pole SUGGEST_COLUMN_SHORTCUT_ID puste w przypadku każdej sugestii, która nie ulegnie zmianie i można ją zapisać jako skrót.

Jeśli żadna z Twoich sugestii się nie zmieni, kolumna SUGGEST_COLUMN_SHORTCUT_ID nie będzie Ci potrzebna.

Informacje o rankingu sugestii Okna szybkiego wyszukiwania

Gdy udostępnisz sugestie wyszukiwania z aplikacji w oknie szybkiego wyszukiwania, ranking w oknie szybkiego wyszukiwania określa, w jaki sposób sugestie będą wyświetlane użytkownikowi w przypadku konkretnego zapytania. Może to zależeć od tego, ile innych aplikacji wyświetla wyniki dla danego zapytania i jak często użytkownik wybiera Twoje wyniki w porównaniu z tymi z innych aplikacji. Nie ma gwarancji co do pozycji sugestii w rankingu ani tego, czy w ogóle się wyświetlą w przypadku danego zapytania. Ogólnie rzecz biorąc, dostarczanie wyników wysokiej jakości zwiększa prawdopodobieństwo, że sugestie dotyczące Twojej aplikacji będą wyświetlane na wysokiej pozycji. Aplikacje z sugestiami niskiej jakości będą częściej wyświetlać się na niższej pozycji lub w ogóle nie będą się wyświetlać.