Programmable Search Element Control API

Komponenty Wyszukiwarki niestandardowej (pola wyszukiwania i strony wyników wyszukiwania) można umieszczać na stronach internetowych i w innych aplikacjach internetowych przy użyciu znaczników HTML. Wyszukiwarka niestandardowa elementy składają się z komponentów renderowanych na podstawie ustawień zapisanych przez serwer Wyszukiwarki niestandardowej wraz ze wszelkimi zmianami wprowadzonymi przez Ciebie.

Cały JavaScript jest wczytywany asynchronicznie, dzięki czemu strona może trwa wczytywanie, gdy przeglądarka pobierze kod JavaScript Wyszukiwarki niestandardowej.

Wprowadzenie

Ten dokument przedstawia podstawowy model dodawania Wyszukiwarki niestandardowej wraz z wyjaśnieniem funkcji konfigurowalne komponenty i elastyczny interfejs JavaScript API.

Zakres

W tym dokumencie opisujemy, jak używać funkcji i właściwości charakterystycznych dla (Programmable Search Engine Control API).

Zgodność z przeglądarką

Listę przeglądarek obsługiwanych przez Wyszukiwarkę niestandardową znajdziesz tutaj.

Odbiorcy

Ta dokumentacja jest przeznaczona dla deweloperów, którzy chcą dodać programowalne aplikacje Google funkcję wyszukiwania na swoich stronach.

Elementy Wyszukiwarki niestandardowej

Aby dodać element Wyszukiwarki niestandardowej do strony, możesz użyć znaczników HTML. Każdy składa się z co najmniej jednego elementu: pola wyszukiwania, bloku albo jedno i drugie. Pole wyszukiwania akceptuje dane wejściowe użytkownika w dowolnym z następujących elementów sposoby:

  • Zapytanie wpisane w polu do wprowadzania tekstu
  • Ciąg zapytania umieszczony w adresie URL
  • Automatyczne wykonanie

Blok wyników wyszukiwania akceptuje też dane wejściowe w następujący sposób:

  • Ciąg zapytania umieszczony w adresie URL
  • Automatyczne wykonanie

Dostępne są te typy elementów Wyszukiwarki niestandardowej:

Typ elementu Komponenty Opis
standardowa <div class="gcse-search"> w polu wyszukiwania i z wynikami wyszukiwania, wyświetlane w tym samym <div>.
dwukolumnowy <div class="gcse-searchbox"><div class="gcse-searchresults"> Układ dwukolumnowy z wynikami wyszukiwania po jednej stronie i polem wyszukiwania z drugiej strony. Jeśli zamierzasz wstawić wiele elementów w trybie dwukolumnowym na swojej stronie, możesz użyć atrybutu gname, aby powiązać pola wyszukiwania z blokiem wyników wyszukiwania.
tylko pole wyszukiwania <div class="gcse-searchbox-only"> Oddzielne pole wyszukiwania.
searchresults-only <div class="gcse-searchresults-only"> Osobny blok wyników wyszukiwania.

Do swojej strony internetowej możesz dodać dowolną liczbę prawidłowych elementów wyszukiwania. Dla 2 kolumn oraz wszystkie wymagane komponenty (pole wyszukiwania blok wyników).

Oto przykład prostego elementu wyszukiwania:

<!-- 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>

Tworzenie różnych opcji układu za pomocą Programmable Search Elements

Na stronie Wygląd i styl w panelu sterowania Wyszukiwarki niestandardowej dostępne są poniższe opcje układu. Oto kilka ogólnych wskazówek dotyczących tworzenia opcji układu za pomocą Programmable Search Elements. Aby zobaczyć wersję demonstracyjną dowolnej z tych opcji, kliknij link.

Opcja Komponenty
Pełna szerokość <div class="gcse-search">
Kompaktowy <div class="gcse-search">
Dwukolumnowa <div class="gcse-searchbox">, <div class="gcse-searchresults">
Dwie strony <div class="gcse-searchbox-only"> na pierwszej stronie, <div class="gcse-searchresults-only"> (lub innych komponentach) na drugiej stronie.
Tylko wyniki <div class="gcse-searchresults-only">
Na stronach hostowanych przez Google <div class="gcse-searchbox-only">

Więcej informacji o opcjach układu

Dostosowywanie elementów Wyszukiwarki niestandardowej

Aby dostosować kolory, czcionkę lub styl linku, otwórz stronę Wygląd i styl wyszukiwarki niestandardowej.

