Добавить предложения пользовательского поиска

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

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

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

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

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

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

Основы

Рисунок 1. Скриншот диалогового окна поиска с пользовательскими подсказками.

Когда пользователь выбирает пользовательское предложение, система отправляет Intent в вашу поисковую активность. В отличие от обычного поискового запроса, который отправляет Intent с действием ACTION_SEARCH , вы можете определить свои пользовательские предложения, используя ACTION_VIEW — или любое другое действие Intent — и также включить данные, относящиеся к выбранному предложению. В примере со словарем, когда пользователь выбирает предложение, приложение может немедленно открыть определение этого слова, вместо того чтобы искать совпадения в словаре.

Для предоставления индивидуальных рекомендаций выполните следующие действия:

• Реализуйте базовую функцию поиска, как описано в разделе «Создание интерфейса поиска» .
• Измените конфигурацию поиска, указав информацию о поставщике контента, предоставляющем пользовательские подсказки.
• Создайте таблицу, например, в SQLiteDatabase , для ваших предложений и отформатируйте ее, добавив необходимые столбцы.
• Создайте поставщика контента , имеющего доступ к вашей таблице предложений, и укажите его в манифесте.
• Укажите тип Intent , который будет отправлен, когда пользователь выберет подсказку, включая пользовательское действие и пользовательские данные.

Подобно тому, как система Android отображает диалоговое окно поиска, она также отображает ваши поисковые подсказки. Вам нужен поставщик контента, от которого система сможет получать ваши подсказки. Прочитайте раздел «Поставщики контента» , чтобы узнать, как создать поставщика контента.

Когда система определяет, что ваша активность доступна для поиска, и предоставляет поисковые подсказки, при вводе пользователем поискового запроса происходит следующая процедура:

1. Система принимает текст поискового запроса — то есть, все, что было введено до сих пор, — и отправляет запрос вашему поставщику контента, который управляет вашими предложениями.
2. Ваш поставщик контента возвращает Cursor , указывающий на все подсказки, релевантные тексту поискового запроса.
3. Система отображает список подсказок, предоставленных Cursor .

После отображения пользовательских подсказок может произойти следующее:

• Если пользователь вводит другую букву или каким-либо образом изменяет запрос, описанные выше шаги повторяются, и список подсказок обновляется соответствующим образом.
• Если пользователь выполняет поиск, предложенные варианты игнорируются, и поиск передается в ваше поисковое окно с помощью обычного интента ACTION_SEARCH .
• Если пользователь выбирает предложенный вариант, в вашу поисковую активность отправляется намерение, содержащее пользовательское действие и пользовательские данные, чтобы ваше приложение могло открыть предложенный контент.

Измените конфигурацию поиска.

Чтобы добавить поддержку пользовательских подсказок, добавьте атрибут android:searchSuggestAuthority к элементу <searchable> в файле конфигурации поиска, как показано в следующем примере:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

В зависимости от типа намерения, которое вы приписываете каждому предложению, и от того, как вы хотите форматировать запросы к вашему поставщику контента, вам могут потребоваться дополнительные атрибуты. Другие необязательные атрибуты обсуждаются в следующих разделах.

Создайте поставщика контента.

Чтобы создать поставщика контента для пользовательских подсказок, сначала ознакомьтесь с разделом «Поставщики контента» , чтобы узнать, как это сделать. Поставщик контента для пользовательских подсказок аналогичен любому другому поставщику контента. Однако для каждой предоставленной вами подсказки соответствующая строка в Cursor должна содержать определенные столбцы, которые система понимает и использует для форматирования подсказок.

Когда пользователь вводит текст в диалоговое окно поиска или виджет поиска, система запрашивает у вашего поставщика контента подсказки, вызывая query() каждый раз, когда вводится буква. В вашей реализации метода query() ваш поставщик контента должен выполнить поиск в данных подсказок и вернуть Cursor , указывающий на строки, которые он считает подходящими подсказками.

