API Programmable Search Element Control

É possível incorporar componentes do Mecanismo de Pesquisa Programável (caixas e páginas de resultados da pesquisa) em suas páginas e outros aplicativos da Web usando marcação HTML. Esses Mecanismos de Pesquisa Programável Os elementos consistem em componentes que são renderizados com base nas configurações armazenadas pelo do servidor de Pesquisa Programável, além de todas as personalizações que você fizer.

Todo o JavaScript é carregado de forma assíncrona, o que permite que sua página da Web continua carregando enquanto o navegador busca o JavaScript do Mecanismo de Pesquisa Programável.

Introdução

Este documento mostra um modelo básico para adicionar o Mecanismo de Pesquisa Programável elementos à sua página da Web, além de explicações sobre o comportamento componentes configuráveis e uma API JavaScript flexível.

Escopo

Este documento descreve como usar as funções e propriedades específicas do a API Programmable Search Engine Control.

Compatibilidade do navegador

A lista de navegadores compatíveis com o Mecanismo de Pesquisa Programável está disponível aqui.

Público

Esta documentação é destinada aos desenvolvedores que querem adicionar recursos programáveis do Google a funcionalidade de pesquisa nas páginas.

Elementos da Pesquisa Programável

Use a marcação HTML para adicionar um Elemento de pesquisa programável à sua página. Cada consiste em pelo menos um componente: uma caixa de pesquisa, um bloco de pesquisa resultados ou ambos. A caixa de pesquisa aceita a entrada do usuário em qualquer um dos 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 entradas no da seguinte maneira:

  • Uma string de consulta incorporada em um URL
  • Execução programática

Os seguintes tipos de Elementos da Pesquisa programável estão disponíveis:

Tipo de elemento Componentes Descrição
padrão <div class="gcse-search"> Uma caixa de pesquisa e resultados de pesquisa, mostrados no mesmo <div>.
duas colunas <div class="gcse-searchbox"> e <div class="gcse-searchresults"> Um layout de duas colunas com resultados de pesquisa em um lado e uma caixa de pesquisa um ao outro. Se você planeja inserir vários elementos no modo de duas colunas na sua página da Web, use o atributo gname para parear um caixa de pesquisa com um bloco de resultados de pesquisa.
somente caixa de pesquisa <div class="gcse-searchbox-only"> Uma caixa de pesquisa independente.
searchresults-only <div class="gcse-searchresults-only"> Um bloco independente de resultados de pesquisa.

É possível adicionar um número ilimitado de elementos de pesquisa válidos à página da Web. Para colunas todos os componentes necessários (uma caixa de pesquisa e bloco de resultados) 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>

Criar diferentes opções de layout usando elementos da Pesquisa programável

As opções de layout a seguir estão disponíveis na página "Aparência" do painel de controle do Mecanismo de Pesquisa Programável. Confira algumas diretrizes gerais sobre como escrever opções de layout usando os Elementos de Pesquisa Programável. Para ver uma demonstração de qualquer uma dessas opções, clique no link.

Opção Componentes
Largura total <div class="gcse-search">
Alta <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, <div class="gcse-searchresults-only"> (ou outros componentes) na segunda página.
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 as cores, a fonte ou o estilo dos links, acesse a página "Aparência" do mecanismo de pesquisa programável.

É possível usar atributos opcionais para substituir configurações criadas no Mecanismo de Pesquisa Programável painel de controle. 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 parâmetro O atributo queryParameterName, junto com a string de consulta do usuário, estão usada para criar o URL dos 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 preenchimento automático ou refinamentos, é possível usar atributos para e personalizar esses recursos. Qualquer personalização especificada usando esses atributos substitui as configurações feitas no painel de controle. O exemplo a seguir 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 searchbox com um componente searchresults. Se não forem fornecidos, O Mecanismo de Pesquisa Programável gera um gname automaticamente com base na a ordem dos componentes na página da Web. Por exemplo, o primeiro sem nome searchbox-only tem a coluna gname "somente caixa de pesquisa0" e o segundo tem o gname "seachbox-only1", e assim por diante. Observe que o gname gerado automaticamente para um componente em o layout de duas colunas será two-column. O exemplo a seguir usa o gname storesearch para vincular um searchbox; com um componente searchresults:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Na recuperação de um objeto, se mais de um componente tiver o mesmo gname, o Mecanismo de Pesquisa Programável vai usar o último componente da página.

