API de Programmable Search Element Control

Puedes incorporar componentes del Motor de Búsqueda Programable (cuadros de búsqueda y páginas de resultados de búsqueda) en tus páginas web y otras aplicaciones web mediante el lenguaje de marcado HTML. Estos elementos del Motor de Búsqueda Programable constan de componentes que se renderizan en función de la configuración que almacena el servidor de Búsqueda Programable, junto con cualquier personalización que realices.

Todo JavaScript se carga de forma asíncrona, lo que permite que tu página web se siga cargando mientras el navegador recupera el JavaScript del Motor de Búsqueda Programable.

Introducción

En este documento, se proporciona un modelo básico para agregar elementos del Motor de Búsqueda Programable a tu página web, junto con explicaciones de los componentes configurables del elemento y la API de JavaScript flexible.

Alcance

En este documento, se describe cómo usar las funciones y propiedades específicas de la API de Control del Motor de Búsqueda Programable.

Compatibilidad con navegadores

Puedes encontrar la lista de navegadores compatibles con el Motor de Búsqueda Programable aquí.

Público

Esta documentación está dirigida a los desarrolladores que deseen agregar la funcionalidad de la Búsqueda Programable de Google a sus páginas.

Elementos de Búsqueda Programable

Puedes usar el lenguaje de marcado HTML para agregar un elemento de Búsqueda Programable a tu página. Cada elemento consta al menos de un componente: un cuadro de búsqueda, un bloque de resultados de la búsqueda o ambos. El cuadro de búsqueda acepta entradas del usuario de cualquiera de las siguientes maneras:

  • Una búsqueda escrita en el campo de entrada de texto
  • Una cadena de consulta incorporada en una URL
  • Ejecución programática

Además, el bloque de resultados de la búsqueda acepta entradas de las siguientes maneras:

  • Una cadena de consulta incorporada en una URL
  • Ejecución programática

Están disponibles los siguientes tipos de elementos de Búsqueda Programable:

Tipo de elemento Componentes Descripción
standard <div class="gcse-search"> Un cuadro de búsqueda y los resultados de la búsqueda, que se muestran en el mismo <div>
dos columnas <div class="gcse-searchbox"> y <div class="gcse-searchresults"> un diseño de dos columnas con resultados de la búsqueda en un lado y un cuadro de búsqueda en el otro. Si planeas insertar varios elementos en el modo de dos columnas en tu página web, puedes usar el atributo gname para vincular un cuadro de búsqueda con un bloque de resultados de la búsqueda.
solo cuadro de búsqueda <div class="gcse-searchbox-only"> Un cuadro de búsqueda independiente
solo resultados de búsqueda <div class="gcse-searchresults-only"> Un bloque independiente de resultados de la búsqueda.

Puedes agregar cualquier cantidad de elementos de búsqueda válidos a tu página web. En el modo de dos columnas, deben estar presentes todos los componentes obligatorios (un cuadro y un bloque de resultados de la búsqueda).

A continuación, se muestra un ejemplo de un elemento de búsqueda simple:

<!-- Put the following javascript before the closing </head> tag
and replace 123456 with your own Programmable Search Engine ID. -->
<script async src="https://cse.google.com/cse.js?cx=123456"></script>

<!-- Place this tag where you want both of the search box and the search results to render -->
<div class="gcse-search"></div>

Redactar diferentes opciones de diseño con los elementos de Búsqueda Programable

Las siguientes opciones de diseño están disponibles en la página Aspecto del panel de control del Motor de Búsqueda Programable. A continuación, se incluyen algunos lineamientos generales sobre la composición de opciones de diseño con elementos de búsqueda programables. Para ver una demostración de cualquiera de estas opciones, haz clic en el vínculo.

