É possível incorporar componentes do Mecanismo de Pesquisa Programável (caixas de pesquisa e páginas de resultados de pesquisa) nas páginas da Web e outros aplicativos da Web usando a marcação HTML. Esses elementos são componentes renderizados com base nas configurações armazenadas pelo servidor de Pesquisa Programável, além das personalizações que você fizer.
Todo o JavaScript é carregado de forma assíncrona, o que permite que a página da Web continue carregando enquanto o navegador busca o JavaScript do Mecanismo de Pesquisa Programável.
Introdução
Neste documento, apresentamos um modelo básico para adicionar elementos do Mecanismo de Pesquisa Programável à sua página da Web, além de explicações sobre os componentes configuráveis do elemento e da API JavaScript flexível.
Escopo
Neste documento, descrevemos como usar as funções e propriedades específicas da API Programmable Search Engine Control.
Compatibilidade do navegador
A lista de navegadores compatíveis com o Mecanismo de Pesquisa Programável está disponível neste link.
Público
Esta documentação é destinada aos desenvolvedores que querem adicionar a funcionalidade da Pesquisa programável do Google às páginas.
Elementos de Pesquisa Programável
Você pode usar a marcação HTML para adicionar um Elemento de Pesquisa Programável à sua página. Cada elemento consiste em pelo menos um componente: uma caixa de pesquisa, um bloco de resultados da pesquisa ou ambos. Ela aceita entradas do usuário de uma das seguintes maneiras:
- Uma consulta de pesquisa digitada no campo de entrada de texto
- Uma string de consulta incorporada em um URL
- Execução programática
Além disso, o bloco de resultados da pesquisa aceita entrada das seguintes maneiras:
- Uma string de consulta incorporada em um URL
- Execução programática
Os seguintes tipos de Elementos de Pesquisa Programável estão disponíveis:
| Tipo de elemento | Componentes | Descrição |
|---|---|---|
| padrão | <div class="gcse-search"> |
Uma caixa e resultados de pesquisa, exibidos no mesmo <div>. |
| duas colunas | <div class="gcse-searchbox"> e <div class="gcse-searchresults"> |
Um layout de duas colunas com resultados da pesquisa em um lado e uma caixa de pesquisa do outro. Se você pretende inserir vários elementos no modo de duas colunas
na página da Web, use o atributo gname para parear uma
caixa de pesquisa com um bloco de resultados da pesquisa. |
| somente caixa de pesquisa | <div class="gcse-searchbox-only"> |
Uma caixa de pesquisa autônoma. |
| Apenas resultados de pesquisa | <div class="gcse-searchresults-only"> |
Um bloco independente de resultados da pesquisa. |
Você pode adicionar quantos elementos de pesquisa quiser à sua página da Web. Para o modo de duas colunas, todos os componentes necessários (uma caixa de pesquisa e um bloco de resultados da pesquisa) precisam estar presentes.
Veja um exemplo de um elemento de pesquisa simples:
<!-- 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>
Crie diferentes opções de layout usando elementos de pesquisa programável
As seguintes opções de layout estão disponíveis na página de aparência do painel de controle do Mecanismo de Pesquisa Programável. Confira algumas diretrizes gerais sobre como criar opções de layout usando elementos de pesquisa programável. Para acessar uma demonstração de qualquer uma dessas opções, clique no link.
| Opção | Componentes |
|---|---|
| Largura total | <div class="gcse-search"> |
| Compacta | <div class="gcse-search"> |
| Duas colunas | <div class="gcse-searchbox">, <div class="gcse-searchresults"> |
| Duas páginas | <div class="gcse-searchbox-only"> na primeira página e <div class="gcse-searchresults-only"> (ou outros componentes) na segunda. |
| Somente resultados | <div class="gcse-searchresults-only"> |
| Hospedado pelo Google | <div class="gcse-searchbox-only"> |
Mais informações sobre as opções de layout.
Como personalizar elementos da Pesquisa programável
Para personalizar cores, fontes ou estilos de link, acesse a página Aparência do mecanismo de pesquisa programável.
É possível usar atributos opcionais para substituir as configurações criadas no
painel de controle do Mecanismo de
Pesquisa Programável. Isso permite que você crie uma experiência de pesquisa específica para a página.
Por exemplo, o código a seguir cria uma caixa de pesquisa que abre uma página de resultados (http://www.example.com?search=lady+gaga) em uma nova janela. O valor do atributo
queryParameterName, junto com a string de consulta do usuário, é
usado para criar o URL de resultados.
O atributo queryParameterName tem o prefixo data-.
Esse prefixo é obrigatório para todos os atributos.
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
Se você usou o painel de controle do Mecanismo de Pesquisa Programável para ativar recursos como o preenchimento automático ou refinamentos, pode usar atributos para personalizar essas funcionalidades. Qualquer personalização que você especificar usando esses atributos substituirá as configurações feitas no painel de controle. O exemplo abaixo cria um elemento de pesquisa de duas colunas com os seguintes recursos:
- O gerenciamento de histórico está ativado
- O número máximo de opções de preenchimento automático exibidas está definido como 5.
- Os refinamentos são exibidos como links.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
Atributos compatíveis
| Atributo | Tipo | Descrição | Componente |
|---|---|---|---|
| Geral | |||
gname |
String | (Opcional) Um nome para o objeto do elemento de pesquisa. Um nome é usado para recuperar um componente associado por nome ou para parear um componente searchbox com um componente searchresults. Se não for fornecido,
o Mecanismo de Pesquisa Programável vai gerar automaticamente um gname, com base na
ordem dos componentes na página da Web. Por exemplo, a primeira searchbox-only sem nome tem a gname "searchbox-only0", a segunda tem a gname "seachbox-only1" e assim por diante.
Observe que o gname gerado automaticamente para um componente no layout de duas colunas será two-column. O exemplo a seguir
usa o gname storesearch para vincular um componente searchbox
a um componente searchresults:
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> Ao recuperar um objeto, se mais de um componente tiver o mesmo
|
Qualquer tipo |
autoSearchOnLoad |
Booleano | Especifica se uma pesquisa será executada pela consulta incorporada no URL
da página que está sendo carregada. Uma string de consulta precisa estar presente no URL para executar a pesquisa automática. Padrão: true. |
Qualquer tipo |
enableHistory |
Booleano | Se true, ativa o gerenciamento de histórico para os botões "Voltar"
e "Avançar" do navegador. Confira uma demonstração. |
searchbox somente caixa de pesquisa |
queryParameterName |
String | O nome do parâmetro de consulta, por exemplo, q (padrão) ou query. Ele será incorporado ao URL (por exemplo,
http://www.example.com?q=lady+gaga). Especificar apenas o nome do parâmetro de consulta não aciona a pesquisa automática no carregamento. Uma string de consulta precisa estar presente no URL para executar a pesquisa automática. |
Qualquer tipo |
resultsUrl |
URL | O URL da página de resultados. O padrão é a página hospedada pelo Google. | somente caixa de pesquisa |
newWindow |
Booleano | Especifica se a página de resultados será aberta em uma nova janela.
Padrão: false. |
somente caixa de pesquisa |
ivt |
Booleano |
Com esse parâmetro, você pode fornecer um booleano informando ao Google que você quer permitir anúncios que usam um cookie somente de tráfego inválido e armazenamento local no tráfego com e sem consentimento.
Padrão: Exemplo de uso: |
resultados da pesquisa Apenas resultados de pesquisa |
mobileLayout |
String |
Especifica se os estilos de layout para dispositivos móveis precisam ser usados para dispositivos móveis.
Padrão: Exemplo de uso: |
Qualquer tipo |
| Preenchimento automático | |||
enableAutoComplete |
Booleano | Disponível apenas se o preenchimento automático estiver ativado no painel de controle do Mecanismo de Pesquisa Programável.
true ativa o preenchimento automático. |
Qualquer tipo |
autoCompleteMaxCompletions |
Número inteiro | O número máximo de opções de preenchimento automático a serem exibidas. | searchbox somente caixa de pesquisa |
autoCompleteMaxPromotions |
Número inteiro | O número máximo de promoções a serem exibidas no preenchimento automático. | searchbox somente caixa de pesquisa |
autoCompleteValidLanguages |
String | Lista de idiomas separados por vírgulas para os quais o preenchimento automático precisa estar ativado. Idiomas compatíveis. | searchbox somente caixa de pesquisa |
| Refinamentos | |||
defaultToRefinement |
String | Disponível apenas se refinamentos tiverem sido criados no painel de controle do Mecanismo de Pesquisa Programável. Especifica o rótulo de refinamento padrão a ser exibido.Observação: esse atributo não é compatível com o layout hospedado pelo Google. | Qualquer tipo |
refinementStyle |
String | Os valores aceitáveis são tab (padrão) e link.
link só será compatível se a pesquisa de imagens estiver desativada ou se
a pesquisa de imagens estiver ativada, mas a pesquisa na Web estiver desativada. |
resultados da pesquisa Apenas resultados de pesquisa |
| Pesquisa de imagens | |||
enableImageSearch |
Booleano | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Se |
resultados da pesquisa Apenas resultados de pesquisa |
defaultToImageSearch |
Booleano | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Se for |
Qualquer tipo |
imageSearchLayout |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Especifica o layout da página de resultados da pesquisa de imagens. Os valores aceitáveis
são |
resultados da pesquisa Apenas resultados de pesquisa |
imageSearchResultSetSize |
Número inteiro, string | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Especifica o tamanho máximo do conjunto de resultados para a pesquisa de imagens.
Por exemplo, |
Qualquer tipo |
image_as_filetype |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Restringe os resultados a arquivos de uma extensão especificada. As extensões com suporte são | Qualquer tipo |
image_as_oq |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Filtre os resultados da pesquisa usando a expressão OR lógica. Exemplo de uso se você quiser resultados da pesquisa que incluam "term1" ou "term2": | Qualquer tipo |
image_as_rights |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Filtros com base no licenciamento. Os valores aceitos são Confira as combinações típicas. | Qualquer tipo |
image_as_sitesearch |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Restrinja os resultados a páginas de um site específico. Exemplo de uso: | Qualquer tipo |
image_colortype |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Restringe a pesquisa a imagens em preto e branco (mono), escala de cinza ou coloridas. Os valores aceitos são | Qualquer tipo |
image_cr |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Restringe os resultados da pesquisa a documentos originários de um país específico. | Qualquer tipo |
image_dominantcolor |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Restringe a pesquisa a imagens de uma cor dominante específica.
Os valores aceitos são | Qualquer tipo |
image_filter |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Filtragem automática dos resultados da pesquisa. Valores compatíveis: 0/1 Exemplo de uso: | Qualquer tipo |
image_gl |
String | Disponível apenas se a pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável. Otimize os resultados da pesquisa cujo país de origem corresponde ao valor do parâmetro. | Qualquer tipo |
image_size |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Retorna imagens de um tamanho especificado, em que o tamanho pode ser | Qualquer tipo |
image_sort_by |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Classifique os resultados usando a data ou outro conteúdo estruturado. Para classificar por relevância, use uma string vazia (image_sort_by=""). Exemplo de uso: | Qualquer tipo |
image_type |
String | Disponível apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável.
Restringe a pesquisa a imagens de um tipo específico.
Os valores aceitos são | Qualquer tipo |
| Pesquisa Google na Web | |||
disableWebSearch |
Booleano | Se for true, a pesquisa na Web será desativada. Geralmente usado apenas se a
pesquisa de imagens estiver ativada no painel de controle do Mecanismo de Pesquisa Programável. |
resultados da pesquisa Apenas resultados de pesquisa |
webSearchQueryAddition |
String | Termos extras adicionados à consulta de pesquisa usando OR lógico.
Exemplo de uso: |
Qualquer tipo |
webSearchResultSetSize |
Número inteiro, string | O tamanho máximo do conjunto de resultados. Aplica-se
à pesquisa de imagens e à pesquisa na Web. O padrão depende do layout e
se o Mecanismo de Pesquisa Programável está configurado para pesquisar em toda a Web ou apenas em sites
especificados. Os valores aceitáveis incluem:
|
Qualquer tipo |
webSearchSafesearch |
String |
Especifica se o
SafeSearch está
ativado para os resultados da pesquisa na Web. Os valores aceitos são off e active.
|
Qualquer tipo |
as_filetype |
String | Restringe os resultados a arquivos de uma extensão especificada. Uma lista dos tipos de arquivo indexáveis pelo Google pode ser encontrada na Central de Ajuda do Search Console. | Qualquer tipo |
as_oq |
String | Filtre os resultados da pesquisa usando a expressão OR lógica.
Exemplo de uso se você quiser resultados da pesquisa que incluam "term1" ou "term2": |
Qualquer tipo |
as_rights |
String | Filtros com base no licenciamento.
Os valores aceitos são Acesse https://wiki.creativecommons.org/wiki/CC_Search_integration para ver as combinações típicas. | Qualquer tipo |
as_sitesearch |
String | Restrinja os resultados a páginas de um site específico.
Exemplo de uso: |
Qualquer tipo |
cr |
String | Restringe os resultados da pesquisa a documentos originários de um país específico.
Exemplo de uso: |
Qualquer tipo |
filter |
String | Filtragem automática dos resultados da pesquisa.
Valores compatíveis: 0/1 Exemplo de uso: |
Qualquer tipo |
gl |
String | Otimize os resultados da pesquisa cujo país de origem corresponde ao valor do parâmetro.
Isso só funcionará em conjunto com a configuração language value. Exemplo de uso: |
Qualquer tipo |
lr |
String | Restringe os resultados da pesquisa a documentos escritos em um idioma específico.
Exemplo de uso: |
Qualquer tipo |
sort_by |
String | Classifique os resultados usando a data ou outro conteúdo estruturado. O valor do atributo precisa ser uma das opções fornecidas nas configurações de Classificação de resultados do mecanismo de pesquisa programável.
Para classificar por relevância, use uma string vazia (sort_by=""). Exemplo de uso: |
Qualquer tipo |
| Resultados da pesquisa | |||
enableOrderBy |
Booleano | Ativa a classificação de resultados por relevância, data ou rótulo. | Qualquer tipo |
linkTarget |
String | Define o destino do link. Padrão: _blank. |
resultados da pesquisa Apenas resultados de pesquisa |
noResultsString |
String | Especifica o texto padrão a ser exibido quando nenhum resultado corresponde à consulta. A string de resultados padrão pode ser usada para mostrar uma string localizada em todos os idiomas com suporte, mas a personalizada não. | resultados da pesquisa Apenas resultados de pesquisa |
resultSetSize |
Número inteiro, string | O tamanho máximo do conjunto de resultados. Por exemplo, large,
small, filtered_cse, 10. O
padrão depende do layout e se o mecanismo está configurado para pesquisar
em toda a Web ou apenas em sites especificados. |
Qualquer tipo |
safeSearch |
String | Especifica se o
SafeSearch está ativado para a pesquisa na Web e por imagens. Os valores aceitos são off
e active. |
Qualquer tipo |
Callbacks
Os callbacks oferecem suporte ao controle detalhado da inicialização do elemento e dos processos de pesquisa.
Eles são registrados com o JavaScript do elemento de pesquisa por meio do objeto __gcse
global. Register Callbacks ilustra o registro de todos os
callbacks compatíveis.
window.__gcse = {
parsetags: 'explicit', // Defaults to 'onload'
initializationCallback: myInitializationCallback,
searchCallbacks: {
image: {
starting: myImageSearchStartingCallback,
ready: myImageResultsReadyCallback,
rendered: myImageResultsRenderedCallback,
},
web: {
starting: myWebSearchStartingCallback,
ready: myWebResultsReadyCallback,
rendered: myWebResultsRenderedCallback,
},
},
};
O callback de inicialização
O callback de inicialização é invocado antes que o JavaScript do elemento de pesquisa renderize elementos de pesquisa no DOM. Se parsetags for definido como explicit em
__gcse, o JavaScript do elemento de pesquisa vai deixar a renderização de elementos de pesquisa para o
callback de inicialização, conforme mostrado em Registrar callbacks.
Isso pode ser usado para selecionar elementos a serem renderizados ou para adiar elementos de renderização até que eles sejam
necessários. Ele também pode substituir os atributos dos elementos. Por exemplo, é possível transformar uma
caixa de pesquisa configurada no painel de controle ou em atributos HTML como padrão para a pesquisa
na Web em uma caixa de pesquisa de imagens ou especificar que as consultas enviadas por um formulário do Mecanismo de Pesquisa Programável sejam
executadas em um elemento somente de resultados de pesquisa.
Veja uma demonstração.
O papel do callback de inicialização é controlado pelo valor da propriedade parsetags
de __gcse.
- Se o valor for
onload, o JavaScript do elemento de pesquisa vai renderizar todos os elementos de pesquisa da página automaticamente. O callback de inicialização ainda é invocado, mas não é responsável por renderizar os elementos de pesquisa. - Se o valor for
explicit, o JavaScript do elemento de pesquisa não renderizará os elementos de pesquisa. O callback pode renderizá-los seletivamente usando a funçãorender()ou renderizar todos os elementos de pesquisa com a funçãogo()
O código a seguir demonstra como renderizar uma caixa de pesquisa com os resultados da pesquisa em um div usando a parsetag explicit e o callback de inicialização:
Precisamos incluir um <div> com um valor de ID em que queremos o código do elemento de pesquisa:
<div id="test"></div>
Adicione esse JavaScript após o <div>. Ele
faz referência a test, o id que usamos para identificar o
<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
};
Inclua este HTML para começar a carregar o Elemento de pesquisa. Substitua o valor cx na cláusula
src pelo seu cx.
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
Pesquisar callbacks
O JavaScript do elemento de pesquisa é compatível com seis callbacks que operam no fluxo de controle de pesquisa. Os callbacks de pesquisa vêm em pares, um callback de pesquisa na Web e um callback de pesquisa por imagem correspondente:
- Início da pesquisa
- Para pesquisa de imagens
- Para pesquisa na Web
- Resultados prontos
- Para pesquisa de imagens
- Para pesquisa na Web
- Resultados renderizados
- Para pesquisa de imagens
- Para pesquisa na Web
Assim como o callback de inicialização,os callbacks de pesquisa são
configurados usando entradas no objeto __gcse. Isso acontece quando o JavaScript do elemento de pesquisa é iniciado. Modificações em __gcse após a inicialização são ignoradas.
Cada um desses callbacks recebe o gName do elemento de pesquisa como um argumento.
O gname é útil quando uma página contém mais de uma pesquisa. Atribua valores gname a um elemento de pesquisa usando o atributo data-gname:
<div class="gcse-searchbox" data-gname="storesearch"></div>
Se o HTML não identificar o gname, o JavaScript do elemento de pesquisa gerará um valor que permanecerá consistente até que o HTML seja modificado.
Callback de início da pesquisa na Web/imagem
Os callbacks de início da pesquisa são invocados imediatamente antes que o JavaScript do elemento de pesquisa solicite os resultados do servidor. Um exemplo de caso de uso seria usar a hora local do dia para controlar as mudanças na consulta.
searchStartingCallback(gname, query)
gname- String de identificação do elemento de pesquisa
query Valor - inserido pelo usuário, possivelmente modificado pelo JavaScript do elemento de pesquisa.
O callback retorna o valor que precisa ser usado como a consulta da pesquisa. Se retornar uma string vazia, o valor de retorno será ignorado e o autor da chamada usará a consulta não modificada.
Como alternativa, é possível colocar a função de callback no objeto __gcse ou
adicionar dinamicamente o callback ao objeto com JavaScript:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Exemplo de retorno de chamada de início da pesquisa
O exemplo de retorno de chamada de pesquisa inicial em Exemplo de retorno de chamada inicial de pesquisa adiciona morning ou afternoon à consulta, dependendo da hora do dia.
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
Instalar este callback em window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
<script
async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Callback pronto para resultados de pesquisa de imagem/na Web
Esses callbacks são invocados imediatamente antes que o JavaScript do elemento de pesquisa renderize promoções e resultados. Um exemplo de caso de uso seria um callback que renderiza promoções e resulta em um estilo que não pode ser especificado com a personalização normal.
resultsReadyCallback(gname, query, promos, results, div)
gname- String de identificação do elemento de pesquisa
query- consulta que produziu esses resultados
promos- Uma matriz de objetos de promoção, que correspondem às promoções correspondentes da consulta do usuário. Consulte a definição do objeto da promoção.
results- : uma matriz de objetos de resultado. Consulte a definição de objeto de resultado.
div- um div HTML posicionado no DOM em que o elemento de pesquisa normalmente colocaria promoções e resultados da pesquisa. Normalmente, o JavaScript do elemento de pesquisa processaria o preenchimento desse div, mas esse callback pode optar por interromper a renderização automática de resultados e usar esse
divpara renderizar os resultados por conta própria.
Se esse callback retornar um valor true, o JavaScript do elemento de pesquisa pulará para o trabalho do rodapé da página.
Exemplo de callback pronto para resultados
O exemplo de callback resultsReady em Example Results Ready Callback substitui a apresentação padrão de promoções e resultados por uma substituição muito simples.
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;
};
Instalar este callback em 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>
Assim como no callback de início da pesquisa, a instrução acima é uma das muitas maneiras de colocar o callback no objeto __gcse.
Callback renderizado de resultados de pesquisa de imagem/na Web
Esses callbacks são invocados imediatamente antes de o JavaScript do elemento de pesquisa renderizar o rodapé da página. Os exemplos de casos de uso incluem um callback que adiciona conteúdo do resultado que o elemento de pesquisa não mostra, como uma caixa de seleção salvar esta ou informações que não são renderizadas automaticamente, ou um callback que adiciona botões para mais informações.
Se um callback de resultados renderizados precisar de informações que estavam nos parâmetros promos e results do callback pronto para resultados, ele poderá transmiti-la entre eles da seguinte forma:
callback(gname, query, promoElts, resultElts);
gname- String de identificação do elemento de pesquisa
query- .
promoElts- Uma matriz dos elementos DOM que contêm promoções.
resultElts- Uma matriz dos elementos DOM contendo resultados.
Não há valor de retorno.
Exemplo de callback renderizado de resultados
O exemplo de callback resultsRendered em
Exemplo de callback renderizado de resultados adiciona uma caixa de seleção fictícia Keep
a cada promoção e resultado.
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);
}
};
Instalar este callback em window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
rendered: 'myWebResultsRenderedCallback',
},
};
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Se o callback dos resultados renderizado precisar de
informações que foram transmitidas para o callback pronto para os resultados, ele vai poder transmitir esses dados entre
os callbacks. O exemplo a seguir mostra uma das muitas maneiras de transmitir um valor de nota de richSnippet do callback results Ready para o callback das results renderizadas.
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>
Mais exemplos de callback
Outros exemplos de callback podem ser encontrados no documento Mais exemplos de callback.
Propriedades de promoção e resultado
Usando a notação JSDoc, estas são as propriedades dos objetos promotion e result. Aqui, listamos todas as propriedades que podem estar presentes. A presença de muitas das propriedades depende dos detalhes da promoção ou do resultado da pesquisa.
{
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 em results tem o tipo flexível de uma matriz de objetos. Os valores das entradas nessa matriz são controlados pelos dados estruturados encontrados na página da Web para cada resultado da pesquisa. Por exemplo, um site de avaliações pode incluir
dados estruturados que adicionam esta entrada de matriz a richSnippet:
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},
API Programmable Search Element Control (V2)
O objeto google.search.cse.element publica as seguintes
funções estáticas:
| Função | Descrição | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
Renderiza um elemento de pesquisa.
Parâmetros
|
||||||
.go(opt_container) |
Renderiza todas as tags/classes do elemento de pesquisa no contêiner especificado.
Parâmetros
|
||||||
.getElement(gname) |
Recebe o objeto de elemento de gname. Se não for encontrado, retorna um valor nulo.
O objeto
O código a seguir executa a consulta "news" no elemento de pesquisa "element1": var element = google.search.cse.element.getElement('element1');
element.execute('news');
|
||||||
.getAllElements() |
Retorna um mapa de todos os objetos de elemento criados com sucesso, codificado por gname. |