Se usó la API de Cloud Translation para traducir esta página.

Configuración de búsqueda

Para implementar la búsqueda con ayuda del sistema Android (es decir, para enviar búsquedas 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 XML.

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

ubicación del archivo:

res/xml/filename.xml
Android usa el nombre de 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úsquedas asistidas.

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 del elemento de manifiesto <activity> o <application>. Esta etiqueta solo es visible para el usuario cuando estableces android:includeInGlobalSearch en "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 búsqueda de texto cuando no se haya ingresado ningún texto. Proporciona una sugerencia al usuario sobre qué contenido se puede buscar. Para mantener la coherencia con otras aplicaciones para Android, dale formato a la cadena 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 debe reescribirse el texto de la búsqueda cuando una sugerencia personalizada recibe el foco. Se aceptan los siguientes valores de modo:

Valor	Descripció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` sean adecuados para la inspección y edición del usuario, como los URIs de HTTP.
`"queryRewriteFromText"`	Usa el valor de la columna `SUGGEST_COLUMN_TEXT_1` para reescribir el texto de la búsqueda.

Para obtener más información, consulta la documentación sobre la reescritura del texto de la búsqueda 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 manera predeterminada, el botón muestra un ícono de búsqueda (una lupa), lo cual es ideal para la internacionalización. Por lo tanto, no uses este atributo para cambiar el botón, a menos que el comportamiento sea algo distinto a 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 es necesario este atributo. El IME predeterminado es actionSearch, que proporciona el botón "buscar" en lugar de un retorno de carro en el teclado virtual. 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. Si 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 cadena 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 solo 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, se trata de 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 búsqueda real que ingresa el usuario, por ejemplo, "query=?". Sin embargo, también puedes usar cualquier valor no nulo para activar la entrega del texto de la búsqueda con el parámetro selectionArgs y, luego, ignorar el parámetro selection.
android:searchSuggestIntentAction: String. Es 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. Son los datos de intención predeterminados que se usarán cuando un usuario presione una sugerencia de búsqueda personalizada. Si la sugerencia seleccionada no anula la opción (por medio 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. Es la cantidad mínima de caracteres necesarios para activar una búsqueda de sugerencias. Esto solo garantiza que el sistema no consultará 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 descritos arriba para las sugerencias de búsqueda, consulta la documentación para agregar sugerencias de búsqueda personalizadas y agregar sugerencias personalizadas.

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

android:includeInGlobalSearch: Booleano. (Obligatorio para proporcionar sugerencias de búsqueda en el cuadro de búsqueda rápida). Establécelo en "true" si quieres que las sugerencias se incluyan en el cuadro de búsqueda rápida de acceso global. El usuario igual debe habilitar tu aplicación como un elemento de búsqueda en la configuración de búsqueda del sistema para 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 ingresas en el cuadro de búsqueda rápida, que se muestra en la entrada de elementos de búsqueda para la aplicación. La descripción debe detallar 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. Establécelo en "true" si quieres que se invoque a tu proveedor de contenido para superconjuntos de búsquedas que anteriormente no devolvieron ningún resultado. Por ejemplo, si tu proveedor de contenido no muestra ningún resultado para "bo", se debe volver a consultar para "bob". Si se establece en "false", los superconjuntos se ignoran para una sola sesión: "bob" no invoca una nueva búsqueda. Esto dura solo la vida del diálogo de búsqueda o la vida de la actividad cuando se utiliza el widget de búsqueda. Cuando se vuelve 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 ese caso, las marcas no tienen ningún efecto. Se aceptan los siguientes valores de modo:

Valor	Descripció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 establecer `"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 incorporada. 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 solicita al usuario que hable, transcribe el texto hablado y reenvía el texto de consulta resultante a la actividad de búsqueda, como si el usuario lo escribiera en la IU de búsqueda y presionara el botón de búsqueda.

android:voiceLanguageModel

Palabra clave. El modelo de idioma que debe usar el sistema de reconocimiento de voz. Se aceptan los siguientes valores:

Valor	Descripció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. Establece la cantidad máxima de resultados que se mostrarán, incluido el "mejor" resultado, 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 aplicación de Contactos ofrece una acción de búsqueda para iniciar una llamada telefónica a la sugerencia de contacto enfocada actual 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 pueden anularse de esta manera. Por ejemplo, no se puede anular la tecla "Inicio", que siempre debe volver a la pantalla de inicio. También debes asegurarte 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 android:keycode para definir la tecla 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 usar 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 búsqueda. Esto se agrega al intent ACTION_SEARCH que el sistema pasa a tu actividad de búsqueda. Para examinar la cadena, 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 tu actividad de búsqueda, con la acción que defines para la sugerencia. Para examinar la cadena, usa getStringExtra(SearchManager.ACTION_MSG). Esto solo debe usarse si todas las sugerencias admiten esta tecla de acción. Si no todas las sugerencias pueden controlar la misma tecla de acción, debes usar el siguiente atributo android:suggestActionMsgColumn.
android:suggestActionMsgColumn: String. El nombre de la columna de 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 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 de todas las sugerencias, cada entrada de tu proveedor de contenido proporciona su propio mensaje de acción.
Primero, debes definir una columna en el proveedor de contenido para cada sugerencia a fin de proporcionar un mensaje de acción. Luego, proporciona el nombre de esa columna en este atributo. El sistema observa el cursor de sugerencias, usa la cadena proporcionada aquí para seleccionar la columna de mensaje de acción y, luego, selecciona la cadena de mensaje de acción del cursor. Esa cadena se agrega al intent que el sistema pasa a tu actividad de búsqueda, con la acción que defines para las sugerencias. Para examinar la cadena, usa getStringExtra(SearchManager.ACTION_MSG). Si los datos no existen 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>

Configuración de búsqueda Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Atributos de sugerencias de búsqueda

Atributos del cuadro de búsqueda rápida

Atributos de búsqueda por voz

Configuración de búsqueda