API Programmable Search Element Control

Puoi incorporare i componenti del Motore di ricerca programmabile (caselle di ricerca e pagine dei risultati di ricerca) in le tue pagine web e altre applicazioni web utilizzando il markup HTML. Il Motore di ricerca programmabile sono costituiti da componenti il cui rendering viene eseguito in base alle impostazioni il server di ricerca programmabile, insieme alle personalizzazioni che apporti.

Tutto il codice JavaScript viene caricato in modo asincrono, il che consente alla tua pagina web di continuano a caricare mentre il browser recupera il codice JavaScript di Motore di ricerca programmabile.

Introduzione

Questo documento fornisce un modello di base per l'aggiunta di Motore di ricerca programmabile elementi alla tua pagina web, insieme alle spiegazioni del relativo componenti configurabili e API JavaScript flessibile.

Ambito

Questo documento descrive come utilizzare le funzioni e le proprietà specifiche di: l'API Programmable Search Engine Control.

Compatibilità del browser

È possibile trovare l'elenco dei browser supportati da Motore di ricerca programmabile qui

Pubblico

Questa documentazione è destinata agli sviluppatori che vogliono aggiungere prodotti la funzionalità di ricerca nelle pagine.

Elementi di ricerca programmabile

Puoi utilizzare il markup HTML per aggiungere un Elemento di ricerca programmabile alla tua pagina. Ciascuna è costituito da almeno un componente: una casella di ricerca, un blocco di ricerca o entrambi i risultati. La casella di ricerca accetta l'input utente in uno dei seguenti modi:

• Una query di ricerca digitata nel campo di immissione del testo
• Una stringa di query incorporata in un URL
• Esecuzione programmatica

Inoltre, il blocco di risultati di ricerca accetta l'input nei nei seguenti modi:

• Una stringa di query incorporata in un URL
• Esecuzione programmatica

Sono disponibili i seguenti tipi di Elementi di ricerca programmabili:

Puoi aggiungere alla tua pagina web il numero desiderato di elementi di ricerca validi, Per due colonne automatica, tutti i componenti necessari (una casella di ricerca e di ricerca) deve essere presente.

Ecco un esempio di elemento di ricerca semplice:

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

Crea diverse opzioni di layout utilizzando Elementi di ricerca programmabili

Le seguenti opzioni di layout sono disponibili nella pagina Aspetto e design del pannello di controllo di Motore di ricerca programmabile. Di seguito sono riportate alcune linee guida generali sulla composizione delle opzioni di layout utilizzando Elementi di ricerca programmabili. Fai clic sul link per visualizzare una demo di queste opzioni.

Scopri di più sulle opzioni di layout.

Personalizzazione degli elementi di ricerca programmabile

Per personalizzare i colori, il carattere o lo stile dei link, vai alla pagina Aspetto e design del tuo motore di ricerca programmabile.

Puoi utilizzare attributi facoltativi per sovrascrivere le configurazioni create nel Motore di ricerca programmabile pannello di controllo. In questo modo puoi creare un'esperienza di ricerca specifica per la pagina. Ad esempio, il seguente codice crea una casella di ricerca che apre una pagina dei risultati (http://www.example.com?search=lady+gaga) in una nuova finestra. Il valore del parametro L'attributo queryParameterName, insieme alla stringa di query dell'utente, è utilizzato per creare l'URL dei risultati.

Tieni presente che l'attributo queryParameterName è preceduto dal prefisso data-. Questo prefisso è obbligatorio per tutti gli attributi.

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

Se hai utilizzato il pannello di controllo di Motore di ricerca programmabile per attivare funzionalità come completamento automatico o perfezionamenti, puoi utilizzare gli attributi per personalizzarle. Eventuali personalizzazioni specificate utilizzando questi attributi le impostazioni configurate nel pannello di controllo verranno sostituite. L'esempio seguente crea un elemento di ricerca a due colonne con le seguenti funzionalità:

• La gestione della cronologia è abilitata
• Il numero massimo di completamenti automatici visualizzati è impostato su 5
• I perfezionamenti vengono visualizzati come link.

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

