Puoi incorporare i componenti del Motore di ricerca programmabile (caselle di ricerca e pagine dei risultati di ricerca) nelle tue pagine web e in altre applicazioni web utilizzando il markup HTML. Questi elementi di Motore di ricerca programmabile sono costituiti da componenti di cui viene eseguito il rendering in base alle impostazioni archiviate dal server Ricerca programmabile, oltre alle eventuali personalizzazioni apportate.
Tutto il codice JavaScript viene caricato in modo asincrono, il che consente alla tua pagina web di continuare a caricarsi mentre il browser recupera il codice JavaScript di Motore di ricerca programmabile.
Introduzione
Questo documento fornisce un modello di base per aggiungere elementi di Motore di ricerca programmabile alla tua pagina web, oltre a spiegazioni dei componenti configurabili dell'elemento e dell'API JavaScript flessibile.
Ambito
Questo documento descrive come utilizzare le funzioni e le proprietà specifiche dell'API Programmable Search Engine Control.
Compatibilità del browser
Puoi trovare l'elenco dei browser supportati dal Motore di ricerca programmabile qui.
Pubblico
Questa documentazione è rivolta agli sviluppatori che vogliono aggiungere la funzionalità Ricerca programmabile alle proprie pagine.
Elementi di Ricerca programmabile
Puoi utilizzare il markup HTML per aggiungere un Elemento di ricerca programmabile alla tua pagina. Ogni elemento è costituito da almeno un componente: una casella di ricerca, un blocco di risultati di ricerca o entrambi. La casella di ricerca accetta l'input utente in uno dei seguenti modi:
- Una query di ricerca digitata nel campo di immissione testo
- Una stringa di query incorporata in un URL.
- Esecuzione programmatica
Inoltre, il blocco dei risultati di ricerca accetta l'input nei seguenti modi:
- Una stringa di query incorporata in un URL.
- Esecuzione programmatica
Sono disponibili i seguenti tipi di Elementi di Ricerca programmabile:
| Tipo di elemento | Componenti | Descrizione |
|---|---|---|
| standard | <div class="gcse-search"> |
Una casella di ricerca e i risultati di ricerca, visualizzati nello stesso <div>. |
| due colonne | <div class="gcse-searchbox"> e <div class="gcse-searchresults"> |
Un layout a due colonne con i risultati di ricerca su un lato e una casella di ricerca dall'altro. Se prevedi di inserire più elementi in modalità a due colonne nella pagina web, puoi utilizzare l'attributo gname per associare una casella di ricerca a un blocco di risultati di ricerca. |
| solo casella di ricerca | <div class="gcse-searchbox-only"> |
Una casella di ricerca autonoma. |
| solo risultati di ricerca | <div class="gcse-searchresults-only"> |
Un blocco autonomo di risultati di ricerca. |
Puoi aggiungere il numero illimitato di elementi di ricerca validi alla tua pagina web. Per la modalità a due colonne, tutti i componenti obbligatori (una casella di ricerca e un blocco dei risultati di ricerca) devono essere presenti.
Ecco un esempio di un semplice elemento di ricerca:
<!-- 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>
Scrivi 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 con Elementi di ricerca programmabili. Per visualizzare una demo di queste opzioni, fai clic sul link.
| Opzione | Componenti |
|---|---|
| Larghezza massima | <div class="gcse-search"> |
| Compatto | <div class="gcse-search"> |
| A due colonne | <div class="gcse-searchbox">, <div class="gcse-searchresults"> |
| Due pagine | <div class="gcse-searchbox-only"> sulla prima pagina, <div class="gcse-searchresults-only"> (o altri componenti) sulla seconda pagina. |
| Solo risultati | <div class="gcse-searchresults-only"> |
| In hosting su Google | <div class="gcse-searchbox-only"> |
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 pannello di controllo di Motore di ricerca programmabile. In questo modo puoi creare un'esperienza di ricerca specifica per la pagina.
Ad esempio, il codice seguente crea una casella di ricerca che apre una pagina dei risultati (http://www.example.com?search=lady+gaga) in una nuova finestra. Il valore dell'attributo queryParameterName, insieme alla stringa di query dell'utente, vengono utilizzati 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 il completamento automatico o i perfezionamenti, puoi utilizzare gli attributi per personalizzare queste funzionalità. Le eventuali personalizzazioni specificate con questi attributi sostituiranno le impostazioni definite nel pannello di controllo. L'esempio seguente crea un elemento di ricerca a due colonne con le seguenti caratteristiche:
- La gestione della cronologia è attivata
- 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
| Attributo | Tipo | Descrizione | Componente |
|---|---|---|---|
| Generali | |||
gname |
Stringa | (Facoltativo) Un nome per l'oggetto Elemento di ricerca. Un nome viene utilizzato per recuperare un componente associato in base al nome o per associare un componente searchbox a un componente searchresults. Se non viene specificato,
Motore di ricerca programmabile genererà automaticamente un valore gname in base
all'ordine dei componenti della pagina web. Ad esempio, il primo searchbox-only senza nome ha gname "searchbox-only0" e il secondo gname "seachbox-only1" e così via.
Tieni presente che il valore gname generato automaticamente per un componente nel layout a due colonne sarà two-column. L'esempio seguente
utilizza il nome gname storesearch per collegare un componente searchbox
a un componente searchresults:
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> Quando recuperi un oggetto, se più componenti hanno lo stesso |
Qualsiasi |
autoSearchOnLoad |
Booleano | Specifica se eseguire una ricerca tramite la query incorporata nell'URL della pagina in fase di caricamento. Tieni presente che per eseguire la ricerca automatica è necessario che nell'URL sia presente una stringa di query. Valore predefinito: true. |
Qualsiasi |
enableHistory |
Booleano | Se true, abilita la gestione della cronologia per i pulsanti Indietro
e Avanti del browser. Guarda una demo. |
searchbox solo casella di ricerca |
queryParameterName |
Stringa | Il nome del parametro di query, ad esempio q (predefinito)
o query. Verrà incorporato nell'URL (ad esempio,
http://www.example.com?q=lady+gaga). Tieni presente che specificare solo il nome del parametro di ricerca non attiva la ricerca automatica al caricamento. Per eseguire la ricerca automatica, è necessario che nell'URL sia presente una stringa di query. |
Qualsiasi |
resultsUrl |
URL | L'URL della pagina dei risultati. (L'impostazione predefinita è la pagina ospitata da Google). | solo casella di ricerca |
newWindow |
Booleano | Specifica se la pagina dei risultati si apre in una nuova finestra.
Valore predefinito: false. |
solo casella di ricerca |
ivt |
Booleano |
Questo parametro ti consente di fornire un valore booleano che indichi a Google che vuoi consentire gli annunci che utilizzano un cookie di solo traffico non valido e spazio di archiviazione locale sia per il traffico per cui è stato fornito il consenso che per quelli che non lo hanno fornito.
URL predefinito: Esempio di utilizzo: |
risultati di ricerca solo risultati di ricerca |
mobileLayout |
Stringa |
Consente di specificare se gli stili di layout per dispositivi mobili devono essere utilizzati.
URL predefinito: Esempio di utilizzo: |
Qualsiasi |
| Completamento automatico | |||
enableAutoComplete |
Booleano | Disponibile solo se è stato abilitato il completamento automatico nel pannello di controllo di Motore di ricerca programmabile.
true attiva il completamento automatico. |
Qualsiasi |
autoCompleteMaxCompletions |
Numero intero | Il numero massimo di completamenti automatici da visualizzare. | searchbox solo casella di ricerca |
autoCompleteMaxPromotions |
Numero intero | Il numero massimo di risultati promossi da visualizzare nel completamento automatico. | searchbox solo casella di ricerca |
autoCompleteValidLanguages |
Stringa | Elenco separato da virgole delle lingue per cui è necessario abilitare il completamento automatico. Lingue supportate. | searchbox solo casella di ricerca |
| Perfezionamenti | |||
defaultToRefinement |
Stringa | Disponibile solo se sono stati creati perfezionamenti nel pannello di controllo di Motore di ricerca programmabile. Specifica l'etichetta di perfezionamento predefinita da visualizzare.Nota: questo attributo non è supportato per il layout ospitato da Google. | Qualsiasi |
refinementStyle |
Stringa | I valori accettati sono tab (valore predefinito) e link.
link è supportato solo se la ricerca immagini è disabilitata o se la ricerca di immagini è abilitata, ma la ricerca web è disabilitata. |
risultati di ricerca solo risultati di ricerca |
| Ricerca immagini | |||
enableImageSearch |
Booleano | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Se |
risultati di ricerca solo risultati di ricerca |
defaultToImageSearch |
Booleano | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Se |
Qualsiasi |
imageSearchLayout |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Specifica il layout della pagina dei risultati di ricerca di immagini. I valori accettati sono |
risultati di ricerca solo risultati di ricerca |
imageSearchResultSetSize |
Numero intero, stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Specifica la dimensione massima dei risultati di ricerca impostati per la ricerca di immagini.
Ad esempio, |
Qualsiasi |
image_as_filetype |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Limita i risultati ai file con un'estensione specificata. Le estensioni supportate sono | Qualsiasi |
image_as_oq |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Filtra i risultati di ricerca utilizzando l'operatore logico OR. Esempio di utilizzo se vuoi che i risultati di ricerca includano "term1" o "term2": | Qualsiasi |
image_as_rights |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Filtri basati sulle licenze. I valori supportati sono Vedi le combinazioni tipiche. | Qualsiasi |
image_as_sitesearch |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Limita i risultati alle pagine di un sito specifico. Esempio di utilizzo: | Qualsiasi |
image_colortype |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Limita la ricerca alle immagini in bianco e nero (mono), in scala di grigi o a colori. I valori supportati sono | Qualsiasi |
image_cr |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Limita i risultati di ricerca a documenti provenienti da un determinato paese. | Qualsiasi |
image_dominantcolor |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Limita la ricerca alle immagini di un colore dominante specifico.
I valori supportati sono | Qualsiasi |
image_filter |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Filtro automatico dei risultati di ricerca. Valori supportati: 0/1 Esempio di utilizzo: | Qualsiasi |
image_gl |
Stringa | Disponibile solo se è stata abilitata la ricerca immagini nel pannello di controllo di Motore di ricerca programmabile. Migliora i risultati di ricerca il cui paese di origine corrisponde al valore parametro. | Qualsiasi |
image_size |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Restituisce immagini di una dimensione specificata che può essere una delle seguenti: | Qualsiasi |
image_sort_by |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Ordina i risultati utilizzando dati o altri contenuti strutturati. Per ordinare i dati in base alla pertinenza, utilizza una stringa vuota (image_sort_by=""). Esempio di utilizzo: | Qualsiasi |
image_type |
Stringa | Disponibile solo se è stata abilitata la
ricerca immagini nel pannello di controllo di Motore di ricerca programmabile.
Limita la ricerca alle immagini di un tipo specifico.
I valori supportati sono | Qualsiasi |
| Ricerca web | |||
disableWebSearch |
Booleano | Se true, disattiva la ricerca web. Di solito viene utilizzato solo se la
ricerca immagini è stata abilitata nel pannello di controllo di Motore di ricerca programmabile. |
risultati di ricerca solo risultati di ricerca |
webSearchQueryAddition |
Stringa | Sono stati aggiunti termini aggiuntivi alla query di ricerca utilizzando l'operatore logico OR.
Esempio di utilizzo: |
Qualsiasi |
webSearchResultSetSize |
Numero intero, stringa | La dimensione massima dell'insieme di risultati. Si applica sia alla ricerca di immagini sia alla ricerca web. Il valore predefinito dipende dal layout e dal fatto che il Motore di ricerca programmabile sia configurato per eseguire ricerche in tutto il web o solo su determinati siti. I valori accettati includono:
|
Qualsiasi |
webSearchSafesearch |
Stringa |
Specifica se SafeSearch è abilitato per i risultati di ricerca web. I valori accettati sono off e active.
|
Qualsiasi |
as_filetype |
Stringa | Limita i risultati ai file con un'estensione specificata. Puoi trovare un elenco dei tipi di file indicizzabili da Google nel Centro assistenza Search Console. | Qualsiasi |
as_oq |
Stringa | Filtra i risultati di ricerca utilizzando l'operatore logico OR.
Esempio di utilizzo se vuoi che i risultati di ricerca includano "term1" o "term2": |
Qualsiasi |
as_rights |
Stringa | Filtri basati sulle licenze.
I valori supportati sono Consulta la pagina https://wiki.creativecommons.org/wiki/CC_Search_integration per le combinazioni tipiche. | Qualsiasi |
as_sitesearch |
Stringa | Limita i risultati alle pagine di un sito specifico.
Esempio di utilizzo: |
Qualsiasi |
cr |
Stringa | Limita i risultati di ricerca a documenti provenienti da un determinato paese.
Esempio di utilizzo: |
Qualsiasi |
filter |
Stringa | Filtro automatico dei risultati di ricerca.
Valori supportati: 0/1 Esempio di utilizzo: |
Qualsiasi |
gl |
Stringa | Migliora i risultati di ricerca il cui paese di origine corrisponde al valore parametro.
Funziona solo in combinazione con l'impostazione valore lingua. Esempio di utilizzo: |
Qualsiasi |
lr |
Stringa | Limita i risultati di ricerca a documenti scritti in una determinata lingua.
Esempio di utilizzo: |
Qualsiasi |
sort_by |
Stringa | Ordina i risultati utilizzando dati o altri contenuti strutturati. Il valore dell'attributo deve essere una delle opzioni fornite nelle impostazioni di Ordinamento dei risultati del gruppo di ricerca programmabile.
Per ordinare i dati in base alla pertinenza, utilizza una stringa vuota (sort_by=""). Esempio di utilizzo: |
Qualsiasi |
| Risultati di ricerca | |||
enableOrderBy |
Booleano | Consente di ordinare i risultati per pertinenza, data o etichetta. | Qualsiasi |
linkTarget |
Stringa | Imposta la destinazione del link. Valore predefinito: _blank. |
risultati di ricerca solo risultati di ricerca |
noResultsString |
Stringa | Specifica il testo predefinito da visualizzare quando nessun risultato corrisponde alla query. La stringa dei risultati predefinita può essere utilizzata per visualizzare una stringa localizzata in tutte le lingue supportate, mentre quella personalizzata no. | risultati di ricerca solo risultati di ricerca |
resultSetSize |
Numero intero, stringa | La dimensione massima dell'insieme di risultati. Ad esempio, large,
small, filtered_cse, 10. Il valore predefinito dipende dal layout e dalla configurazione del motore per la ricerca in tutto il Web o solo nei siti specificati. |
Qualsiasi |
safeSearch |
Stringa | Specifica se
SafeSearch è abilitato sia per la ricerca web sia per la ricerca di immagini. I valori accettati sono off
e active. |
Qualsiasi |
Richiamate
I callback supportano un controllo dettagliato dei processi di inizializzazione e ricerca degli elementi di ricerca.
Sono registrate con JavaScript dell'elemento di ricerca tramite l'oggetto __gcse globale. Registra callback illustra 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 degli elementi di ricerca nel DOM. Se parsetags è impostato su explicit in
__gcse, il codice JavaScript dell'elemento di ricerca lascia il rendering degli elementi di ricerca
al callback di inizializzazione (come mostrato in Registrare i callback).
Questa opzione può essere utilizzata per selezionare gli elementi di cui eseguire il rendering o per posticipare gli elementi di rendering finché non sono necessari. Può anche eseguire l'override degli attributi degli elementi; ad esempio, può trasformare una casella di ricerca configurata tramite gli attributi del pannello di controllo o HTML in modo che esegua per impostazione predefinita la ricerca web in una casella di ricerca di immagini oppure specificare che le query inviate tramite un modulo di Motore di ricerca programmabile vengano eseguite in un elemento solo dei risultati di ricerca.
Guarda una demo.
Il ruolo del callback di inizializzazione è controllato dal valore della proprietà parsetags
di __gcse.
- Se il valore è
onload, il codice JavaScript dell'elemento di ricerca esegue automaticamente il rendering di tutti gli elementi di ricerca della pagina. Il callback di inizializzazione viene ancora richiamato, ma non è responsabile del rendering degli elementi di ricerca. - Se il valore è
explicit, il codice JavaScript dell'elemento di ricerca non esegue il rendering degli elementi di ricerca. Il callback può eseguire il rendering degli elementi in modo selettivo utilizzando la funzionerender()oppure di tutti gli elementi di ricerca con la funzionego().
Il seguente codice mostra come visualizzare una casella di ricerca, insieme ai risultati di ricerca, in un
div, utilizzando il tag di analisi explicit e il callback di inizializzazione:
Dobbiamo includere un elemento <div> con un valore ID
dove vogliamo il codice dell'elemento di ricerca:
<div id="test"></div>
Aggiungi questo codice JavaScript dopo <div>. Tieni presente che
fa riferimento a test, il id che abbiamo utilizzato per identificare
<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
};
Includi questo codice HTML per iniziare a caricare l'elemento di ricerca. Sostituisci il valore cx nella
clausola src con il tuo cx.
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
Cerca callback
Il codice JavaScript dell'elemento di ricerca supporta sei callback che operano nel flusso di controllo della ricerca. I callback di ricerca sono disponibili in coppie, con un callback di ricerca web e un callback di ricerca immagini corrispondente:
- Inizio della ricerca
- Per la ricerca immagini
- Per la ricerca web
- Risultati pronti
- Per la ricerca immagini
- Per la ricerca web
- Risultati visualizzati
- Per la ricerca immagini
- Per la ricerca web
Come il callback di inizializzazione,i callback di ricerca vengono configurati utilizzando le voci nell'oggetto __gcse. Questo accade quando viene avviato il codice JavaScript dell'elemento di ricerca. Le modifiche apportate a __gcse dopo l'avvio vengono ignorate.
A ognuno di questi callback viene passato il gName per
l'elemento di ricerca come argomento.
gname è utile quando una pagina contiene più di una ricerca. Assegna un valore gname a un elemento di ricerca utilizzando l'attributo data-gname:
<div class="gcse-searchbox" data-gname="storesearch"></div>
Se il codice HTML non identifica il gname, il codice JavaScript dell'elemento di ricerca genera un valore che rimarrà coerente fino alla modifica dell'HTML.
Richiamata di avvio/ricerca web di immagini
I callback di avvio della ricerca vengono richiamati immediatamente prima che il codice JavaScript dell'elemento di ricerca richieda i risultati di ricerca al suo server. Un caso d'uso di esempio potrebbe essere l'utilizzo dell'ora locale del giorno per controllare le modifiche alla query.
searchStartingCallback(gname, query)
gname- Stringa identificativa dell'elemento di ricerca
query- inserito dall'utente (possibilmente modificato dal codice JavaScript dell'elemento di ricerca).
Il callback restituisce il valore da utilizzare come query per questa ricerca. Se restituisce una 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 aggiungere dinamicamente il callback all'oggetto con JavaScript:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Esempio di callback iniziale della rete di ricerca
L'esempio di callback di inizio della ricerca in Esempio di callback di avvio della ricerca aggiunge morning o afternoon alla query in base all'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>
Richiamata di immagini/risultati della ricerca web-Pronto
Questi callback vengono richiamati immediatamente prima che il codice JavaScript dell'elemento di ricerca mostri promozioni e risultati. Un caso d'uso di esempio potrebbe essere un callback che esegue il rendering di promozioni e risultati in 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 promozionali, che corrispondono alle promozioni corrispondenti alla query dell'utente. Consulta la definizione dell'oggetto promozione.
results- un array di oggetti risultato. Consulta la definizione dell'oggetto risultato.
div- un div HTML posizionato nel DOM nel punto in cui l'elemento di ricerca normalmente posizionerebbe promozioni e risultati di ricerca. In genere, il codice JavaScript dell'elemento di ricerca gestisce il completamento di questo div, ma questo callback potrebbe scegliere di interrompere il rendering automatico dei risultati e utilizzare questo
divper il rendering dei risultati.
Se questo callback restituisce un valore true, il codice JavaScript dell'elemento di ricerca salta
al suo lavoro a piè di pagina.
Richiamata di risultati di esempio pronta
Il callback resultsReady di esempio in
Esempio di callback di risultati pronti 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;
};
Installa questo callback in 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>
Come per il callback di avvio della ricerca, quello riportato sopra è uno dei tanti modi per inserire il callback nell'oggetto
__gcse.
Callback di immagini/risultati della ricerca web-rendering
Questi callback vengono richiamati immediatamente prima che il codice JavaScript dell'elemento di ricerca esegua il rendering del piè di pagina della pagina. Esempi di casi d'uso potrebbero includere un callback in cui vengono aggiunti contenuti dei risultati che l'elemento di ricerca non mostra, ad esempio una casella di controllo Salva, informazioni che non vengono visualizzate automaticamente oppure un callback che aggiunge pulsanti per ulteriori informazioni.
Se un callback con rendering dei risultati richiede informazioni che erano contenute nei parametri promos e results del callback risultati pronti, può trasmetterle tra loro, 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 contenenti promozioni.
resultElts- un array di elementi DOM contenenti i risultati.
Non viene restituito alcun valore.
Callback sottoposto a rendering dei risultati di esempio
Il callback resultsRendered di esempio in
Richiamato visualizzato dei risultati di esempio aggiunge una casella di controllo fittizia Keep
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);
}
};
Installa questo callback in 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>
Se il callout dei risultati visualizzati richiede le informazioni che sono state trasmesse al callout dei risultati pronti, può passare questi dati tra i callback. L'esempio seguente mostra uno dei molti modi per trasmettere un valore di valutazione da
richSnippet dal callback pronto per i risultati al callback con visualizzazione dei risultati
.
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};
};__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>
Altri esempi di callback
Ulteriori esempi di callback sono disponibili nel documento Altri esempi di callback.
Proprietà di promozioni e risultati
Utilizzando la notazione JSDoc, queste sono le proprietà degli oggetti promotion e result. Qui sono elencate tutte le proprietà che potrebbero essere presenti. La presenza di molte proprietà dipende 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 nei risultati include il tipo libero di un array di oggetti. I valori delle voci in questo array sono controllati dai dati strutturati che si trovano nella pagina web per ogni risultato di ricerca. Ad esempio, un sito web di recensioni potrebbe includere dati strutturati che aggiungono questa voce dell'array a richSnippet:
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},
API Programmable Search Element Control (V2)
L'oggetto google.search.cse.element pubblica le seguenti
funzioni statiche:
| Funzione | Descrizione | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
Esegue il rendering di un elemento di ricerca.
Parametri
|
||||||
.go(opt_container) |
Visualizza tutti i tag/le classi dell'elemento di ricerca nel contenitore specificato.
Parametri
|
||||||
.getElement(gname) |
Restituisce l'oggetto dell'elemento tramite gname. Se non lo trovi, restituisci null.
L'oggetto
Il seguente codice esegue la query "news" nell'elemento di ricerca "element1": var element = google.search.cse.element.getElement('element1');
element.execute('news');
|
||||||
.getAllElements() |
Restituisce una mappa di tutti gli oggetti elemento creati correttamente, digitati da gname. |