Konfiguracja wyszukiwania

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

Aby wdrożyć wyszukiwanie z pomocą systemu Android, czyli przekazywać zapytania do wyszukiwania do aktywności i wyświetlać sugestie wyszukiwania, aplikacja musi udostępniać konfigurację wyszukiwania w formie pliku XML.

Na tej stronie opisujemy plik konfiguracji wyszukiwania pod kątem jego składni i sposobu użycia. Więcej informacji o wdrażaniu 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 wspomagania wyszukiwania.

Atrybuty:

android:label
Zasób tekstowy. (Wymagane) Nazwa aplikacji. Musi być taka sama jak nazwa zastosowana w atrybucie android:label elementu manifestu <activity> lub <application>. Ta etykieta jest widoczna dla użytkownika tylko wtedy, gdy ustawisz wartość android:includeInGlobalSearch na "true". W takim przypadku ta etykieta służy do identyfikowania aplikacji jako elementu, który można wyszukać w ustawieniach wyszukiwania systemu.
android:hint
Zasób tekstowy. (Zalecane). Tekst, który ma się wyświetlać w polu tekstowym wyszukiwania, gdy nie wpisano żadnego tekstu. Podpowiada użytkownikowi, jakie treści można wyszukiwać. Aby zachować spójność z innymi aplikacjami na Androida, sformatuj ciąg znaków dla android:hint jako „Wyszukaj <treści lub produkty>”. Na przykład „Wyszukaj utwory i wykonawców” lub „Wyszukaj w YouTube”.
android:searchMode
Słowo kluczowe Ustawia dodatkowe tryby, które kontrolują prezentację wyszukiwania. Dostępne tryby określają, jak należy przepisać tekst zapytania, gdy niestandardowa sugestia zostanie zaznaczona. Akceptowane są te wartości trybu:
WartośćOpis
"queryRewriteFromData" Użyj wartości z kolumnySUGGEST_COLUMN_INTENT_DATA, aby zmienić tekst zapytania. Ta opcja powinna być używana tylko wtedy, gdy wartości w SUGGEST_COLUMN_INTENT_DATA nadają się do sprawdzenia i edytowania przez użytkownika, np. identyfikatory URI HTTP.
"queryRewriteFromText" Użyj wartości z kolumnySUGGEST_COLUMN_TEXT_1, aby zmodyfikować tekst zapytania.

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

android:searchButtonText
Zasób tekstowy. Tekst, który ma być wyświetlany na przycisku uruchamiającym wyszukiwanie. Domyślnie przycisk zawiera ikonę wyszukiwania (lupę), co jest idealne w przypadku internacjonalizacji. Nie używaj więc tego atrybutu do zmiany przycisku, chyba że jego działanie jest inne niż wyszukiwanie, np. żądanie adresu URL w przeglądarce.
android:inputType
Słowo kluczowe Określa typ metody wprowadzania, np. typ klawiatury ekranowej. W przypadku większości wyszukiwań, w których oczekiwany jest tekst w dowolnej formie, nie potrzebujesz tego atrybutu. Listę odpowiednich wartości tego atrybutu znajdziesz na inputType.
android:imeOptions
Słowo kluczowe Zawiera dodatkowe opcje metody wprowadzania. W przypadku większości wyszukiwań, w których oczekiwany jest tekst w dowolnej formie, nie potrzebujesz tego atrybutu. Domyślny edytor IME to actionSearch, który na klawiaturze ekranowej udostępnia przycisk „Szukaj” zamiast znaku powrotu karetki. Listę odpowiednich wartości tego atrybutu znajdziesz na imeOptions.

Atrybuty sugestii wyszukiwania

Jeśli zdefiniujesz usługę, która ma generować sugestie wyszukiwania, musisz zdefiniować dodatkowe atrybuty, które konfigurują komunikację z tą usługą. Podczas podawania sugestii wyszukiwania musisz podać niektóre z tych atrybutów <searchable>:


