Vous pouvez intégrer des composants Programmable Search Engine (champs de recherche et pages de résultats de recherche) dans vos pages Web et d'autres applications Web à l'aide du balisage HTML. Ces éléments Programmable Search Engine sont constitués de composants affichés en fonction des paramètres stockés par le serveur Programmable Search, ainsi que des personnalisations que vous effectuez.
Tout le code JavaScript est chargé de manière asynchrone, ce qui permet à votre page Web de continuer à se charger pendant que le navigateur récupère le code JavaScript Programmable Search Engine.
Introduction
Ce document fournit un modèle de base pour ajouter des éléments Programmable Search Engine à votre page Web, ainsi que des explications sur les composants configurables de l'élément et l'API JavaScript flexible.
Champ d'application
Ce document explique comment utiliser les fonctions et les propriétés spécifiques à l'API Programmable Search Engine Control.
Compatibilité du navigateur
Pour consulter la liste des navigateurs compatibles avec le moteur de recherche programmable, cliquez ici.
Audience
Cette documentation est destinée aux développeurs qui souhaitent ajouter la fonctionnalité Programmable Search de Google à leurs pages.
Éléments de recherche programmable
Vous pouvez utiliser le balisage HTML pour ajouter un Programmable Search Element à votre page. Chaque élément se compose d'au moins un composant : un champ de recherche, un bloc de résultats de recherche ou les deux. Le champ de recherche accepte les saisies des utilisateurs de l'une des manières suivantes :
- Requête de recherche saisie dans le champ de saisie de texte
- Chaîne de requête intégrée à une URL
- Exécution programmatique
De plus, le bloc de résultats de recherche accepte les entrées des manières suivantes :
- Chaîne de requête intégrée à une URL
- Exécution programmatique
Les types d'éléments de recherche programmable suivants sont disponibles :
| Type d'élément | Composant(s) | Description |
|---|---|---|
| standard | <div class="gcse-search"> |
Champ de recherche et résultats de recherche affichés dans le même <div>. |
| deux colonnes | <div class="gcse-searchbox"> et <div class="gcse-searchresults"> |
Mise en page à deux colonnes avec les résultats de recherche d'un côté et un champ de recherche de l'autre. Si vous prévoyez d'insérer plusieurs éléments en mode deux colonnes sur votre page Web, vous pouvez utiliser l'attribut gname pour associer un champ de recherche à un bloc de résultats de recherche. |
| searchbox-only | <div class="gcse-searchbox-only"> |
Champ de recherche autonome. |
| searchresults-only | <div class="gcse-searchresults-only"> |
Bloc autonome de résultats de recherche. |
Vous pouvez ajouter autant d'éléments de recherche valides que vous le souhaitez à votre page Web. En mode à deux colonnes, tous les composants requis (un champ de recherche et un bloc de résultats de recherche) doivent être présents.
Voici un exemple d'élément de recherche 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>
Composer différentes options de mise en page à l'aide des éléments Programmable Search
Les options de mise en page suivantes sont disponibles sur la page "Apparence" du panneau de configuration Programmable Search Engine. Voici quelques consignes générales concernant la composition des options de mise en page à l'aide des éléments de recherche programmable. Pour voir une démonstration de l'une de ces options, cliquez sur le lien.
| Option | Composant(s) |
|---|---|
| Pleine largeur | <div class="gcse-search"> |
| Compact | <div class="gcse-search"> |
| Deux colonnes | <div class="gcse-searchbox">, <div class="gcse-searchresults"> |
| Deux pages | <div class="gcse-searchbox-only"> sur la première page, <div class="gcse-searchresults-only"> (ou d'autres composants) sur la deuxième page. |
| Résultats uniquement | <div class="gcse-searchresults-only"> |
| Hébergé par Google | <div class="gcse-searchbox-only"> |
En savoir plus sur les options de mise en page
Personnaliser les éléments de Recherche programmable
Pour personnaliser les couleurs, la police ou le style des liens, accédez à la page "Apparence" de votre moteur de recherche programmable.
Vous pouvez utiliser des attributs facultatifs pour remplacer les configurations créées dans le panneau de configuration Programmable Search Engine. Cela vous permet de créer une expérience de recherche spécifique à une page.
Par exemple, le code suivant crée un champ de recherche qui ouvre une page de résultats (http://www.example.com?search=lady+gaga) dans une nouvelle fenêtre. La valeur de l'attribut queryParameterName, ainsi que la chaîne de requête utilisateur, sont utilisées pour créer l'URL des résultats.
Notez que l'attribut queryParameterName est précédé de data-.
Ce préfixe est obligatoire pour tous les attributs.
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
Si vous avez utilisé le panneau de configuration du Programmable Search Engine pour activer des fonctionnalités telles que la saisie semi-automatique ou les affinement, vous pouvez utiliser des attributs pour les personnaliser. Toutes les personnalisations que vous spécifiez à l'aide de ces attributs remplaceront les paramètres définis dans le panneau de configuration. L'exemple suivant crée un élément de recherche à deux colonnes avec les caractéristiques suivantes :
- La gestion de l'historique est activée
- Le nombre maximal de saisies semi-automatiques affichées est défini sur 5.
- Les affinements s'affichent sous forme de liens.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
Attributs acceptés
| Attribut | Type | Description | Composant |
|---|---|---|---|
| Général | |||
gname |
Chaîne | (Facultatif) Nom de l'objet "Search Element". Un nom est utilisé pour récupérer un composant associé par son nom ou pour associer un composant searchbox à un composant searchresults. Si aucune valeur n'est fournie, Programmable Search Engine génère automatiquement un gname en fonction de l'ordre des composants sur la page Web. Par exemple, le premier searchbox-only sans nom a le gname "searchbox-only0", le deuxième a le gname "seachbox-only1", et ainsi de suite.
Notez que le gname généré automatiquement pour un composant dans une mise en page à deux colonnes sera two-column. L'exemple suivant utilise le nom générique storesearch pour associer un composant searchbox à un composant searchresults :
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> Lorsque vous récupérez un objet, si plusieurs composants ont le même |
Tous |
autoSearchOnLoad |
Booléen | Indique s'il faut exécuter une recherche à l'aide de la requête intégrée à l'URL de la page en cours de chargement. Notez qu'une chaîne de requête doit être présente dans l'URL pour exécuter la recherche automatique. Valeur par défaut : true |
Tous |
enableHistory |
Booléen | Si la valeur est true, la gestion de l'historique est activée pour les boutons "Précédent" et "Suivant" du navigateur. Regardez une démonstration. |
champ de recherche searchbox-only |
queryParameterName |
Chaîne | Nom du paramètre de requête, par exemple q (par défaut) ou query. Il sera intégré à l'URL (par exemple, http://www.example.com?q=lady+gaga). Notez que le fait de spécifier le nom du paramètre de requête seul ne déclenche pas la recherche automatique au chargement. Une chaîne de requête doit être présente dans l'URL pour exécuter la recherche automatique. |
Tous |
resultsUrl |
URL | URL de la page de résultats. (La page hébergée par Google est la page par défaut.) | searchbox-only |
newWindow |
Booléen | Indique si la page de résultats s'ouvre dans une nouvelle fenêtre.
Valeur par défaut : false |
searchbox-only |
ivt |
Booléen |
Ce paramètre vous permet de fournir une valeur booléenne qui indique à Google que vous souhaitez autoriser les annonces qui utilisent un cookie dédié uniquement à la détection du trafic incorrect et un espace de stockage local pour le trafic avec et sans consentement.
Valeur par défaut : Exemple d'utilisation : |
searchresults searchresults-only |
mobileLayout |
Chaîne |
Indique si les styles de mise en page pour mobile doivent être utilisés pour les appareils mobiles.
Valeur par défaut : Exemple d'utilisation : |
Tous |
| Saisie semi-automatique | |||
enableAutoComplete |
Booléen | Disponible uniquement si la saisie semi-automatique a été activée dans le panneau de configuration de Programmable Search Engine.
true active la saisie semi-automatique. |
Tous |
autoCompleteMaxCompletions |
Nombre entier | Nombre maximal de saisies semi-automatiques à afficher. | champ de recherche searchbox-only |
autoCompleteMaxPromotions |
Nombre entier | Nombre maximal de promotions à afficher dans la saisie semi-automatique. | champ de recherche searchbox-only |
autoCompleteValidLanguages |
Chaîne | Liste des langues pour lesquelles la saisie semi-automatique doit être activée, séparées par une virgule. Langues disponibles. | champ de recherche searchbox-only |
| Améliorations | |||
defaultToRefinement |
Chaîne | Disponible uniquement si des affinements ont été créés dans le panneau de configuration de Programmable Search Engine. Spécifie le libellé d'affinage par défaut à afficher.Remarque : Cet attribut n'est pas accepté pour la mise en page hébergée par Google. | Tous |
refinementStyle |
Chaîne | Les valeurs acceptées sont tab (par défaut) et link.
link n'est accepté que si la recherche d'images est désactivée, ou si elle est activée, mais que la recherche sur le Web est désactivée. |
searchresults searchresults-only |
| Recherche d'images | |||
enableImageSearch |
Booléen | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Si elle est définie sur |
searchresults searchresults-only |
defaultToImageSearch |
Booléen | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Si la valeur est |
Tous |
imageSearchLayout |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Spécifie la mise en page de la page de résultats de la recherche d'images. Les valeurs acceptables sont |
searchresults searchresults-only |
imageSearchResultSetSize |
Entier, Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Spécifie la taille maximale de l'ensemble de résultats de recherche pour la recherche d'images.
Par exemple, |
Tous |
image_as_filetype |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite les résultats aux fichiers d'une extension spécifiée. Les extensions acceptées sont | Tous |
image_as_oq |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Filtre les résultats de recherche à l'aide de l'opérateur logique OU. Exemple d'utilisation si vous souhaitez obtenir des résultats de recherche incluant "terme1" ou "terme2" : | Tous |
image_as_rights |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Filtres basés sur les licences. Les valeurs acceptées sont Consultez les combinaisons types. | Tous |
image_as_sitesearch |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limiter les résultats aux pages d'un site spécifique Exemple d'utilisation : | Tous |
image_colortype |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite la recherche aux images en noir et blanc (monochrome), en niveaux de gris ou en couleur. Les valeurs acceptées sont | Tous |
image_cr |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite les résultats de recherche aux documents provenant d'un pays spécifique. | Tous |
image_dominantcolor |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite la recherche aux images d'une couleur dominante spécifique.
Les valeurs acceptées sont | Tous |
image_filter |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Filtrage automatique des résultats de recherche. Valeurs acceptées : 0/1 Exemple d'utilisation : | Tous |
image_gl |
Chaîne | Disponible uniquement si la recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine. Mettez en avant les résultats de recherche dont le pays d'origine correspond à la valeur du paramètre. | Tous |
image_size |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Renvoie des images d'une taille spécifiée, qui peut être l'une des suivantes : | Tous |
image_sort_by |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Trier les résultats en fonction de la date ou d'un autre contenu structuré. Pour trier par pertinence, utilisez une chaîne vide (image_sort_by=""). Exemple d'utilisation : | Tous |
image_type |
Chaîne | Disponible uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine.
Limite la recherche aux images d'un type spécifique.
Les valeurs acceptées sont | Tous |
| Recherche sur le Web | |||
disableWebSearch |
Booléen | Si la valeur est true, la recherche sur le Web est désactivée. Généralement utilisé uniquement si la
recherche d'images a été activée dans le panneau de configuration Programmable Search Engine. |
searchresults searchresults-only |
webSearchQueryAddition |
Chaîne | Termes supplémentaires ajoutés à la requête de recherche à l'aide de l'opérateur logique OU.
Exemple d'utilisation : |
Tous |
webSearchResultSetSize |
Entier, chaîne | Taille maximale de l'ensemble de résultats. S'applique à la recherche d'images et à la recherche sur le Web. La valeur par défaut dépend de la mise en page et de la configuration du Programmable Search Engine (recherche sur l'ensemble du Web ou sur des sites spécifiques). Les valeurs acceptées incluent les suivantes :
|
Tous |
webSearchSafesearch |
Chaîne |
Indique si SafeSearch est activé pour les résultats de recherche sur le Web. Les valeurs acceptées sont off et active.
|
Tous |
as_filetype |
Chaîne | Limite les résultats aux fichiers d'une extension spécifiée. Vous trouverez la liste des types de fichiers indexables par Google dans le Centre d'aide de la Search Console. | Tous |
as_oq |
Chaîne | Filtre les résultats de recherche à l'aide de l'opérateur logique OU.
Exemple d'utilisation si vous souhaitez obtenir des résultats de recherche incluant "terme1" ou "terme2" : |
Tous |
as_rights |
Chaîne | Filtres basés sur les licences.
Les valeurs acceptées sont Pour connaître les combinaisons typiques, consultez https://wiki.creativecommons.org/wiki/CC_Search_integration. | Tous |
as_sitesearch |
Chaîne | Limiter les résultats aux pages d'un site spécifique
Exemple d'utilisation : |
Tous |
cr |
Chaîne | Limite les résultats de recherche aux documents provenant d'un pays spécifique.
Exemple d'utilisation : |
Tous |
filter |
Chaîne | Filtrage automatique des résultats de recherche.
Valeurs acceptées : 0/1 Exemple d'utilisation : |
Tous |
gl |
Chaîne | Mettez en avant les résultats de recherche dont le pays d'origine correspond à la valeur du paramètre.
Cela ne fonctionnera qu'avec le paramètre valeur de langue. Exemple d'utilisation : |
Tous |
lr |
Chaîne | Limite les résultats de recherche aux documents rédigés dans une langue spécifique.
Exemple d'utilisation : |
Tous |
sort_by |
Chaîne | Trier les résultats en fonction de la date ou d'un autre contenu structuré. La valeur de l'attribut doit correspondre à l'une des options fournies dans les paramètres de tri des résultats du moteur de recherche programmable.
Pour trier par pertinence, utilisez une chaîne vide (sort_by=""). Exemple d'utilisation : |
Tous |
| Résultats de recherche | |||
enableOrderBy |
Booléen | Permet de trier les résultats par pertinence, date ou libellé. | Tous |
linkTarget |
Chaîne | Définit la cible du lien. Valeur par défaut : _blank |
searchresults searchresults-only |
noResultsString |
Chaîne | Définit le texte par défaut à afficher lorsque la requête ne renvoie aucun résultat. La chaîne de résultat par défaut peut être utilisée pour afficher une chaîne localisée dans toutes les langues acceptées, contrairement à la chaîne personnalisée. | searchresults searchresults-only |
resultSetSize |
Entier, Chaîne | Taille maximale de l'ensemble de résultats. Par exemple, large, small, filtered_cse, 10. La valeur par défaut dépend de la mise en page et de la configuration du moteur (recherche sur l'ensemble du Web ou sur des sites spécifiques). |
Tous |
safeSearch |
Chaîne | Indique si
SafeSearch est activé pour la recherche sur le Web et la recherche d'images. Les valeurs acceptées sont off et active. |
Tous |
Rappels
Les rappels permettent de contrôler précisément l'initialisation des éléments de recherche et les processus de recherche.
Ils sont enregistrés auprès de l'élément de recherche JavaScript via l'objet global __gcse. Register Callbacks illustre l'enregistrement de tous les rappels acceptés.
window.__gcse = {
parsetags: 'explicit', // Defaults to 'onload'
initializationCallback: myInitializationCallback,
searchCallbacks: {
image: {
starting: myImageSearchStartingCallback,
ready: myImageResultsReadyCallback,
rendered: myImageResultsRenderedCallback,
},
web: {
starting: myWebSearchStartingCallback,
ready: myWebResultsReadyCallback,
rendered: myWebResultsRenderedCallback,
},
},
};
Rappel d'initialisation
Le rappel d'initialisation est appelé avant que le JavaScript de l'élément de recherche ne rende les éléments de recherche dans le DOM. Si parsetags est défini sur explicit dans __gcse, le code JavaScript de l'élément de recherche laisse le rendu des éléments de recherche au rappel d'initialisation (comme indiqué dans Enregistrer les rappels).
Cela peut être utilisé pour sélectionner les éléments à afficher ou pour différer l'affichage des éléments jusqu'à ce qu'ils soient nécessaires. Il peut également remplacer les attributs des éléments. Par exemple, il peut transformer un champ de recherche configuré via le panneau de configuration ou les attributs HTML pour qu'il soit défini par défaut sur la recherche sur le Web en un champ de recherche d'images, ou spécifier que les requêtes envoyées via un formulaire Programmable Search Engine sont exécutées dans un élément de résultats de recherche uniquement.
Regardez une démonstration.
Le rôle du rappel d'initialisation est contrôlé par la valeur de la propriété parsetags de __gcse.
- Si sa valeur est
onload, le JavaScript de l'élément de recherche affiche automatiquement tous les éléments de recherche sur la page. Le rappel d'initialisation est toujours appelé, mais il n'est pas responsable du rendu des éléments de recherche. - Si sa valeur est
explicit, le JavaScript de l'élément de recherche n'affiche pas les éléments de recherche. La fonction de rappel peut les afficher de manière sélective à l'aide de la fonctionrender()ou afficher tous les éléments de recherche avec la fonctiongo().
Le code suivant montre comment afficher un champ de recherche et les résultats de recherche dans un div, à l'aide du tag d'analyse explicit et du rappel d'initialisation :
Nous devons inclure un <div> avec une valeur d'ID à l'endroit où nous souhaitons insérer le code de l'élément de recherche :
<div id="test"></div><div>. Notez qu'il fait référence à test, le id que nous avons utilisé pour identifier le <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
};
Incluez ce code HTML pour commencer à charger l'élément de recherche. Remplacez la valeur cx dans la clause src par votre propre cx.
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>Rappels de recherche
Le JavaScript de l'élément de recherche est compatible avec six rappels qui fonctionnent dans le flux de contrôle de la recherche. Les rappels de recherche sont fournis par paires : un rappel de recherche sur le Web et un rappel de recherche d'images correspondant :
- Recherche en cours
- Pour la recherche d'images
- Pour la recherche sur le Web
- Résultats disponibles
- Pour la recherche d'images
- Pour la recherche sur le Web
- Résultats affichés
- Pour la recherche d'images
- Pour la recherche sur le Web
Comme le rappel d'initialisation,les rappels de recherche sont configurés à l'aide d'entrées dans l'objet __gcse. Cela se produit au démarrage du code JavaScript de l'élément de recherche. Les modifications apportées à __gcse après le démarrage sont ignorées.
Chacun de ces rappels reçoit le gName de l'élément de recherche en tant qu'argument.
Le gname est utile lorsqu'une page contient plusieurs recherches. Attribuez des valeurs gname à un élément de recherche à l'aide de l'attribut data-gname :
<div class="gcse-searchbox" data-gname="storesearch"></div>
Si le nom n'est pas identifié dans le code HTML, le JavaScript de l'élément de recherche génère une valeur qui restera cohérente jusqu'à ce que le code HTML soit modifié.
Rappel de début de recherche d'images/sur le Web
Les rappels de début de recherche sont appelés immédiatement avant que l'élément de recherche JavaScript ne demande des résultats de recherche à son serveur. Par exemple, vous pouvez utiliser l'heure locale pour contrôler les modifications apportées à la requête.
searchStartingCallback(gname, query)
gname- Chaîne d'identification de l'élément de recherche
query Valeur - saisie par l'utilisateur (éventuellement modifiée par le code JavaScript de l'élément de recherche).
Le rappel renvoie la valeur à utiliser comme requête pour cette recherche. S'il renvoie une chaîne vide, la valeur de retour est ignorée et l'appelant utilise la requête non modifiée.
Vous pouvez également placer la fonction de rappel dans l'objet __gcse ou ajouter dynamiquement le rappel à l'objet avec JavaScript :
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};Exemple de rappel de début de recherche
L'exemple de rappel de début de recherche dans Exemple de rappel de début de recherche ajoute morning ou afternoon à la requête en fonction de l'heure de la journée.
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
Installez ce rappel dans 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 "Résultats de recherche d'images/Web prêts"
Ces rappels sont appelés immédiatement avant que le JavaScript de l'élément de recherche n'affiche les promotions et les résultats. Un cas d'utilisation typique serait un rappel qui affiche des promotions et des résultats dans un style qui ne peut pas être spécifié avec une personnalisation normale.
resultsReadyCallback(gname, query, promos, results, div)
gname- Chaîne d'identification de l'élément de recherche
query- requête ayant généré ces résultats
promos- un tableau d'objets de promotion correspondant aux promotions associées à la requête de l'utilisateur. Consultez la définition de l'objet promotion.
results- , tableau d'objets de résultat. Consultez la définition de l'objet de résultat.
div- une balise div HTML positionnée dans le DOM où l'élément de recherche placerait normalement les promotions et les résultats de recherche. Normalement, le JavaScript de l'élément de recherche gère le remplissage de cette div, mais ce rappel peut choisir d'arrêter le rendu automatique des résultats et d'utiliser ce
divpour afficher lui-même les résultats.
Si ce rappel renvoie une valeur true, le code JavaScript de l'élément de recherche passe à son travail de pied de page.
Exemple de rappel "Résultats disponibles"
L'exemple de rappel resultsReady dans Exemple de rappel "Résultats prêts" remplace la présentation par défaut des promotions et des résultats par un remplacement très simple.
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;
};
Installez ce rappel dans 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>
Comme pour le rappel de début de recherche, ce qui précède n'est qu'une des nombreuses façons de placer le rappel dans l'objet __gcse.
Rappel de rendu des résultats de recherche d'images/Web
Ces rappels sont invoqués juste avant que le JavaScript de l'élément de recherche n'affiche le pied de page. Par exemple, un rappel qui ajoute du contenu de résultat que l'élément de recherche n'affiche pas, comme une case à cocher Enregistrer ou des informations qui ne sont pas rendues automatiquement, ou un rappel qui ajoute des boutons Pour en savoir plus.
Si un rappel de résultats affichés a besoin d'informations qui se trouvaient dans les paramètres promos et results du rappel de résultats prêts, il peut les transmettre entre eux, comme ceci :
callback(gname, query, promoElts, resultElts);
gname- Chaîne d'identification de l'élément de recherche
query
Chaîne de recherche - .
promoElts- , tableau des éléments DOM contenant les promotions.
resultElts- : tableau des éléments DOM contenant les résultats.
Aucune valeur n'est renvoyée.
Exemple de rappel de rendu des résultats
L'exemple de rappel resultsRendered dans Exemple de rappel de rendu des résultats ajoute une case à cocher Keep (Conserver) factice à chaque promotion et résultat.
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);
}
};
Installez ce rappel dans window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
rendered: 'myWebResultsRenderedCallback',
},
}; <script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Si le rappel des résultats affichés a besoin d'informations qui ont été transmises au rappel des résultats prêts, il peut transmettre ces données entre les rappels. L'exemple suivant montre l'une des nombreuses façons de transmettre une valeur de note de richSnippet du rappel "résultats prêts" au rappel "résultats affichés".
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>Exemple de rappel de rendu des résultats : ouverture de types de fichiers spécifiques dans un nouvel onglet/une nouvelle fenêtre
L'exemple de rappel suivant peut modifier les liens des résultats de recherche après leur affichage pour ouvrir un fichier spécifique dans un nouvel onglet ou une nouvelle page au lieu de la fenêtre actuelle (par exemple, un fichier PDF, Excel ou Word). Cela améliore l'expérience de navigation lorsque les utilisateurs ne souhaitent pas ouvrir un fichier dans la même fenêtre et quitter la page de résultats.
Cet exemple de rappel identifie les liens PDF dans les résultats de recherche et définit l'attribut target="_blank" sur les liens PDF afin qu'ils s'ouvrent dans un nouvel onglet. Un MutationObserver est utilisé pour gérer dynamiquement les nouveaux résultats si la page est actualisée. Remarque : Vous pouvez remplacer .pdf dans handleSearchResults par n'importe quel autre type de fichier selon vos besoins.
Cet exemple de rappel ne fonctionne pas avec les mises en page Google Hosted et Overlay.
function handleSearchResults() {
const links = document.querySelectorAll('.gsc-results .gs-title');
links.forEach(link => {
const url = link.href;
if (url?.toLowerCase().endsWith('.pdf')) {
link.setAttribute('target', '_blank');
}
});
}
const myWebResultsRenderedCallback = () => {
// Call handleSearchResults when results are rendered
handleSearchResults();
// Set up a MutationObserver to handle subsequent updates to the results
const observer = new MutationObserver(handleSearchResults);
const searchResultsContainer = document.querySelector('.gsc-results');
if (searchResultsContainer) {
observer.observe(searchResultsContainer, {
childList: true,
subtree: true
});
} else {
console.log('No Results.');
}
};
Installez ce rappel dans 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>Autres exemples de rappel
Vous trouverez d'autres exemples de rappel dans le document Autres exemples de rappel.
Propriétés de la promotion et du résultat
En utilisant la notation JSDoc, voici les propriétés des objets promotion et result. Nous listons ici toutes les propriétés qui peuvent être présentes. La présence de nombreuses propriétés dépend des détails de la promotion ou du résultat de recherche.
{
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 dans results a le type lâche d'un tableau d'objets. Les valeurs des entrées de ce tableau sont contrôlées par les données structurées trouvées sur la page Web pour chaque résultat de recherche. Par exemple, un site Web d'avis peut inclure des données structurées qui ajoutent cette entrée de tableau à richSnippet :
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},API Programmable Search Element Control (V2)
L'objet google.search.cse.element publie les fonctions statiques suivantes :
| Fonction | Description | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
Affiche un élément de recherche.
Paramètres
|
||||||
.go(opt_container) |
Affiche tous les tags/classes d'éléments de recherche dans le conteneur spécifié.
Paramètres
|
||||||
.getElement(gname) |
Récupère l'objet élément par gname. Si aucun élément n'est trouvé, renvoie la valeur "null".
L'objet
Le code suivant exécute la requête "news" dans l'élément de recherche "element1" : var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
Renvoie une carte de tous les objets d'élément créés, indexés par gname. |