Opción Componentes
Ancho completo <div class="gcse-search">
Compacta <div class="gcse-search">
Dos columnas <div class="gcse-searchbox">, <div class="gcse-searchresults">
Dos páginas <div class="gcse-searchbox-only"> en la primera página y <div class="gcse-searchresults-only"> (u otros componentes) en la segunda.
Solo resultados <div class="gcse-searchresults-only">
Alojada en Google <div class="gcse-searchbox-only">

Obtén más información sobre las opciones de diseño.

Cómo personalizar los elementos de la Búsqueda Programable

Para personalizar los colores, la fuente o el estilo de los vínculos, ve a la página Aspecto de tu motor de búsqueda programable.

Puedes usar atributos opcionales para reemplazar los parámetros de configuración creados en el panel de control del Motor de Búsqueda Programable. Esto te permite crear una experiencia de búsqueda específica para la página. Por ejemplo, el siguiente código crea un cuadro de búsqueda que abre una página de resultados (http://www.example.com?search=lady+gaga) en una ventana nueva. El valor del atributo queryParameterName, junto con la cadena de consulta del usuario, se usa para crear la URL de resultados.

Ten en cuenta que el atributo queryParameterName tiene el prefijo data-. Este prefijo es obligatorio para todos los atributos.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

Si usaste el panel de control del Motor de Búsqueda Programable para habilitar funciones como autocompletar o perfeccionamientos, puedes usar atributos para personalizarlas. Cualquier personalización que especifiques con estos atributos anulará la configuración realizada en el panel de control. En el siguiente ejemplo, se crea un elemento de búsqueda de dos columnas con los siguientes atributos:

  • La administración del historial está habilitada
  • La cantidad máxima de opciones de autocompletado que se muestran se establece en 5
  • Las refinamientos se muestran como vínculos.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

Atributos admitidos

Atributo Tipo Descripción Componente
General
gname String Un nombre para el objeto del elemento de búsqueda (opcional). Un nombre se usa para recuperar un componente asociado por nombre o para vincular un componente searchbox con un componente searchresults. Si no se proporciona, el Motor de Búsqueda Programable generará automáticamente un gname, según el orden de los componentes de la página web. Por ejemplo, la primera searchbox-only sin nombre tiene el gname "searchbox-only0", la segunda tiene la gname "seachbox-only1", y así sucesivamente. Ten en cuenta que el gname generado automáticamente para un componente con diseño de dos columnas será two-column. En el siguiente ejemplo, se usa gname storesearch para vincular un componente searchbox con un componente searchresults:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Cuando se recupera un objeto, si más de un componente tiene el mismo gname, Programmable Search Engine usará el último componente de la página.

Cualquiera
autoSearchOnLoad Booleano Especifica si se debe ejecutar una búsqueda mediante la consulta incorporada en la URL de la página que se está cargando. Ten en cuenta que una cadena de consulta debe estar presente en la URL para ejecutar la búsqueda automática. Valor predeterminado: true. Cualquiera
enableHistory Booleano Si es true, se habilita la administración del historial para los botones Atrás y Avanzar del navegador. Mira una demostración.

searchbox

solo cuadro de búsqueda

queryParameterName String El nombre del parámetro de consulta, por ejemplo, q (predeterminado) o query Se incorporará en la URL (por ejemplo, http://www.example.com?q=lady+gaga). Ten en cuenta que especificar solo el nombre del parámetro de consulta no activa la búsqueda automática durante la carga. Debe haber una cadena de consulta en la URL para ejecutar la búsqueda automática. Cualquiera
resultsUrl URL La URL de la página de resultados. (La configuración predeterminada es la página alojada en Google). solo cuadro de búsqueda
newWindow Booleano Especifica si la página de resultados se abre en una ventana nueva. Valor predeterminado: false. solo cuadro de búsqueda
ivt Booleano

Este parámetro te permite proporcionar un valor booleano que le informa a Google que deseas permitir anuncios que usan una cookie de tráfico no válido y un almacenamiento local tanto en el tráfico con consentimiento como en el que no.

true Cuando este parámetro no esté presente o lo configures como "true", configuraremos una cookie exclusiva de tráfico no válido y usaremos el almacenamiento local solo en el tráfico que se otorgue con consentimiento.

false Si estableces este parámetro en "false", configuraremos una cookie de solo tráfico no válido y usaremos el almacenamiento local tanto en el tráfico con consentimiento como en el que no.

Valor predeterminado: false

Ejemplo de uso: <div class="gcse-search" data-ivt="true"></div>

resultadosdebúsqueda

solo resultados de búsqueda

mobileLayout String

Especifica si los estilos de diseño para dispositivos móviles deben utilizarse para dispositivos móviles.

enabled Utiliza el diseño móvil solo en dispositivos móviles.

disabled No utiliza el diseño móvil para ningún dispositivo.

forced Usa el diseño móvil para todos los dispositivos.

Valor predeterminado: enabled

Ejemplo de uso: <div class="gcse-search" data-mobileLayout="disabled"></div>

Cualquiera
Autocompletar
enableAutoComplete Booleano Solo está disponible si se habilitó la función de autocompletar en el panel de control del Motor de Búsqueda Programable. true habilita la función de autocompletar. Cualquiera
autoCompleteMaxCompletions Número entero La cantidad máxima de opciones de autocompletado que se mostrará.

searchbox

solo cuadro de búsqueda

autoCompleteMaxPromotions Número entero La cantidad máxima de promociones que se muestran en autocompletar.

searchbox

solo cuadro de búsqueda

autoCompleteValidLanguages String Es la lista separada por comas de los idiomas en los que se debería habilitar la función de autocompletar. Idiomas compatibles.

searchbox

solo cuadro de búsqueda

Mejoras
defaultToRefinement String Solo está disponible si se crearon mejoras en el panel de control del Motor de Búsqueda Programable. Especifica la etiqueta de perfeccionamiento predeterminada que se mostrará.Nota: Este atributo no es compatible con el diseño alojado en Google. Cualquiera
refinementStyle String Los valores aceptables son tab (predeterminado) y link. link solo se admite si la búsqueda con imágenes está inhabilitada o si la búsqueda de imágenes está habilitada, pero la búsqueda web está inhabilitada.

resultadosdebúsqueda

solo resultados de búsqueda

Búsqueda de imágenes
enableImageSearch Booleano Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Si es true, habilita la búsqueda de imágenes. Los resultados de las imágenes se mostrarán en una pestaña aparte.

resultadosdebúsqueda

solo resultados de búsqueda

defaultToImageSearch Booleano Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Si el valor es true, la página de resultados de búsqueda mostrará resultados de la búsqueda de imágenes de forma predeterminada. Los resultados web estarán disponibles en una pestaña aparte.

Cualquiera
imageSearchLayout String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Especifica el diseño de la página de resultados de búsqueda de imágenes. Los valores aceptables son classic, column o popup.

resultadosdebúsqueda

solo resultados de búsqueda

imageSearchResultSetSize Entero, cadena Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Especifica el tamaño máximo del conjunto de resultados de la búsqueda para la búsqueda con imágenes. Por ejemplo, large, small, filtered_cse y 10.

Cualquiera
image_as_filetype String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Restringe los resultados a los archivos de una extensión especificada.

Las extensiones admitidas son jpg, gif, png, bmp, svg, webp, ico y raw.

Cualquiera

image_as_oq String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Filtra los resultados de la búsqueda con un OR lógico.

Ejemplo de uso si quieres obtener resultados de la búsqueda que incluyan "term1" o "term2":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

Cualquiera

image_as_rights String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Filtros basados en licencias.

Los valores admitidos son cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived y combinaciones de estos.

Consulta las combinaciones típicas.

Cualquiera

image_as_sitesearch String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Restringe los resultados a páginas de un sitio específico.

Ejemplo de uso: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

Cualquiera

image_colortype String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Restringe la búsqueda a imágenes en blanco y negro (mono), en escala de grises o en color. Los valores admitidos son mono, gray y color.

Cualquiera

image_cr String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Restringe los resultados de la búsqueda a los documentos que se originan en un país en particular.

Valores admitidos

Cualquiera

image_dominantcolor String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Restringe la búsqueda a las imágenes de un color dominante específico. Los valores admitidos son red, orange, yellow, green, teal, blue, purple, pink, white, gray, black y brown.

Cualquiera

image_filter String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Filtrado automático de los resultados de la búsqueda.

Valores admitidos: 0/1

Ejemplo de uso: <div class="gcse-search" data-image_filter="0"></div>

Cualquiera

image_gl String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable. Optimiza los resultados de la búsqueda cuyo país de origen coincida con el valor del parámetro.

Valores admitidos

Cualquiera

image_size String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Muestra imágenes de un tamaño especificado, en el que el tamaño puede ser uno de los siguientes: icon, small, medium, large, xlarge, xxlarge o huge.

Cualquiera

image_sort_by String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Ordena los resultados con fecha o con otro contenido estructurado.

Para ordenar por relevancia, usa una cadena vacía (image_sort_by="").

Ejemplo de uso: <div class="gcse-search" data-image_sort_by="date"></div>

Cualquiera

image_type String Solo está disponible si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

Restringe la búsqueda a imágenes de un tipo específico. Los valores admitidos son clipart (Clip Art), face (Rostros de personas), lineart (Dibujos de líneas), stock (Fotos de archivo), photo (Fotografías) y animated (GIF animados).

Cualquiera

Búsqueda web
disableWebSearch Booleano Si el valor es true, se inhabilita la búsqueda web. Por lo general, se usa solo si se habilitó la búsqueda de imágenes en el panel de control del Motor de Búsqueda Programable.

resultadosdebúsqueda

solo resultados de búsqueda

webSearchQueryAddition String Se agregaron términos adicionales a la búsqueda con un operador lógico OR.

Ejemplo de uso: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

Cualquiera
webSearchResultSetSize Entero, cadena El tamaño máximo del conjunto de resultados. Se aplica a la búsqueda con imágenes y en la Web. El valor predeterminado depende del diseño y de si el Motor de Búsqueda Programable está configurado para buscar en toda la Web o solo en sitios específicos. Entre los valores aceptables, se incluyen los siguientes:
  • Un número entero entre 1 y 20
  • small: Solicita un conjunto de resultados pequeño, por lo general, 4 resultados por página.
  • large: Solicita un conjunto de resultados grande, por lo general, 8 resultados por página.
  • filtered_cse: Solicita hasta 10 resultados por página, para un máximo de 10 páginas o 100 resultados.
Cualquiera
webSearchSafesearch String Especifica si SafeSearch está habilitado para los resultados de búsqueda. Los valores aceptados son off y active. Cualquiera
as_filetype String Restringe los resultados a los archivos de una extensión especificada. Puedes encontrar una lista de los tipos de archivos indexables por Google en el Centro de ayuda de Search Console.

Cualquiera

as_oq String Filtra los resultados de la búsqueda con un OR lógico.

Ejemplo de uso si quieres obtener resultados de la búsqueda que incluyan "term1" o "term2":<div class="gcse-search" data-as_oq="term1 term2"></div>

Cualquiera
as_rights String Filtros basados en licencias.

Los valores admitidos son cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived y combinaciones de estos.

Para conocer las combinaciones típicas, consulta https://wiki.creativecommons.org/wiki/CC_Search_integration.

Cualquiera

as_sitesearch String Restringe los resultados a páginas de un sitio específico.

Ejemplo de uso: <div class="gcse-search" data-as_sitesearch="example.com"></div>

Cualquiera
cr String Restringe los resultados de la búsqueda a los documentos que se originan en un país en particular.

Valores admitidos

Ejemplo de uso: <div class="gcse-search" data-cr="countryFR"></div>

Cualquiera
filter String Filtrado automático de los resultados de la búsqueda.

Valores admitidos: 0/1

Ejemplo de uso: <div class="gcse-search" data-filter="0"></div>

Cualquiera
gl String Optimiza los resultados de la búsqueda cuyo país de origen coincida con el valor del parámetro.

Solo funcionará si se define en el parámetro language value.

Valores admitidos

Ejemplo de uso: <div class="gcse-search" data-gl="fr"></div>

Cualquiera
lr String Restringe los resultados de la búsqueda a los documentos escritos en un idioma específico.

Valores admitidos

Ejemplo de uso: <div class="gcse-search" data-lr="lang_fr"></div>

Cualquiera
sort_by String Ordena los resultados con fecha o con otro contenido estructurado. El valor del atributo debe ser una de las opciones proporcionadas en la configuración de Orden de resultados de la búsqueda programable.

Para ordenar por relevancia, usa una cadena vacía (sort_by="").

Ejemplo de uso: <div class="gcse-search" data-sort_by="date"></div>

Cualquiera
Resultados de la búsqueda
enableOrderBy Booleano Habilita el orden de resultados por relevancia, fecha o etiqueta. Cualquiera
linkTarget String Establece el destino del vínculo. Valor predeterminado: _blank.

resultadosdebúsqueda

solo resultados de búsqueda

noResultsString String Especifica el texto predeterminado que se mostrará cuando no haya resultados que coincidan con la consulta. La string de resultado predeterminada se puede usar para mostrar una string localizada en todos los idiomas admitidos, mientras que la personalizada no lo hace.

resultadosdebúsqueda

solo resultados de búsqueda

resultSetSize Entero, cadena El tamaño máximo del conjunto de resultados. Por ejemplo, large, small, filtered_cse y 10. Este depende del diseño y de si el motor está configurado para buscar en toda la Web o solo en sitios específicos. Cualquiera
safeSearch String Especifica si SafeSearch está habilitado para la búsqueda web y de imágenes. Los valores aceptados son off y active. Cualquiera

Devoluciones de llamada

Diagrama de secuencia de devolución de llamada
diagrama de secuencias de devoluciones de llamada de JavaScript del elemento de búsqueda

Las devoluciones de llamada admiten el control detallado de la inicialización de elementos de búsqueda y los procesos de búsqueda. Se registran con el elemento de búsqueda de JavaScript en JavaScript a través del objeto __gcse global. En Registrar devoluciones de llamada, se muestra el registro de todas las devoluciones de llamada compatibles.

Registrar devoluciones de llamada

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };
  

Devolución de llamada de inicialización

Se invoca la devolución de llamada de inicialización antes de que JavaScript del elemento de búsqueda renderice los elementos de búsqueda en el DOM. Si parsetags se configura como explicit en __gcse, el JavaScript del elemento de búsqueda deja el procesamiento de los elementos de búsqueda en la devolución de llamada de inicialización (como se muestra en Registrar devoluciones de llamada). Puede usarse a fin de seleccionar elementos para renderizar o para diferir la renderización de elementos hasta que sean necesarios. También puede anular los atributos de los elementos; por ejemplo, puede convertir un cuadro de búsqueda configurado a través del Panel de control o los atributos HTML de forma predeterminada en un cuadro de búsqueda de imágenes o especificar que las consultas enviadas a través de un formulario del Motor de Búsqueda Programable se ejecuten en un elemento solo de resultados de búsqueda. Mira una demostración.

El valor de la propiedad parsetags de __gcse controla la función de la devolución de llamada de inicialización.

  • Si su valor es onload, el elemento de búsqueda JavaScript renderiza todos los elementos de búsqueda en la página automáticamente. La devolución de llamada de inicialización se sigue invocando, pero no es responsable de renderizar los elementos de búsqueda.
  • Si su valor es explicit, el elemento de búsqueda JavaScript no procesa esos elementos. La devolución de llamada puede renderizarlos de forma selectiva con la función render() o renderizar todos los elementos de búsqueda con la función go().

En el siguiente código, se muestra cómo renderizar un cuadro de búsqueda, junto con los resultados de la búsqueda, en un div, mediante la etiqueta de análisis explicit y la devolución de llamada de inicialización:

Ejemplo de devolución de llamada de inicialización

Debemos incluir un elemento <div> con un valor de ID en el que nos gustaría el código del elemento de búsqueda:

    <div id="test"></div>
Agrega este JavaScript después de <div>. Ten en cuenta que hace referencia a test, el id que usamos para identificar el <div>
const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};
.

