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:

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.

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

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

Wywołania zwrotne

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.

  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:

    <div id="test"></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
};

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

    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ć.

    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;
    };

  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>

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.

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);
    }
  };

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.

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};
};

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.

{
  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,
}

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:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');