android:searchSuggestAuthority
Ciąg znaków (Wymagane do dostarczania sugestii wyszukiwania). Ta wartość musi być zgodna z ciągiem znaków autoryzacji podanym w atrybucie android:authorities elementu <provider> w pliku manifestu Androida.
android:searchSuggestPath
Ciąg znaków Ta ścieżka jest używana jako część zapytania o sugestie Uri po prefiksie i władzy, a przed standardową ścieżką sugestii. Jest to wymagane tylko wtedy, gdy masz jednego dostawcę treści, który wydaje różne typy sugestii, np. dla różnych typów danych, i potrzebujesz sposobu na rozróżnianie zapytań o sugestie, gdy je otrzymujesz.
android:searchSuggestSelection
Ciąg znaków Ta wartość jest przekazywana do funkcji zapytania jako parametr selection. Zwykle jest to klauzula WHERE w bazie danych, która musi zawierać jeden znak zapytania jako symbol zastępczy dla rzeczywistego ciągu zapytania wpisanego przez użytkownika, np. "query=?". Możesz jednak użyć dowolnej wartości niezerowej, aby wywołać dostarczenie tekstu zapytania za pomocą parametru selectionArgs, a następnie zignorować parametr selection).
android:searchSuggestIntentAction
Ciąg znaków Domyślna intencja, która ma być używana, gdy użytkownik kliknie niestandardową sugestię wyszukiwania, np. "android.intent.action.VIEW". Jeśli ta wartość nie zostanie zastąpiona przez wybraną sugestię za pomocą kolumny SUGGEST_COLUMN_INTENT_ACTION, zostanie umieszczona w polu działania Intent, gdy użytkownik kliknie sugestię.
android:searchSuggestIntentData
Ciąg znaków Domyślne dane o intencjach, które mają być używane, gdy użytkownik kliknie niestandardową sugestię wyszukiwania. Jeśli nie zostanie zastąpiona przez wybraną sugestię (za pomocą kolumny SUGGEST_COLUMN_INTENT_DATA), ta wartość zostanie umieszczona w polu danych Intent, gdy użytkownik kliknie sugestię.
android:searchSuggestThreshold
Liczba całkowita Minimalna liczba znaków potrzebnych do wywołania wyszukiwania sugestii. Gwarantuje to tylko, że system nie będzie wysyłać do dostawcy treści zapytań o nic krótszego niż próg. Wartością domyślną jest 0.

Więcej informacji o atrybutach sugestii wyszukiwania znajdziesz w dokumentacji dotyczącej dodawania niestandardowych sugestii wyszukiwania i dodawania niestandardowych sugestii.

Atrybuty okna szybkiego wyszukiwania

Aby niestandardowe sugestie wyszukiwania były dostępne w polu szybkiego wyszukiwania, musisz podać niektóre z tych atrybutów:<searchable>


android:includeInGlobalSearch
Wartość logiczna. (Wymagane do wyświetlania sugestii wyszukiwania w polu szybkiego wyszukiwania). Ustaw na "true", jeśli chcesz, aby Twoje sugestie były uwzględniane w globalnie dostępnym polu szybkiego wyszukiwania. Zanim sugestie zaczną się pojawiać w Szybkim polu wyszukiwania, użytkownik musi włączyć aplikację jako element, który można wyszukiwać w ustawieniach wyszukiwania systemowego.
android:searchSettingsDescription
Zasób tekstowy. Zawiera krótki opis sugestii wyszukiwania, które przekazujesz do pola szybkiego wyszukiwania. Jest on wyświetlany w pozycji elementów, które można wyszukiwać w aplikacji. Opis musi zwięźle przedstawiać treści, które można wyszukiwać. Na przykład „Wykonawcy, albumy i utwory” w przypadku aplikacji do odtwarzania muzyki lub „Zapisane notatki” w przypadku aplikacji do robienia notatek.
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 zwróci 0 wyników dla zapytania „bo”, musi ponownie wysłać zapytanie „bob”. Jeśli ma wartość "false", nadzbiory są ignorowane w przypadku pojedynczej sesji – zapytanie „bob” nie powoduje ponownego wysłania zapytania. Trwa to tylko przez czas działania okna wyszukiwania lub aktywności podczas korzystania z widżetu wyszukiwania. Gdy okno wyszukiwania lub aktywność zostaną ponownie otwarte, „bo” ponownie wysyła zapytanie do dostawcy treści. Wartość domyślna to false (fałsz).