Incluye este código HTML para comenzar a cargar el elemento de búsqueda. Reemplaza el valor cx en la cláusula src por tu propio cx.

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

Buscar devoluciones de llamada

El elemento de búsqueda de JavaScript admite seis devoluciones de llamada que operan en el flujo de control de búsqueda. Las devoluciones de llamada de búsqueda vienen en pares, una devolución de llamada de búsqueda web y una devolución de llamada de búsqueda de imágenes coincidente:

  • Iniciando la búsqueda
    • Para la búsqueda de imágenes
    • Para la búsqueda web
  • Resultados listos
    • Para la búsqueda de imágenes
    • Para la búsqueda web
  • Resultados renderizados
    • Para la búsqueda de imágenes
    • Para la búsqueda web

Al igual que la devolución de llamada de inicialización,las devoluciones de llamada de búsqueda se configuran mediante entradas en el objeto __gcse. que sucede cuando se inicia JavaScript en el elemento de búsqueda. Se ignoran las modificaciones en __gcse después del inicio.

Cada una de estas devoluciones de llamada recibe el gName del elemento de búsqueda como argumento. El gname es útil cuando una página contiene más de una búsqueda. Proporciona valores gname a un elemento de búsqueda con el atributo data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

Si el código HTML no identifica el gname, el elemento JavaScript de búsqueda genera un valor que se mantiene coherente hasta que se modifica el código HTML.

