Konfiguracja wyszukiwania

Aby zaimplementować wyszukiwanie z pomocą systemu Android, czyli dostarczać zapytania wyszukiwania do działania i podawać sugestie dotyczące wyszukiwania, aplikacja musi udostępniać konfigurację wyszukiwania w formie pliku XML.

Na tej stronie opisujemy składnię i sposób użycia pliku konfiguracji wyszukiwania. Więcej informacji o implementowaniu funkcji wyszukiwania w aplikacji znajdziesz w artykule Tworzenie interfejsu wyszukiwania.

lokalizacja pliku:
res/xml/filename.xml
Android używa nazwy pliku jako identyfikatora zasobu.
składnia:
<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>
elementy:
<searchable>
Określa wszystkie konfiguracje wyszukiwania używane przez system Android do udostępniania wspomaganego wyszukiwania.

Atrybuty:

android:label
Zasób z ciągiem znaków. (Wymagane) Nazwa Twojej aplikacji. Musi być taka sama jak nazwa zastosowana do atrybutu android:label elementu manifestu <activity> lub <application>. Ta etykieta jest widoczna dla użytkownika tylko wtedy, gdy ustawisz android:includeInGlobalSearch na "true". W takim przypadku ta etykieta służy do identyfikowania aplikacji jako elementu możliwego do wyszukiwania w ustawieniach wyszukiwania w systemie.
android:hint
Zasób z ciągiem znaków. (zalecane). Tekst wyświetlany w polu wyszukiwania, gdy nie wpiszesz tekstu. Informuje on użytkownika o tym, jakie treści można wyszukać. Aby zachować spójność z innymi aplikacjami na Androida, sformatuj ciąg znaków android:hint jako „Szukaj <treści lub produktu>”, np. „Szukaj utworów i wykonawców” lub „Szukaj w YouTube”.
android:searchMode
Słowo kluczowe. Ustawia dodatkowe tryby, które kontrolują prezentację wyszukiwania. Dostępne tryby określają, w jaki sposób trzeba przepisać tekst zapytania, gdy niestandardowa sugestia zostanie zaznaczona. Akceptowane są te wartości trybu:
WartośćOpis
"queryRewriteFromData" Użyj wartości z kolumny SUGGEST_COLUMN_INTENT_DATA, aby przeredagować tekst bquery. Tej opcji należy używać tylko wtedy, gdy wartości w SUGGEST_COLUMN_INTENT_DATA nadają się do sprawdzania i edytowania przez użytkowników, takich jak identyfikatory URI HTTP.
"queryRewriteFromText" Użyj wartości z kolumny SUGGEST_COLUMN_TEXT_1, aby przepisać tekst zapytania.

Więcej informacji znajdziesz w dokumentacji dotyczącej przepisywania tekstu zapytania w artykule Dodawanie niestandardowych sugestii wyszukiwania.

android:searchButtonText
Zasób z ciągiem znaków. Tekst wyświetlany na przycisku uruchamiającym wyszukiwanie. Domyślnie przycisk ten zawiera ikonę wyszukiwania (lupę), co idealnie sprawdza się w przypadku internacjonalizacji. Nie używaj więc tego atrybutu do zmiany przycisku, chyba że jego działanie nie jest związane z wyszukiwaniem, np. żądaniem adresu URL w przeglądarce.
android:inputType
Słowo kluczowe. Określa typ używanej metody wprowadzania, np. typ klawiatury programowej. Ten atrybut nie jest potrzebny w większości wyszukiwań, w przypadku których powinien być widoczny dowolny tekst. Listę odpowiednich wartości tego atrybutu znajdziesz w inputType.
android:imeOptions
Słowo kluczowe. Udostępnia dodatkowe opcje metody wprowadzania. Ten atrybut nie jest potrzebny w przypadku większości wyszukiwań, w których oczekiwany jest dowolny tekst. Domyślny edytor IME to actionSearch. Zawiera on przycisk wyszukiwania zamiast znaku przejścia do nowej linii na klawiaturze programowej. Listę odpowiednich wartości tego atrybutu znajdziesz w imeOptions.

Atrybuty sugestii wyszukiwania

