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

Попробуйте способ «Композиции»

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

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

android:hint

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

android:searchMode

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

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

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

android:searchButtonText

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

android:inputType

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

android:imeOptions

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

Атрибуты поисковых предложений

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

android:searchSuggestAuthority

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

android:searchSuggestPath

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

android:searchSuggestSelection

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

android:searchSuggestIntentAction

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

android:searchSuggestIntentData

String . Данные намерения по умолчанию, которые будут использоваться при нажатии пользователем на пользовательскую поисковую подсказку. Если это значение не переопределено выбранной подсказкой (через столбец 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

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

android:voiceMaxResults

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

<actionkey>

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

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

Необходимо определить android:keycode для определения клавиши и по крайней мере один из трех других атрибутов для определения действия поиска.

Атрибуты:

android:keycode

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

android:queryActionMsg

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

android:suggestActionMsg

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

android:suggestActionMsgColumn

String . Имя столбца в вашем поставщике контента, определяющего сообщение о действии для этой клавиши, которое будет отправлено, если пользователь нажмёт клавишу действия, когда предложение находится в фокусе. Этот атрибут позволяет управлять клавишей действия для каждого предложения, поскольку вместо использования атрибута 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>