Devolución de llamada de inicio de búsqueda web/imagen

Las devoluciones de llamada de inicio de la búsqueda se invocan inmediatamente antes de que el JavaScript del elemento de búsqueda solicite resultados de la búsqueda de su servidor. Un ejemplo de caso práctico sería usar la hora local del día para controlar los cambios en la consulta.

searchStartingCallback(gname, query)
gname
String de identificación del elemento de búsqueda
query
Es el valor
que ingresa el usuario (posiblemente modificado por el elemento de búsqueda JavaScript).

La devolución de llamada muestra el valor que se debe usar como consulta para esta búsqueda. Si muestra una string vacía, se ignora el valor que se muestra y el emisor usa la consulta sin modificar.

Como alternativa, puedes colocar la función de devolución de llamada en el objeto __gcse o agregar de forma dinámica la devolución de llamada al objeto con JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Ejemplo de devolución de llamada de inicio de búsqueda

La devolución de llamada de inicio de búsqueda de ejemplo en Ejemplo de devolución de llamada de inicio de búsqueda agrega morning o afternoon a la consulta según la hora del día.

Ejemplo de devolución de llamada de inicio de búsqueda
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

Instala esta devolución de llamada en window.__gcse:

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      image: {
        starting: 'myImageSearchStartingCallbackName',
      },
      web: {
        starting: myWebSearchStartingCallback,
      },
    };
  
  <script
  async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Devolución de llamada lista de resultados de la búsqueda web/imagen

