Configuración de búsqueda

Para implementar la búsqueda con la ayuda del sistema Android, es decir, para enviar consultas de búsqueda a una actividad y proporcionar sugerencias de búsqueda, tu aplicación debe proporcionar una configuración de búsqueda en forma de un archivo en formato XML.

En esta página, se describe el archivo de configuración de búsqueda en cuanto a su sintaxis y su uso. Si quieres obtener más información para implementar funciones de búsqueda en tu aplicación, consulta Cómo crear una interfaz de búsqueda.

ubicación del archivo:
res/xml/filename.xml
Android usa el nombre del archivo como ID de recurso.
sintaxis:
<?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>
elementos:
<searchable>
Define todas las configuraciones de búsqueda que utiliza el sistema Android para proporcionar búsqueda asistida.

Atributos:

android:label
Recurso de cadenas. (Obligatorio). El nombre de tu aplicación. Debe ser el mismo que el nombre aplicado al atributo android:label de tu elemento de manifiesto <activity> o <application>. Esta etiqueta solo es visible para el usuario cuando configuras android:includeInGlobalSearch como "true". En ese caso, esta etiqueta se usa para identificar tu aplicación como un elemento de búsqueda en la configuración de búsqueda del sistema.
android:hint
Recurso de cadenas. (Recomendado). Es el texto que se mostrará en el campo de texto de búsqueda cuando no se ingrese texto. Proporciona una sugerencia al usuario sobre qué contenido se puede buscar. A fin de mantener la coherencia con otras aplicaciones para Android, da formato a la string de android:hint como "Buscar <content-or-product>". Por ejemplo, "Buscar canciones y artistas" o "Buscar en YouTube".
android:searchMode
Palabra clave. Establece modos adicionales que controlan la presentación de búsqueda. Los modos disponibles definen cómo se debe reescribir el texto de la consulta cuando una sugerencia personalizada recibe el foco. Se aceptan los siguientes valores de modo:
ValorDescripción
"queryRewriteFromData" Usa el valor de la columna SUGGEST_COLUMN_INTENT_DATA para reescribir el texto de la consulta. Esto solo debe usarse cuando los valores en SUGGEST_COLUMN_INTENT_DATA son adecuados para la inspección y edición del usuario, como los URI de HTTP.
"queryRewriteFromText" Usa el valor de la columna SUGGEST_COLUMN_TEXT_1 para reescribir el texto de la consulta.

Para obtener más información, consulta la documentación sobre la reescritura del texto de la consulta en Cómo agregar sugerencias de búsqueda personalizadas.

android:searchButtonText
Recurso de cadenas. El texto que se mostrará en el botón que ejecuta la búsqueda. De forma predeterminada, el botón muestra un ícono de búsqueda (una lupa), que es ideal para la internacionalización. Por lo tanto, no uses este atributo para cambiar el botón, a menos que el comportamiento no sea una búsqueda, como una solicitud de URL en un navegador web.
android:inputType
Palabra clave. Define el tipo de método de entrada que se usará, como el tipo de teclado en pantalla. Para la mayoría de las búsquedas, en las que se espera texto de formato libre, no es necesario este atributo. Consulta inputType para obtener una lista de valores adecuados para este atributo.
android:imeOptions
Palabra clave. Proporciona opciones adicionales para el método de entrada. Para la mayoría de las búsquedas, en las que se espera texto de formato libre, no necesitas este atributo. El IME predeterminado es actionSearch, que proporciona el botón "buscar" en lugar de un retorno de carro en el teclado en pantalla. Consulta imeOptions para obtener una lista de valores adecuados para este atributo.

Atributos de sugerencias de búsqueda

Si defines un proveedor de contenido para generar sugerencias de búsqueda, debes definir atributos adicionales que configuren las comunicaciones con el proveedor de contenido. Cuando proporcionas sugerencias de búsqueda, necesitas algunos de los siguientes atributos <searchable>:


