API de Programmable Search Element Control

Puedes incorporar componentes de Motor de Búsqueda Programable (cuadros de búsqueda y páginas de resultados de búsqueda) en sus páginas web y otras aplicaciones web con lenguaje de marcado HTML. Estos Motores de Búsqueda Programable son componentes renderizados a partir de la configuración almacenada por en el servidor de Programmable Search, junto con todas las personalizaciones que realice.

Todo JavaScript se carga de forma asíncrona, lo que permite que tu página web continúa cargándose mientras el navegador recupera el código JavaScript del Motor de Búsqueda Programable.

Introducción

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

Alcance

En este documento, se describe cómo utilizar las funciones y propiedades específicas de la API de Programmable Search Engine Control.

Compatibilidad con navegadores

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

Público

Esta documentación está dirigida a los desarrolladores que quieran agregar los programas Función de búsqueda en sus páginas.

Elementos de Búsqueda Programable

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

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

Además, el bloque de resultados de búsqueda acepta entradas en de la siguiente manera:

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

Están disponibles los siguientes tipos de elementos de Programmable Search:

Tipo de elemento Componentes Descripción
standard <div class="gcse-search"> Un cuadro de búsqueda y resultados de la búsqueda se muestra 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 de 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 en el cuadro de búsqueda <div class="gcse-searchbox-only"> Un cuadro de búsqueda independiente
searchresults-only <div class="gcse-searchresults-only"> Un bloque independiente de resultados de búsqueda.

Puedes agregar cualquier cantidad de elementos de búsqueda válidos a tu página web. Para dos columnas todos los componentes necesarios (un cuadro de búsqueda y del bloque de resultados) debe estar presente.

Este es 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>

Redacta diferentes opciones de diseño con los elementos de Programmable Search

Las siguientes opciones de diseño están disponibles en la página Apariencia y estilo del panel de control del Motor de Búsqueda Programable. Estos son algunos lineamientos generales para redactar opciones de diseño con los Elementos Programables de Búsqueda. 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, <div class="gcse-searchresults-only"> (o algún otro componente) en la segunda página.
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.

Personaliza 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 Apariencia y estilo de tu motor de búsqueda programable.

Puedes usar atributos opcionales para reemplazar las configuraciones creadas en el Motor de Búsqueda Programable panel de control. 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 el atributo queryParameterName, junto con la cadena de consulta del usuario, se que se usó 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 personalizar esas funciones. Cualquier personalización que especifiques con estos atributos anulará la configuración establecida en el panel de control. En el siguiente ejemplo, se crea un elemento de búsqueda de dos columnas con las siguientes funciones:

  • La administración del historial está habilitada
  • La cantidad máxima de opciones de autocompletado que se muestra se estableció en 5
  • Las mejoras 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 Elemento de búsqueda (opcional). Un nombre se usa para recuperar un componente asociado por nombre, o bien para vincular un searchbox con un componente searchresults. Si no se proporciona, El Motor de Búsqueda Programable generará automáticamente un gname basado en el orden de los componentes en la página web. Por ejemplo, la primera sin nombre searchbox-only tiene la gname "cuadro de búsqueda-solo0" y el segundo tiene el gname “seachbox-only1”, y así sucesivamente. Ten en cuenta que el gname generado automáticamente para un componente en el diseño de dos columnas será two-column. El siguiente ejemplo usa gname storesearch para vincular un 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, Motor de Búsqueda Programable usará el último componente del .

Cualquiera
autoSearchOnLoad Booleano Especifica si se debe ejecutar una búsqueda a través de la consulta incorporada en la URL. de la página que se está cargando. Ten en cuenta que la URL debe incluir una cadena de consulta. para ejecutar la búsqueda automática. Valor predeterminado: true. Cualquiera
enableHistory Booleano Si es true, se habilita la administración del historial para el botón Atrás del navegador y Reenviar. Mira una demostración.

cuadro de búsqueda

solo en el cuadro de búsqueda

