Konfiguracja wyszukiwania

Wypróbuj metodę 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>

elements:

<searchable>

Określa wszystkie konfiguracje wyszukiwania używane przez system Android do wspomagania wyszukiwania.

Atrybuty:

android:label

Zasób tekstowy. (opcja wymagana). Nazwa 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 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 być wyświetlany 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ść lub produkt>”. 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 tekst zapytania ma być przepisywany, 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 może 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 zmienić 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 wyświetla 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ć dostarczanie tekstu zapytania za pomocą parametru selectionArgs, a następnie zignorować parametr selection).

android:searchSuggestIntentAction

Ciąg znaków Domyślne działanie 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ę 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ę w kolumnie 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 oknie szybkiego wyszukiwania, musisz podać niektóre z tych atrybutów:<searchable>

android:includeInGlobalSearch

Wartość logiczna. (Wymagane do wyświetlania sugestii wyszukiwania w oknie szybkiego wyszukiwania). Ustaw na "true", jeśli chcesz, aby Twoje sugestie były uwzględniane w globalnie dostępnym oknie szybkiego wyszukiwania. Zanim sugestie zaczną się pojawiać w oknie szybkiego 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 okna 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 ustawisz wartość "false", nadzbiory będą ignorowane w przypadku pojedynczej sesji – zapytanie „bob” nie spowoduje ponownego wysłania zapytania. Trwa to tylko przez czas działania okna wyszukiwania lub aktywności podczas korzystania z widżetu wyszukiwania. Gdy okno dialogowe wyszukiwania lub aktywność zostaną ponownie otwarte, usługa „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 podać 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 ten parametr jest ustawiony, należy też ustawić parametr "launchWebSearch" lub "launchRecognizer", rozdzielając je 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ż odciąga ona użytkownika od 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 wynikowy tekst zapytania do aktywności, w której można wyszukiwać, tak jakby użytkownik wpisał go 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 wyszukiwarki internetowej 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 tekstowego stałej w Locale, np. "de" dla języka niemieckiego lub "fr" dla 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 do obsługi kontaktów udostępnia działanie wyszukiwania, które umożliwia nawiązanie połączenia telefonicznego z aktualnie wybraną sugestią kontaktu po kliknięciu przycisku ZADZWOŃ.

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 (opcja wymagana). Kod klawisza 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 podczas ustawienia fokusu na sugestii zostanie naciśnięty klawisz działania. Jest on dodawany do intencji, którą system przekazuje do aktywności z możliwością wyszukiwania, używając działania zdefiniowanego dla sugestii. Aby sprawdzić ciąg znaków, użyj funkcji getStringExtra(SearchManager.ACTION_MSG). Możesz użyć tej opcji tylko wtedy, gdy wszystkie Twoje sugestie obsługują ten klawisz działania. Jeśli nie wszystkie sugestie mogą obsługiwać ten sam klawisz 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 wiadomość o działaniu dla tego klucza działania. Wiadomość ta ma być wysyłana, gdy użytkownik naciśnie klawisz działania, gdy sugestia jest aktywna. Ten atrybut umożliwia kontrolowanie klawisza działania w przypadku poszczególnych sugestii, ponieważ zamiast używać atrybutu android:suggestActionMsg do definiowania 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 dostawcy treści kolumnę dla każdej sugestii, dla której chcesz podać wiadomość o działaniu, a następnie podać nazwę tej kolumny w tym atrybucie. System sprawdza kursor 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 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, klawisz 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>