Конфигурация поиска

Попробуйте Compose

Jetpack Compose – это рекомендуемый набор инструментов для создания пользовательского интерфейса в Android. Узнайте, как добавить функцию поиска в Compose.

Строка поиска →

Чтобы реализовать поиск с помощью системы Android, то есть передавать поисковые запросы в объект activity и предоставлять подсказки при поиске, ваше приложение должно содержать конфигурацию поиска в виде XML-файла.

На этой странице описаны синтаксис и использование файла конфигурации поиска. Подробнее о том, как реализовать функции в результатах поиска для вашего приложения, см. Создание интерфейса поиска.

местоположение файла;

res/xml/filename.xml
Android использует название файла в качестве идентификатора ресурса.

Синтаксис:

<?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>

Определяет все конфигурации поиска, используемые системой Android для предоставления вспомогательного поиска.

Атрибуты:

android:label

Строковый ресурс. Это обязательная кнопка. Название приложения. Оно должно совпадать с названием, указанным в атрибуте android:label элемента манифеста <activity> или <application>. Этот ярлык виден пользователю, только если для параметра android:includeInGlobalSearch задано значение "true". В этом случае ярлык используется для идентификации вашего приложения как объекта, доступного для поиска в настройках поиска системы.

android:hint

Строковый ресурс. (рекомендуется). Текст, который будет показываться в поле поиска, когда в нем ничего не введено. Она подсказывает пользователю, какой контент можно найти. Для согласованности с другими приложениями для Android отформатируйте строку для android:hint как "Поиск <контент-или-продукт>". Например, "Поиск песен и исполнителей" или "Поиск на YouTube".

android:searchMode

Ключевое слово. Задает дополнительные режимы, управляющие представлением результатов поиска. Доступные режимы определяют, как должен быть переписан текст запроса, когда пользователь выбирает собственную подсказку. Допустимые значения:

Значение	Описание
"queryRewriteFromData"	Используйте значение из столбца SUGGEST_COLUMN_INTENT_DATA, чтобы переписать текст запроса. Используйте этот атрибут, только если значения в SUGGEST_COLUMN_INTENT_DATA подходят для просмотра и редактирования пользователем, например являются URI HTTP.
"queryRewriteFromText"	Используйте значение из столбца SUGGEST_COLUMN_TEXT_1, чтобы переписать текст запроса.

Дополнительную информацию вы найдете в статье Как добавить собственные подсказки при поиске.

android:searchButtonText

Строковый ресурс. Текст, который будет показываться на кнопке, запускающей поиск. По умолчанию на кнопке показывается значок поиска (лупа), который подходит для всех языков. Поэтому не используйте этот атрибут для изменения кнопки, если только поведение не является чем-то иным, кроме поиска, например запросом URL в веб-браузере.

android:inputType

Ключевое слово. Определяет тип метода ввода, например тип экранной клавиатуры. Для большинства поисковых запросов, в которых ожидается текст в свободной форме, этот атрибут не нужен. Список допустимых значений атрибута приведен в inputType.

android:imeOptions

Ключевое слово. Предоставляет дополнительные параметры для способа ввода. Для большинства поисковых запросов, в которых ожидается текст в свободной форме, этот атрибут не нужен. По умолчанию используется IME actionSearch, который добавляет на экранную клавиатуру кнопку поиска вместо символа возврата каретки. Список допустимых значений атрибута приведен в imeOptions.

Атрибуты подсказок при поиске

Если вы определяете поставщика контента для создания подсказок при поиске, вам нужно определить дополнительные атрибуты, которые настраивают связь с поставщиком контента. Чтобы показывать подсказки при поиске, вам понадобятся некоторые из следующих атрибутов <searchable>:

android:searchSuggestAuthority

Строка. (необходимо для показа подсказок при поиске). Это значение должно совпадать со строкой, указанной в атрибуте android:authorities элемента <provider> манифеста Android.

android:searchSuggestPath

Строка. Этот путь используется как часть запроса подсказок Uri после префикса и источника и перед стандартным путем подсказок. Это необходимо, только если у вас есть один поставщик контента, который выдает разные типы подсказок (например, для разных типов данных), и вам нужно различать запросы подсказок при их получении.

android:searchSuggestSelection