queryParameterName String El nombre del parámetro de consulta, por ejemplo, q (predeterminado) o query. Esta información se incorporará en la URL (por ejemplo, http://www.example.com?q=lady+gaga). Ten en cuenta que especificar el El nombre del parámetro de consulta por sí solo no activa la búsqueda automática durante la carga. Una consulta tiene que estar presente 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 en el cuadro de búsqueda
newWindow Booleano Especifica si la página de resultados se abre en una ventana nueva. Valor predeterminado: false. solo en el cuadro de búsqueda
ivt Booleano

Este parámetro te permite proporcionar un valor booleano para informar a Google que deseas permitir anuncios que usan una cookie solo para tráfico no válido almacenamiento local en bases de datos el tráfico sin consentimiento.

true Cuando este parámetro no está presente o lo configuras como "true", estableceremos una cookie no válida solo para tráfico no válido y usar el almacenamiento local solo en el tráfico con consentimiento.

false Si estableces este parámetro como "false" estableceremos una política las cookies solo para el tráfico y usar el almacenamiento local en el tráfico con consentimiento y sin consentimiento.

Valor predeterminado: false

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

resultadosdebúsqueda

searchresults-only

mobileLayout String

Especifica si los estilos de diseño para dispositivos móviles deben usarse en este tipo de dispositivos.

enabled: Solo usa el diseño para dispositivos móviles.

disabled No se usa el diseño para dispositivos móviles en ningún dispositivo.

forced Usa el diseño para dispositivos móviles de 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á.

cuadro de búsqueda

solo en el cuadro de búsqueda

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

cuadro de búsqueda

solo en el cuadro de búsqueda

autoCompleteValidLanguages String Lista de idiomas separados por comas para los que se debe usar la función de autocompletar habilitado. Idiomas admitidos.

cuadro de búsqueda

solo en el cuadro de búsqueda

Mejoras
defaultToRefinement String Disponible solo si se crearon mejoras en el Panel de control del Motor de Búsqueda Programable Especifica la etiqueta de perfeccionamiento predeterminada para display.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 con imágenes está habilitada, pero la búsqueda web está inhabilitada.

resultadosdebúsqueda

searchresults-only

Búsqueda con imágenes
enableImageSearch Booleano Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable.

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

resultadosdebúsqueda

searchresults-only

defaultToImageSearch Booleano Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable.

Si es true, la página de resultados de búsqueda mostrará resultados de la búsqueda de imágenes de forma predeterminada. Los resultados de la Web estarán disponibles en otra pestaña.

Cualquiera
imageSearchLayout String Disponible solo si se habilitó la búsqueda con 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. Valores aceptables son classic, column o popup.

resultadosdebúsqueda

searchresults-only

imageSearchResultSetSize Número entero, cadena Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable.

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

Cualquiera
image_as_filetype String Disponible solo si se habilitó la búsqueda con 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 compatibles son jpg, gif, png, bmp, svg, webp, ico y raw.

Cualquiera

image_as_oq String Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable.

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

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

Cualquiera

image_as_rights String Disponible solo si se habilitó la búsqueda con 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 Disponible solo si se habilitó la búsqueda con 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 Disponible solo si se habilitó la búsqueda con 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), escala de grises o en color. Los valores admitidos son mono, gray y color.

Cualquiera

image_cr String Disponible solo si se habilitó la búsqueda con 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 Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable.

Restringe la búsqueda a 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 Disponible solo si se habilitó la búsqueda con 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 Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable. Mejora los resultados de la búsqueda cuyo país de origen coincida con el valor del parámetro.

Valores admitidos

Cualquiera

image_size String Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable.

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

Cualquiera

image_sort_by String Disponible solo si se habilitó la búsqueda con imágenes en el panel de control del Motor de Búsqueda Programable.

Ordena los resultados con la fecha o con otro contenido estructurado.

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

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

Cualquiera

image_type String Disponible solo si se habilitó la búsqueda con 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 (imágenes prediseñadas), face (rostros de personas), lineart (dibujos lineales), stock (fotos de archivo), photo (fotografías) y animated (GIF animados).

Cualquiera

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

resultadosdebúsqueda

searchresults-only

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

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

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

Cualquiera

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

Ejemplo de uso si quieres resultados de la búsqueda que incluyan "término1" 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 ver 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 Mejora los resultados de la búsqueda cuyo país de origen coincida con el valor del parámetro.

Esto solo funcionará junto con la configuración de valor de idioma.

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 en particular.

Valores admitidos

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

Cualquiera
sort_by String Ordena los resultados con la 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 del egnine de búsqueda programable.

Para ordenar por relevancia, utiliza 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 los resultados por relevancia, fecha o etiqueta. Cualquiera
linkTarget String Establece el destino del vínculo. Valor predeterminado: _blank.

resultadosdebúsqueda

searchresults-only