Подробности о создании поставщика контента для пользовательских подсказок обсуждаются в следующих двух разделах:

Обработайте запрос на предложение.

Как система отправляет запросы вашему поставщику контента и как их обрабатывает.

Создайте таблицу предложений.

Как определить столбцы, которые система ожидает увидеть в Cursor , возвращаемом каждым запросом?

Обработайте запрос на предложение.

Когда система запрашивает подсказки у вашего поставщика контента, она вызывает метод query() вашего поставщика контента. Реализуйте этот метод для поиска в данных подсказок и возврата Cursor , указывающего на подсказки, которые вы считаете релевантными.

Ниже приведено краткое описание параметров, которые система передает вашему методу query() , в порядке их перечисления:

uri

Всегда Uri содержимого, отформатированный следующим образом:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

По умолчанию система передает этот URI и добавляет к нему текст запроса:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

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

Часть optional.suggest.path включается в URI только в том случае, если вы задали такой путь в файле конфигурации поиска с помощью атрибута android:searchSuggestPath . Это необходимо только в том случае, если вы используете один и тот же поставщик контента для нескольких действий с возможностью поиска. В этом случае необходимо уточнить источник запроса подсказок.

projection

Всегда пусто.

selection

Значение, указанное в атрибуте android:searchSuggestSelection вашего файла конфигурации поиска, или null, если вы не указываете атрибут android:searchSuggestSelection . В следующем разделе это будет рассмотрено подробнее.

selectionArgs

Если в конфигурации поиска указан атрибут android:searchSuggestSelection этот параметр содержит поисковый запрос в качестве первого и единственного элемента массива. Если же атрибут android:searchSuggestSelection не указан, этот параметр имеет значение null. Более подробно это рассматривается в следующем разделе.

sortOrder

Всегда пусто.

Система может отправлять вам текст поискового запроса двумя способами. По умолчанию текст запроса включается в качестве последнего пути URI контента, переданного в параметре uri . Однако, если вы укажете значение выбора в атрибуте android:searchSuggestSelection вашей конфигурации поиска, то текст запроса будет передаваться в качестве первого элемента строкового массива selectionArgs . Эти два варианта описаны далее.

Получите запрос по URI.

По умолчанию запрос добавляется в качестве последнего сегмента параметра uri — объекта Uri . Чтобы получить текст запроса в этом случае, используйте getLastPathSegment() , как показано в следующем примере:

val query: String = uri.lastPathSegment.toLowerCase()

String query = uri.getLastPathSegment().toLowerCase();

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

Получите запрос в аргументах выбора.

Вместо использования URI, возможно, будет целесообразнее, чтобы ваш метод query() получал все необходимые данные для выполнения поиска, и вам может потребоваться, чтобы параметры selection и selectionArgs содержали соответствующие значения. В этом случае добавьте атрибут android:searchSuggestSelection в конфигурацию поиска с вашей строкой выбора SQLite. В строке выбора укажите вопросительный знак ( ? ) в качестве заполнителя для фактического поискового запроса. Система вызывает query() со строкой выбора в качестве параметра selection и поисковым запросом в качестве первого элемента массива selectionArgs .

Например, вот как можно сформировать атрибут android:searchSuggestSelection для создания запроса полнотекстового поиска:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

При такой конфигурации ваш метод query() передает параметр selection в виде "word MATCH ?" , а параметр selectionArgs в виде поискового запроса. Когда вы передаете их в метод SQLite query() в качестве соответствующих аргументов, они объединяются — то есть вопросительный знак заменяется текстом запроса. Если вы получаете запросы с подсказками таким образом и вам нужно добавить подстановочные знаки к тексту запроса, добавьте или укажите их в префиксе к параметру selectionArgs , поскольку это значение заключается в кавычки и вставляется вместо вопросительного знака.

В приведенном выше примере еще одним атрибутом является android:searchSuggestIntentAction , который определяет действие, отправляемое с каждым интентом, когда пользователь выбирает подсказку. Это более подробно обсуждается в разделе «Объявление интента для подсказок» .