Możesz użyć atrybutów opcjonalnych, aby zastąpić konfiguracje utworzone w Wyszukiwarka niestandardowa panelu sterowania. Dzięki temu możesz przeprowadzić wyszukiwanie dostosowane do konkretnej strony. Na przykład ten kod tworzy pole wyszukiwania, które otwiera stronę wyników (http://www.example.com?search=lady+gaga) w nowym oknie. Wartość klucza Atrybut queryParameterName wraz z ciągiem zapytania użytkownika jest posłuży do utworzenia adresu URL wyników.

Pamiętaj, że atrybut queryParameterName ma przedrostek data-. Ten prefiks jest wymagany dla wszystkich atrybutów.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

Jeśli w panelu sterowania Wyszukiwarki niestandardowej są włączone funkcje takie jak autouzupełniania lub doprecyzowań, możesz użyć atrybutów, i dostosować te funkcje. Wszelkie dostosowania określone za pomocą tych atrybutów zastąpi ustawienia wprowadzone w panelu sterowania. Ten przykład tworzy dwukolumnowy element wyszukiwania z następującymi funkcjami:

  • Zarządzanie historią jest włączone
  • Maksymalna liczba wyświetlanych autouzupełnień jest ustawiona na 5.
  • Zawężenia wyszukiwania są wyświetlane jako linki.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

Obsługiwane atrybuty

Atrybut Typ Opis Komponent
Ogólne
gname Ciąg znaków (Opcjonalnie) Nazwa obiektu elementu wyszukiwania. Nazwa jest używana do pobierania powiązanego komponentu według nazwy lub sparowania komponentu searchbox. z komponentem searchresults. Jeśli nie zostanie podany, Wyszukiwarka niestandardowa wygeneruje automatycznie gname na podstawie kolejność komponentów na stronie. Na przykład pierwszy element bez nazwy searchbox-only ma gname „tylko pole wyszukiwania0” a drugi ma gname „tylko_schowanie11” itd. Zwróć uwagę, że automatycznie wygenerowana wartość gname dla komponentu w dwukolumnowy będzie two-column. Przykład poniżej używa Gname storesearch do połączenia usługi searchbox z komponentem searchresults:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Podczas pobierania obiektu, jeśli więcej niż 1 komponent ma taki sam gname, Wyszukiwarka niestandardowa użyje ostatniego komponentu w parametrze stronę.

Dowolny
autoSearchOnLoad Wartość logiczna Określa, czy mają być wykonywane wyszukiwanie za pomocą zapytania umieszczonego w adresie URL strony, która się wczytuje. Pamiętaj, że adres URL musi zawierać ciąg zapytania aby uruchomić automatyczne wyszukiwanie. Domyślnie: true. Dowolny
enableHistory Wartość logiczna Jeśli zasada ma wartość true, zarządzanie historią w przeglądarce jest włączone. i Dalej. Zobacz prezentację

pole wyszukiwania

tylko pole wyszukiwania

queryParameterName Ciąg znaków nazwa parametru zapytania, na przykład q (domyślna); lub query. Zostanie ona umieszczona w adresie URL (na przykład http://www.example.com?q=lady+gaga). Pamiętaj, że określenie parametru sama nazwa parametru zapytania nie powoduje automatycznego wyszukiwania po wczytaniu. Zapytanie Aby można było przeprowadzić automatyczne wyszukiwanie, URL musi zawierać ciąg znaków. Dowolny
resultsUrl URL Adres URL strony wyników. (Domyślnie jest to strona na serwerze Google). tylko pole wyszukiwania
newWindow Wartość logiczna Określa, czy strona wyników ma się otwierać w nowym oknie. Domyślnie: false. tylko pole wyszukiwania
ivt Wartość logiczna

Ten parametr umożliwia podanie wartości logicznej, która informuje Google, że chcesz zezwolić na wyświetlanie reklam, które korzystają z pliku cookie służącego tylko do wykrywania nieprawidłowego ruchu; pamięci lokalnej w przypadku użytkowników, którzy wyrazili zgodę, użytkowników, którzy nie wyrazili zgody.

true Jeśli ten parametr nie istnieje lub ma wartość „true” (prawda), ustawimy na podstawie pliku cookie służącego tylko do wykrywania nieprawidłowego ruchu i używać pamięci lokalnej tylko w przypadku ruchu, który wyraził zgodę na przetwarzanie danych.

false Gdy ustawisz ten parametr na „false” ustawimy nieprawidłowy pliki cookie służące tylko do ruchu i korzystają z pamięci lokalnej zarówno w przypadku użytkowników, którzy wyrazili zgodę, jak i tych, którzy jej nie wyrazili.

Domyślnie: false

Przykładowe zastosowanie: <div class="gcse-search" data-ivt="true"></div>

wyniki wyszukiwania

searchresults-only

mobileLayout Ciąg znaków

Określa, czy w przypadku urządzeń mobilnych mają być używane style układu mobilnego.

enabled Używa układu mobilnego tylko na urządzeniach mobilnych.

disabled Nie korzysta z układu mobilnego na żadnych urządzeniach.

forced Na wszystkich urządzeniach jest używany układ mobilny.

Domyślnie: enabled

Przykładowe zastosowanie: <div class="gcse-search" data-mobileLayout="disabled"></div>

Dowolny
Autouzupełnianie
enableAutoComplete Wartość logiczna Ta opcja jest dostępna tylko po włączeniu autouzupełniania w panelu sterowania Wyszukiwarki niestandardowej. true włącza autouzupełnianie. Dowolny
autoCompleteMaxCompletions Liczba całkowita Maksymalna liczba autouzupełnień do wyświetlenia.

pole wyszukiwania

tylko pole wyszukiwania

autoCompleteMaxPromotions Liczba całkowita Maksymalna liczba wyników promowanych do wyświetlenia w autouzupełnianiu.

pole wyszukiwania

tylko pole wyszukiwania

autoCompleteValidLanguages Ciąg znaków Rozdzielona przecinkami lista języków, dla których ma być wykonywane autouzupełnianie . Obsługiwane języki.

pole wyszukiwania

tylko pole wyszukiwania

Doprecyzowania
defaultToRefinement Ciąg znaków Dostępne tylko wtedy, gdy doprecyzowania wyszukiwania zostały utworzone w Panel sterowania Wyszukiwarki niestandardowej. Określa domyślną etykietę zawężania display.Uwaga: ten atrybut nie jest obsługiwany w przypadku układu hostowanego przez Google. Dowolny
refinementStyle Ciąg znaków Akceptowane wartości to tab (wartość domyślna) i link. Funkcja link jest obsługiwana tylko wtedy, gdy wyszukiwanie grafiki jest wyłączone lub jeśli wyszukiwanie obrazów jest włączone, ale wyszukiwanie w internecie jest wyłączone.

wyniki wyszukiwania

searchresults-only

Wyszukiwarka grafiki
enableImageSearch Wartość logiczna Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Jeśli zasada true, umożliwia wyszukiwanie obrazów. Wyniki wyszukiwania grafiki będą wyświetlane na osobnej karcie.

wyniki wyszukiwania

searchresults-only

defaultToImageSearch Wartość logiczna Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Jeśli true, na stronie wyników wyszukiwania będą wyświetlane wyniki wyszukiwania obrazów domyślnie. Wyniki z internetu będą dostępne na osobnej karcie.

Dowolny
imageSearchLayout Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Określa układ strony wyników wyszukiwania grafiki. Akceptowane wartości to classic, column lub popup.

wyniki wyszukiwania

searchresults-only

imageSearchResultSetSize Liczba całkowita, ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Określa maksymalny rozmiar wyników wyszukiwania ustawionych dla wyszukiwania grafiki. Przykłady: large, small, filtered_cse, 10.

Dowolny
image_as_filetype Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Ogranicza wyniki do plików z określonym rozszerzeniem.

Obsługiwane rozszerzenia to jpg, gif, png, bmp, svg, webp, ico oraz raw.

Dowolny

image_as_oq Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Przefiltruj wyniki wyszukiwania, używając logicznego LUB.

Przykładowe zastosowanie, gdy chcesz otrzymywać wyniki wyszukiwania zawierające hasło „term1” lub "term2":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

Dowolny

image_as_rights Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Filtry na podstawie licencji.

Obsługiwane wartości to cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial i cc_nonderived oraz ich kombinacje.

Zobacz typowe kombinacje.

Dowolny

image_as_sitesearch Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Ogranicz wyniki do stron z określonej witryny.

Przykładowe zastosowanie: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

Dowolny

image_colortype Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Ogranicza wyszukiwanie do obrazów czarno-białych (mono), skali szarości lub kolorowych. Obsługiwane wartości to mono, gray oraz color.

Dowolny

image_cr Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Ogranicza wyniki wyszukiwania do dokumentów pochodzących z konkretnego kraju.

Obsługiwane wartości

Dowolny

image_dominantcolor Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Ogranicza wyszukiwanie do obrazów o określonym dominującym kolorze. Obsługiwane wartości to red, orange, yellow, green, teal, blue, purple, pink, white, gray, black oraz brown.

Dowolny

image_filter Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

automatyczne filtrowanie wyników wyszukiwania;

Obsługiwane wartości: 0/1

Przykładowe zastosowanie: <div class="gcse-search" data-image_filter="0"></div>

Dowolny

image_gl Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki. Wyróżniaj wyniki wyszukiwania z kraju, który pasuje do wartości parametru.

Obsługiwane wartości

Dowolny

image_size Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Zwraca obrazy o określonym rozmiarze, przy czym rozmiar może być następujący: icon, small, medium, large, xlarge, xxlarge lub huge.

Dowolny

image_sort_by Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Możesz sortować wyniki według daty lub innej uporządkowanych treści.

Aby posortować według trafności, użyj pustego ciągu (image_sort_by=).

Przykładowe zastosowanie: <div class="gcse-search" data-image_sort_by="date"></div>

Dowolny

image_type Ciąg znaków Dostępne tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

Ogranicza wyszukiwanie do obrazów określonego typu. Obsługiwane wartości to clipart (Clipart), face (twarze ludzi), lineart (rysunki liniowe), stock (zdjęcia licencjonowane), photo (zdjęcia) i animated (animowane GIF-y).

Dowolny

Wyszukiwarka Google
disableWebSearch Wartość logiczna Jeśli true, wyłącza wyszukiwanie w internecie. Zwykle używane tylko wtedy, gdy w panelu sterowania Wyszukiwarki niestandardowej jest włączone wyszukiwanie grafiki.

wyniki wyszukiwania

searchresults-only

webSearchQueryAddition Ciąg znaków Dodatkowe hasła zostały dodane do zapytania za pomocą operatora logicznego LUB.

Przykładowe zastosowanie: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

Dowolny
webSearchResultSetSize Liczba całkowita, ciąg znaków Maksymalny rozmiar zestawu wyników. Dotyczy zarówno w wyszukiwarce grafiki, jak i w internecie. Zależy ona od układu czy Wyszukiwarka niestandardowa jest skonfigurowana tak, aby przeszukiwać cały internet, czy tylko określone witryn. Akceptowane wartości:
  • Liczba całkowita od 1 do 20
  • small: prosi o niewielki zestaw wyników, zwykle 4 wyniki. na stronę.
  • large: żąda dużego zestawu wyników, zwykle 8 wyników na stronie.
  • filtered_cse: żąda maksymalnie 10 wyników na stronę, dla maksymalnie 10 stron lub 100 wyników.
Dowolny
webSearchSafesearch Ciąg znaków Określa, jeśli SafeSearch jest z wynikami wyszukiwania w internecie. Akceptowane wartości to off i active. Dowolny
as_filetype Ciąg znaków Ogranicza wyniki do plików z określonym rozszerzeniem. Listę typów plików, które Google może indeksować, znajdziesz w Centrum pomocy Search Console.

Dowolny

as_oq Ciąg znaków Przefiltruj wyniki wyszukiwania, używając logicznego LUB.

Przykładowe zastosowanie, gdy chcesz otrzymywać wyniki wyszukiwania zawierające hasło „term1” lub "term2":<div class="gcse-search" data-as_oq="term1 term2"></div>

Dowolny
as_rights Ciąg znaków Filtry na podstawie licencji.

Obsługiwane wartości to cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial i cc_nonderived oraz ich kombinacje.

Typowe kombinacje znajdziesz na stronie https://wiki.creativecommons.org/wiki/CC_Search_integration.

Dowolny

as_sitesearch Ciąg znaków Ogranicz wyniki do stron z określonej witryny.

Przykładowe zastosowanie: <div class="gcse-search" data-as_sitesearch="example.com"></div>

Dowolny
cr Ciąg znaków Ogranicza wyniki wyszukiwania do dokumentów pochodzących z konkretnego kraju.

Obsługiwane wartości

Przykładowe zastosowanie: <div class="gcse-search" data-cr="countryFR"></div>

Dowolny
filter Ciąg znaków automatyczne filtrowanie wyników wyszukiwania;

Obsługiwane wartości: 0/1

Przykładowe zastosowanie: <div class="gcse-search" data-filter="0"></div>

Dowolny
gl Ciąg znaków Wyróżniaj wyniki wyszukiwania z kraju, który pasuje do wartości parametru.

Ta funkcja działa tylko w połączeniu z wartością języka.

Obsługiwane wartości

Przykładowe zastosowanie: <div class="gcse-search" data-gl="fr"></div>

Dowolny
lr Ciąg znaków Ogranicza wyniki wyszukiwania do dokumentów napisanych w określonym języku.

Obsługiwane wartości

Przykładowe zastosowanie: <div class="gcse-search" data-lr="lang_fr"></div>

Dowolny
sort_by Ciąg znaków Możesz sortować wyniki według daty lub innej uporządkowanych treści. Wartość atrybutu musi być jedną z opcji dostępnych w ustawieniach sortowania wyników w Egnine Programmable Search.

Aby posortować według trafności, użyj pustego ciągu (sort_by="”).

Przykładowe zastosowanie: <div class="gcse-search" data-sort_by="date"></div>

Dowolny
Wyniki wyszukiwania
enableOrderBy Wartość logiczna Włącza sortowanie wyników według trafności, daty lub etykiety. Dowolny
linkTarget Ciąg znaków Określa wartość docelową linku. Domyślnie: _blank.

wyniki wyszukiwania

searchresults-only

noResultsString Ciąg znaków Określa tekst domyślny wyświetlany, gdy żadne wyniki nie pasują do zapytania. Domyślny ciąg wynikowy może służyć do wyświetlania zlokalizowanego ciągu znaków we wszystkich obsługiwanych języków, w przeciwieństwie do języka dostosowanego.

wyniki wyszukiwania

searchresults-only

resultSetSize Liczba całkowita, ciąg znaków Maksymalny rozmiar zestawu wyników. Na przykład: large, small, filtered_cse, 10. zależy od układu i tego, czy wyszukiwarka jest skonfigurowana do wyszukiwania w całym internecie lub tylko w wybranych witrynach. Dowolny
safeSearch Ciąg znaków Określa, jeśli Filtr SafeSearch jest włączony zarówno w przypadku wyszukiwania w internecie, jak i wyszukiwaniu grafiki. Akceptowane wartości to off i active. Dowolny

Wywołania zwrotne

Schemat sekwencji wywołań zwrotnych
diagram sekwencji wywołań zwrotnych z elementu wyszukiwania w JavaScripcie
.

Wywołania zwrotne obsługują szczegółową kontrolę nad inicjowaniem i wyszukiwaniem elementu wyszukiwania. Są rejestrowane w kodzie JavaScript elementu wyszukiwania przez globalny __gcse obiektu. Pole Register Callbacks (Zarejestruj wywołania zwrotne) pokazuje rejestrację wszystkich wywołań obsługiwane wywołania zwrotne.

Rejestrowanie wywołań zwrotnych

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

Wywołanie zwrotne inicjujące

Wywołanie zwrotne inicjowania jest wywoływane przed wyrenderowaniem wyszukiwania w JavaScripcie przez element wyszukiwania elementów modelu DOM. Jeśli parsetags ma wartość explicit w __gcse, kod JavaScript elementu wyszukiwania pozostawia renderowanie elementów wyszukiwania wywołanie zwrotne inicjowania (jak pokazano w sekcji Rejestrowanie wywołań zwrotnych). Pozwala to wybrać elementy do wyrenderowania lub opóźnić renderowanie do momentu, gdy zostaną niezbędną. Może też zastąpić atrybuty elementów. na przykład może zmienić jest konfigurowane za pomocą Panelu sterowania lub atrybutów HTML tak, aby domyślnie wskazywała internet. w polu wyszukiwania grafiki lub określ, że zapytania przesłane za pomocą formularza Wyszukiwarki niestandardowej wykonywane w elemencie dostępnym tylko z wynikami wyszukiwania. Obejrzyj prezentację

Rola wywołania zwrotnego inicjowania jest określana przez wartość parsetags właściwość __gcse.

  • Jeżeli jego wartość to onload, element wyszukiwania JavaScript automatycznie renderuje wszystkie elementy wyszukiwania na stronie. Wywołanie zwrotne inicjujące to ale nie odpowiada za renderowanie elementów wyszukiwania.
  • Jeśli jego wartość to explicit, kod JavaScript elementu wyszukiwania nie będzie renderowany. Elementy wyszukiwania. Wywołanie zwrotne może renderować je selektywnie przy użyciu funkcji funkcja render(), lub wyrenderuj wszystkie elementy wyszukiwania za pomocą funkcji go()

Poniższy kod pokazuje, jak renderować pole wyszukiwania wraz z wynikami wyszukiwania w div przy użyciu wywołania zwrotnego analizy i inicjowania explicit:

.
Przykład wywołania zwrotnego inicjowania

Musimy wstawić <div> z wartością identyfikatora w którym chcemy znaleźć kod elementu wyszukiwania:

    <div id="test"></div>
Dodaj ten JavaScript po <div>. Pamiętaj, że odwołuje się do testid użyliśmy do identyfikacji <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
};

Dołącz ten kod HTML, aby rozpocząć wczytywanie elementu wyszukiwania. Zastąp wartość cx w kolumnie src z Twoją własną klauzulą cx.

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

Szukaj wywołań zwrotnych

JavaScript elementu wyszukiwania obsługuje sześć wywołań zwrotnych działających w sekcji procedurę kontroli wyszukiwania. Wywołania zwrotne wyszukiwania występują parami: wywołanie zwrotne wyszukiwania w internecie oraz pasujące wywołanie zwrotne wyszukiwania grafiki:

  • Rozpoczęcie wyszukiwania
    • Wyszukiwarka grafiki
    • Wyszukiwarka Google
  • Wyniki są gotowe
    • Wyszukiwarka grafiki
    • Wyszukiwarka Google
  • Wyrenderowane wyniki
    • Wyszukiwarka grafiki
    • Wyszukiwarka Google

Tak jak wywołanie zwrotne inicjujące,wywołania zwrotne wyszukiwania są skonfigurowane za pomocą wpisów w obiekcie __gcse. Dzieje się tak, gdy element wyszukiwania Uruchomi się JavaScript. Zmiany w zasadzie __gcse po uruchomieniu są ignorowane.

Każde z tych wywołań zwrotnych jest przekazywane do parametru gName dla elementu wyszukiwania jako argumentu. gname jest przydatny, gdy strona zawiera więcej niż jedno wyszukiwanie. Wyszukaj elementu gname za pomocą atrybutu data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

Jeśli w kodzie HTML nie zostanie zidentyfikowana nazwa gname, skrypt JavaScript elementu wyszukiwania wygeneruje wartość, która spowoduje pozostają spójne do czasu zmodyfikowania kodu HTML.

Wywołanie zwrotne inicjującej wyszukiwanie grafiki/wyszukiwarki internetowej

Początkowe wywołania zwrotne wyszukiwania są wywoływane bezpośrednio przed żądaniami JavaScript elementu wyszukiwania wyników wyszukiwania z serwera. Przykładem może być użycie lokalnej pory dnia do kontrolować zmiany w zapytaniu.

searchStartingCallback(gname, query)
gname
Ciąg identyfikujący element wyszukiwania
query
Wartość wpisana przez użytkownika (może zostać zmodyfikowana przez wyszukiwanie JavaScript).

Wywołanie zwrotne zwraca wartość, która powinna zostać użyta jako zapytanie. Jeśli zwraca pusty ciąg znaków, zwrócona wartość jest ignorowana, a element wywołujący używa niezmodyfikowanego zapytania.

Możesz też umieścić funkcję wywołania zwrotnego w obiekcie __gcse lub dynamicznie dodaj wywołanie zwrotne do obiektu za pomocą JavaScriptu:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Przykładowe wyszukiwanie rozpoczynające oddzwonienie

Przykładowe wyszukiwanie rozpoczynające oddzwonienie za Przykładowe wywołanie zwrotne w wyszukiwarce dodaje parametr morning lub afternoon do zapytania w zależności od pory dnia.

Szukaj przykładowego wywołania zwrotnego
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
.

Zainstaluj to wywołanie zwrotne za 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>

Wywołanie zwrotne gotowe do użycia obrazu/wyników wyszukiwania w internecie

Te wywołania zwrotne są wywoływane bezpośrednio przed wyrenderowaniem wyników promowanych przez JavaScript elementu wyszukiwania i wyników. Przykładem może być wywołanie zwrotne, które renderuje promocje i zapewnia styl nie można określić w normalnym dostosowywaniu.

resultsReadyCallback(gname, query, promos, results, div)
gname
Ciąg identyfikujący element wyszukiwania
query
zapytanie, które zwróciło te wyniki
promos
tablica obiektów promocji, która odpowiada dopasowanym promocji do zapytania użytkownika. Zobacz definicję obiektu promocji.
results
tablica obiektów wyników. Zobacz definicji obiektu wyniku wyszukiwania.
div
element div HTML w modelu DOM, w którym zwykle znajduje się element wyszukiwania zamieszczania promocji i wyników wyszukiwania. Normalnie skrypt JavaScript elementu wyszukiwania obsługujełby jest wypełniany ten element div, ale wywołanie zwrotne może zatrzymać automatyczne renderowanie wyników i użyj tego elementu div, aby samodzielnie renderować wyniki.
.
.

Jeśli to wywołanie zwrotne zwraca wartość true, JavaScript elementu wyszukiwania przechodzi do stopki strony.

Przykładowe wyniki gotowe – wywołanie zwrotne

Przykładowe wywołanie zwrotne funkcji resultsReady w: Przykładowe wywołanie zwrotne wyników gotowe zastępuje prezentację domyślną promocji i wyników, które można bardzo łatwo zastąpić.

Przykład gotowego wywołania zwrotnego wyników
    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;
    };

Zainstaluj to wywołanie zwrotne za 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>

Podobnie jak w przypadku początkowego wywołania zwrotnego wyszukiwania, opisana wyżej metoda jest jednym z wielu sposobów na umieszczenie wywołania zwrotnego __gcse obiekt.

Wywołanie zwrotne renderowania strony z wynikami wyszukiwania grafiki/wyszukiwania w internecie

Te wywołania zwrotne są wywoływane bezpośrednio przed wyrenderowaniem strony przez kod JavaScript elementu wyszukiwania stopkę. Może to być np. wywołanie zwrotne polegające na dodaniu do wyników wyszukiwania treści, nie będzie wyświetlany, np. pole wyboru zapisz to lub informacje, które nie są renderowane automatycznie lub wywołanie zwrotne z przyciskiem for more information.

Jeśli wyrenderowanie wywołania zwrotnego wymaga informacji zawartych w tabelach promos i results wywołania zwrotnego gotowych wyników, może je przekazywać między nimi w następujący sposób:

callback(gname, query, promoElts, resultElts);
gname
Ciąg identyfikujący element wyszukiwania
query
wyszukiwany ciąg znaków.
promoElts
tablica elementów DOM zawierających wyniki promowane.
resultElts
tablica elementów DOM zawierających wyniki.

Nie ma wartości zwróconej.

Przykładowe wyniki renderowane wywołanie zwrotne

Przykładowe wywołanie zwrotne funkcji resultsRendered w: Przykładowe wyniki renderowania wywołanego wywołania zwrotnego dodaje zastępczy element Keep przy każdej promocji i wyniku.

Przykład wywołania zwrotnego renderowania wyników
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);
    }
  };