noResultsString String Especifica el texto predeterminado que se muestra cuando no hay resultados que coincidan con la consulta. La cadena de resultados predeterminada se puede usar para mostrar una cadena localizada en todos idiomas admitidos, mientras que el personalizado no.

resultadosdebúsqueda

searchresults-only

resultSetSize Número entero, cadena El tamaño máximo del conjunto de resultados. Por ejemplo, large, small, filtered_cse y 10 El la opción predeterminada depende del diseño y de si el motor está configurado para buscar toda la Web o solo 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 la secuencia de devolución de llamada
diagrama de secuencias de devoluciones de llamada de elementos de búsqueda de JavaScript

Las devoluciones de llamada admiten un control detallado de la inicialización de elementos de búsqueda y los procesos de búsqueda. Se registran con JavaScript del elemento de búsqueda a través del __gcse global. . Registrar devoluciones de llamada ilustra el registro de todos los las devoluciones de llamada admitidas.

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

La devolución de llamada de inicialización se invoca antes de que el JavaScript del elemento de búsqueda renderice la búsqueda. elementos en el DOM. Si parsetags se establece en explicit en __gcse, el JavaScript del elemento de búsqueda deja la renderización de los elementos de búsqueda en devolución de llamada de inicialización (como se muestra en Cómo registrar devoluciones de llamada). Se puede usar para seleccionar los elementos que se renderizarán o para diferir la renderización de los elementos hasta que se según tus necesidades. También puede anular los atributos de los elementos; por ejemplo, puede convertir una en el cuadro de búsqueda que se configura mediante el Panel de control o los atributos HTML buscar en un cuadro de búsqueda de imágenes o especificar que las consultas enviadas a través de un formulario de Motor de Búsqueda Programable se se ejecuta en un elemento searchresults-only. Mira una demostración.

La función de la devolución de llamada de inicialización está controlada por el valor de parsetags propiedad de __gcse.

  • Si su valor es onload, el elemento de búsqueda JavaScript procesa todos los elementos de búsqueda de la página automáticamente. La devolución de llamada de inicialización se aún se invoca, pero no es responsable de renderizar los elementos de búsqueda.
  • Si su valor es explicit, no se renderiza el JavaScript del elemento de búsqueda. Buscar elementos. La devolución de llamada puede representarlas de manera selectiva con la función render(), o renderiza todos los elementos de búsqueda con la función go()

El siguiente código demuestra cómo representar un cuadro de búsqueda, junto con los resultados de la búsqueda, en una div, con 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 <div> con un valor de ID. donde queremos 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 la <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 Cláusula src con tu propio cx

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

Buscar devoluciones de llamada

El JavaScript del elemento de búsqueda admite seis devoluciones de llamada que operan en el 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 la devolución de llamada de búsqueda de imágenes correspondiente:

  • Inicio de la búsqueda
    • Para la búsqueda con imágenes
    • Para búsquedas web
  • Resultados listos
    • Para la búsqueda con imágenes
    • Para búsquedas web
  • Resultados renderizados
    • Para la búsqueda con imágenes
    • Para búsquedas web

Al igual que la devolución de llamada de inicialización,se hace lo siguiente con las devoluciones de llamada de búsqueda: y se configura con entradas en el objeto __gcse. Esto sucede cuando el Elemento Se inicia JavaScript. Se ignorarán las modificaciones que se realicen en __gcse después del inicio.

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

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

Si el HTML no identifica el gname, el JavaScript del elemento de búsqueda genera un valor que y que mantenga su coherencia hasta que se modifique el código HTML.

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

Las devoluciones de llamada de inicio de búsqueda se invocan inmediatamente antes de las solicitudes de JavaScript del elemento de búsqueda resultados de la búsqueda desde su servidor. Un ejemplo de caso de uso sería usar la hora local del día para control de cambios en la consulta.

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

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

También puedes colocar la función de devolución de llamada en el objeto __gcse o Agrega dinámicamente 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 búsqueda de ejemplo inicia la devolución de llamada 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 de resultados de búsqueda web/imagen lista

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

resultsReadyCallback(gname, query, promos, results, div)
gname
String de identificación del elemento de búsqueda
query
búsqueda que produjo estos resultados
promos
un array de objetos de promoción, que corresponden a objetos coincidentes. promociones del 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 resultante.
div
un div de HTML posicionado en el DOM, donde normalmente el elemento de búsqueda se colocaría promociones de lugares y resultados de la búsqueda. Normalmente, el Elemento de búsqueda JavaScript se encarga de Se propaga este elemento div, pero esta devolución de llamada puede detener la renderización automática de los resultados. y usa este div para renderizar los resultados.

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