Строка. Это значение передается в функцию запроса в качестве параметра selection. Обычно это предложение WHERE для базы данных, которое должно содержать один вопросительный знак в качестве заполнителя для фактической строки запроса, введенной пользователем, например "query=?". Однако вы можете использовать любое ненулевое значение, чтобы инициировать передачу текста запроса с помощью параметра selectionArgs, а затем игнорировать параметр selection.

android:searchSuggestIntentAction

Строка. Действие по умолчанию, которое выполняется, когда пользователь нажимает на подсказку при поиске, например "android.intent.action.VIEW". Если это значение не переопределено выбранной подсказкой с помощью столбца SUGGEST_COLUMN_INTENT_ACTION, оно помещается в поле действия Intent, когда пользователь нажимает на подсказку.

android:searchSuggestIntentData

Строка. Данные о намерении по умолчанию, которые будут использоваться, когда пользователь нажимает на подсказку при поиске. Если значение не переопределено выбранной подсказкой (через столбец SUGGEST_COLUMN_INTENT_DATA), оно помещается в поле данных Intent, когда пользователь нажимает на подсказку.

android:searchSuggestThreshold

Целое число. Минимальное количество символов, необходимое для запуска поиска подсказок. Это лишь гарантирует, что система не будет запрашивать у поставщика контента данные за период, который меньше порогового значения. Значение по умолчанию – 0.

Дополнительную информацию об атрибутах для подсказок при поиске можно найти в документации по добавлению специальных подсказок при поиске и добавлению специальных подсказок.

Атрибуты окна быстрого поиска

Чтобы ваши подсказки при поиске были доступны в окне быстрого поиска, вам понадобятся некоторые из следующих атрибутов <searchable>:

android:includeInGlobalSearch

Логическое значение. (Требуется для предоставления подсказок при поиске в окне быстрого поиска.) Установите значение "true", если хотите, чтобы подсказки включались в окно быстрого поиска, доступное на всех экранах. Чтобы подсказки из вашего приложения появились в окне быстрого поиска, пользователь должен включить его в настройках системного поиска.

android:searchSettingsDescription

Строковый ресурс. Краткое описание подсказок при поиске, которые вы предоставляете окну быстрого поиска. Оно показывается в записи о вашем приложении в списке объектов, по которым выполняется поиск. Описание должно кратко характеризовать контент, доступный для поиска. Например, "Исполнители, альбомы и треки" для музыкального приложения или "Сохраненные заметки" для блокнота.

android:queryAfterZeroResults

Логическое значение. Установите значение "true", если хотите, чтобы поставщик контента вызывался для супернаборов запросов, которые ранее не возвращали результатов. Например, если поставщик контента не возвращает результатов по запросу "bo", необходимо выполнить повторный запрос по слову "bob". Если задано значение "false", суперсеты игнорируются в рамках одного сеанса, то есть запрос "bob" не вызывает повторный запрос. Они сохраняются только до закрытия диалогового окна поиска или до завершения действия при использовании виджета поиска. При повторном открытии диалогового окна или действия поиска "bo" снова запрашивает данные у поставщика контента. Значение по умолчанию – false.

Атрибуты голосового поиска

Чтобы включить голосовой поиск, вам понадобятся некоторые из следующих атрибутов <searchable>:

android:voiceSearchMode

Ключевое слово. (необходимо для голосового поиска). Включает голосовой поиск и специальный режим для него. Если устройство не поддерживает голосовой поиск, эти флаги не будут работать. Допустимые значения:

Значение	Описание
"showVoiceSearchButton"	Показывать кнопку голосового поиска, если он доступен на устройстве. Если задан этот параметр, то также должен быть задан параметр "launchWebSearch" или "launchRecognizer". Они должны быть разделены вертикальной чертой (|).
"launchWebSearch"	Кнопка голосового поиска перенаправляет пользователя непосредственно к встроенной функции голосового поиска в интернете. Большинство приложений не используют этот флаг, так как он уводит пользователя от действия, в котором был вызван поиск.
"launchRecognizer"	Кнопка голосового поиска перенаправляет пользователя непосредственно к встроенной функции записи голоса. Это действие предлагает пользователю сказать что-нибудь, преобразует речь в текст и передает полученный текст запроса в действие с возможностью поиска, как если бы пользователь ввел его в интерфейсе поиска и нажал кнопку поиска.

android:voiceLanguageModel

Ключевое слово. Языковая модель, которую должна использовать система распознавания речи. Допустимые значения:

Значение	Описание
"free_form"	Используйте свободное распознавание речи для диктовки запросов. В основном она оптимизирована для английского языка. Это значение используется по умолчанию.
"web_search"	Используйте распознавание поисковых запросов для коротких фраз, похожих на запросы. Она доступна на большем количестве языков, чем "free_form".

Подробнее: EXTRA_LANGUAGE_MODEL.

android:voicePromptText

Строковый ресурс. Дополнительное сообщение, которое будет показываться в диалоговом окне голосового ввода.

android:voiceLanguage

Строка. Ожидаемый язык, выраженный в виде строкового значения константы в Locale, например "de" для немецкого или "fr" для французского. Это необходимо, только если оно отличается от текущего значения Locale.getDefault().

android:voiceMaxResults

Целое число. Задает максимальное количество результатов, включая "лучший", который всегда возвращается как основной запрос намерения ACTION_SEARCH. Значение должно быть не меньше 1. Используйте EXTRA_RESULTS, чтобы получить результаты из намерения. Если значение не указано, распознаватель сам выбирает, сколько результатов вернуть.

<actionkey>

Определяет клавишу устройства и действие, которое выполняется при ее нажатии. Действие поиска – это специальное поведение, которое запускается нажатием кнопки на устройстве и зависит от текущего запроса или выбранной подсказки. Например, приложение "Контакты" предоставляет действие поиска, которое позволяет позвонить выбранному контакту, нажав кнопку "Вызов".

Не все клавиши действий доступны на каждом устройстве, и не все клавиши можно переназначить таким образом. Например, клавиша Home всегда должна возвращать пользователя на главный экран. Также не назначайте клавишу действия, которая используется для ввода поискового запроса. Это ограничивает доступные и разумные клавиши действий кнопкой вызова и кнопкой меню.

Чтобы задать ключ, необходимо определить атрибут android:keycode, а чтобы задать действие поиска – хотя бы один из трех других атрибутов.

Атрибуты:

android:keycode

Строка. Это обязательная кнопка. Код клавиши из KeyEvent, который представляет клавишу действия, на которую вы хотите ответить, например "KEYCODE_CALL". Это значение добавляется к намерению ACTION_SEARCH, которое передается в действие с возможностью поиска. Чтобы проверить код клавиши, используйте getIntExtra(SearchManager.ACTION_KEY). Не все клавиши поддерживаются для поиска, так как многие из них используются для ввода текста, навигации или системных функций.

android:queryActionMsg

Строка. Сообщение о действии, которое отправляется, если пользователь нажимает клавишу действия при вводе текста запроса. Она добавляется к намерению ACTION_SEARCH, которое система передает в действие с возможностью поиска. Для проверки строки используйте getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

Строка. Сообщение о действии, которое будет отправлено, если нажать клавишу действия, когда подсказка находится в фокусе. Оно добавляется к намерению, которое система передает в ваше действие с возможностью поиска, используя действие, которое вы определяете для подсказки. Чтобы проверить строку, используйте getStringExtra(SearchManager.ACTION_MSG). Используйте его, только если все ваши подсказки поддерживают эту клавишу действия. Если не все подсказки могут обрабатывать одну и ту же клавишу действия, используйте атрибут android:suggestActionMsgColumn.

android:suggestActionMsgColumn

Строка. Название столбца в поставщике контента, который определяет сообщение о действии для этой клавиши действия. Оно отправляется, если пользователь нажимает клавишу действия, когда подсказка находится в фокусе. Этот атрибут позволяет управлять клавишей действия для каждой подсказки отдельно, поскольку вместо использования атрибута android:suggestActionMsg для определения сообщения о действии для всех подсказок каждая запись в поставщике контента предоставляет собственное сообщение о действии.

Сначала необходимо определить столбец в поставщике контента для каждой подсказки, для которой нужно предоставить сообщение о действии, а затем указать имя этого столбца в этом атрибуте. Система просматривает курсор подсказки, используя указанную здесь строку, чтобы выбрать столбец сообщения о действии, а затем выбирает строку сообщения о действии из курсора. Эта строка добавляется к намерению, которое система передает в ваше действие с возможностью поиска, используя действие, которое вы определяете для подсказок. Чтобы проверить строку, используйте getStringExtra(SearchManager.ACTION_MSG). Если для выбранной подсказки нет данных, клавиша действия игнорируется.

пример:

XML-файл сохранен в 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>