Jeśli zdefiniujesz dostawcę treści w celu generowania sugestii wyszukiwania, musisz zdefiniować dodatkowe atrybuty, które skonfigurują komunikację z tym dostawcą. Podczas podawania sugestii wyszukiwania potrzebujesz niektórych z tych atrybutów <searchable>:


android:searchSuggestAuthority
Ciąg znaków. (Wymagane do wyświetlania sugestii wyszukiwania). Ta wartość musi być zgodna z ciągiem znaków dotyczącym urzędów podanym w atrybucie android:authorities elementu <provider> manifestu Androida.
android:searchSuggestPath
Ciąg znaków. Ta ścieżka jest używana jako część zapytania sugestii Uri, po prefiksie i uprawnieniu oraz przed standardową ścieżką sugestii. Jest to wymagane tylko wtedy, gdy jeden dostawca treści wystawia różne typy sugestii, np. dla różnych typów danych, i potrzebujesz sposobu na rozróżnianie zapytań z sugestiami po ich otrzymaniu.
android:searchSuggestSelection
Ciąg znaków. Ta wartość jest przekazywana do funkcji zapytania jako parametr selection. Zwykle jest to klauzula WHERE w odniesieniu do bazy danych. Musi zawierać pojedynczy znak zapytania jako obiekt zastępczy rzeczywistego ciągu zapytania wpisanego przez użytkownika, np. "query=?". Możesz też jednak użyć dowolnej wartości niezerowej, aby za pomocą parametru selectionArgs aktywować wyświetlenie tekstu zapytania, a potem zignorować parametr selection.
android:searchSuggestIntentAction
Ciąg znaków. Domyślne działanie dotyczące intencji, które ma być używane, gdy użytkownik kliknie niestandardową sugestię wyszukiwania, np. "android.intent.action.VIEW". Jeśli ta wartość nie zostanie zastąpiona przez wybraną sugestię w kolumnie SUGGEST_COLUMN_INTENT_ACTION, zostanie ona umieszczona w polu działania Intent, gdy użytkownik kliknie sugestię.
android:searchSuggestIntentData
Ciąg znaków. Domyślne dane dotyczące intencji, które mają być używane, gdy użytkownik kliknie niestandardową sugestię wyszukiwania. Jeśli nie zostanie ona zastąpiona przez wybraną sugestię (w kolumnie SUGGEST_COLUMN_INTENT_DATA), zostanie ona umieszczona w polu danych Intent, gdy użytkownik kliknie sugestię.
android:searchSuggestThreshold
Liczba całkowita. Minimalna liczba znaków wymaganych do aktywowania wyszukiwania sugestii. To daje tylko pewność, że system nie wyśle zapytania do dostawcy treści w przypadku wartości krótszych niż wartość progowa. Wartość domyślna to 0.

Więcej informacji o powyższych atrybutach na potrzeby sugestii wyszukiwania znajdziesz w dokumentacji dotyczącej dodawania niestandardowych sugestii wyszukiwania i dodawania niestandardowych sugestii.

Atrybuty okna szybkiego wyszukiwania

Aby udostępnić niestandardowe sugestie wyszukiwania w Oknie szybkiego wyszukiwania, potrzebujesz niektórych z następujących atrybutów <searchable>:


android:includeInGlobalSearch
Wartość logiczna. (Wymagane do wyświetlania sugestii wyszukiwania w Oknie szybkiego wyszukiwania). Ustaw wartość "true", jeśli chcesz, aby Twoje sugestie były uwzględniane w dostępnym globalnie Oknie szybkiego wyszukiwania. Zanim sugestie pojawią się w oknie szybkiego wyszukiwania, użytkownik musi włączyć Twoją aplikację jako element, który można przeszukiwać w ustawieniach wyszukiwania w systemie.
android:searchSettingsDescription
Zasób z ciągiem znaków. Zawiera krótki opis sugestii wyszukiwania podanych w Oknie szybkiego wyszukiwania, który jest wyświetlany we wpisie elementów dostępnych do przeszukiwania w danej aplikacji. Opis musi zwięźle opisywać zawartość dostępną dla wyszukiwarki. Może to być na przykład „Wykonawcy, albumy i utwory” w przypadku aplikacji muzycznej lub „Zapisane notatki” w przypadku notatnika.
android:queryAfterZeroResults
Wartość logiczna. Ustaw wartość "true", jeśli chcesz, aby dostawca treści był wywoływany w przypadku nadzbiorów zapytań, które wcześniej nie zwracały żadnych wyników. Jeśli na przykład dostawca treści nie zwróci żadnych wyników dla słowa „bo”, trzeba je będzie wyszukać w przypadku słowa „bob”. Jeśli ustawiona jest wartość "false", superzbiory są ignorowane w czasie pojedynczej sesji – „bob” nie wywołuje ponownego zapytania. Ta zasada obowiązuje tylko przez cały czas istnienia okna wyszukiwania lub okres aktywności aktywności podczas korzystania z widżetu wyszukiwania. Gdy okno wyszukiwania lub aktywność zostaną ponownie otwarte, „bo” ponownie wyśle zapytanie do dostawcy treści. Wartość domyślna to false (fałsz).