Создайте таблицу предложений.

Когда вы возвращаете системе подсказки с помощью Cursor , система ожидает определенные столбцы в каждой строке. Независимо от того, храните ли вы данные подсказок в базе данных SQLite на устройстве, в базе данных на веб-сервере или в другом формате на устройстве или в сети, отформатируйте подсказки в виде строк таблицы и отобразите их с помощью Cursor .

Система распознает несколько столбцов, но обязательными являются только два из них:

_ID

Для каждого предложения присваивается уникальный целочисленный идентификатор строки. Система требует этого для отображения предложений в ListView ).

SUGGEST_COLUMN_TEXT_1

Строка, которая отображается в качестве подсказки.

Следующие столбцы являются необязательными. Большинство из них более подробно рассмотрены в следующих разделах.

SUGGEST_COLUMN_TEXT_2

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

SUGGEST_COLUMN_ICON_1

URI ресурса, контента или файла, доступного для отображения. Если ваш Cursor включает этот столбец, то все подсказки отображаются в формате «значок плюс текст», при этом значок ресурса находится слева. Это значение может быть равно null или нулю, что означает отсутствие значка в этой строке.

SUGGEST_COLUMN_ICON_2

URI ресурса, контента или файла. Если ваш Cursor содержит этот столбец, то все подсказки отображаются в формате «значок плюс текст», при этом значок находится справа. Это значение может быть равно null или нулю, что означает отсутствие значка в этой строке.

SUGGEST_COLUMN_INTENT_ACTION

Строка действия Intent. Если этот столбец существует и содержит значение в данной строке, то при формировании Intent для подсказки используется определенное здесь действие. Если элемент не указан, действие берется из поля android:searchSuggestIntentAction в вашей конфигурации поиска. Если ваше действие одинаково для всех подсказок, эффективнее указать действие с помощью android:searchSuggestIntentAction и опустить этот столбец.

SUGGEST_COLUMN_INTENT_DATA

URI-строка данных. Если этот столбец существует и содержит значение в данной строке, эти данные используются при формировании намерения для подсказки. Если элемент не указан, данные берутся из поля android:searchSuggestIntentData в вашей конфигурации поиска. Если ни один из источников не указан, поле данных намерения имеет значение null. Если ваши данные одинаковы для всех подсказок или могут быть описаны с помощью постоянной части и конкретного ID, эффективнее указать их с помощью android:searchSuggestIntentData и опустить этот столбец.

SUGGEST_COLUMN_INTENT_DATA_ID

Строковый путь URI. Если этот столбец существует и содержит значение в указанной строке, то "/", и это значение добавляется к полю данных в интенте. Используйте это только в том случае, если поле данных, указанное атрибутом android:searchSuggestIntentData в конфигурации поиска, уже установлено на соответствующую базовую строку.

SUGGEST_COLUMN_INTENT_EXTRA_DATA

Произвольные данные. Если этот столбец существует и содержит значение в данной строке, это дополнительные данные, используемые при формировании намерения подсказки. Если не указано, поле дополнительных данных намерения имеет значение null. Этот столбец позволяет подсказкам предоставлять дополнительные данные, которые включаются в качестве дополнительных данных в ключ EXTRA_DATA_KEY намерения.

SUGGEST_COLUMN_QUERY

Если этот столбец существует и этот элемент присутствует в данной строке, то именно эти данные используются при формировании запроса для подсказки и включаются в качестве дополнительного параметра в ключ QUERY намерения. Это обязательно, если действие подсказки — ACTION_SEARCH , в противном случае — необязательно.

SUGGEST_COLUMN_SHORTCUT_ID

