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:

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.

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

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

Devoluciones de llamada

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.

  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:

    <div id="test"></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
};

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

    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.

    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;
    };

  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>

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.

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);
    }
  };

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.

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};
};

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.

{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}

{
  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:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');