Atrybuty wyszukiwania głosowego

Aby włączyć wyszukiwanie głosowe, potrzebujesz niektórych z tych atrybutów <searchable>:


android:voiceSearchMode
Słowo kluczowe. (Wymagane do udostępniania funkcji wyszukiwania głosowego). Włącza wyszukiwanie głosowe z określonym trybem wyszukiwania. Urządzenie może nie udostępniać wyszukiwania głosowego. W takim przypadku te flagi nie mają żadnego efektu. Akceptowane są te wartości trybu:
WartośćOpis
"showVoiceSearchButton" Wyświetla przycisk wyszukiwania głosowego, jeśli na urządzeniu jest dostępne wyszukiwanie głosowe. Jeśli jest ustawiony, trzeba też ustawić "launchWebSearch" lub "launchRecognizer" rozdzielone pionową kreską (|).
"launchWebSearch" Po kliknięciu przycisku wyszukiwania głosowego użytkownik może przejść bezpośrednio do wbudowanej funkcji wyszukiwania głosowego. Większość aplikacji nie używa tej flagi, ponieważ powoduje ona wycofanie użytkownika z działania, w ramach którego wywołano wyszukiwanie.
"launchRecognizer" Po kliknięciu przycisku wyszukiwania głosowego użytkownik może przejść bezpośrednio do wbudowanej funkcji nagrywania głosu. To działanie zachęca użytkownika do mówienia, transkrybuje wypowiedziany tekst i przekazuje powstały w ten sposób tekst zapytania do aktywności, którą można wyszukać, tak jakby użytkownik wpisał go w interfejsie wyszukiwania i kliknął przycisk wyszukiwania.
android:voiceLanguageModel
Słowo kluczowe. Model językowy, którego musi używać system rozpoznawania głosu. Akceptowane są te wartości:
WartośćOpis
"free_form" Używaj swobodnego rozpoznawania mowy do dyktowania zapytań. która jest zoptymalizowana głównie pod kątem języka angielskiego. Jest to ustawienie domyślne.
"web_search" Używaj rozpoznawania wyszukiwanych haseł w internecie, by tworzyć krótsze wyrażenia przypominające wyszukiwania. Ta funkcja jest dostępna w większej liczbie języków niż "free_form".

Więcej informacji znajdziesz w sekcji EXTRA_LANGUAGE_MODEL.

android:voicePromptText
Zasób z ciągiem znaków. Dodatkowy komunikat do wyświetlenia w oknie wprowadzania głosowego.
android:voiceLanguage
Ciąg znaków. Oczekiwany język, wyrażony w postaci ciągu stałej w polu Locale, np. "de" w przypadku języka niemieckiego lub "fr" w przypadku języka francuskiego. Jest potrzebne tylko wtedy, gdy różni się ona od bieżącej wartości Locale.getDefault().
android:voiceMaxResults
Liczba całkowita. Określa maksymalną liczbę wyników do zwrócenia, w tym wynik „najlepszy”, który jest zawsze podawany jako główne zapytanie intencji ACTION_SEARCH. Wartość musi wynosić co najmniej 1. Aby uzyskać wyniki intencji, użyj polecenia EXTRA_RESULTS. Jeśli nie zostanie podany, moduł rozpoznawania określa, ile wyników ma zostać zwróconych.
<actionkey>
Definiowanie klucza urządzenia i zachowanie działania związanego z wyszukiwaniem. Działanie związane z wyszukiwaniem to szczególny sposób działania kliknięcia przycisku na urządzeniu na podstawie bieżącego zapytania lub wybranej sugestii. Na przykład aplikacja Kontakty udostępnia działanie wyszukiwania, które umożliwia inicjowanie połączenia telefonicznego z obecnie zaznaczonym kontaktem po kliknięciu przycisku ZADZWOŃ.