Qualquer
autoSearchOnLoad Booleano Especifica se é necessário executar uma pesquisa pela consulta incorporada no URL da página que está carregando. Uma string de consulta precisa estar presente no URL para executar a pesquisa automática. Padrão: true. Qualquer
enableHistory Booleano Se true, ativa o gerenciamento do histórico do navegador Voltar e "Avançar". Veja uma demonstração.

caixa de pesquisa

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 o O nome do parâmetro de consulta por si só não aciona a pesquisa automática no carregamento. Uma consulta deve estar presente no URL para executar a pesquisa automática. Qualquer
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

Esse parâmetro permite fornecer um booleano que informa ao Google que você quer permitir anúncios que usam um cookie somente para tráfego inválido e o armazenamento local no o tráfego sem consentimento de cookies.

true Quando esse parâmetro não está presente ou você o define como "true", vamos definir um cookie exclusivo para tráfego inválido e usa o armazenamento local apenas em tráfego com consentimento.

false Quando você define esse parâmetro como "false" vamos definir um valor dos cookies somente de tráfego e usam o armazenamento local no tráfego com e sem consentimento.

Padrão: false

Exemplo de uso: <div class="gcse-search" data-ivt="true"></div>

resultadosdapesquisa

searchresults-only

mobileLayout String

Especifica se os estilos de layout para dispositivos móveis precisam ser usados.

enabled Usa o layout móvel apenas para dispositivos móveis.

disabled Não usa o layout para dispositivos móveis nos dispositivos.

forced usa o layout móvel para todos os dispositivos;

Padrão: enabled

Exemplo de uso: <div class="gcse-search" data-mobileLayout="disabled"></div>

Qualquer
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
autoCompleteMaxCompletions Número inteiro O número máximo de preenchimentos automáticos a serem exibidos.

caixa de pesquisa

somente caixa de pesquisa

autoCompleteMaxPromotions Número inteiro O número máximo de promoções a serem exibidas no preenchimento automático.

caixa de pesquisa

somente caixa de pesquisa

autoCompleteValidLanguages String Lista de idiomas separados por vírgulas para os quais o preenchimento automático deve ser ativado. Idiomas disponíveis.

caixa de pesquisa

somente caixa de pesquisa

Refinamentos
defaultToRefinement String Disponível somente se refinamentos tiverem sido criados no Painel de controle do Mecanismo de Pesquisa Programável. Especifica o marcador de refinamento padrão para display.Observação: esse atributo não é compatível com o layout hospedado pelo Google. Qualquer
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 está ativada, mas a pesquisa na Web está desativada.

resultadosdapesquisa

searchresults-only

Pesquisa de imagens
enableImageSearch Booleano Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Se for true, ativa a pesquisa de imagens. Os resultados de imagens serão exibidos guia separada.

resultadosdapesquisa

searchresults-only

defaultToImageSearch Booleano Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Se for true, a página de resultados da pesquisa vai mostrar os resultados da pesquisa de imagens por padrão. Os resultados da Web vão estar disponíveis em uma guia separada.

Qualquer
imageSearchLayout String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Especifica o layout da página de resultados da pesquisa de imagens. Valores aceitáveis são classic, column ou popup.

resultadosdapesquisa

searchresults-only

imageSearchResultSetSize Número inteiro, string Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Especifica o tamanho máximo do conjunto de resultados da pesquisa definido para a pesquisa de imagens. Por exemplo, large, small, filtered_cse, 10.

Qualquer
image_as_filetype String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Restringe os resultados aos arquivos de uma extensão especificada.

As extensões aceitas são jpg, gif, png, bmp, svg, webp, ico e raw.

Qualquer