Attributi supportati

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

Callback

I callback supportano il controllo dettagliato dell'inizializzazione degli elementi di ricerca e dei processi di ricerca. Sono registrati con l'elemento di ricerca JavaScript tramite la __gcse globale . L'opzione Registra callback mostra la registrazione di tutti i callback supportati.

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

Il callback di inizializzazione

Il callback di inizializzazione viene richiamato prima che il codice JavaScript dell'elemento di ricerca esegua il rendering della nel DOM. Se parsetags è impostato su explicit in __gcse, il codice JavaScript dell'elemento di ricerca lascia il rendering degli elementi di ricerca alla callback di inizializzazione (come mostrato in Registra callback). Può essere usato per selezionare gli elementi da visualizzare o per rinviare gli elementi di rendering finché necessaria. Può anche sostituire gli attributi degli elementi; Ad esempio, può trasformare casella di ricerca configurata tramite il Pannello di controllo o gli attributi HTML in modo che sia web eseguire una ricerca in una casella di ricerca di immagini o specificare che le query inviate tramite un modulo di Motore di ricerca programmabile eseguita in un elemento solo per i risultati di ricerca. Guarda una demo.

Il ruolo del callback di inizializzazione è controllato dal valore dell'attributo parsetags proprietà di __gcse.

• Se il suo valore è onload, l'elemento di ricerca JavaScript esegue automaticamente il rendering di tutti gli elementi di ricerca presenti sulla pagina. Il callback di inizializzazione è ancora richiamato, ma non è responsabile del rendering degli elementi di ricerca.
• Se il valore è explicit, il codice JavaScript dell'elemento di ricerca non viene visualizzato Elementi di ricerca. Il callback può mostrarli in modo selettivo utilizzando Funzione render(), oppure eseguire il rendering di tutti gli elementi di ricerca con la funzione go()

Il codice seguente mostra come eseguire il rendering di una casella di ricerca, insieme ai risultati di ricerca, in un div, utilizzando il tag di analisi explicit e il callback di inizializzazione:

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

Cerca callback

Search Element JavaScript supporta sei callback che operano nel parametro flusso di controllo della ricerca. I callback di ricerca vengono forniti in coppia, un callback di ricerca web e un callback di ricerca immagini corrispondente:

• Inizio della ricerca
  • Per la ricerca immagini
  • Per ricerca web
• Risultati pronti
  • Per la ricerca immagini
  • Per ricerca web
• Risultati visualizzati
  • Per la ricerca immagini
  • Per ricerca web

Come il callback di inizializzazione,i callback di ricerca vengono configurato utilizzando le voci nell'oggetto __gcse. Ciò accade quando l'elemento di ricerca JavaScript viene avviato. Le modifiche apportate a __gcse dopo l'avvio vengono ignorate.

Ciascuno di questi callback viene passato il gName per l'elemento di ricerca come argomento. gname è utile quando una pagina contiene più di una ricerca. Effettua una ricerca l'elemento a gname utilizza l'attributo data-gname:

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

Se l'HTML non identifica il gname, il codice JavaScript dell'elemento di ricerca genera un valore che rimangono coerenti finché l'HTML non viene modificato.

Callback di avvio della ricerca tramite immagine/Web

I callback di avvio della ricerca vengono richiamati immediatamente prima delle richieste JavaScript di Search Element i risultati di ricerca dal suo server. Un caso d'uso di esempio è l'uso dell'ora locale del giorno per le modifiche apportate alla query.

searchStartingCallback(gname, query)

gname

Stringa identificativa dell'elemento di ricerca

query

valore inserito dall'utente (eventualmente modificato dalla ricerca JavaScript).

Il callback restituisce il valore da utilizzare come query per questa ricerca. Se restituisce un stringa vuota, il valore restituito viene ignorato e il chiamante utilizza la query non modificata.

In alternativa, puoi inserire la funzione di callback nell'oggetto __gcse o aggiungi dinamicamente il callback all'oggetto con JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};