android:searchSuggestAuthority
String. (Obligatorio para proporcionar sugerencias de búsqueda). Este valor debe coincidir con la string de autoridad proporcionada en el atributo android:authorities del elemento <provider> del manifiesto de Android.
android:searchSuggestPath
String. Esta ruta se utiliza como una parte de la consulta de sugerencias Uri, después del prefijo y la autoridad y antes de la ruta de sugerencias estándar. Esto solo es necesario si tienes un único proveedor de contenido que emite diferentes tipos de sugerencias (por ejemplo, para diferentes tipos de datos) y necesitas una forma de desambiguar las consultas de sugerencias cuando las recibes.
android:searchSuggestSelection
String. Este valor se pasa a la función de consulta como el parámetro selection. Por lo general, es una cláusula WHERE para tu base de datos y debe contener un solo signo de interrogación como marcador de posición para la cadena de consulta real que ingresó el usuario, por ejemplo, "query=?". Sin embargo, también puedes usar cualquier valor no nulo para activar la publicación del texto de la consulta mediante el parámetro selectionArgs y, luego, ignorar el parámetro selection.
android:searchSuggestIntentAction
String. La acción de intent predeterminada que se utilizará cuando un usuario presione una sugerencia de búsqueda personalizada, como "android.intent.action.VIEW". Si la sugerencia seleccionada no anula este valor con la columna SUGGEST_COLUMN_INTENT_ACTION, el valor se coloca en el campo de acción de Intent cuando el usuario presiona una sugerencia.
android:searchSuggestIntentData
String. Datos de intents predeterminados que se usarán cuando un usuario presione una sugerencia de búsqueda personalizada Si la sugerencia seleccionada no lo anula (a través de la columna SUGGEST_COLUMN_INTENT_DATA), este valor se coloca en el campo de datos de Intent cuando el usuario presiona una sugerencia.
android:searchSuggestThreshold
Entero. La cantidad mínima de caracteres necesarios para activar una búsqueda de sugerencias. Esto solo garantiza que el sistema no consulte a tu proveedor de contenido por un período inferior al límite. El valor predeterminado es 0.

Si quieres obtener más información sobre los atributos mencionados anteriormente para las sugerencias de búsqueda, consulta la documentación sobre cómo agregar sugerencias de búsqueda personalizadas y cómo agregar sugerencias personalizadas.

Atributos del cuadro de búsqueda rápida

Para que tus sugerencias de búsqueda personalizadas estén disponibles en el cuadro de búsqueda rápida, necesitarás algunos de los siguientes atributos <searchable>:


android:includeInGlobalSearch
Booleano. (Obligatorio para proporcionar sugerencias de búsqueda en el cuadro de búsqueda rápida). Configúralo en "true" si deseas que tus sugerencias se incluyan en el cuadro de búsqueda rápida de acceso global. El usuario aún debe habilitar tu aplicación como un elemento de búsqueda en la configuración de búsqueda del sistema antes de que tus sugerencias aparezcan en el cuadro de búsqueda rápida.
android:searchSettingsDescription
Recurso de cadenas. Proporciona una descripción breve de las sugerencias de búsqueda que proporcionas al cuadro de búsqueda rápida, que se muestra en la entrada de elementos de búsqueda de tu aplicación. Tu descripción debe describir de manera concisa el contenido que se puede buscar. Por ejemplo, "Artistas, álbumes y pistas" para una aplicación de música, o "Notas guardadas" para una aplicación de bloc de notas.
android:queryAfterZeroResults
Booleano. Configúralo en "true" si deseas que se invoque tu proveedor de contenido para superconjuntos de consultas que antes no mostraban resultados. Por ejemplo, si tu proveedor de contenido no muestra ningún resultado para "bo", debe volver a buscarse para "bob". Si se configura como "false", los superconjuntos se ignoran para una sola sesión; “bob” no invoca una nueva consulta. Esto dura solo la vida del diálogo de búsqueda o la vida de la actividad cuando se usa el widget de búsqueda. Cuando se vuelven a abrir el diálogo o la actividad de búsqueda, "bo" vuelve a consultar al proveedor de contenido. El valor predeterminado es falso.

Atributos de búsqueda por voz

Para habilitar la búsqueda por voz, necesitas algunos de los siguientes atributos <searchable>:


android:voiceSearchMode
Palabra clave. (Obligatorio para proporcionar funcionalidades de búsqueda por voz). Habilita la búsqueda por voz con un modo específico para la búsqueda por voz. Es posible que el dispositivo no proporcione la búsqueda por voz, en cuyo caso estas marcas no tienen efecto. Se aceptan los siguientes valores de modo:
ValorDescripción
"showVoiceSearchButton" Muestra un botón de búsqueda por voz si esta función está disponible en el dispositivo. Si se configura, también se debe configurar "launchWebSearch" o "launchRecognizer", separados por el carácter de barra vertical (|).
"launchWebSearch" El botón de búsqueda por voz lleva al usuario directamente a una actividad de búsqueda web de voz integrada. La mayoría de las aplicaciones no usan esta marca, ya que aleja al usuario de la actividad en la que se invocó la búsqueda.
"launchRecognizer" El botón de búsqueda por voz lleva al usuario directamente a una actividad de grabación de voz integrada. Esta actividad le pide al usuario que hable, transcribe el texto hablado y reenvía el texto de consulta resultante a la actividad de búsqueda, como si lo escribiera en la IU de búsqueda y presionara el botón de búsqueda.
android:voiceLanguageModel
Palabra clave. El modelo de lenguaje que debe utilizar el sistema de reconocimiento de voz. Se aceptan los siguientes valores:
ValorDescripción
"free_form" Usa el reconocimiento de voz de formato libre para dictar consultas. Esto está optimizado principalmente para inglés. Es el valor predeterminado.
"web_search" Usa el reconocimiento de término de búsqueda web para frases más cortas similares a búsquedas. Está disponible en más idiomas que "free_form".