image_as_oq String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Filtra 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":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

Qualquer

image_as_rights String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Filtros com base no licenciamento.

Os valores aceitos são cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived e combinações desses valores.

Veja as combinações típicas.

Qualquer

image_as_sitesearch String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Restringir os resultados a páginas de um site específico.

Exemplo de uso: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

Qualquer

image_colortype String Disponível apenas se a pesquisa de imagens foi 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 mono, gray e color.

Qualquer

image_cr String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Restringe os resultados da pesquisa a documentos originados em um determinado país.

Valores compatíveis

Qualquer

image_dominantcolor String Disponível apenas se a pesquisa de imagens foi 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 red, orange, yellow, green, teal, blue, purple, pink, white, gray, black e brown.

Qualquer

image_filter String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Filtragem automática dos resultados da pesquisa.

Valores aceitos: 0/1

Exemplo de uso: <div class="gcse-search" data-image_filter="0"></div>

Qualquer

image_gl String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável. Otimize os resultados da pesquisa com o país de origem que corresponde ao valor do parâmetro.

Valores compatíveis

Qualquer

image_size String Disponível apenas se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

Retorna imagens de um tamanho especificado, em que o tamanho pode ser: icon, small, medium, large, xlarge, xxlarge ou huge.

Qualquer

image_sort_by String Disponível apenas se a pesquisa de imagens foi 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: <div class="gcse-search" data-image_sort_by="date"></div>

Qualquer

image_type String Disponível apenas se a pesquisa de imagens foi 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 clipart (Clip Art), face (Rostos de pessoas), lineart (Desenhos de linha), stock (Fotos de banco de imagens), photo (Fotografias) e animated (GIFs animados).

Qualquer

Pesquisa na Web
disableWebSearch Booleano Se for true, a pesquisa na Web será desativada. Em geral, usado somente se a pesquisa de imagens foi ativada no painel de controle do Mecanismo de Pesquisa Programável.

resultadosdapesquisa

searchresults-only

webSearchQueryAddition String Termos extras foram adicionados à consulta de pesquisa usando o operador lógico "OR".

Exemplo de uso: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

Qualquer
webSearchResultSetSize Número inteiro, string O tamanho máximo do conjunto de resultados. Válido para tanto na pesquisa de imagens quanto na 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 se especificou locais Os valores aceitáveis são os seguintes:
  • Um número inteiro de 1 a 20.
  • small: solicita um conjunto pequeno de resultados, normalmente quatro resultados. por página.
  • large: solicita um conjunto grande de resultados, normalmente 8. resultados por página.
  • filtered_cse: solicita até 10 resultados por página, para uma máximo de 10 páginas ou 100 resultados.
Qualquer
webSearchSafesearch String Especifica se O SafeSearch é ativado para resultados da pesquisa na Web. Os valores aceitos são off e active. Qualquer
as_filetype String Restringe os resultados aos arquivos de uma extensão especificada. Uma lista de tipos de arquivo indexáveis pelo Google pode ser encontrada na Central de Ajuda do Search Console.

Qualquer

as_oq String Filtra 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":<div class="gcse-search" data-as_oq="term1 term2"></div>

Qualquer
as_rights String Filtros com base no licenciamento.

Os valores aceitos são cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived e combinações desses valores.

Consulte https://wiki.creativecommons.org/wiki/CC_Search_integration para conferir combinações comuns.

Qualquer

as_sitesearch String Restringir os resultados a páginas de um site específico.

Exemplo de uso: <div class="gcse-search" data-as_sitesearch="example.com"></div>

Qualquer
cr String Restringe os resultados da pesquisa a documentos originados em um determinado país.

Valores compatíveis

Exemplo de uso: <div class="gcse-search" data-cr="countryFR"></div>

Qualquer
filter String Filtragem automática dos resultados da pesquisa.

Valores aceitos: 0/1

Exemplo de uso: <div class="gcse-search" data-filter="0"></div>

Qualquer
gl String Otimize os resultados da pesquisa com o país de origem que corresponde ao valor do parâmetro.

