Programmable Search Element Control API

Komponenty Wyszukiwarki niestandardowej (pola wyszukiwania i strony wyników wyszukiwania) możesz umieszczać na stronach internetowych i w innych aplikacjach internetowych za pomocą znaczników HTML. Elementy Wyszukiwarki niestandardowej składają się z komponentów renderowanych na podstawie ustawień przechowywanych przez serwer Wyszukiwarki niestandardowej oraz wprowadzonych przez Ciebie zmian.

Cały kod JavaScript jest wczytywany asynchronicznie, co umożliwia dalsze wczytywanie strony internetowej, podczas gdy przeglądarka pobiera kod JavaScript Wyszukiwarki niestandardowej.

Wprowadzenie

W tym dokumencie znajdziesz podstawowy model dodawania elementów wyszukiwarki programowalnej do strony internetowej oraz wyjaśnienia dotyczące konfigurowalnych komponentów elementu i elastycznego interfejsu JavaScript API.

Zakres

W tym dokumencie opisujemy, jak używać funkcji i właściwości specyficznych dla interfejsu API elementu sterującego wyszukiwarki programowalnej.

Zgodność z przeglądarką

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

Odbiorcy

Ta dokumentacja jest przeznaczona dla programistów, którzy chcą dodać do swoich stron funkcje Wyszukiwarki niestandardowej Google.

Elementy Wyszukiwarki niestandardowej

Aby dodać element Wyszukiwarki niestandardowej do strony, możesz użyć znaczników HTML. Każdy element składa się z co najmniej 1 komponentu: pola wyszukiwania, bloku wyników wyszukiwania lub obu tych elementów. W polu wyszukiwania można wpisywać dane na te sposoby:

• Zapytanie wpisane w polu wprowadzania tekstu
• Ciąg zapytania osadzony w adresie URL
• Wykonanie zautomatyzowane

Blok wyników wyszukiwania akceptuje dane wejściowe w ten sposób:

• Ciąg zapytania osadzony w adresie URL
• Wykonanie zautomatyzowane

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

Do strony internetowej możesz dodać dowolną liczbę prawidłowych elementów wyszukiwania. W przypadku trybu dwukolumnowego muszą być obecne wszystkie wymagane komponenty (pole wyszukiwania i blok wyników wyszukiwania).

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ą elementów Wyszukiwarki niestandardowej

Na stronie Wygląd w panelu sterowania Wyszukiwarki niestandardowej dostępne są te opcje układu: Oto kilka ogólnych wskazówek dotyczących tworzenia opcji układu za pomocą programowalnych elementów wyszukiwania. 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 działanie wyszukiwarki niestandardowej.

Za pomocą atrybutów opcjonalnych możesz zastępować konfiguracje utworzone w panelu sterowania Wyszukiwarki niestandardowej. Dzięki temu możesz tworzyć 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ść atrybutu queryParameterName wraz z ciągiem zapytania użytkownika służy do tworzenia adresu URL wyników.

Pamiętaj, że atrybut queryParameterName ma prefiks data-. Ten prefiks jest wymagany w przypadku 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 włączysz funkcje takie jak autouzupełnianie czy ulepszenia, możesz dostosować te funkcje za pomocą atrybutów. Wszelkie dostosowania określone za pomocą tych atrybutów zastąpią ustawienia wprowadzone w panelu sterowania. W tym przykładzie tworzymy element wyszukiwania z 2 kolumnami, który ma te funkcje:

• Zarządzanie historią jest włączone
• Maksymalna liczba wyświetlanych sugestii autouzupełniania jest ustawiona na 5.
• Uściślenia 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

Funkcje wywołania zwrotnego umożliwiają szczegółową kontrolę nad inicjowaniem elementu wyszukiwania i procesami wyszukiwania. Są one rejestrowane w skrypcie JavaScript elementu wyszukiwania za pomocą globalnego obiektu __gcse. Register Callbacks ilustruje rejestrację wszystkich obsługiwanych 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 inicjowania

Wywołanie zwrotne inicjowania jest wywoływane, zanim kod JavaScript elementu wyszukiwania wyrenderuje elementy wyszukiwania w DOM. Jeśli w parametrze __gcse wartość parsetags jest ustawiona na explicit, skrypt JavaScript elementu wyszukiwania pozostawia renderowanie elementów wyszukiwania funkcji wywołania zwrotnego inicjowania (jak pokazano w sekcji Rejestrowanie wywołań zwrotnych). Może to służyć do wybierania elementów do renderowania lub odraczania renderowania elementów do momentu, gdy będą potrzebne. Może też zastępować atrybuty elementów. Na przykład może zmienić pole wyszukiwania skonfigurowane w panelu sterowania lub za pomocą atrybutów HTML na domyślne pole wyszukiwania w internecie w pole wyszukiwania obrazów lub określić, że zapytania przesyłane za pomocą formularza Wyszukiwarki niestandardowej są wykonywane tylko w elemencie wyników wyszukiwania. Zobacz prezentację