Nie wszystkie klawisze działań są dostępne na każdym urządzeniu i nie wszystkie klawisze można w ten sposób zastąpić. Na przykład klucza „Ekran główny” nie można zastąpić i zawsze musi on wrócić do ekranu głównego. Pamiętaj też, aby nie definiować klawisza działania dla klucza, który jest potrzebny do wpisania zapytania. Ogranicza to liczbę dostępnych i uzasadnionych klawiszy działań do przycisku połączenia i przycisku menu.

Musisz zdefiniować klucz android:keycode, aby zdefiniować klucz, i co najmniej 1 z 3 pozostałych atrybutów definiujących działanie wyszukiwania.

Atrybuty:

android:keycode
Ciąg znaków. (Wymagane) Kluczowy kod z KeyEvent reprezentujący klucz działania, na który chcesz odpowiedzieć, np. "KEYCODE_CALL". Ta wartość jest dodawana do intencji ACTION_SEARCH, która jest przekazywana do aktywności, którą można przeszukiwać. Aby przeanalizować kod klucza, użyj getIntExtra(SearchManager.ACTION_KEY). Nie wszystkie klawisze są obsługiwane przy wyszukiwaniu, ponieważ wiele z nich służy do pisania, nawigacji i funkcji systemowych.
android:queryActionMsg
Ciąg znaków. Komunikat o działaniu, który ma być wysłany po naciśnięciu klawisza działania podczas wpisywania tekstu zapytania. Wartość ta jest dodawana do intencji ACTION_SEARCH, którą system przekazuje do aktywności dostępnej do przeszukiwania. Aby sprawdzić ciąg znaków, użyj funkcji getStringExtra(SearchManager.ACTION_MSG).
android:suggestActionMsg
Ciąg znaków. Komunikat o działaniu, który jest wysyłany po naciśnięciu klawisza działania podczas zaznaczania sugestii. Wartość ta jest dodawana do intencji, którą system przekazuje do aktywności dostępnej do przeszukiwania, korzystając z działania zdefiniowanego dla sugestii. Aby sprawdzić ciąg znaków, użyj funkcji getStringExtra(SearchManager.ACTION_MSG). Tej opcji należy używać tylko wtedy, gdy wszystkie sugestie są zgodne z tym klawiszem działania. Jeśli nie wszystkie sugestie mogą obsługiwać ten sam klawisz działania, użyj atrybutu android:suggestActionMsgColumn.
android:suggestActionMsgColumn
Ciąg znaków. Nazwa kolumny u dostawcy treści definiującej komunikat działania dla tego klawisza działania. Jest ona wysyłana, gdy użytkownik naciśnie klawisz działania, gdy aktywna jest sugestia. Ten atrybut umożliwia kontrolowanie klawisza działania na podstawie każdej sugestii, ponieważ zamiast używać atrybutu android:suggestActionMsg do definiowania komunikatu działania dla wszystkich sugestii, każdy wpis u dostawcy treści zawiera własną wiadomość o działaniu.

Najpierw musisz zdefiniować u dostawcy treści kolumnę dla każdej sugestii z komunikatem dotyczącym działania, a potem w tym atrybucie podać nazwę tej kolumny. System sprawdza kursor sugestii, używając podanego tutaj ciągu, aby wybrać kolumnę komunikatu działania, a następnie wybiera za pomocą kursora ciąg komunikatu działania. Ciąg ten jest dodawany do intencji, którą system przekazuje do aktywności dostępnej do przeszukiwania, korzystając ze zdefiniowanego przez Ciebie działania na potrzeby sugestii. Aby sprawdzić ciąg znaków, użyj funkcji getStringExtra(SearchManager.ACTION_MSG). Jeśli dane nie istnieją dla wybranej sugestii, klawisz działania jest ignorowany.

przykład:
Plik XML zapisany res/xml/searchable.xml: 
<?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:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>