Estas devoluciones de llamada se invocan inmediatamente antes de que JavaScript del elemento de búsqueda renderice promociones y resultados. Un ejemplo de caso de uso sería una devolución de llamada que procesa promociones y genera un estilo que no se puede especificar con una personalización normal.

resultsReadyCallback(gname, query, promos, results, div)
gname
String de identificación del elemento de búsqueda
query
consulta que produjo estos resultados
promos
Es un array de objetos de promoción que corresponden a las promociones coincidentes de la consulta del usuario. Consulta la definición del objeto de promoción.
results
Es un array de objetos de resultado. Consulta la definición del objeto del resultado.
div
Es un div HTML posicionado en el DOM en el que el elemento de búsqueda normalmente colocaría promociones y resultados de la búsqueda. Normalmente, el elemento de búsqueda JavaScript se encarga de propagar este div, pero la devolución de llamada puede detener el procesamiento automático de los resultados y usar este div para renderizar los resultados por sí mismo.

Si esta devolución de llamada muestra un valor true, el elemento de búsqueda de JavaScript omite el trabajo del pie de página.

Devolución de llamada de resultados de ejemplo listos

La devolución de llamada resultsReady de ejemplo en Devolución de llamada de resultados listos para el ejemplo anula la presentación predeterminada de promociones y resultados con un reemplazo muy simple.