Isso só funciona em conjunto com a configuração language value.

Valores compatíveis

Exemplo de uso: <div class="gcse-search" data-gl="fr"></div>

Qualquer
lr String Restringe os resultados da pesquisa a documentos escritos em um idioma específico.

Valores compatíveis

Exemplo de uso: <div class="gcse-search" data-lr="lang_fr"></div>

Qualquer
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 egno de pesquisa programável.

Para classificar por relevância, use uma string vazia (sort_by="").

Exemplo de uso: <div class="gcse-search" data-sort_by="date"></div>

Qualquer
Resultados da pesquisa
enableOrderBy Booleano Permite a classificação de resultados por relevância, data ou marcador. Qualquer
linkTarget String Define o destino do link. Padrão: _blank.

resultadosdapesquisa

searchresults-only

noResultsString String Especifica o texto padrão a ser exibido quando nenhum resultado corresponder à consulta. A string de resultado padrão pode ser usada para exibir uma string localizada em todo idiomas compatíveis, mas o personalizado não.

resultadosdapesquisa

searchresults-only

resultSetSize Número inteiro, string O tamanho máximo do conjunto de resultados. Por exemplo, large, small, filtered_cse e 10. A padrão depende do layout e da configuração do mecanismo para pesquisar de toda a Web ou apenas de sites especificados. Qualquer
safeSearch String Especifica se O SafeSearch está ativado para a pesquisa na Web e de imagens. Os valores aceitos são off e active. Qualquer

Callbacks

Diagrama de sequência de callback
diagrama de sequência de callbacks do Search Element JavaScript

Os callbacks permitem um controle detalhado da inicialização do elemento de pesquisa e dos processos de pesquisa. Eles são registrados com o elemento de pesquisa JavaScript por meio do __gcse global objeto. Register Callbacks ilustra o registro de todos os os callbacks compatíveis.

Registrar callbacks

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };
  

O callback de inicialização

