Mithilfe von HTML-Markup können Sie Programmable Search Engine-Komponenten (Suchfelder und Suchergebnisseiten) in Ihre Webseiten und andere Webanwendungen einbetten. Diese Elemente der Programmable Search Engine bestehen aus Komponenten, die basierend auf den vom Server gespeicherten Einstellungen sowie den von Ihnen vorgenommenen Anpassungen gerendert werden.
Der gesamte JavaScript-Code wird asynchron geladen. Ihre Webseite kann also weiterhin geladen werden, während der Browser das Programmable Search Engine-JavaScript abruft.
Einführung
In diesem Dokument findest du ein grundlegendes Modell zum Hinzufügen von Programmable Search Engine-Elementen zu deiner Webseite. Außerdem werden die konfigurierbaren Komponenten des Elements und die flexible JavaScript API erläutert.
Umfang
In diesem Dokument wird beschrieben, wie die spezifischen Funktionen und Eigenschaften der Programmable Search Engine Control API verwendet werden.
Browserkompatibilität
Eine Liste der von der Programmable Search Engine unterstützten Browser finden Sie hier.
Zielgruppe
Diese Dokumentation richtet sich an Entwickler, die ihren Seiten Funktionen für die programmierbare Google Suche hinzufügen möchten.
Elemente der programmierbaren Suche
Mithilfe von HTML-Markup können Sie Ihrer Seite ein programmierbares Suchelement hinzufügen. Jedes Element besteht aus mindestens einer Komponente: einem Suchfeld und/oder einem Block mit Suchergebnissen. Das Suchfeld akzeptiert Nutzereingaben auf folgende Weise:
- Eine in das Texteingabefeld eingegebene Suchanfrage
- Einen in eine URL eingebetteten Abfragestring
- Programmatische Ausführung
Darüber hinaus akzeptiert der Suchergebnisblock folgende Eingaben:
- Einen in eine URL eingebetteten Abfragestring
- Programmatische Ausführung
Die folgenden Typen programmierbarer Suchelemente sind verfügbar:
| Unterelementtyp | Komponenten | Beschreibung |
|---|---|---|
| standard | <div class="gcse-search"> |
Ein Suchfeld und Suchergebnisse, die im selben <div> angezeigt werden. |
| zweispaltig | <div class="gcse-searchbox"> und <div class="gcse-searchresults"> |
Ein zweispaltiges Layout mit Suchergebnissen auf der einen Seite und einem Suchfeld auf der anderen Seite. Wenn Sie auf Ihrer Webseite mehrere Elemente im zweispaltigen Modus einfügen möchten, können Sie mit dem Attribut gname ein Suchfeld mit einem Block von Suchergebnissen koppeln. |
| Nur Suchfeld | <div class="gcse-searchbox-only"> |
Ein eigenständiges Suchfeld. |
| Nur Suchergebnisse | <div class="gcse-searchresults-only"> |
Ein eigenständiger Block mit Suchergebnissen. |
Sie können Ihrer Webseite eine beliebige Anzahl gültiger Suchelemente hinzufügen. Für den zweispaltigen Modus müssen alle erforderlichen Komponenten (Suchfeld und Suchergebnisblock) vorhanden sein.
Hier ist ein Beispiel für ein einfaches Suchelement:
<!-- 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>
Mit programmierbaren Suchelementen verschiedene Layoutoptionen erstellen
Die folgenden Layoutoptionen sind auf der Seite „Design“ im Steuerfeld der Programmable Search Engine verfügbar. Im Folgenden finden Sie einige allgemeine Richtlinien zum Erstellen von Layoutoptionen mithilfe von programmierbaren Suchelementen. Klicken Sie auf den Link, um sich eine Demo dieser Optionen anzusehen.
| Option | Komponenten |
|---|---|
| Volle Breite | <div class="gcse-search"> |
| Kompakt | <div class="gcse-search"> |
| Zweispaltig | <div class="gcse-searchbox">, <div class="gcse-searchresults"> |
| Zweiseitig | <div class="gcse-searchbox-only"> auf der ersten Seite, <div class="gcse-searchresults-only"> (oder andere Komponenten) auf der zweiten Seite. |
| Nur Ergebnisse | <div class="gcse-searchresults-only"> |
| Von Google gehostet | <div class="gcse-searchbox-only"> |
Weitere Informationen zu Layoutoptionen
Programmierbare Elemente der Suche anpassen
Wenn Sie die Farben, die Schriftart oder den Linkstil anpassen möchten, rufen Sie die Seite „Design“ Ihrer programmierbaren Suchmaschine auf.
Mit optionalen Attributen können Sie Konfigurationen überschreiben, die im Programmable Search Engine-Steuerfeld erstellt wurden. So kannst du eine seitenspezifische Suche erstellen.
Mit dem folgenden Code wird beispielsweise ein Suchfeld erstellt, über das eine Ergebnisseite (http://www.example.com?search=lady+gaga) in einem neuen Fenster geöffnet wird. Der Wert des Attributs queryParameterName wird zusammen mit dem Nutzerabfragestring zum Erstellen der Ergebnis-URL verwendet.
Beachten Sie, dass dem Attribut queryParameterName das Präfix data- vorangestellt ist.
Dieses Präfix ist für alle Attribute erforderlich.
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
Wenn Sie über das Steuerfeld der Programmable Search Engine Funktionen wie die automatische Vervollständigung oder Optimierungen aktiviert haben, können Sie diese Funktionen mithilfe von Attributen anpassen. Alle mithilfe dieser Attribute vorgenommenen Anpassungen überschreiben die im Steuerfeld vorgenommenen Einstellungen. Im folgenden Beispiel wird ein zweispaltiges Search Element mit den folgenden Funktionen erstellt:
- Verlaufsverwaltung ist aktiviert
- Die maximale Anzahl angezeigter Autovervollständigungen ist auf 5 festgelegt
- Suchfilter werden als Links angezeigt.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
Unterstützte Attribute
| Attribut | Typ | Beschreibung | Komponente |
|---|---|---|---|
| Allgemein | |||
gname |
String | Optional: Ein Name für das Suchelementobjekt. Der Name wird verwendet, um eine verknüpfte Komponente über ihren Namen abzurufen oder eine searchbox-Komponente mit einer searchresults-Komponente zu koppeln. Wenn nicht angegeben, generiert die Programmable Search Engine basierend auf der Reihenfolge der Komponenten auf der Webseite automatisch eine gname. Die erste unbenannte searchbox-only hat beispielsweise die gname „searchbox-only0“, die zweite die gname „seachbox-only1“ usw.
Die automatisch generierte gname für eine Komponente im zweispaltigen Layout ist two-column. Im folgenden Beispiel wird der gname storesearch verwendet, um eine searchbox-Komponente mit einer searchresults-Komponente zu verknüpfen:
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> Wenn beim Abrufen eines Objekts mehr als eine Komponente dieselbe |
Beliebig |
autoSearchOnLoad |
Boolesch | Gibt an, ob eine Suche mit der Abfrage ausgeführt werden soll, die in die URL der Seite, die geladen wird, eingebettet ist. In der URL muss ein Abfragestring vorhanden sein, damit die automatische Suche ausgeführt werden kann. Standardeinstellung: true. |
Beliebig |
enableHistory |
Boolesch | Bei true wird die Verlaufsverwaltung für die Browserschaltflächen „Zurück“ und „Weiter“ aktiviert. Demo ansehen |
searchbox Nur Suchfeld |
queryParameterName |
String | Der Name des Abfrageparameters, z. B. q (Standard) oder query. Diese wird in die URL eingebettet, z. B. http://www.example.com?q=lady+gaga. Wenn Sie nur den Namen des Abfrageparameters angeben, wird beim Laden keine automatische Suche ausgelöst. In der URL muss ein Abfragestring vorhanden sein, damit die automatische Suche ausgeführt werden kann. |
Beliebig |
resultsUrl |
URL | Die URL der Ergebnisseite. Die Standardeinstellung ist die von Google gehostete Seite. | Nur Suchfeld |
newWindow |
Boolesch | Gibt an, ob die Ergebnisseite in einem neuen Fenster geöffnet wird.
Standardeinstellung: false. |
Nur Suchfeld |
ivt |
Boolesch |
Mit diesem Parameter können Sie einen booleschen Wert angeben, der Google darüber informiert, dass Sie Anzeigen zulassen möchten, bei denen ein Cookie nur für ungültige Zugriffe und lokale Speicherung sowohl für Zugriffe mit als auch ohne Einwilligung verwendet werden.
Standardwert: Verwendungsbeispiel: |
Suchergebnisse Nur Suchergebnisse |
mobileLayout |
String |
Gibt an, ob die mobilen Layoutstile auf Mobilgeräten verwendet werden sollen.
Standardwert: Verwendungsbeispiel: |
Beliebig |
| Automatische Vervollständigung | |||
enableAutoComplete |
Boolesch | Nur verfügbar, wenn die automatische Vervollständigung im Steuerfeld der Programmable Search Engine aktiviert wurde.
true aktiviert die automatische Vervollständigung. |
Beliebig |
autoCompleteMaxCompletions |
Ganzzahl | Die maximale Anzahl der automatischen Vervollständigungen, die angezeigt werden sollen. | searchbox Nur Suchfeld |
autoCompleteMaxPromotions |
Ganzzahl | Die maximale Anzahl von bevorzugten Suchergebnissen, die in der automatischen Vervollständigung angezeigt werden. | searchbox Nur Suchfeld |
autoCompleteValidLanguages |
String | Durch Kommas getrennte Liste der Sprachen, für die die automatische Vervollständigung aktiviert werden soll. Unterstützte Sprachen. | searchbox Nur Suchfeld |
| Suchfilter | |||
defaultToRefinement |
String | Nur verfügbar, wenn im Steuerfeld der Programmable Search Engine Verfeinerungen erstellt wurden. Gibt das Standardlabel für den Suchfilter an, das angezeigt werden soll.Hinweis: Dieses Attribut wird für das von Google gehostete Layout nicht unterstützt. | Beliebig |
refinementStyle |
String | Zulässige Werte sind tab (Standardeinstellung) und link.
link wird nur unterstützt, wenn die Bildersuche bzw. die Bildersuche aktiviert, aber die Websuche deaktiviert ist. |
Suchergebnisse Nur Suchergebnisse |
| Bildersuche | |||
enableImageSearch |
Boolesch | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Wenn |
Suchergebnisse Nur Suchergebnisse |
defaultToImageSearch |
Boolesch | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Bei |
Beliebig |
imageSearchLayout |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Legt das Layout der Ergebnisseite für die Bildersuche fest. Zulässige Werte sind |
Suchergebnisse Nur Suchergebnisse |
imageSearchResultSetSize |
Ganzzahl, String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Gibt die maximale Größe der Suchergebnisse für die Bildersuche an.
Beispiele: |
Beliebig |
image_as_filetype |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Beschränkt die Ergebnisse auf Dateien mit einer bestimmten Erweiterung. Unterstützte Erweiterungen sind | Beliebig |
image_as_oq |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Suchergebnisse mithilfe eines logischen ODER filtern Verwendungsbeispiel, wenn Sie Suchergebnisse erhalten möchten, die „term1“ oder „term2“ enthalten: | Beliebig |
image_as_rights |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Filter sind lizenzbasiert. Unterstützte Werte sind Siehe Typische Kombinationen. | Beliebig |
image_as_sitesearch |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Die Ergebnisse werden auf Seiten von einer bestimmten Website beschränkt. Verwendungsbeispiel: | Beliebig |
image_colortype |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Beschränkt die Suche auf Schwarz-Weiß- (Mono), Graustufen- oder Farbbilder. Unterstützte Werte: | Beliebig |
image_cr |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Beschränkt die Suchergebnisse auf Dokumente aus einem bestimmten Land. | Beliebig |
image_dominantcolor |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Beschränkt die Suche auf Bilder einer bestimmten dominanten Farbe.
Unterstützte Werte: | Beliebig |
image_filter |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Automatisches Filtern von Suchergebnissen. Unterstützte Werte: 0/1 Verwendungsbeispiel: | Beliebig |
image_gl |
String | Nur verfügbar, wenn die Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde. Heben Sie Suchergebnisse hervor, deren Ursprungsland mit dem Parameterwert übereinstimmt. | Beliebig |
image_size |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Gibt Bilder einer bestimmten Größe zurück, wobei die Größe einer der folgenden sein kann: | Beliebig |
image_sort_by |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Ergebnisse nach Datum oder anderen strukturierten Inhalten sortieren Um nach Relevanz zu sortieren, verwenden Sie einen leeren String (image_sort_by=""). Verwendungsbeispiel: | Beliebig |
image_type |
String | Nur verfügbar, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde.
Beschränkt die Suche auf Bilder eines bestimmten Typs.
Unterstützte Werte sind | Beliebig |
| Websuche | |||
disableWebSearch |
Boolesch | Bei true wird die Websuche deaktiviert. Wird normalerweise nur verwendet, wenn die
Bildersuche im Steuerfeld der Programmable Search Engine aktiviert wurde. |
Suchergebnisse Nur Suchergebnisse |
webSearchQueryAddition |
String | Zusätzliche Begriffe, die mit logischem ODER zur Suchanfrage hinzugefügt wurden
Verwendungsbeispiel: |
Beliebig |
webSearchResultSetSize |
Ganzzahl, String | Die maximale Größe der Ergebnismenge. Gilt sowohl für die Bildersuche als auch für die Websuche. Die Standardeinstellung hängt vom Layout und davon ab, ob die Programmable Search Engine so konfiguriert ist, dass das gesamte Web oder nur bestimmte Websites durchsucht werden. Zulässige Werte:
|
Beliebig |
webSearchSafesearch |
String |
Gibt an, ob SafeSearch für Ergebnisse der Websuche aktiviert ist. Zulässige Werte sind off und active.
|
Beliebig |
as_filetype |
String | Beschränkt die Ergebnisse auf Dateien mit einer bestimmten Erweiterung. Eine Liste der Dateitypen, die von Google indexiert werden können, finden Sie in der Search Console-Hilfe. | Beliebig |
as_oq |
String | Suchergebnisse mithilfe eines logischen ODER filtern
Verwendungsbeispiel, wenn Sie Suchergebnisse erhalten möchten, die „term1“ oder „term2“ enthalten: |
Beliebig |
as_rights |
String | Filter sind lizenzbasiert.
Unterstützte Werte sind Typische Kombinationen finden Sie unter https://wiki.creativecommons.org/wiki/CC_Search_integration. | Beliebig |
as_sitesearch |
String | Die Ergebnisse werden auf Seiten von einer bestimmten Website beschränkt.
Verwendungsbeispiel: |
Beliebig |
cr |
String | Beschränkt die Suchergebnisse auf Dokumente aus einem bestimmten Land.
Verwendungsbeispiel: |
Beliebig |
filter |
String | Automatisches Filtern von Suchergebnissen.
Unterstützte Werte: 0/1 Verwendungsbeispiel: |
Beliebig |
gl |
String | Heben Sie Suchergebnisse hervor, deren Ursprungsland mit dem Parameterwert übereinstimmt.
Dies funktioniert nur in Verbindung mit der Einstellung language value. Verwendungsbeispiel: |
Beliebig |
lr |
String | Beschränkt die Suchergebnisse auf Dokumente, die in einer bestimmten Sprache verfasst sind.
Verwendungsbeispiel: |
Beliebig |
sort_by |
String | Ergebnisse nach Datum oder anderen strukturierten Inhalten sortieren Der Attributwert muss eine der Optionen sein, die in den Einstellungen für die Sortierung der Ergebnisse des programmierbaren Suchergebnisses verfügbar sind.
Um nach Relevanz zu sortieren, verwenden Sie einen leeren String (sort_by=""). Verwendungsbeispiel: |
Beliebig |
| Suchergebnisse | |||
enableOrderBy |
Boolesch | Ermöglicht das Sortieren der Ergebnisse nach Relevanz, Datum oder Label. | Beliebig |
linkTarget |
String | Legt das Linkziel fest. Standardeinstellung: _blank. |
Suchergebnisse Nur Suchergebnisse |
noResultsString |
String | Gibt den Standardtext an, der angezeigt wird, wenn keine Ergebnisse mit der Suchanfrage übereinstimmen. Mit dem standardmäßigen Ergebnisstring kann ein lokalisierter String in allen unterstützten Sprachen angezeigt werden, mit dem benutzerdefinierten String jedoch nicht. | Suchergebnisse Nur Suchergebnisse |
resultSetSize |
Ganzzahl, String | Die maximale Größe der Ergebnismenge. Beispiel: large, small, filtered_cse, 10. Die Standardeinstellung hängt vom Layout und davon ab, ob die Suchmaschine so konfiguriert ist, dass das gesamte Web oder nur bestimmte Websites durchsucht werden. |
Beliebig |
safeSearch |
String | Gibt an, ob
SafeSearch sowohl für die Web- als auch die Bildersuche aktiviert ist. Zulässige Werte sind off und active. |
Beliebig |
Callbacks
Callbacks unterstützen eine detaillierte Steuerung der Initialisierung und der Suchprozesse des Suchelements.
Sie werden mit dem Search Element-JavaScript über das globale __gcse-Objekt registriert. Register Callbacks veranschaulicht die Registrierung aller unterstützten Callbacks.
window.__gcse = {
parsetags: 'explicit', // Defaults to 'onload'
initializationCallback: myInitializationCallback,
searchCallbacks: {
image: {
starting: myImageSearchStartingCallback,
ready: myImageResultsReadyCallback,
rendered: myImageResultsRenderedCallback,
},
web: {
starting: myWebSearchStartingCallback,
ready: myWebResultsReadyCallback,
rendered: myWebResultsRenderedCallback,
},
},
};
Initialisierungsrückruf
Der Initialisierungs-Callback wird aufgerufen, bevor das Suchelement-JavaScript die Suchelemente im DOM rendert. Wenn parsetags in __gcse auf explicit gesetzt ist, überlässt das Suchelement-JavaScript das Rendern von Suchelementen wie im Abschnitt Callbacks registrieren dargestellt dem Initialisierungs-Callback.
Dies kann verwendet werden, um Elemente zum Rendern auszuwählen oder um Renderingelemente zu verschieben, bis sie benötigt werden. Außerdem kann sie die Attribute der Elemente überschreiben. So kann beispielsweise ein Suchfeld, das über das Steuerfeld oder HTML-Attribute konfiguriert wird, standardmäßig für die Websuche in ein Bildersuchfeld umgewandelt werden. Oder es kann festgelegt werden, dass Anfragen, die über ein Programmable Search Engine-Formular gesendet werden, in einem Element ausgeführt werden, das ausschließlich für die Suchergebnisse bestimmt ist.
Demo ansehen
Die Rolle des Initialisierungs-Callbacks wird durch den Wert des Attributs parsetags von __gcse gesteuert.
- Wenn der Wert
onloadlautet, rendert das Suchelement-JavaScript alle Suchelemente auf der Seite automatisch. Der Initialisierungs-Callback wird weiterhin aufgerufen, ist jedoch nicht für das Rendern der Suchelemente verantwortlich. - Lautet der Wert
explicit, rendert das Suchelement-JavaScript keine Suchelemente. Der Callback kann sie selektiv mit derrender()-Funktion oder alle Suchelemente mit dergo()-Funktion rendern.
Der folgende Code zeigt, wie ein Suchfeld zusammen mit Suchergebnissen in einem div gerendert wird. Dazu werden das Parse-Tag explicit und ein Initialisierungs-Callback verwendet:
Wir müssen einen <div> mit einem ID-Wert an der Stelle einfügen, an der der Search Element-Code angegeben werden soll:
<div id="test"></div>
Fügen Sie diesen JavaScript-Code nach <div> ein. Er verweist auf test, das id, mit dem <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
};
Fügen Sie diesen HTML-Code ein, um das Laden des Suchelements zu starten. Ersetzen Sie den cx-Wert in der src-Klausel durch Ihren eigenen cx-Wert.
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
Rückrufe suchen
Das Suchelement-JavaScript unterstützt sechs Callbacks, die in der Suchsteuerung ausgeführt werden. Die Callbacks für die Suche werden paarweise ausgegeben: ein Callback für die Websuche und ein Callback für die Bildersuche:
- Suche wird gestartet
- Für die Bildersuche
- Für die Websuche
- Ergebnisse verfügbar
- Für die Bildersuche
- Für die Websuche
- Gerenderte Ergebnisse
- Für die Bildersuche
- Für die Websuche
Wie beim Initialisierungs-Callback werden auch die Such-Callbacks mithilfe von Einträgen im __gcse-Objekt konfiguriert. Dies geschieht, wenn das Suchelement-JavaScript gestartet wird. Änderungen an __gcse nach dem Start werden ignoriert.
Jedem dieser Callbacks wird das gName-Element für das Suchelement als Argument übergeben.
Die gname ist nützlich, wenn eine Seite mehr als eine Suche enthält. Weisen Sie einem Suchelement mithilfe des Attributs data-gname einen gname-Wert zu:
<div class="gcse-searchbox" data-gname="storesearch"></div>
Wenn der gname im HTML-Code nicht identifiziert wird, generiert das Suchelement-JavaScript einen Wert, der bis zur Änderung des HTML-Codes konsistent bleibt.
Callback zum Starten der Bild-/Websuche
Die Callbacks zum Starten der Suche werden unmittelbar vor der JavaScript-Abfrage des Suchelements von seinem Server aufgerufen. Ein Anwendungsbeispiel wäre die Verwendung der lokalen Tageszeit, um Änderungen an der Abfrage zu steuern.
searchStartingCallback(gname, query)
gname- Identifizierungsstring des Suchelements
query Vom Nutzer eingegebener - -Wert (möglicherweise geändert mit JavaScript für das Suchelement.)
Der Callback gibt den Wert zurück, der als Abfrage für diese Suche verwendet werden soll. Wenn ein leerer String zurückgegeben wird, wird der Rückgabewert ignoriert und der Aufrufer verwendet die unveränderte Abfrage.
Alternativ kannst du die Callback-Funktion in das __gcse-Objekt einfügen oder den Callback dynamisch mit JavaScript zum Objekt hinzufügen:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Beispiel für einen Callback beim Starten einer Suche
Bei der Beispielsuche zum Starten des Callbacks im Abschnitt Beispielsuche startet einen Rückruf wird der Abfrage je nach Tageszeit entweder morning oder afternoon hinzugefügt.
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
Diesen Callback in window.__gcse: installieren
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 für bereite Bilder-/Websuchergebnisse
Diese Callbacks werden unmittelbar vor dem Rendern von bevorzugten Suchergebnissen und Ergebnissen durch das JavaScript des Suchelements aufgerufen. Ein Anwendungsbeispiel wäre ein Callback, der Angebote rendert und zu einem Stil führt, der bei normaler Anpassung nicht angegeben werden kann.
resultsReadyCallback(gname, query, promos, results, div)
gname- Identifizierungsstring des Suchelements
query- Abfrage, die diese Ergebnisse geliefert hat
promos- : ein Array von Angebotsobjekten, die übereinstimmenden Angeboten für die Suchanfrage des Nutzers entsprechen. Weitere Informationen finden Sie in der Definition des Angebotsobjekts.
results- Ein Array von Ergebnisobjekten. Weitere Informationen finden Sie in der Ergebnisobjektdefinition.
div- Ein HTML-div-Element, das im DOM an der Stelle positioniert wird, an der das Suchelement normalerweise bevorzugte Suchergebnisse und Suchergebnisse platzieren würde. Normalerweise wird dieses div-Element über den JavaScript-Code des Suchelements ausgefüllt. Durch diesen Callback kann jedoch das automatische Rendern der Ergebnisse gestoppt und die
divzum Rendern der Ergebnisse selbst verwendet werden.
Wenn dieser Callback einen true-Wert zurückgibt, springt das Suchelement-JavaScript auf die Seitenfußzeile über.
Beispiel-Callback mit bereiter Ergebnisausgabe
Der Beispiel-Callback resultsReady im Example Results Ready Callback überschreibt die Standardpräsentation von Angeboten und Ergebnissen durch einen sehr einfachen Ersatz.
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;
};
Diesen Callback in window.__gcse: installieren
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>
Wie beim Start der Suche ist dies eine von vielen Möglichkeiten, den Callback in das __gcse-Objekt einzufügen.
Callback für gerenderte Bild-/Websuchergebnisse
Diese Callbacks werden unmittelbar vor dem Rendern der Fußzeile durch das Suchelement-JavaScript aufgerufen. Beispielanwendungsfälle wären z. B. ein Callback, der Ergebnisinhalte hinzufügt, die im Suchelement nicht angezeigt werden, z. B. das Kästchen Speichern, Informationen, die nicht automatisch gerendert werden, oder ein Callback, der die Schaltfläche Weitere Informationen hinzufügt.
Wenn für einen Callback zu den Ergebnissen Informationen benötigt werden, die sich in den Parametern promos und results des Callbacks für Ergebnisse bereit befanden, kann er diese wie folgt zwischen ihnen übergeben:
callback(gname, query, promoElts, resultElts);
gname- Identifizierungsstring des Suchelements
query- Suchstring.
promoElts- Ein Array der DOM-Elemente, die bevorzugte Suchergebnisse enthalten.
resultElts- : ein Array der DOM-Elemente, die Ergebnisse enthalten.
Es gibt keinen Rückgabewert.
Beispiel-Callback für gerenderte Ergebnisse
Durch den Beispiel-Callback resultsRendered im Callback mit Beispielergebnissen gerenderter Form wird jedem bevorzugten Ergebnis und jedem Ergebnis ein Dummy-Keep-Kästchen hinzugefügt.
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);
}
};
Diesen Callback in window.__gcse: installieren
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>
Wenn für den Callback mit den Ergebnissen Informationen benötigt werden, die an den Callback für verfügbare Ergebnisse übergeben wurden, können diese Daten zwischen den Callbacks weitergegeben werden. Das folgende Beispiel zeigt eine von vielen Möglichkeiten, einen Bewertungswert von richSnippet aus dem Callback für verfügbare Ergebnisse an den Callback für zurückgegebene Ergebnisse zu übergeben.
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 einrichten:
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>
Weitere Callback-Beispiele
Weitere Callback-Beispiele findest du im Dokument Weitere Callback-Beispiele.
Angebots- und Ergebniseigenschaften
In der JSDoc-Notation sind dies die Properties der promotion- und result-Objekte. Hier werden alle Eigenschaften aufgelistet, die möglicherweise vorhanden sind. Ob viele der Unterkünfte vorhanden sind, hängt von den Details des Angebots oder des Suchergebnisses ab.
{
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 hat den lockeren Typ eines Arrays von Objekten. Die Werte der Einträge in diesem Array werden von den strukturierten Daten gesteuert, die auf der Webseite für jedes Suchergebnis gefunden werden. Beispielsweise kann eine Rezensionswebsite strukturierte Daten enthalten, durch die dieser Array-Eintrag zu richSnippet hinzugefügt wird:
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},
Programmable Search Element Control API (V2)
Das Objekt google.search.cse.element veröffentlicht die folgenden statischen Funktionen:
| Funktion | Beschreibung | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
Rendert ein Suchelement.
Parameter
|
||||||
.go(opt_container) |
Rendert alle Search Element-Tags/-Klassen im angegebenen Container.
Parameter
|
||||||
.getElement(gname) |
Ruft das Elementobjekt nach gname ab. Wenn nicht gefunden, wird null zurückgegeben.
Das zurückgegebene
Der folgende Code führt die Abfrage "news" im Suchelement "element1" aus: var element = google.search.cse.element.getElement('element1');
element.execute('news');
|
||||||
.getAllElements() |
Gibt eine Zuordnung aller erfolgreich erstellten Elementobjekte mit dem Schlüssel gname zurück. |