Devolución de llamada lista de los resultados de ejemplo

La devolución de llamada resultsReady de ejemplo en La devolución de llamada de resultados de ejemplo lista anula la presentación predeterminada. de promociones y resultados con un reemplazo muy sencillo.

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 que inicia la búsqueda, la opción anterior es una de las muchas formas de colocar la devolución de llamada en la __gcse.

Devolución de llamada renderizada para los resultados de la búsqueda web o la imagen

Estas devoluciones de llamada se invocan inmediatamente antes de que el JavaScript del elemento de búsqueda renderice la página. pie de página. Los casos de uso de ejemplo incluyen una devolución de llamada que agrega contenido de resultados que la búsqueda no se muestra, como la casilla de verificación Guardar este o información que no se muestra se renderiza 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 promos y results parámetros de la devolución de llamada de resultados listos, puedes pasarlos 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 contiene resultados.

No se muestra ningún valor.

Devolución de llamada de resultados renderizados de ejemplo

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

Ejemplo de devolución de llamada de resultados renderizados
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 pasada a la devolución de llamada de resultados listos, puede pasar esos datos las devoluciones de llamada. El siguiente ejemplo muestra una de las muchas maneras de pasar un valor de calificación desde richSnippet de la devolución de llamada de resultados listos a la devolución de resultados renderizados. devolución de llamada.

. Ejemplo de 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 este cuando configures __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 devoluciones de llamada

Puedes encontrar ejemplos adicionales de devolución de llamada en el Más ejemplos de devoluciones de llamadas.

Propiedades de la promoción y los resultados

Con la notación JSDoc, estas son las propiedades de promotion y result. Aquí, enumeramos todas las propiedades que podrían estar presentes. La presencia de muchas de las propiedades dependen 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 suelto de un array de lo siguiente: objetos. Los valores de las entradas en este array son controlados por el datos estructurados que se encuentran en la página web para cada resultado de búsqueda. Por ejemplo, un sitio web de reseñas puede incluir Datos estructurados que agregan 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 lo siguiente: funciones estáticas:

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

Parámetros

Nombre Descripción
componentConfig La configuración de un componente de Elemento de Búsqueda Programable. Especifica lo siguiente:
  • div (string|Element): Es el id del elemento <div> o div en el que se renderizará el elemento Programmable Search.
  • tag (cadena): 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 resultados de la búsqueda, que se muestran 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 sincronizará 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 (cadena): Es un nombre único para este componente (opcional). Si no se proporciona, el Motor de Búsqueda Programable generará automáticamente un elemento gname.
  • attributes (Objeto): Atributos opcionales en forma de par clave-valor. Atributos admitidos:
opt_componentConfig Opcional. Es el segundo argumento de configuración del componente. Se utiliza en TWO_COLUMN para proporcionar el componente searchresults. Especifica lo siguiente:
  • div (cadena): El id de <div> o el elemento div en el que se renderizará.
  • tag (cadena): Es el tipo de componentes que se renderizarán. Cuándo Se proporciona opt_componentConfig, el valor de tag. debe ser searchresults. Además, el valor de la Atributo tag de componentConfig debe ser searchbox.
  • gname (cadena): Es un nombre único para este componente (opcional). Si no es así Si se proporciona, el Motor de Búsqueda Programable generará automáticamente un gname para esta este componente. Si se proporciona, debe coincidir con gname en componentConfig
  • attributes (Objeto): Atributos opcionales con el formato de un par clave-valor par. Atributos admitidos.
.go(opt_container) Renderiza todas las etiquetas o clases de elemento de búsqueda del contenedor especificado.

Parámetros

Nombre Descripción
opt_container El contenedor que contiene los componentes del Elemento de búsqueda que se renderizarán. Especificar el ID del contenedor (cadena) o del elemento en sí. Si omitido, todos los componentes del Elemento de Búsqueda Programable dentro del Se renderizará body etiqueta.
.getElement(gname) Obtiene el objeto de elemento de gname. Si no lo encuentras, se 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, 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 consulta. sin ejecutar la consulta.
  • getInputQuery - function(): Obtiene el valor actual que se muestra en la entrada. .
  • clearAllResults: function(): Borra el control ocultando todo, excepto el cuadro de búsqueda, si lo hay.

El siguiente código ejecuta la consulta "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.