Zainstaluj to wywołanie zwrotne za 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>

Jeśli wyrenderowanie wywołania zwrotnego wymaga informacje przekazane do wywołania zwrotnego gotowych wyników, które mogą przekazywać te dane między na wywołania zwrotne. Poniższy przykład pokazuje jeden z wielu sposobów przekazywania wartości oceny z: richSnippet z wywołania zwrotnego gotowych wyników do wyrenderowanych wyników oddzwanianie.

.
Przykład wywołania zwrotnego z wynikami gotowego do współpracy z wywołaniem zwrotnym renderowania wyników
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};
};
Zainstaluj to wywołanie zwrotne, używając kodu podobnego do tego podczas konfigurowania usługi __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>

Więcej przykładów wywołań zwrotnych

Dodatkowe przykłady wywołań zwrotnych znajdziesz tutaj: Więcej przykładów wywołań zwrotnych.

Właściwości promocji i wyników

W notacji JSDoc zostały opisane właściwości: promotion i result. Poniżej znajduje się lista wszystkich właściwości, które mogą występować. Obecność wielu obiektów zależą od szczegółów promocji lub wyniku wyszukiwania.

Właściwości promocji
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
.
Właściwości obiektu wyniku
{
  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,
}
.

Funkcja richSnippet w tabeli results ma luźny typ tablicy obiektów. Wartościami wpisów w tej tablicy są kontrolowane przez uporządkowane dane znalezionej na stronie dla każdego wyniku wyszukiwania. Na przykład witryna z recenzjami może zawierać uporządkowane dane, które dodaje ten wpis tablicy do richSnippet:

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