Используется только при предоставлении подсказок для поля быстрого поиска. Этот столбец указывает, должна ли поисковая подсказка сохраняться как ярлык и должна ли она проверяться. Ярлыки обычно формируются, когда пользователь нажимает на подсказку в поле быстрого поиска. Если подсказка отсутствует, результат сохраняется как ярлык и никогда не обновляется. Если установлено значение SUGGEST_NEVER_MAKE_SHORTCUT , результат не сохраняется как ярлык. В противном случае идентификатор ярлыка используется для проверки наличия актуальной подсказки с помощью SUGGEST_URI_PATH_SHORTCUT .

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

Используется только при предоставлении подсказок для поля быстрого поиска. В этом столбце указано, что вместо значка из SUGGEST_COLUMN_ICON_2 должен отображаться индикатор загрузки, пока ярлык этой подсказки обновляется в поле быстрого поиска.

Большинство из этих колонок более подробно рассматриваются в следующих разделах.

Заявить о намерении внести предложения.

Когда пользователь выбирает подсказку из списка, отображаемого под диалоговым окном поиска или виджетом, система отправляет пользовательский Intent в ваше поисковое окно. Вам необходимо определить действие и данные для этого Intent.

Объявить о намерении совершить действие

Наиболее распространенным действием для пользовательского предложения является ACTION_VIEW , что подходит, когда вы хотите открыть что-либо, например, определение слова, контактную информацию человека или веб-страницу. Однако действие может быть любым другим и отличаться для каждого предложения.

В зависимости от того, хотите ли вы, чтобы все предложения использовали одно и то же действие намерения, вы можете определить это действие двумя способами:

• Используйте атрибут android:searchSuggestIntentAction в файле конфигурации поиска, чтобы определить действие для всех подсказок, как показано в следующем примере:

  <?xml version="1.0" encoding="utf-8"?>
  <searchable xmlns:android="http://schemas.android.com/apk/res/android"
      android:label="@string/app_label"
      android:hint="@string/search_hint"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW" >
  </searchable>

• Используйте столбец SUGGEST_COLUMN_INTENT_ACTION для определения действия для отдельных подсказок. Для этого добавьте столбец SUGGEST_COLUMN_INTENT_ACTION в таблицу подсказок и для каждой подсказки укажите используемое действие, например, "android.intent.action.VIEW" .

Вы также можете комбинировать эти два метода. Например, вы можете добавить атрибут android:searchSuggestIntentAction с действием, которое будет использоваться со всеми подсказками по умолчанию, а затем переопределить это действие для некоторых подсказок, указав другое действие в столбце SUGGEST_COLUMN_INTENT_ACTION . Если вы не укажете значение в столбце SUGGEST_COLUMN_INTENT_ACTION , будет использоваться намерение, указанное в атрибуте android:searchSuggestIntentAction .

Объявить данные о намерениях

Когда пользователь выбирает подсказку, ваша поисковая активность получает интент с определенным вами действием — как обсуждалось в предыдущем разделе, — но интент также должен содержать данные, чтобы ваша активность могла идентифицировать, какая подсказка выбрана. В частности, данные должны быть уникальными для каждой подсказки, например, идентификатор строки подсказки в вашей таблице SQLite. После получения интента вы можете получить прикрепленные данные с помощью getData() или getDataString() .

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

• Укажите данные для каждого предложения в столбце SUGGEST_COLUMN_INTENT_DATA вашей таблицы предложений.

  Предоставьте всю необходимую информацию для каждого намерения в таблице предложений, включив столбец SUGGEST_COLUMN_INTENT_DATA и заполнив его уникальными данными для каждой строки. Данные из этого столбца прикрепляются к намерению точно так, как вы его определяете в этом столбце. Затем вы можете получить их с помощью getData() или getDataString() .