Atrybuty wyszukiwania głosowego

Aby włączyć wyszukiwanie głosowe, musisz mieć niektóre z tych atrybutów <searchable>:


android:voiceSearchMode
Słowo kluczowe (Wymagane do udostępniania funkcji wyszukiwania głosowego). Umożliwia wyszukiwanie głosowe z określonym trybem wyszukiwania głosowego. Wyszukiwanie głosowe może nie być obsługiwane przez urządzenie, w którym to przypadku te flagi nie mają wpływu. Akceptowane są te wartości trybu:
WartośćOpis
"showVoiceSearchButton" Wyświetl przycisk wyszukiwania głosowego, jeśli jest ono dostępne na urządzeniu. Jeśli jest ustawiona, musi być też ustawiona wartość "launchWebSearch" lub "launchRecognizer", rozdzielona znakiem pionowej kreski (|).
"launchWebSearch" Przycisk wyszukiwania głosowego przekierowuje użytkownika bezpośrednio do wbudowanej aktywności wyszukiwania głosowego w internecie. Większość aplikacji nie używa tej flagi, ponieważ powoduje ona opuszczenie przez użytkownika aktywności, w której wywołano wyszukiwanie.
"launchRecognizer" Przycisk wyszukiwania głosowego przekierowuje użytkownika bezpośrednio do wbudowanej funkcji nagrywania głosu. Ta aktywność zachęca użytkownika do mówienia, transkrybuje wypowiedziany tekst i przesyła wynikowe zapytanie do aktywności, w której można wyszukiwać, tak jakby użytkownik wpisał je w interfejsie wyszukiwania i kliknął przycisk wyszukiwania.
android:voiceLanguageModel
Słowo kluczowe Model językowy, który musi być używany przez system rozpoznawania głosu. Akceptowane są te wartości:
WartośćOpis
"free_form" Używaj rozpoznawania mowy w formie swobodnej, aby dyktować zapytania. Jest ona zoptymalizowana głównie pod kątem języka angielskiego. Jest to ustawienie domyślne.
"web_search" Używaj rozpoznawania terminów wyszukiwania w internecie w przypadku krótszych fraz podobnych do wyszukiwanych. Jest ona 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 tekstowy. Dodatkowa wiadomość, która ma się wyświetlać w oknie rozpoznawania mowy.
android:voiceLanguage
Ciąg znaków Oczekiwany język mówiony, wyrażony jako wartość ciągu stałej w Locale, np. "de" w przypadku języka niemieckiego lub "fr" w przypadku języka francuskiego. Jest to wymagane tylko wtedy, gdy różni się od bieżącej wartości Locale.getDefault().
android:voiceMaxResults
Liczba całkowita Ustawia maksymalną liczbę wyników do zwrócenia, w tym „najlepszy” wynik, który jest zawsze podawany jako główne zapytanie intencji.ACTION_SEARCH Musi wynosić co najmniej 1. Użyj EXTRA_RESULTS , aby uzyskać wyniki z intencji. Jeśli nie zostanie podana, rozpoznawanie wybierze, ile wyników ma zwrócić.
<actionkey>
Określa klucz urządzenia i zachowanie w przypadku działania wyszukiwania. Działanie wyszukiwania zapewnia specjalne zachowanie po kliknięciu 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 rozpoczęcie połączenia telefonicznego z aktualnie wybraną sugestią kontaktu po kliknięciu przycisku POŁĄCZ.