Interfejs Programmable Search Element Control API (wersja 2)

Obiekt google.search.cse.element publikuje funkcje statyczne:

Funkcja Opis
.render(componentConfig, opt_componentConfig) Renderuje wyszukiwane hasło.

Parametry

Nazwa Opis
componentConfig Konfiguracja komponentu Wyszukiwarka niestandardowa. Określa:
  • div (ciąg|Element): id elementu <div> lub div, w którym ma zostać wyrenderowany element Wyszukiwarki niestandardowej.
  • tag (ciąg znaków): typ komponentów do renderowania. (Jeśli podano opt_componentConfig, atrybut tag musi mieć wartość searchbox). Dozwolone wartości to:
    • search: pole wyszukiwania i wyniki wyszukiwania wyświetlane razem.
    • searchbox: komponent pola wyszukiwania elementu Wyszukiwarki niestandardowej.
    • searchbox-only: autonomiczne pole wyszukiwania, które zostanie połączone z blokiem wyników wyszukiwania określonym przez opt_componentConfig w układzie dwukolumnowym.
    • searchresults-only: samodzielny blok wyników wyszukiwania. Wyszukiwania są wywoływane przez parametr zapytania osadzony w adresie URL lub przez wykonanie automatyczne.
  • gname (ciąg znaków): (opcjonalnie) unikalna nazwa tego komponentu. Jeśli go nie podasz, Wyszukiwarka niestandardowa automatycznie wygeneruje gname.
  • attributes (obiekt): opcjonalne atrybuty w formie pary klucz-wartość. Obsługiwane atrybuty.
