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 ustawiszandroid: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 wSUGGEST_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 wimeOptions
.
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ą parametruselectionArgs
aktywować wyświetlenie tekstu zapytania, a potem zignorować parametrselection
. 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 kolumnieSUGGEST_COLUMN_INTENT_ACTION
, zostanie ona umieszczona w polu działaniaIntent
, 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 danychIntent
, 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ściLocale.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 poleceniaEXTRA_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 intencjiACTION_SEARCH
, która jest przekazywana do aktywności, którą można przeszukiwać. Aby przeanalizować kod klucza, użyjgetIntExtra(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 funkcjigetStringExtra(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 atrybutuandroid: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>