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

Чтобы реализовать поиск с помощью системы 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 как «Поиск <content-or-product> ». Например, «Поиск песен и исполнителей» или «Поиск на 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=?" . Однако вы также можете использовать любое значение, отличное от NULL, чтобы инициировать доставку текста запроса с помощью параметра 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» снова запрашивает вашего контент-провайдера. Значение по умолчанию — ложь.

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

Чтобы включить голосовой поиск, вам потребуются некоторые из следующих атрибутов <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>
Определяет ключ устройства и поведение для действия поиска. Действие поиска обеспечивает особое поведение при нажатии кнопки на устройстве в зависимости от текущего запроса или конкретного предложения. Например, приложение «Контакты» предоставляет действие поиска, позволяющее инициировать телефонный звонок по предложенному в данный момент контакту при нажатии кнопки «ЗВОНОК».

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

Вы должны определить 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>