opt_componentConfig Opcjonalnie: Drugi argument konfiguracji komponentu. Użyto w: TWO_COLUMN aby udostępnić komponent searchresults. Określa:
  • div (ciąg znaków): id elementu <div> lub element div, w którym ma zostać wyrenderowany.
  • tag (ciąg znaków): typ komponentów do renderowania. Kiedy Podano opt_componentConfig, wartość tag musi mieć wartość searchresults. Ponadto wartość atrybutu Atrybut tag o wartości componentConfig musi mieć wartość searchbox.
  • gname (ciąg znaków): (opcjonalnie) unikalna nazwa tego komponentu. Jeśli nie, podany, Wyszukiwarka niestandardowa automatycznie wygeneruje dla tego parametru gname . Jeśli jest podany, musi być zgodny z wartością gname w componentConfig
  • attributes (obiekt): opcjonalne atrybuty w formacie klucz:wartość. parować. Obsługiwane atrybuty.
.go(opt_container) Renderuje wszystkie tagi/klasy elementu wyszukiwania w określonym kontenerze.

Parametry

Nazwa Opis
opt_container Kontener zawierający komponenty elementu wyszukiwania do renderowania. Określ identyfikator kontenera (ciąg znaków) lub samego elementu. Jeśli został pominięty, wszystkie komponenty Wyszukiwarki niestandardowej w obrębie tagu Zostanie wyrenderowany body tag.
.getElement(gname) Pobiera obiekt elementu według parametru gname. Jeśli go nie znaleziono, zwraca wartość null.

Zwrócony obiekt element ma te atrybuty:

  • gname: nazwa obiektu elementu. Wyszukiwarka niestandardowa, jeśli nie zostanie podana automatycznie wygeneruje gname dla obiektu. Więcej informacji
  • type: typ elementu.
  • uiOptions: końcowe atrybuty używane do renderowania elementu.
  • execute – funkcja(ciąg znaków): wykonuje zapytanie programowe.
  • prefillQuery – funkcja(ciąg znaków): wstępnie wypełnia pole wyszukiwania zapytaniem. bez wykonywania zapytania.
  • getInputQuery – function(): pobiera bieżącą wartość wyświetlaną w danych wejściowych. .
  • clearAllResults – function(): czyści element sterujący, ukrywając wszystko oprócz pola wyszukiwania.

Następujący kod wykonuje zapytanie „news” w elemencie wyszukiwania „element1”:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() Zwraca mapę wszystkich pomyślnie utworzonych obiektów elementów, których kluczem jest gname.