Search API Autocomplete
Añade funcionalidad de autocompletado a las búsquedas de Search API, permitiendo a los usuarios ver sugerencias de búsqueda mientras escriben.
search_api_autocomplete
Install
composer require 'drupal/search_api_autocomplete:8.x-1.11'
composer require 'drupal/search_api_autocomplete:8.x-1.9'
Overview
Search API Autocomplete añade capacidades de autocompletado a las búsquedas de Search API. A medida que los usuarios escriben en los campos de búsqueda, reciben sugerencias en tiempo real basadas en datos indexados, búsquedas anteriores o resultados de búsqueda en vivo.
El módulo proporciona control detallado sobre el comportamiento del autocompletado, permitiendo a los administradores habilitar y configurar el autocompletado para cada búsqueda individualmente. Esto incluye vistas de búsqueda creadas con el módulo Views y páginas de búsqueda creadas con el módulo Search API Pages.
Se pueden configurar múltiples métodos de sugerencia (suggesters) por búsqueda, incluyendo sugerencias basadas en servidor a partir de datos indexados, visualización de resultados en vivo mostrando resultados de búsqueda reales mientras el usuario escribe, e integración de scripts personalizados para casos de uso avanzados. Cada suggester puede ser ponderado y limitado de forma independiente.
Los permisos por búsqueda aseguran un control de acceso apropiado, y las opciones de configuración completas permiten personalizar los límites de sugerencias, retrasos de entrada, requisitos mínimos de caracteres, visualización del conteo de resultados y comportamiento de envío automático.
Features
- Autocompletado para campos de texto completo en formularios expuestos de Views de Search API
- Autocompletado para formularios de búsqueda de Search API Pages
- Múltiples plugins de sugerencias: Sugerencias basadas en servidor, Resultados en vivo, Script personalizado
- Configuración por búsqueda con controles individuales de activar/desactivar
- Límite máximo configurable de sugerencias por búsqueda
- Requisito de longitud mínima de entrada antes de mostrar sugerencias
- Retraso ajustable entre pulsaciones de teclas y solicitudes de sugerencias
- Visualización opcional del conteo estimado de resultados para cada sugerencia
- Funcionalidad de envío automático cuando se selecciona una sugerencia
- Ordenamiento por peso y límites de resultados por suggester
- Control de permisos por búsqueda para acceso detallado
- Soporte para transliteración en la coincidencia de autocompletado
- Suggester de Resultados en vivo con modos de vista configurables por bundle de entidad
- Resaltado de Resultados en vivo usando el procesador Highlight de Search API
- Suggester de Script personalizado para endpoints externos optimizados en rendimiento
- Arquitectura de plugins extensible para suggesters y tipos de búsqueda personalizados
Use Cases
Autocompletado básico de búsqueda para Views
Habilita el autocompletado en el filtro expuesto de texto completo de una View de Search API. Navega a la pestaña Autocompletado del índice, habilita la búsqueda de la View, selecciona el suggester 'Recuperar del servidor' y guarda. Los usuarios verán sugerencias de palabras clave mientras escriben basadas en el contenido indexado.
Vista previa de resultados en vivo
Muestra resultados de búsqueda reales mientras los usuarios escriben. Configura el suggester 'Mostrar resultados en vivo' y opcionalmente selecciona modos de vista para cada tipo de contenido. Los usuarios ven enlaces de resultados clicables con etiquetas de entidad o contenido renderizado en modo de vista mientras escriben.
Estrategia de sugerencias combinadas
Habilita múltiples suggesters con diferentes pesos. Por ejemplo, usa 'Recuperar del servidor' (peso -10) para sugerencias de palabras clave y 'Mostrar resultados en vivo' (peso 0) para vistas previas de resultados. Establece límites por suggester para mostrar 5 sugerencias de palabras clave y 3 resultados en vivo.
Autocompletado personalizado de alto rendimiento
Para sitios de alto tráfico, habilita la configuración enable_custom_scripts y configura el suggester 'Usar script personalizado' apuntando a un endpoint PHP ligero que consulta el servidor de búsqueda directamente, evitando el bootstrap de Drupal para tiempos de respuesta más rápidos.
Autocompletado de páginas de búsqueda
Añade autocompletado a bloques de búsqueda de Search API Pages. Después de habilitar el módulo, el autocompletado está disponible automáticamente en Search API Pages. Configura a través de la pestaña Autocompletado del índice asociado.
Autocompletado específico por campo
Restringe las sugerencias de autocompletado a campos indexados específicos. En la configuración del suggester, selecciona 'Sobrescribir campos usados' y elige solo los campos que deben ser buscados para generar sugerencias (por ejemplo, solo el campo de título, no el cuerpo).
Tips
- Usa el módulo Search API Solr Autocomplete cuando uses el backend Solr para funcionalidad de autocompletado mejorada con completación de términos e integración de corrector ortográfico
- Establece límites por suggester cuando uses múltiples suggesters para asegurar una buena mezcla de tipos de sugerencias
- El suggester 'Mostrar resultados en vivo' funciona mejor cuando el backend soporta coincidencia parcial o cuando se usa con el procesador Highlight
- Para Views con múltiples filtros de texto completo, el autocompletado se añade a todos los campos identificados como campos de texto completo
- Prueba el autocompletado con diferentes roles de usuario para asegurar que los permisos estén correctamente configurados
- Considera la opción 'Sugerir etiquetas de resultados como palabras clave' en Resultados en vivo cuando quieras que los usuarios refinen su búsqueda en lugar de saltar directamente a los resultados
- La configuración de retraso balancea la experiencia de usuario contra la carga del servidor - 300ms es un buen valor por defecto, aumenta para sitios de alto tráfico
Technical Details
Admin Pages 2
/admin/config/search/search-api/index/{index}/autocomplete
Página de resumen para gestionar la configuración de autocompletado para todas las búsquedas asociadas con un índice de Search API. Lista todas las búsquedas disponibles (Views, Pages) agrupadas por tipo, con casillas de verificación para habilitar/deshabilitar el autocompletado para cada una. Proporciona enlaces para editar configuraciones de búsqueda individuales o eliminar configuraciones existentes.
/admin/config/search/search-api/index/{index}/autocomplete/{search}/edit
Formulario de configuración detallada para una búsqueda de autocompletado individual. Permite la selección y configuración de plugins de sugerencias, establecer opciones de comportamiento del autocompletado, y configuraciones específicas del plugin de búsqueda.
Permissions 2
Hooks 4
hook_search_api_autocomplete_suggestions_alter
Modifica las sugerencias que serán devueltas para una solicitud de autocompletado. Permite a los módulos añadir, eliminar o modificar sugerencias antes de que sean enviadas al cliente.
hook_search_api_autocomplete_suggester_info_alter
Modifica las definiciones de plugins de sugerencias disponibles. Permite sobrescribir la clase del plugin, etiqueta, descripción u otras propiedades.
hook_search_api_autocomplete_search_info_alter
Modifica las definiciones de plugins de búsqueda disponibles. Permite sobrescribir la clase del plugin u otras propiedades para plugins de búsqueda.
hook_search_api_autocomplete_views_fulltext_fields_alter
Modifica qué campos de Views se consideran campos de texto completo para autocompletado. El autocompletado se añadirá a las entradas de texto para estos campos.
Troubleshooting 6
Verifica: 1) El autocompletado está habilitado para la búsqueda en la pestaña Autocompletado del índice, 2) El usuario tiene el permiso 'Usar autocompletado para X', 3) Al menos un suggester está habilitado y configurado, 4) Para el suggester 'Recuperar del servidor', asegúrate de que el backend soporte la característica search_api_autocomplete, 5) Revisa la consola del navegador por errores de JavaScript.
El backend del servidor de búsqueda debe soportar la característica 'search_api_autocomplete'. Revisa la documentación de Search API para el soporte de características del backend. Considera usar el suggester 'Mostrar resultados en vivo' como alternativa.
Aumenta la configuración de 'Retraso' para reducir la frecuencia de solicitudes (por ejemplo, 500ms). Considera usar límites por suggester. Para sitios de alto tráfico, implementa un suggester de script personalizado que evite Drupal.
Verifica qué campos se están buscando. En la configuración del suggester, usa 'Sobrescribir campos usados' para seleccionar explícitamente los campos que deben ser buscados. Asegúrate de que el índice esté actualizado y contenga el contenido esperado.
El suggester de Resultados en vivo respeta el acceso a los elementos. Asegúrate de que el índice de búsqueda tenga configurada la verificación de acceso apropiada. Los elementos a los que el usuario no puede acceder son filtrados de las sugerencias.
Habilita el suggester oculto estableciendo search_api_autocomplete.settings:enable_custom_scripts a TRUE mediante drush config:set o editando el YAML de configuración directamente.
Security Notes 5
- Cada búsqueda de autocompletado tiene su propio permiso - revisa y asigna estos permisos cuidadosamente a los roles apropiados
- El suggester 'Usar script personalizado' evita la verificación normal de acceso de Drupal - solo habilítalo si entiendes las implicaciones de seguridad
- Los endpoints de scripts personalizados deben implementar su propio control de acceso y validación de entrada
- El endpoint de autocompletado devuelve JSON con valores no sanitizados en la clave 'value' - siempre escapa antes de renderizar como HTML
- Los conteos de resultados pueden revelar información sobre la existencia de contenido - considera deshabilitar show_count para búsquedas sensibles