Ejemplo de devolución de llamada de resultados listos
    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

Instala esta devolución de llamada en window.__gcse:

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Al igual que con la devolución de llamada de inicio de la búsqueda, la anterior es una de las muchas maneras de colocar la devolución de llamada en el objeto __gcse.

Devolución de llamada procesada de los resultados de la búsqueda web o de imágenes

Estas devoluciones de llamada se invocan inmediatamente antes de que JavaScript del elemento de búsqueda renderice el pie de página de la página. Algunos casos prácticos de ejemplo incluyen una devolución de llamada que agrega contenido de resultados que el elemento de búsqueda no muestra, como una casilla de verificación para guardar esto o información que no se procesa automáticamente, o una devolución de llamada que agrega botones para obtener más información.

Si una devolución de llamada de resultados renderizados necesita información que estaba en los parámetros promos y results de la devolución de llamada de resultados listos, puede pasarla entre ellos de la siguiente manera:

callback(gname, query, promoElts, resultElts);
gname
String de identificación del elemento de búsqueda
query
cadena de búsqueda.
promoElts
Es un array de los elementos del DOM que contienen promociones.
resultElts
Es un array de los elementos del DOM que contienen resultados.

No hay un valor de retorno.

Devolución de llamada renderizada de resultados de ejemplo

