Поиск конфигурации

Попробуйте способ создания композиций.

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

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

Для реализации поиска с помощью системы Android — то есть для отправки поисковых запросов в активность и предоставления поисковых подсказок — ваше приложение должно предоставить конфигурацию поиска в виде 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>

элементы:

<searchable>

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

Атрибуты:

android:label

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

android:hint

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

android:searchMode

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

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

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

android:searchButtonText

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

android:inputType

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

android:imeOptions

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

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

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

android:searchSuggestAuthority

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

android:searchSuggestPath

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

android:searchSuggestSelection

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

android:searchSuggestIntentAction

Строка . Действие по умолчанию для Intent, используемое при нажатии пользователем на пользовательское подсказку поиска, например, "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

Ресурс типа String . Дополнительное сообщение для отображения в диалоговом окне голосового ввода.

android:voiceLanguage

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

android:voiceMaxResults

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

<actionkey>

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

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

Для определения клавиши необходимо указать атрибут 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>