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 de toutes les 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.
Présentation
Ce document fournit un modèle de base permettant d'ajouter des éléments Programmable Search Engine à votre page Web, ainsi que des explications sur leurs composants configurables et l'API JavaScript flexible.
Portée
Ce document explique comment utiliser les fonctions et les propriétés spécifiques à l'API Programmable Search Engine Control.
Compatibilité des navigateurs
La liste des navigateurs compatibles avec Programmable Search Engine est disponible ici.
Audience
Cette documentation est destinée aux développeurs qui souhaitent ajouter la fonctionnalité Recherche programmable Google à leurs pages.
Éléments Programmable Search
Vous pouvez utiliser le balisage HTML pour ajouter un Programmable Search Element à votre page. Chaque élément comprend au moins un composant: un champ de recherche, un bloc de résultats de recherche ou les deux. Le champ de recherche accepte les entrées utilisateur 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 dans 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 dans une URL
- Exécution programmatique
Les types d'éléments Programmable Search suivants sont disponibles:
| Type d'élément | Composant(s) | Description |
|---|---|---|
| standard | <div class="gcse-search"> |
Un champ de recherche et des 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 en 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. |
| champ de recherche uniquement | <div class="gcse-searchbox-only"> |
Un champ de recherche autonome |
| résultats de recherche uniquement | <div class="gcse-searchresults-only"> |
Bloc autonome de résultats de recherche. |
Vous pouvez ajouter autant d'éléments Search Elements valides à votre page Web que vous le souhaitez. Pour le 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>
Rédiger différentes options de mise en page à l'aide des Programmable Search Elements
Les options de mise en page suivantes sont disponibles sur la page "Aspect" du panneau de configuration de Programmable Search Engine. Voici quelques consignes générales sur la composition des options de mise en page à l'aide des Programmable Search Elements. Pour voir une démonstration 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 Programmable Search
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 écraser les configurations créées dans le panneau de configuration de Programmable Search Engine. Cela vous permet de créer une expérience de recherche spécifique à la 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 et 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 Programmable Search Engine pour activer des fonctionnalités telles que la saisie semi-automatique ou les affinages, vous pouvez personnaliser ces fonctionnalités à l'aide d'attributs. Toutes les personnalisations que vous spécifiez à l'aide de ces attributs remplacent les paramètres définis dans le panneau de configuration. L'exemple suivant crée un élément de recherche à deux colonnes avec les fonctionnalités suivantes:
- La gestion de l'historique est activée
- Le nombre maximal de termes de saisie semi-automatique affichés est défini sur 5
- Les filtres sont affichés 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 permet de récupérer un composant associé par son nom ou d'associer un composant searchbox à un composant searchresults. S'il n'est pas fourni, 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 contient gname "searchbox-only0" et le second 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> Lors de la récupération d'un objet, si plusieurs composants ont le même |
Toutes les tailles |
autoSearchOnLoad |
Booléen | Indique si une recherche doit être exécutée à l'aide de la requête intégrée dans 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 |
Toutes les tailles |
enableHistory |
Booléen | Si la valeur est true, active la gestion de l'historique pour les boutons "Précédent" et "Suivant" du navigateur. Regardez une démonstration. |
searchbox champ de recherche uniquement |
queryParameterName |
Chaîne | Nom du paramètre de requête, par exemple q (par défaut) ou query. Il sera intégré dans l'URL (par exemple, http://www.example.com?q=lady+gaga). Notez que spécifier seulement le nom du paramètre de requête ne déclenche pas de recherche automatique au chargement. L'URL doit contenir une chaîne de requête pour exécuter la recherche automatique. |
Toutes les tailles |
resultsUrl |
URL | URL de la page de résultats. Par défaut, il s'agit de la page hébergée par Google. | champ de recherche uniquement |
newWindow |
Booléen | Indique si la page de résultats s'ouvre dans une nouvelle fenêtre.
Valeur par défaut : false |
champ de recherche uniquement |
ivt |
Booléen |
Ce paramètre vous permet de fournir une valeur booléenne indiquant à Google que vous souhaitez autoriser les annonces qui utilisent un cookie de trafic incorrect et un stockage local pour le trafic autorisé et non autorisé.
Valeur par défaut : Exemple d'utilisation: |
résultats de recherche résultats de recherche uniquement |
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: |
Toutes les tailles |
| 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. |
Toutes les tailles |
autoCompleteMaxCompletions |
Entier | Nombre maximal de termes de saisie semi-automatique à afficher. | searchbox champ de recherche uniquement |
autoCompleteMaxPromotions |
Entier | Nombre maximal de promotions à afficher lors de la saisie semi-automatique. | searchbox champ de recherche uniquement |
autoCompleteValidLanguages |
Chaîne | Liste de langues séparées par une virgule pour lesquelles la saisie semi-automatique doit être activée. Langues acceptées | searchbox champ de recherche uniquement |
| Filtres | |||
defaultToRefinement |
Chaîne | Disponible uniquement si des améliorations ont été créées dans le panneau de configuration de Programmable Search Engine. Spécifie le libellé de suggestion à afficher par défaut.Remarque: Cet attribut n'est pas compatible avec la mise en page hébergée par Google. | Toutes les tailles |
refinementStyle |
Chaîne | Les valeurs acceptables sont tab (par défaut) et link.
link n'est disponible que si la recherche d'images est désactivée, ou si la recherche d'images est activée, mais pas la recherche sur le Web. |
résultats de recherche résultats de recherche uniquement |
| 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 la valeur est |
résultats de recherche résultats de recherche uniquement |
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 |
Toutes les tailles |
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 recherche d'images. Les valeurs acceptées sont |
résultats de recherche résultats de recherche uniquement |
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.
Exemples : |
Toutes les tailles |
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 portant l'extension spécifiée. Les extensions compatibles sont | Toutes les tailles |
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.
Filtrez 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 contenant "term1" ou "term2": | Toutes les tailles |
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 habituelles. | Toutes les tailles |
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.
Limitez les résultats aux pages d'un site spécifique. Exemple d'utilisation: | Toutes les tailles |
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 (mono), en nuances de gris ou en couleur. Les valeurs acceptées sont | Toutes les tailles |
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. | Toutes les tailles |
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 | Toutes les tailles |
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: | Toutes les tailles |
image_gl |
Chaîne | Disponible uniquement si la recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine. Optimisez les résultats de recherche dont le pays d'origine correspond à la valeur du paramètre. | Toutes les tailles |
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, où la taille peut être l'une des suivantes: | Toutes les tailles |
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.
Triez 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: | Toutes les tailles |
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 certain type.
Les valeurs acceptées sont | Toutes les tailles |
| Recherche sur le Web | |||
disableWebSearch |
Booléen | Si la valeur est true, désactive la recherche sur le Web. Généralement utilisée uniquement si la
recherche d'images a été activée dans le panneau de configuration de Programmable Search Engine. |
résultats de recherche résultats de recherche uniquement |
webSearchQueryAddition |
Chaîne | Termes supplémentaires ajoutés à la requête à l'aide de l'opérateur logique OR.
Exemple d'utilisation: |
Toutes les tailles |
webSearchResultSetSize |
Entier, chaîne | Taille maximale de l'ensemble de résultats. S'applique à la fois à 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 de Programmable Search Engine pour l'ensemble du Web ou uniquement sur les sites spécifiés. Voici les valeurs acceptées :
|
Toutes les tailles |
webSearchSafesearch |
Chaîne |
Indique si SafeSearch est activé pour les résultats de recherche. Les valeurs acceptées sont off et active.
|
Toutes les tailles |
as_filetype |
Chaîne | Limite les résultats aux fichiers portant l'extension spécifiée. Vous trouverez une liste des types de fichiers indexables par Google dans le Centre d'aide de la Search Console. | Toutes les tailles |
as_oq |
Chaîne | Filtrez 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 contenant "term1" ou "term2": |
Toutes les tailles |
as_rights |
Chaîne | Filtres basés sur les licences.
Les valeurs acceptées sont Pour connaître les combinaisons courantes, consultez la page https://wiki.creativecommons.org/wiki/CC_Search_integration. | Toutes les tailles |
as_sitesearch |
Chaîne | Limitez les résultats aux pages d'un site spécifique.
Exemple d'utilisation: |
Toutes les tailles |
cr |
Chaîne | Limite les résultats de recherche aux documents provenant d'un pays spécifique.
Exemple d'utilisation: |
Toutes les tailles |
filter |
Chaîne | Filtrage automatique des résultats de recherche.
Valeurs acceptées: 0/1 Exemple d'utilisation: |
Toutes les tailles |
gl |
Chaîne | Optimisez les résultats de recherche dont le pays d'origine correspond à la valeur du paramètre.
Cette option ne fonctionne qu'avec le paramètre Valeur de langue. Exemple d'utilisation: |
Toutes les tailles |
lr |
Chaîne | Limite les résultats de recherche aux documents rédigés dans une langue spécifique.
Exemple d'utilisation: |
Toutes les tailles |
sort_by |
Chaîne | Triez 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 modèle de recherche programmable.
Pour trier par pertinence, utilisez une chaîne vide (sort_by=""). Exemple d'utilisation: |
Toutes les tailles |
| Résultats de recherche | |||
enableOrderBy |
Booléen | Permet de trier les résultats par pertinence, date ou libellé. | Toutes les tailles |
linkTarget |
Chaîne | Définit la cible du lien. Valeur par défaut : _blank |
résultats de recherche résultats de recherche uniquement |
noResultsString |
Chaîne | Spécifie le texte par défaut à afficher lorsqu'aucun résultat ne correspond à la requête. La chaîne de résultat par défaut peut être utilisée pour afficher une chaîne localisée dans toutes les langues compatibles, contrairement à la chaîne personnalisée. | résultats de recherche résultats de recherche uniquement |
resultSetSize |
Entier, chaîne | Taille maximale de l'ensemble de résultats. Exemples : large, small, filtered_cse, 10. La valeur par défaut dépend de la mise en page et de la configuration du moteur pour l'ensemble du Web ou uniquement sur les sites spécifiés. |
Toutes les tailles |
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. |
Toutes les tailles |
Rappels
Les rappels permettent un contrôle détaillé des processus d'initialisation et de recherche des éléments de recherche.
Ils sont enregistrés avec le JavaScript de l'élément de recherche via l'objet __gcse global. Register Callbacks (Enregistrer des rappels) illustre l'enregistrement de tous les rappels compatibles.
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 invoqué avant que le code JavaScript de l'élément de recherche n'affiche les éléments de recherche dans le DOM. Si parsetags est défini sur explicit dans __gcse, le JavaScript de l'élément de recherche laisse le rendu des éléments de recherche au rappel d'initialisation (comme indiqué dans la section Enregistrer des rappels).
Cela peut être utilisé pour sélectionner les éléments à afficher ou pour différer le rendu d'éléments jusqu'à ce qu'ils soient nécessaires. Elle peut également remplacer les attributs des éléments. Elle peut, par exemple, transformer un champ de recherche configuré via le panneau de configuration ou les attributs HTML pour définir par défaut la recherche sur le Web en 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 uniquement des résultats de recherche.
Voir 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 de la page. Le rappel d'initialisation est toujours appelé, mais il n'est pas responsable de l'affichage des éléments de recherche. - Si sa valeur est
explicit, le JavaScript de l'élément de recherche n'affiche pas ces éléments. Le 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 de la balise d'analyse explicit et du rappel d'initialisation:
Nous devons inclure un <div> avec une valeur d'ID où nous aimerions le code de l'élément de recherche:
<div id="test"></div>
Ajoutez ce code JavaScript après <div>. Notez qu'il fait référence à test, le id que nous avons utilisé pour identifier <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 lancer le chargement de 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>
Rechercher des rappels
Le JavaScript de l'élément de recherche accepte six rappels qui opèrent dans le flux de commandes de recherche. Les rappels de recherche sont combinés par paire, un rappel de recherche sur le Web et un rappel de recherche d'image correspondant:
- Début de la recherche :
- Pour la recherche d'images
- Pour la recherche sur le Web
- Résultats prêts
- 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 pour 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 JavaScript de l'élément de recherche. Les modifications de __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 code HTML n'identifie pas le gname, 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émarrage de la recherche d'images/sur le Web
Les rappels de démarrage de la recherche sont appelés immédiatement avant que le JavaScript de l'élément de recherche ne demande les résultats de recherche à son serveur. Exemple de cas d'utilisation : 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 JavaScript de l'élément de recherche).
Le rappel renvoie la valeur à utiliser comme requête pour cette recherche. Si elle renvoie une chaîne vide, la valeur renvoyée 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 le rappel de manière dynamique à l'objet avec JavaScript:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Exemple de rappel de démarrage de la recherche
L'exemple de rappel de début de recherche dans Exemple de rappel de démarrage de recherche ajoute morning ou afternoon à la requête en fonction de l'heure.
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
Installer 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>
Rappel de chargement d'images/de résultats de recherche Web
Ces rappels sont appelés immédiatement avant que le JavaScript de l'élément de recherche n'affiche les résultats mis en avant et les résultats. Voici un exemple de cas d'utilisation : un rappel qui affiche les promotions et donne 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 Promotion correspondant aux promotions correspondantes pour la requête de l'utilisateur. Consultez la définition de l'objet promotion.
results- Un tableau d'objets de résultats. Consultez la définition de l'objet de résultat.
div- div HTML placé dans le DOM à l'endroit où l'élément de recherche place habituellement les promotions et les résultats de recherche. Normalement, le JavaScript de l'élément de recherche gèrerait le remplissage de cet élément div, mais ce rappel peut choisir d'arrêter l'affichage automatique des résultats et d'utiliser ce
divpour afficher les résultats lui-même.
Si ce rappel renvoie une valeur true, le JavaScript de l'élément de recherche passe directement à sa tâche de pied de page.
Exemple de rappel prêt pour les résultats
L'exemple de rappel resultsReady dans le rappel prêt pour l'exemple de résultats remplace la présentation par défaut des promotions et des résultats avec 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;
};
Installer 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, voici l'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 appelés immédiatement avant que le JavaScript de l'élément de recherche n'affiche le pied de page. Voici quelques exemples de cas d'utilisation : un rappel qui ajoute du contenu dans les résultats que l'élément de recherche n'affiche pas, comme une case à cocher Save this (enregistrer) ou des informations qui ne sont pas automatiquement affichées, ou un rappel qui ajoute des boutons for more information (pour plus d'informations).
Si un rappel des résultats affichés a besoin d'informations qui se trouvaient dans les paramètres promos et results du rappel de résultat prêt, il peut les transmettre entre eux, comme suit:
callback(gname, query, promoElts, resultElts);
gname- Chaîne d'identification de l'élément de recherche
query- chaîne de recherche.
promoElts- Un tableau des éléments DOM contenant des promotions.
resultElts- Un tableau des éléments DOM contenant les résultats.
Aucune valeur renvoyée.
Exemple de rappel affiché pour les résultats
L'exemple de rappel resultsRendered dans le rappel de rendu des résultats d'exemple ajoute une case à cocher factice Keep à 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);
}
};
Installer 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 de l'affichage des résultats a besoin d'informations transmises au rappel de disponibilité des résultats, il peut les transmettre entre les rappels. L'exemple suivant illustre l'une des nombreuses façons de transmettre une valeur de note depuis richSnippet depuis le rappel "results ready" au rappel des 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>
Plus d'exemples de rappel
Vous trouverez d'autres exemples de rappel dans le document Autres exemples de rappel.
Propriétés de la promotion et des résultats
En utilisant la notation JSDoc, il s'agit des propriétés des objets promotion et result. Nous énumérons ici toutes les propriétés susceptibles d'être présentes. La présence de nombreuses propriétés dépend des détails de la promotion ou des résultats 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 les résultats possède le type libre 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 toutes les classes/balises Search Element dans le conteneur spécifié.
Paramètres
|
||||||
.getElement(gname) |
Récupère l'objet de l'élément par gname. S'il est introuvable, la valeur renvoyée est "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 map de tous les objets d'élément créés avec succès, associés à gname. |