Consulta EXTRA_LANGUAGE_MODEL para obtener más información.

android:voicePromptText
Recurso de cadenas. Un mensaje adicional para mostrar en el diálogo de entrada de voz.
android:voiceLanguage
String. El idioma hablado que se espera, expresado como el valor de cadena de una constante en Locale, como "de" para alemán o "fr" para francés. Esto es necesario solo si es diferente del valor actual de Locale.getDefault().
android:voiceMaxResults
Entero. Configura la cantidad máxima de resultados que se mostrarán, incluido el "mejor", que siempre se proporciona como la consulta principal del intent ACTION_SEARCH. Debe ser 1 o mayor. Usa EXTRA_RESULTS para obtener los resultados del intent. Si no se proporciona, el reconocedor elige cuántos resultados mostrar.
<actionkey>
Define una tecla de dispositivo y un comportamiento para una acción de búsqueda. Una acción de búsqueda proporciona un comportamiento especial con solo presionar un botón en el dispositivo, según la consulta actual o la sugerencia enfocada. Por ejemplo, la app de Contactos proporciona una acción de búsqueda para iniciar una llamada telefónica a la sugerencia del contacto enfocado actualmente cuando se presiona el botón LLAMAR.

No todas las teclas de acción están disponibles en todos los dispositivos, y no todas las teclas se pueden anular de esta manera. Por ejemplo, no se puede anular la tecla "Inicio" y debe volver siempre a la pantalla principal. Además, asegúrate de no definir una tecla de acción para una tecla que se necesita para escribir una búsqueda. Esto limita las teclas de acción disponibles y razonables al botón de llamada y al botón de menú.

Debes definir el android:keycode para definir la clave y al menos uno de los otros tres atributos para definir la acción de búsqueda.

Atributos:

android:keycode
String. (Obligatorio). Un código de tecla de KeyEvent que representa la tecla de acción a la que deseas responder, por ejemplo, "KEYCODE_CALL" Esto se agrega al intent ACTION_SEARCH que se pasa a tu actividad de búsqueda. Para examinar el código de tecla, usa getIntExtra(SearchManager.ACTION_KEY). No todas las teclas son compatibles con una acción de búsqueda, ya que muchas de ellas se usan para escribir, navegar o funciones del sistema.
android:queryActionMsg
String. Un mensaje de acción que se enviará si se presiona la tecla de acción mientras el usuario ingresa el texto de la consulta. Esto se agrega al intent ACTION_SEARCH que el sistema pasa a tu actividad de búsqueda. Para examinar la string, usa getStringExtra(SearchManager.ACTION_MSG).
android:suggestActionMsg
String. Un mensaje de acción que se enviará si se presiona la tecla de acción mientras una sugerencia está enfocada. Esto se agrega al intent que el sistema pasa a la actividad de búsqueda mediante la acción que defines para la sugerencia. Para examinar la string, usa getStringExtra(SearchManager.ACTION_MSG). Solo se debe usar si todas las sugerencias admiten esta tecla de acción. Si no todas las sugerencias pueden manejar la misma tecla de acción, debes utilizar el siguiente atributo android:suggestActionMsgColumn.
android:suggestActionMsgColumn
String. Es el nombre de la columna en tu proveedor de contenido que define el mensaje de acción para esta tecla de acción, que se enviará si el usuario presiona la tecla de acción mientras una sugerencia está enfocada. Este atributo te permite controlar la tecla de acción sugerencia por sugerencia, ya que, en lugar de usar el atributo android:suggestActionMsg para definir el mensaje de acción para todas las sugerencias, cada entrada del proveedor de contenido proporciona su propio mensaje de acción.

Primero, debes definir una columna en tu proveedor de contenido para cada sugerencia a fin de proporcionar un mensaje de acción y, luego, proporcionar el nombre de esa columna en este atributo. El sistema mira el cursor de sugerencias, usa la string proporcionada aquí para seleccionar la columna de mensaje de acción y, luego, selecciona la string del mensaje de acción del cursor. Esa cadena se agrega al intent que el sistema pasa a la actividad de búsqueda con la acción que defines para las sugerencias. Para examinar la string, usa getStringExtra(SearchManager.ACTION_MSG). Si no existen datos para la sugerencia seleccionada, se ignora la tecla de acción.

ejemplo:
Archivo en formato XML guardado en 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>