O callback de inicialização é invocado antes que o JavaScript do elemento de pesquisa renderize a pesquisa. elementos no DOM. Se parsetags estiver definido como explicit em __gcse, o JavaScript do Elemento de pesquisa deixa a renderização dos elementos de pesquisa para o retorno de chamada de inicialização (como 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, ela pode transformar caixa de pesquisa configurada por meio do Painel de controle ou de atributos HTML para padronizar para a web pesquisar em uma caixa de pesquisa de imagens ou especificar que as consultas enviadas por um formulário do Mecanismo de Pesquisa Programável são executada em um elemento somente searchresults. Veja uma demonstração.

A função do callback de inicialização é controlada pelo valor de parsetags propriedade de __gcse.

  • Se o valor for onload, o elemento de pesquisa O JavaScript renderiza todos os elementos de pesquisa da página automaticamente. O callback de inicialização é ainda invocado, mas não é responsável pela renderização dos elementos de pesquisa.
  • Se o valor for explicit, o JavaScript do elemento de pesquisa não será renderizado. Elementos de pesquisa. O callback pode renderizá-los seletivamente usando o função render(), ou renderizar todos os elementos da pesquisa com a função go()

O código a seguir demonstra como exibir uma caixa de pesquisa, junto com os resultados da pesquisa, em um div, usando a parsetag explicit e o callback de inicialização:

.
Exemplo de callback de inicialização

Precisamos incluir um <div> com um valor de ID. em que gostaríamos do código do Elemento de pesquisa:

    <div id="test"></div>
Adicione esse JavaScript após <div>. Observe que 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 nas src pela sua própria cx.

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

Pesquisar retornos de chamada

O JavaScript do Elemento de pesquisa suporta 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 de 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 configurado usando entradas no objeto __gcse. Isso acontece, porque o Elemento de pesquisa O JavaScript é iniciado. Modificações em __gcse após a inicialização são ignoradas.

Cada um desses callbacks recebe o gName para o elemento de pesquisa como um argumento. O gname é útil quando uma página contém mais de uma pesquisa. Faça uma pesquisa um elemento gname com valores 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 será permanecem consistentes até que o HTML seja modificado.

Callback de inicialização da pesquisa de imagem/na Web

Os callbacks iniciais da pesquisa são invocados imediatamente antes das solicitações JavaScript do elemento de pesquisa. resultados de pesquisa do seu servidor. Um exemplo de caso de uso seria usar a hora local do dia para controlar as mudanças feitas na consulta.

searchStartingCallback(gname, query)
gname
String de identificação do elemento de pesquisa
query
valor inserido pelo usuário (possivelmente modificado pela pesquisa JavaScript.

O callback retorna o valor que deve ser usado como a consulta para essa pesquisa. Se ele retornar um string vazia, o valor de retorno é ignorado e o autor da chamada usa a consulta não modificada.

Como alternativa, coloque a função de callback no objeto __gcse ou adicione dinamicamente o callback ao objeto com JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Exemplo de callback inicial da pesquisa

O exemplo de pesquisa que inicia o callback em Exemplo de retorno de chamada de inicialização de pesquisa adiciona morning. ou afternoon à consulta, dependendo da hora do dia.

Exemplo de callback de início da pesquisa
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

Instale 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 da pesquisa na Web/de imagem

Esses callbacks são invocados imediatamente antes que o JavaScript do elemento de pesquisa processe 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 aos promotions para o a consulta do usuário. Veja a definição do objeto de promoção.
results
uma matriz de objetos de resultado. Consulte a definição do objeto resultante.
div
um div HTML posicionado no DOM onde o elemento de pesquisa normalmente promoções de lugares e resultados de pesquisa. Normalmente, o JavaScript do elemento de pesquisa lida preenchendo o div. No entanto, esse callback poderá interromper a renderização automática dos resultados. e usar esse div para renderizar os resultados.
.

Se esse callback retornar um valor true, o JavaScript do elemento de pesquisa vai pular para o e o rodapé da página funcionam.

Exemplo de callback de resultados prontos

O exemplo de callback resultsReady em O Exemplo de chamada de retorno de resultados prontos substitui a apresentação padrão de promoções e resultados com uma substituição muito simples.

Exemplo de callback de resultados prontos
    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;
    };

Instale 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 acontece com o retorno de chamada de início da pesquisa, o exemplo acima é uma das muitas maneiras de colocar o retorno de chamada no __gcse.

Callback renderizado nos resultados da pesquisa da Web/de imagem

Esses callbacks são invocados imediatamente antes que o JavaScript do elemento de pesquisa renderize a página. rodapé. Exemplos de casos de uso incluem um callback que adiciona o conteúdo do resultado que a pesquisa não exibe, como uma caixa de seleção salvar isto ou informações que não estão renderizados automaticamente ou um callback que adicione botões para mais informações.

Se um callback renderizado de resultados precisar de informações que estavam no promos e results do callback Ready de resultados, ele pode transmiti-los entre eles, desta forma:

callback(gname, query, promoElts, resultElts);
gname
String de identificação do elemento de pesquisa
query
string de pesquisa.
promoElts
uma matriz dos elementos DOM que contém promoções.
resultElts
: uma matriz de elementos DOM contendo resultados.

Não há valor de retorno.

Exemplo de callback renderizado de resultados

O exemplo de callback resultsRendered em Example Results Rendered Callback adiciona um Keep (link em inglês) fictício caixa de seleção a cada promoção e resultado.

Exemplo de callback de resultado renderizado
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);
    }
  };

Instale 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 renderizado dos resultados precisar informações que foram transmitidas para o callback pronto para resultados, ele pode transmitir esses dados entre os callbacks. O exemplo a seguir mostra uma das várias maneiras de transmitir um valor de avaliação de richSnippet do callback pronto para resultados até os resultados renderizados .

.
Exemplo de callback de resultados prontos que coopera com o callback de resultados renderizados
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};
};
Instale esse callback usando um código como este ao configurar o __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 na Documento Mais exemplos de callback.

Propriedades da promoção e do resultado