Rola wywołania zwrotnego inicjowania jest kontrolowana przez wartość właściwości parsetags obiektu __gcse.

• Jeśli jego wartość to onload, JavaScript elementu wyszukiwania automatycznie renderuje wszystkie elementy wyszukiwania na stronie. Wywołanie zwrotne inicjowania jest nadal wywoływane, ale nie odpowiada za renderowanie elementów wyszukiwania.
• Jeśli wartość to explicit, kod JavaScript elementu wyszukiwania nie renderuje elementów wyszukiwania. Wywołanie zwrotne może renderować je selektywnie za pomocą funkcji render() lub renderować wszystkie elementy wyszukiwania za pomocą funkcji go().

Poniższy kod pokazuje, jak renderować pole wyszukiwania wraz z wynikami wyszukiwania w div za pomocą tagu explicit i wywołania zwrotnego inicjowania:

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

Wyszukiwanie wywołań zwrotnych

Element wyszukiwania JavaScript obsługuje 6 wywołań zwrotnych, które działają w przepływie sterowania wyszukiwaniem. Wywołania zwrotne wyszukiwania występują w parach: wywołanie zwrotne wyszukiwania w internecie i odpowiadające mu wywołanie zwrotne wyszukiwania grafiki:

• Wyszukiwanie początkowe
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie
• Wyniki gotowe
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie
• Wyświetlone wyniki:
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie

Podobnie jak wywołanie zwrotne inicjowania,wywołania zwrotne wyszukiwania są konfigurowane za pomocą wpisów w obiekcie __gcse. Dzieje się tak, gdy uruchamia się kod JavaScript elementu wyszukiwania. Modyfikacje __gcse po uruchomieniu są ignorowane.

Każde z tych wywołań zwrotnych otrzymuje jako argument obiekt gName elementu wyszukiwania. Symbol gname przydaje się, gdy strona zawiera więcej niż jedno wyszukiwanie. Nadaj elementowi wyszukiwania wartości gname za pomocą atrybutu data-gname:

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

Jeśli kod HTML nie identyfikuje nazwy gname, skrypt JavaScript elementu wyszukiwania generuje wartość, która pozostanie niezmieniona do czasu zmodyfikowania kodu HTML.

Wywołanie zwrotne rozpoczynające wyszukiwanie obrazów lub w internecie

Wywołania zwrotne rozpoczynające wyszukiwanie są wywoływane bezpośrednio przed wysłaniem przez JavaScript elementu wyszukiwania żądania wyników wyszukiwania z serwera. Przykładem może być użycie lokalnej pory dnia do kontrolowania zmian w zapytaniu.

searchStartingCallback(gname, query)

gname

Ciąg identyfikujący element wyszukiwania

query

wartość wpisana przez użytkownika (może być zmodyfikowana przez element JavaScript wyszukiwania);

Wywołanie zwrotne zwraca wartość, która powinna być używana jako zapytanie w tym wyszukiwaniu. Jeśli zwraca pusty ciąg znaków, zwracana wartość jest ignorowana, a wywołujący używa niezmienionego zapytania.

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

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};

Przykładowe wywołanie zwrotne rozpoczynające wyszukiwanie

Przykładowe wywołanie zwrotne rozpoczynające wyszukiwanie w Example Search Starting Callback dodaje do zapytania wartość morning lub afternoon 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 w 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 gotowych wyników wyszukiwania obrazów lub w internecie

Te wywołania zwrotne są wywoływane bezpośrednio przed wyrenderowaniem promocji i wyników przez JavaScript elementu wyszukiwania. Przykładem może być wywołanie zwrotne, które renderuje promocje i wyniki w stylu, którego nie można określić za pomocą zwykłej personalizacji.

resultsReadyCallback(gname, query, promos, results, div)

gname

Ciąg identyfikujący element wyszukiwania

query

zapytanie, które wygenerowało te wyniki

;

promos

tablicę obiektów promocji, które odpowiadają dopasowanym promocjom w przypadku zapytania użytkownika. Zapoznaj się z definicją obiektu promocji.

results

tablicę obiektów wyników. Zobacz definicję obiektu wyniku.

div