Nie wszystkie klawisze działania są dostępne na każdym urządzeniu i nie wszystkie klawisze można w ten sposób zastąpić. Na przykład klawisza „Home” nie można zastąpić i musi on zawsze wracać do ekranu głównego. Nie definiuj też klawisza działania dla klawisza, który jest potrzebny do wpisywania zapytania. Ogranicza to dostępne i rozsądne klawisze działania do przycisku połączenia i przycisku menu.

Aby zdefiniować klucz, musisz określić atrybut android:keycode, a aby zdefiniować działanie wyszukiwania, musisz określić co najmniej 1 z pozostałych 3 atrybutów.

Atrybuty:

android:keycode
Ciąg znaków (Wymagane) Kod klucza z KeyEvent, który reprezentuje klawisz działania, na który chcesz reagować, np. "KEYCODE_CALL". Ten element jest dodawany do ACTION_SEARCHintencji przekazywanej do aktywności, w której można wyszukiwać. Aby sprawdzić kod klucza, użyj getIntExtra(SearchManager.ACTION_KEY). Nie wszystkie klawisze są obsługiwane w przypadku działania wyszukiwania, ponieważ wiele z nich służy do pisania, nawigacji lub funkcji systemowych.
android:queryActionMsg
Ciąg znaków Wiadomość z działaniem, która ma zostać wysłana, jeśli podczas wpisywania tekstu zapytania przez użytkownika zostanie naciśnięty klawisz działania. Jest on dodawany do intencji ACTION_SEARCH, którą system przekazuje do Twojej aktywności z możliwością wyszukiwania. Aby sprawdzić ciąg znaków, użyj getStringExtra(SearchManager.ACTION_MSG).
android:suggestActionMsg
Ciąg znaków Wiadomość z działaniem, która ma zostać wysłana, jeśli klawisz działania zostanie naciśnięty, gdy sugestia jest aktywna. Jest on dodawany do intencji, którą system przekazuje do aktywności z możliwością wyszukiwania, używając działania zdefiniowanego przez Ciebie na potrzeby sugestii. Aby sprawdzić ciąg znaków, użyj getStringExtra(SearchManager.ACTION_MSG). Tej opcji należy używać tylko wtedy, gdy wszystkie sugestie obsługują ten klawisz działania. Jeśli nie wszystkie sugestie mogą obsługiwać ten sam klucz działania, musisz zamiast tego użyć atrybutu android:suggestActionMsgColumn.
android:suggestActionMsgColumn
Ciąg znaków Nazwa kolumny w Twoim dostawcy treści, która określa komunikat działania dla tego klucza działania. Komunikat ten ma być wysyłany, gdy użytkownik naciśnie klawisz działania, gdy sugestia jest aktywna. Ten atrybut umożliwia kontrolowanie klucza działania w przypadku poszczególnych sugestii, ponieważ zamiast używać atrybutu android:suggestActionMsg do zdefiniowania komunikatu działania dla wszystkich sugestii każdy wpis dostawcy treści zawiera własny komunikat działania.

Najpierw musisz zdefiniować w swoim pliku danych kolumnę dla każdej sugestii, dla której chcesz podać wiadomość o działaniu, a potem podać nazwę tej kolumny w tym atrybucie. System sprawdza położenie kursora sugestii, używając podanego tu ciągu znaków, aby wybrać kolumnę wiadomości o działaniu, a następnie wybiera ciąg znaków wiadomości o działaniu z kursora. Ten ciąg znaków jest dodawany do intencji, którą system przekazuje do Twojej aktywności z możliwością wyszukiwania, przy użyciu działania zdefiniowanego przez Ciebie na potrzeby sugestii. Aby sprawdzić ciąg znaków, użyj getStringExtra(SearchManager.ACTION_MSG). Jeśli dane nie istnieją w przypadku wybranej sugestii, klucz działania jest ignorowany.

przykład:
Plik XML zapisany w lokalizacji 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>