La devolución de llamada resultsRendered de ejemplo en Devolución de llamada renderizada de resultados de ejemplo agrega una casilla de verificación ficticia Keep a cada promoción y resultado.

Ejemplo de devolución de llamada renderizada de resultados
myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

Instala esta devolución de llamada en window.__gcse:

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Si la devolución de llamada de resultados renderizados necesita información que se pasó a la devolución de llamada de resultados listos, puede pasar esos datos entre las devoluciones de llamada. En el siguiente ejemplo, se muestra una de las muchas maneras de pasar un valor de calificación de richSnippet de la devolución de llamada de resultados listos a la devolución de llamada de renderizado de resultados.

Ejemplo de la devolución de llamada de resultados listos que coopera con la devolución de llamada de resultados renderizados
const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};
Instala esta devolución de llamada con un código como el siguiente mientras configuras __gcse:
const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Más ejemplos de devolución de llamada

Puedes encontrar ejemplos adicionales de devoluciones de llamada en el documento Más ejemplos de devoluciones de llamada.

Propiedades de promoción y resultado

Con la notación JSDoc, estas son las propiedades de los objetos promotion y result. Aquí, enumeramos todas las propiedades que podrían estar presentes. La presencia de muchas de las propiedades depende de los detalles de la promoción o del resultado de la búsqueda.

Propiedades de la promoción
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
Propiedades del objeto del resultado
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

richSnippet en results tiene el tipo libre de un array de objetos. Los datos estructurados que se encuentran en la página web controlan los valores de las entradas de este array de cada resultado de la búsqueda. Por ejemplo, un sitio web de opiniones podría incluir datos estructurados que agreguen esta entrada de array a richSnippet:

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},
.