element div HTML umieszczony w DOM, w którym element wyszukiwania zwykle umieszcza promocje i wyniki wyszukiwania. Zwykle kod JavaScript elementu wyszukiwania wypełnia ten element div, ale ta funkcja zwrotna może zatrzymać automatyczne renderowanie wyników i użyć tego elementu div do samodzielnego renderowania wyników.

Jeśli to wywołanie zwrotne zwróci wartość true, kod JavaScript elementu wyszukiwania przejdzie do pracy w stopce strony.

Przykładowe wywołanie zwrotne wyników gotowych

Przykładowe wywołanie zwrotne resultsReady w Example Results Ready Callback zastępuje domyślny sposób wyświetlania promocji i wyników bardzo prostym zamiennikiem.

    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>

Wyniki wyszukiwania obrazów lub w internecie – wywołanie zwrotne po renderowaniu

Te wywołania zwrotne są wywoływane bezpośrednio przed wyrenderowaniem stopki strony przez kod JavaScript elementu wyszukiwania. Przykłady zastosowań to wywołanie zwrotne, które dodaje treść wyniku, która nie jest wyświetlana przez element wyszukiwania, np. pole wyboru Zapisz to lub informacje, które nie są renderowane automatycznie, albo wywołanie zwrotne, które dodaje przyciski Więcej informacji.

Jeśli wywołanie zwrotne po wyrenderowaniu wyników potrzebuje informacji, które znajdowały się w parametrach promos i results wywołania zwrotnego po przygotowaniu wyników, może przekazać je między nimi w ten sposób:

callback(gname, query, promoElts, resultElts);

gname

Ciąg identyfikujący element wyszukiwania

query

ciąg wyszukiwania.

promoElts

tablicę elementów DOM zawierających promocje;

resultElts

tablica elementów DOM zawierających wyniki.

Nie zwraca żadnej wartości.

Przykład wywołania zwrotnego wyrenderowanych wyników

Przykładowe resultsRendered wywołanie zwrotne w sekcji Przykład wywołania zwrotnego renderowania wyników dodaje do każdej promocji i każdego wyniku fikcyjne pole wyboru Zachowaj.

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 funkcja zwrotna renderowania wyników potrzebuje informacji przekazanych do funkcji zwrotnej gotowości wyników, może przekazywać te dane między funkcjami zwrotnymi. Poniższy przykład pokazuje jeden z wielu sposobów przekazywania wartości oceny z richSnippet z wywołania zwrotnego gotowości wyników do wywołania zwrotnego 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};
};

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>

Przykład wywołania zwrotnego renderowania wyników: otwieranie określonych typów plików w nowej karcie lub nowym oknie

Poniższy przykład wywołania zwrotnego może modyfikować linki w wynikach wyszukiwania po ich wyrenderowaniu, aby otwierać określony plik w nowej karcie lub stronie zamiast w bieżącym oknie (np. PDF, Excel lub Word). Ułatwia to przeglądanie, gdy użytkownicy nie chcą otwierać pliku w tym samym oknie i opuszczać strony wyników.

Ten przykład wywołania zwrotnego identyfikuje linki do plików PDF w wynikach wyszukiwania i ustawia atrybut target="_blank" w linkach do plików PDF, aby otwierały się w nowej karcie. MutationObserver służy do dynamicznego obsługiwania nowych wyników, jeśli strona zostanie zaktualizowana. Uwaga: w handleSearchResults możesz zastąpić .pdf dowolnym innym typem pliku zgodnie z Twoimi wymaganiami.

Ten przykład wywołania zwrotnego nie działa w przypadku układów hostowanych przez Google i nakładkowych.

function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

const myWebResultsRenderedCallback = () => {
  // Call handleSearchResults when results are rendered
  handleSearchResults();
  // Set up a MutationObserver to handle subsequent updates to the results
  const observer = new MutationObserver(handleSearchResults);
  const searchResultsContainer = document.querySelector('.gsc-results');
  if (searchResultsContainer) {
    observer.observe(searchResultsContainer, {
      childList: true,
      subtree: true
    });
  } else {
    console.log('No Results.');
  }
};

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>

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

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

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

Korzystając z notacji JSDoc, podajemy właściwości obiektów promotion i result. Poniżej znajdziesz listę wszystkich właściwości, które mogą być obecne. Wiele właściwości zależy od szczegółów promocji lub wyników 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,
}

richSnippet w wynikach ma luźny typ tablicy obiektów. Wartości wpisów w tej tablicy są kontrolowane przez uporządkowane dane znalezione na stronie internetowej dla każdego wyniku wyszukiwania. Na przykład witryna z opiniami może zawierać dane strukturalne, które dodają ten wpis do tablicy richSnippet:

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

Programmable Search Element Control API (V2)

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

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