Para implementar la búsqueda con ayuda del sistema Android (a fin de 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. A fin de obtener más información para implementar funciones de búsqueda para tu aplicación, comienza leyendo la guía para desarrolladores sobre Cómo crear 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 utilizadas por el sistema Android para proporcionar búsquedas asistidas.
atributos:
android:label- Recurso de string. (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 string. (Recomendado). 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. A fin de mantener la coherencia con otras aplicaciones para Android, debes darle 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 actualmente definen cómo debe reescribirse el texto de la consulta cuando una sugerencia personalizada recibe el foco. Se aceptan los siguientes valores de modo:
| Valor | Descripción |
|---|
"queryRewriteFromText" |
Usa el valor de la columna SUGGEST_COLUMN_TEXT_1 para reescribir el texto de la consulta. |
"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, en general el URI de HTTP. |
Para obtener más información, consulta la descripción sobre la reescritura del texto de la consulta en Cómo agregar sugerencias personalizadas.
android:searchButtonText- Recurso de string. 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. Debes usar el 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 (como el tipo de teclado en pantalla) que se usará. Para la mayoría de las búsquedas, en las que se espera texto de formato libre, no es necesario ese atributo. Consulta
inputType para obtener una lista de valores adecuados de este atributo.
android:imeOptions- Palabra clave. Proporciona opciones adicionales para el método de entrada.
En 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" (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 ese atributo.
Atributos de sugerencias de búsqueda
Si definiste 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 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, pero antes de la ruta de sugerencias estándar.
Esto solo es necesario si tienes un proveedor de contenido único 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. Normalmente, esta es una cláusula WHERE para la base de datos y debe contener un solo signo de interrogación, que es un marcador de posición para la cadena de consulta real que escribió el usuario (por ejemplo, "query=?"). Sin embargo, también puedes usar cualquier valor no nulo para activar la entrega del texto de la consulta por medio del 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 haga clic en una sugerencia de búsqueda personalizada (como
"android.intent.action.VIEW"). Si la sugerencia seleccionada no anula esta opción (por medio de la columna SUGGEST_COLUMN_INTENT_ACTION), este valor se coloca en el campo de acción de Intent cuando el usuario hace clic en una sugerencia.
android:searchSuggestIntentData- String. Los datos de intent predeterminados que se utilizarán cuando un usuario haga clic en 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 hace clic en una sugerencia.
android:searchSuggestThreshold- Entero. El número mínimo de caracteres necesarios para activar una búsqueda de sugerencias. 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 las guías Cómo agregar sugerencias de consultas recientes y Cómo agregar sugerencias personalizadas.
Atributos del cuadro de búsqueda rápida
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- Valor 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- String. 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- Valor booleano. Establécelo en "true" si quieres que se invoque a tu proveedor de contenido para superconjuntos de consultas que no mostraron ningún resultado en el pasado. Por ejemplo, si el proveedor de contenido no mostró ningún resultado para "bo", debería ser necesario para "bob". Si se configura como "false", los superconjuntos se ignoran para una sola sesión ("bob" no invoca una consulta nueva). 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 false.
Atributos de búsqueda por voz
Para habilitar la búsqueda por voz, necesitarás 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, "launchWebSearch" o "launchRecognizer" también deben establecerse (separados por la 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 necesitan esta marca, ya que aleja al usuario de la actividad en la que se invoca 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 e hiciera clic en 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 también EXTRA_LANGUAGE_MODEL para obtener más información.
android:voicePromptText- String. 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 string de las constantes 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. Fuerza 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 tocar 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 con solo presionar 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 usar 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. Eso, esencialmente, limita las teclas de acción disponibles y define el botón de llamada y el botón de menú como las opciones razonables. También ten en cuenta que, por lo general, las teclas de acción no se pueden descubrir, así que no debes proporcionarlas como una función principal de usuario.
Debes establecer android:keycode para definir la tecla y al menos uno de los otros tres atributos para determinar 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 la 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 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 (usando la acción que definiste para la sugerencia). Para examinar la string, 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 manejar la misma tecla de acción, debes utilizar 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 la 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 mira el cursor de sugerencias, usa la string provista aquí para seleccionar la columna de mensaje de acción y luego selecciona la string de mensaje de acción del cursor. Esa string se agrega al intent que el sistema pasa a tu actividad de búsqueda (con la acción que definiste para las sugerencias). Para examinar la string, usa getStringExtra(SearchManager.ACTION_MSG). Si los datos no existen para la sugerencia seleccionada, se ignora la tecla de acción.
- ejemplo:
- Archivo 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>