Esempio di callback di avvio della ricerca

Esempio di ricerca all'avvio del callback in Esempio di callback all'inizio della ricerca aggiunge morning o afternoon alla query a seconda dell'ora del giorno.

    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

Installa questo callback in 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>

Callback pronto per i risultati di ricerca di immagini/Web

Questi callback vengono richiamati immediatamente prima che l'elemento di ricerca JavaScript esegua il rendering delle promozioni e che consentono di analizzare i dati e visualizzare i risultati. Un caso d'uso di esempio è un callback che esegue il rendering delle promozioni e genera uno stile che non può essere specificato con la personalizzazione normale.

resultsReadyCallback(gname, query, promos, results, div)

gname

Stringa identificativa dell'elemento di ricerca

query

query che ha prodotto questi risultati

promos

un array di oggetti di promozione, che corrispondono a promozioni per la query dell'utente. Consulta la definizione dell'oggetto promozione.

results

un array di oggetti dei risultati. Consulta le definizione dell'oggetto risultato.

div

Un div HTML posizionato nel DOM in cui l'elemento di ricerca di solito verrebbe fatto risultati di ricerca e promozioni di luoghi. Normalmente, il codice JavaScript dell'elemento di ricerca questo div, ma questo callback potrebbe scegliere di interrompere il rendering automatico dei risultati e usa questo div per visualizzare i risultati stessi.

di Gemini Advanced.

Se questo callback restituisce un valore true, il codice JavaScript dell'elemento di ricerca passa al relativo lavoro a piè di pagina di pagina.

Callback di risultati di esempio pronto

Il callback resultsReady di esempio in Il callback pronto per i risultati di esempio sostituisce la presentazione predefinita di promozioni e risultati con una sostituzione molto semplice.

    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>

Callback visualizzato nei risultati della ricerca di immagini/web

Questi callback vengono richiamati immediatamente prima che il codice JavaScript dell'elemento di ricerca esegua il rendering della pagina. piè di pagina. I casi d'uso di esempio includono un callback che aggiunge contenuti dei risultati che la ricerca dell'elemento non viene visualizzato, ad esempio una casella di controllo Salva questo o informazioni non visualizzato automaticamente o un callback che aggiunge pulsanti per ulteriori informazioni.

Se un callback nei risultati di cui è stato eseguito il rendering richiede le informazioni nei promos e results del callback per i risultati pronti, può passare da uno all'altro in questo modo:

callback(gname, query, promoElts, resultElts);

gname

Stringa identificativa dell'elemento di ricerca

query

stringa di ricerca.

promoElts

un array di elementi DOM contenente promozioni.

resultElts

un array di elementi DOM contenente i risultati.

Non è presente alcun valore restituito.

Callback visualizzato per risultati di esempio

Il callback resultsRendered di esempio in Risultati di esempio sottoposti a callback aggiunge un valore Keep fittizio casella di controllo a ogni promozione e risultato.

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>

Se è necessario il callback per i risultati visualizzati informazioni passate al callback per i risultati pronti, può trasmettere questi dati tra i callback. L'esempio seguente mostra uno dei molti modi per passare un valore di valutazione da richSnippet dal callback per risultati pronti ai risultati visualizzati il callback.

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>

Altri esempi di callback

Puoi trovare altri esempi di callback nel Documento Altri esempi di callback.

Proprietà delle promozioni e dei risultati

Se usi la notazione JSDoc, queste sono le proprietà promotion e result. Qui sono elencate tutte le proprietà che potrebbero essere presenti. La presenza di molte strutture dipendono dai dettagli della promozione o del risultato di ricerca.

{
  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 in results contiene il tipo libero di un array di di oggetti strutturati. I valori delle voci in questo array sono controllati dati strutturati trovati sulla pagina web per ogni risultato di ricerca. Ad esempio, un sito web di recensioni potrebbe includere dati strutturati che aggiungono questa voce di array a richSnippet:

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

API Programmable Search Element Control (V2)

L'oggetto google.search.cse.element pubblica quanto segue funzioni statiche:

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