• Разделите URI данных на две части: часть, общую для всех предложений, и часть, уникальную для каждого предложения. Поместите эти части в атрибут android:searchSuggestintentData конфигурации поиска и в столбец SUGGEST_COLUMN_INTENT_DATA_ID вашей таблицы предложений соответственно.

  В следующем примере показано, как объявить часть URI, общую для всех подсказок, в атрибуте android:searchSuggestIntentData вашей конфигурации поиска:

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:searchSuggestIntentData="content://com.example/datatable" >
    </searchable>
    

  Включите конечный путь для каждого предложения — уникальную часть — в столбец SUGGEST_COLUMN_INTENT_DATA_ID вашей таблицы предложений. Когда пользователь выбирает предложение, система берет строку из android:searchSuggestIntentData , добавляет косую черту ( / ), а затем добавляет соответствующее значение из столбца SUGGEST_COLUMN_INTENT_DATA_ID , чтобы сформировать полный URI контента. Затем вы можете получить Uri с помощью getData() .

Добавить больше данных

Если вам необходимо предоставить больше информации о вашем намерении, вы можете добавить еще один столбец таблицы, например SUGGEST_COLUMN_INTENT_EXTRA_DATA , который может хранить дополнительную информацию о предложении. Данные, сохраненные в этом столбце, помещаются в EXTRA_DATA_KEY дополнительного пакета намерения.

Обработайте намерение

После предоставления пользовательских поисковых подсказок с пользовательскими интентами, вашему поисковому действию необходимо обрабатывать эти интенты, когда пользователь выбирает подсказку. Это необходимо в дополнение к обработке интента ACTION_SEARCH , которую ваше поисковое действие уже обрабатывает. Вот пример того, как можно обрабатывать интенты во время вызова onCreate() вашего действия:

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

В этом примере действие намерения — ACTION_VIEW , а данные содержат полный URI, указывающий на предлагаемый элемент, синтезированный строкой android:searchSuggestIntentData и столбцом SUGGEST_COLUMN_INTENT_DATA_ID . Затем URI передается локальному методу showResult() , который запрашивает у поставщика контента элемент, указанный в URI.

Перепишите текст запроса

По умолчанию, если пользователь перемещается по списку подсказок с помощью элементов управления направлением, например, трекбола или D-pad, текст запроса не обновляется. Однако вы можете временно заменить текст запроса пользователя, отображаемый в текстовом поле, на запрос, соответствующий текущей подсказке. Это позволит пользователю увидеть предлагаемый запрос, выбрать поле поиска и отредактировать запрос перед отправкой его на поиск.

Текст запроса можно переписать следующими способами:

• Добавьте атрибут android:searchMode в конфигурацию поиска со значением "queryRewriteFromText" . В этом случае для перезаписи текста запроса будет использоваться содержимое столбца SUGGEST_COLUMN_TEXT_1 в подсказке.
• Добавьте атрибут android:searchMode в конфигурацию searchable\ со значением "queryRewriteFromData" . В этом случае для перезаписи текста запроса будет использоваться содержимое столбца SUGGEST_COLUMN_INTENT_DATA подсказки. Используйте это только с URI или другими форматами данных, предназначенными для отображения пользователю, например, HTTP-адресами. Не используйте внутренние схемы URI для перезаписи запроса таким образом.
• Укажите уникальную строку запроса в столбце SUGGEST_COLUMN_QUERY вашей таблицы предложений. Если этот столбец присутствует и содержит значение для текущего предложения, он используется для перезаписи текста запроса и переопределения одной из предыдущих реализаций.

Отображать поисковые подсказки в поле быстрого поиска

После настройки приложения для предоставления пользовательских поисковых подсказок, сделать их доступными для глобально доступного поля быстрого поиска так же просто, как изменить конфигурацию поиска, добавив в нее параметр android:includeInGlobalSearch со значением "true" .

Дополнительную работу необходимо выполнить только в том случае, если ваш поставщик контента запрашивает разрешение на чтение. В этом случае вам нужно добавить элемент <path-permission> , чтобы поставщик предоставил вашему поставщику контента доступ на чтение к полю быстрого поиска, как показано в следующем примере:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

В этом примере поставщик контента ограничивает доступ на чтение и запись к содержимому. Элемент <path-permission> изменяет это ограничение, предоставляя доступ на чтение к содержимому внутри префикса пути "/search_suggest_query" если существует разрешение "android.permission.GLOBAL_SEARCH" . Это предоставляет доступ к полю быстрого поиска, позволяя ему запрашивать у вашего поставщика контента подсказки.

