AJAX search

La búsqueda AJAX añade un campo de búsqueda con sugerencias de productos en vivo mientras se escribe, sin recargar la página. Se coloca con el shortcode [polski_ajax_search], el bloque Polski - AJAX Search o el widget de Elementor.

Activar el módulo

Ve a Polski > Módulos, activa la opción AJAX Search y coloca el shortcode, el bloque o el widget donde deba aparecer el buscador. El buscador propio del tema no se reemplaza, pero su página de resultados gana la misma búsqueda por SKU y categoría.

Campos buscados

La barra de búsqueda busca en varios campos del producto de forma simultánea:

SKU (número de catálogo)

El cliente puede introducir el SKU de un producto o un fragmento del mismo. La búsqueda por SKU es especialmente útil en tiendas B2B, donde los clientes piden productos por números de catálogo.

Fabricante

Si el módulo Fabricante está activo, la búsqueda incluye el nombre del fabricante en los resultados. Escribir, por ejemplo, “Samsung” mostrará todos los productos de ese fabricante.

GTIN (EAN/UPC)

Búsqueda por códigos de barras GTIN/EAN/UPC. El cliente puede introducir un código de barras completo o un fragmento del mismo para encontrar un producto.

Campos adicionales

• Nombre del producto
• Descripción corta
• Categorías
• Etiquetas
• Atributos (color, talla, etc.)

Configuración de los campos buscados: Polski > Módulos > AJAX Search > Campos de búsqueda.

Resultados de la búsqueda

El desplegable de resultados muestra:

• Miniatura del producto
• Nombre del producto (con resaltado del fragmento coincidente)
• Precio
• Categoría
• Valoración (estrellas)
• Estado de disponibilidad

De forma predeterminada se muestran hasta 8 sugerencias. El límite se puede cambiar:

add_filter('polski/ajax_search/results_limit', function (): int {
    return 12;
});

El número mínimo de caracteres para iniciar la búsqueda es 3. Para cambiarlo:

add_filter('polski/ajax_search/min_chars', function (): int {
    return 2;
});

Endpoint de la API REST

La búsqueda utiliza su propio endpoint de la API REST en lugar de admin-ajax.php, lo que ofrece un mejor rendimiento.

Endpoint: GET /wp-json/polski/v1/search

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
q	string	Sí	Frase de búsqueda
limit	int	No	Límite de resultados (predeterminado 8)
cat	int	No	ID de categoría para filtrar

Ejemplo de solicitud:

curl "https://yourstore.com/wp-json/polski/v1/search?q=t-shirt&limit=5"

Ejemplo de respuesta:

{
  "results": [
    {
      "id": 123,
      "title": "Cotton T-shirt",
      "url": "https://yourstore.com/product/cotton-t-shirt/",
      "image": "https://yourstore.com/wp-content/uploads/tshirt.jpg",
      "price_html": "<span class=\"amount\">49.00&nbsp;PLN</span>",
      "category": "Clothing",
      "in_stock": true,
      "rating": 4.5
    }
  ],
  "total": 1,
  "query": "t-shirt"
}

Bloque Gutenberg

El módulo proporciona un bloque Polski - AJAX Search en el editor Gutenberg. El bloque se puede colocar en cualquier entrada, página o widget.

Opciones del bloque:

• Placeholder - texto de marcador de posición en el campo de búsqueda
• Ancho - ancho del campo (auto, completo, personalizado en px)
• Icono - mostrar/ocultar el icono de lupa
• Filtro de categoría - mostrar un desplegable de filtrado por categoría junto al campo de búsqueda
• Estilo - esquinas redondeadas, borde, sombra

Para insertar el bloque: en el editor Gutenberg haz clic en + y busca Polski o AJAX Search.

Widget de Elementor

Para los usuarios de Elementor, hay disponible un widget dedicado AJAX Search. El widget se encuentra en la categoría Polski for WooCommerce en la barra lateral de Elementor.

Las opciones del widget incluyen todos los ajustes del bloque Gutenberg más:

• Controles de tipografía (familia de fuente, tamaño, grosor)
• Colores (fondo, texto, borde, hover)
• Márgenes y rellenos
• Animación de aparición de los resultados
• Responsividad (ajustes por breakpoint)

Shortcode [polski_ajax_search]

Parámetros

Parámetro	Tipo	Predeterminado	Descripción
placeholder	string	Search products...	Texto de marcador de posición
width	string	100%	Ancho del campo
show_icon	string	yes	Mostrar el icono de lupa
show_cat	string	no	Mostrar el filtro de categoría
limit	int	8	Número máximo de sugerencias

Ejemplo de uso

[polski_ajax_search placeholder="What are you looking for?" show_cat="yes" limit="10"]

Insertar en la cabecera del tema

// En el functions.php del tema
add_action('wp_body_open', function (): void {
    echo do_shortcode('[polski_ajax_search placeholder="Search..." width="400px"]');
});

Debouncing y rendimiento

La búsqueda utiliza un debouncing de 300 ms - la solicitud al servidor se envía solo 300 ms después de la última pulsación de tecla. Esto evita consultas excesivas durante una escritura rápida.

Los resultados se almacenan en caché en el lado del cliente, en la sesión del navegador. Volver a introducir la misma frase no genera una solicitud al servidor.

En el lado del servidor, los resultados se almacenan en caché mediante la API de transients de WordPress (1 hora de forma predeterminada). La caché se borra automáticamente cuando se guarda, añade o elimina un producto.

// Cambiar el tiempo de caché
add_filter('polski/ajax_search/cache_ttl', function (): int {
    return 1800; // 30 minutos en segundos
});

Estilos CSS

Clases CSS del módulo:

• .polski-ajax-search - contenedor de la búsqueda
• .polski-ajax-search__input - campo de texto
• .polski-ajax-search__results - desplegable de resultados
• .polski-ajax-search__item - resultado individual
• .polski-ajax-search__item--active - resultado resaltado (navegación con teclado)
• .polski-ajax-search__highlight - resaltado del fragmento coincidente
• .polski-ajax-search__loading - indicador de carga

Accesibilidad

La búsqueda admite navegación completa con el teclado:

• Flecha abajo/arriba - navegar por los resultados
• Enter - ir al producto seleccionado
• Escape - cerrar el desplegable
• Atributos ARIA: role="combobox", aria-expanded, aria-activedescendant

Informar de problemas: github.com/wppoland/polski/issues

Esta página tiene únicamente carácter informativo y no constituye asesoramiento legal. Consulta a un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) proporcionado sin garantía.