Usando a notação JSDoc, essas são as propriedades do objetos promotion e result. Aqui, listamos todas as propriedades que podem estar presentes. A presença de muitas das propriedades dependem dos detalhes da promoção ou do resultado da pesquisa.

Propriedades da promoção
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
Propriedades do objeto de resultados
{
  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 livre de uma matriz de objetos. Os valores das entradas nessa matriz são controlados pelo dados estruturados encontrados na página da Web para cada resultado de pesquisa. Por exemplo, um site de resenhas pode incluir dados estruturados que adicionam essa entrada de matriz a richSnippet:

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

API Programmable Search Element Control (V2)

O objeto google.search.cse.element publica o seguinte funções estáticas:

Função Descrição
.render(componentConfig, opt_componentConfig) Renderiza um elemento de pesquisa.

Parâmetros

Nome Descrição
componentConfig A configuração de um componente do Programmable Search Element. Especifica o seguinte:
  • div (string|Element): o id do <div> ou do elemento div em que o elemento da Pesquisa Programável será renderizado.
  • tag (string): o tipo de componente a ser renderizado. Quando opt_componentConfig é fornecido, o valor do atributo tag precisa ser searchbox. Os valores permitidos são:
    • search: uma caixa de pesquisa e os resultados da pesquisa, exibidos juntos
    • searchbox: um componente da caixa de pesquisa de um Elemento de pesquisa programável.
    • searchbox-only: uma caixa de pesquisa autônoma, que será pareada com um bloco de resultados de pesquisa especificado por opt_componentConfig em um layout de duas colunas.
    • searchresults-only: um bloco independente de resultados da pesquisa. As pesquisas são acionadas por um parâmetro de consulta incorporado em um URL ou por execução programática.
  • gname (string): (opcional) um nome exclusivo para este componente. Se ele não for informado, o Mecanismo de Pesquisa Programável vai gerar um gname automaticamente.
  • attributes (objeto): atributos opcionais na forma de um par de chave-valor. Atributos compatíveis.
opt_componentConfig Opcional. Argumento de configuração do segundo componente. Usada em TWO_COLUMN para fornecer o componente searchresults. Especifica o seguinte:
  • div (string): o id do <div> ou o elemento div em que o elemento será renderizado.
  • tag (string): o tipo de componente a ser renderizado. Quando opt_componentConfig é fornecido, o valor do parâmetro tag atributo precisa ser searchresults. Além disso, o valor do atributo Atributo tag de componentConfig precisa ser searchbox.
  • gname (string): (opcional) um nome exclusivo para este componente. Caso contrário fornecido, o Mecanismo de Pesquisa Programável vai gerar automaticamente um gname para ele componente. Se fornecido, ele precisa corresponder ao gname no componentConfig.
  • attributes (objeto): atributos opcionais no formato de uma chave-valor. par. Atributos compatíveis.
.go(opt_container) Renderiza todas as tags/classes do Elemento de pesquisa no contêiner especificado.

Parâmetros

Nome Descrição
opt_container O contêiner que contém os componentes do Elemento de pesquisa a serem renderizados. Especificar o ID do contêiner (string) ou o próprio elemento. Se omitidos, todos os componentes do Elemento de Pesquisa Programável dentro do elemento A tag body será renderizada.
.getElement(gname) Recebe o objeto do elemento por gname. Se não for encontrado, retorna nulo.

O objeto element retornado tem os seguintes atributos:

  • gname: o nome do objeto do elemento. Se não for informado, o Mecanismo de Pesquisa Programável vai gerar automaticamente um gname para o objeto. Mais informações.
  • type: o tipo de elemento.
  • uiOptions: os atributos finais usados para renderizar o elemento.
  • execute – function(string): executa uma consulta programática.
  • prefillQuery - function(string): preenche automaticamente a caixa de pesquisa com uma consulta sem executar a consulta.
  • getInputQuery – function(): recebe o valor atual exibido na entrada caixa
  • clearAllResults - function(): limpa o controle ocultando tudo, exceto na caixa de pesquisa, se houver.

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, codificados por gname.