Если ваш поставщик контента не устанавливает права на чтение, то Quick Search Box будет читать его по умолчанию.

Включить подсказки на устройстве

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

Каждое приложение, доступное для быстрого поиска, имеет запись на странице настроек «Поисковые элементы» . Запись включает название приложения и краткое описание того, какой контент можно искать в приложении и какие подсказки доступны в быстром поиске. Чтобы определить текст описания для вашего приложения, добавьте атрибут android:searchSettingsDescription в конфигурацию поиска, как показано в следующем примере:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

Сделайте строку для атрибута android:searchSettingsDescription максимально краткой и укажите, какой контент доступен для поиска. Например, «Исполнители, альбомы и треки» для музыкального приложения или «Сохраненные заметки» для приложения-блокнота. Предоставление этого описания важно, чтобы пользователь понимал, какие подсказки ему предлагаются. Всегда добавляйте этот атрибут, если android:includeInGlobalSearch имеет значение true.

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

Управление ярлыками подсказок в поле быстрого поиска

Выбранные пользователем в поле быстрого поиска подсказки могут автоматически преобразовываться в ярлыки. Система копирует эти подсказки у вашего поставщика контента, чтобы быстро получить к ним доступ без необходимости повторного запроса к поставщику контента.

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

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

  Укажите значение в столбце SUGGEST_COLUMN_SHORTCUT_ID , чтобы запрос на обновление подсказки выполнялся каждый раз при отображении ярлыка. Ярлык быстро отображается с самыми актуальными данными до тех пор, пока не будет выполнен запрос на обновление, после чего подсказка обновляется новой информацией. Запрос на обновление отправляется вашему поставщику контента с URI-путем SUGGEST_URI_PATH_SHORTCUT вместо SUGGEST_URI_PATH_QUERY .

  Возвращаемый Cursor должен содержать одно предложение, использующее те же столбцы, что и исходное предложение, или быть пустым, указывая на то, что ярлык больше недействителен — в этом случае предложение исчезнет, ​​а ярлык будет удален.

  Если в предложении упоминаются данные, обновление которых может занять больше времени, например, обновление по сети, вы также можете добавить в таблицу предложений столбец SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING со значением true, чтобы отображать индикатор выполнения для значка справа до завершения обновления. Любое значение, отличное от true, не отображает индикатор выполнения.

• Полностью запретите копирование предложенного варианта в ярлык.

  Укажите значение SUGGEST_NEVER_MAKE_SHORTCUT в столбце SUGGEST_COLUMN_SHORTCUT_ID . В этом случае подсказка никогда не будет скопирована в ярлык. Это необходимо только в том случае, если вы категорически не хотите, чтобы ранее скопированная подсказка отображалась. Если вы укажете обычное значение для столбца, то ярлык с подсказкой будет отображаться только до тех пор, пока не будет выполнен запрос на обновление.

• Пусть будет применено поведение сочетаний клавиш по умолчанию.

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

Если ни одно из ваших предложений не меняется, то вам не нужен столбец SUGGEST_COLUMN_SHORTCUT_ID .

О ранжировании подсказок в строке быстрого поиска

После того, как вы добавите поисковые подсказки вашего приложения в Quick Search Box, рейтинг Quick Search Box будет определять, как эти подсказки будут отображаться пользователю по конкретному запросу. Это может зависеть от того, сколько других приложений имеют результаты по этому запросу и как часто пользователь выбирает ваши результаты по сравнению с результатами других приложений. Нет никаких гарантий относительно того, как будут ранжированы ваши подсказки или будут ли они вообще отображаться по данному запросу. В целом, предоставление качественных результатов повышает вероятность того, что подсказки вашего приложения будут отображаться на видном месте, а приложения, предоставляющие некачественные подсказки, с большей вероятностью будут занимать более низкие позиции в рейтинге или вообще не отображаться.