API de Programmable Search Element Control (V2)

El objeto google.search.cse.element publica las siguientes funciones estáticas:

Función Descripción
.render(componentConfig, opt_componentConfig) Renderiza un elemento de búsqueda.

Parámetros

Nombre Descripción
componentConfig Es la configuración de un componente del Elemento de Búsqueda Programable. Especifica lo siguiente:
  • div (string|Element): Es el id del <div> o el elemento div en el que se renderizará el elemento de Búsqueda Programable.
  • tag (string): Es el tipo de componentes que se renderizarán. (Cuando se proporciona opt_componentConfig, el valor del atributo tag debe ser searchbox). Los valores permitidos son los siguientes:
    • search: Un cuadro de búsqueda y los resultados de la búsqueda, juntos
    • searchbox: Es un componente de cuadro de búsqueda de un elemento de Búsqueda Programable.
    • searchbox-only: Es un cuadro de búsqueda independiente que se asociará con un bloque de resultados de la búsqueda especificado por opt_componentConfig en un diseño de dos columnas.
    • searchresults-only: Es un bloque independiente de resultados de la búsqueda. Las búsquedas se activan mediante un parámetro de búsqueda incorporado en una URL o mediante la ejecución programática.
  • gname (string): Opcional: Es un nombre único para este componente. Si no se proporciona, el Motor de Búsqueda Programable generará automáticamente un gname.
  • attributes (objeto): Atributos opcionales en forma de un par clave-valor. Atributos admitidos.
opt_componentConfig Opcional. Segundo argumento de configuración del componente. Se usa en modo TWO_COLUMN para proporcionar el componente searchresults. Especifica lo siguiente:
  • div (string): Es el id del <div> o del elemento div en el que se renderizará el elemento.
  • tag (string): Es el tipo de componentes que se renderizarán. Cuando se proporciona opt_componentConfig, el valor del atributo tag debe ser searchresults. Además, el valor del atributo tag de componentConfig debe ser searchbox.
  • gname (string): Opcional: Es un nombre único para este componente. Si no se proporciona, Motor de Búsqueda Programable generará automáticamente un gname para este componente. Si se proporciona, debe coincidir con gname en componentConfig.
  • attributes (objeto): Atributos opcionales en forma de par clave-valor. Atributos admitidos.
.go(opt_container) Renderiza todas las etiquetas o clases de elementos de búsqueda en el contenedor especificado.

Parámetros

Nombre Descripción
opt_container El contenedor que contiene los componentes del elemento de búsqueda que se renderizarán. Especifica el ID del contenedor (string) o el elemento en sí. Si se omite, se renderizarán todos los componentes del Elemento de búsqueda programable dentro de la etiqueta body de la página.
.getElement(gname) Obtiene el objeto de elemento de gname. Si no lo encuentras, muestra un valor nulo.

El objeto element que se muestra tiene los siguientes atributos:

  • gname: Es el nombre del objeto del elemento. Si no se proporciona, el Motor de Búsqueda Programable generará automáticamente un gname para el objeto. Obtén más información.
  • type: Es el tipo de elemento.
  • uiOptions: Son los atributos finales que se usan para renderizar el elemento.
  • execute: función(string): Ejecuta una consulta programática.
  • prefillQuery - Función(string): Completa previamente el cuadro de búsqueda con una cadena de consulta sin ejecutar la consulta.
  • getInputQuery - function(): Obtiene el valor actual que se muestra en el cuadro de entrada.
  • clearAllResults - function(): Borra el control ocultando todo excepto el cuadro de búsqueda, si corresponde.

El siguiente código ejecuta la búsqueda "news" en el elemento de búsqueda "element1":

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() Muestra un mapa de todos los objetos de elementos creados correctamente, con la clave gname.