Programmable Search Element Control API

Komponenty Wyszukiwarki niestandardowej (pola wyszukiwania i strony wyników wyszukiwania) możesz umieszczać na swoich stronach internetowych i w innych aplikacjach internetowych za pomocą znaczników HTML. Te elementy Wyszukiwarki niestandardowej składają się z komponentów renderowanych na podstawie ustawień zapisanych przez serwer Wyszukiwarki niestandardowej, a także wszystkich wprowadzonych modyfikacji.

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

Wprowadzenie

Ten dokument zawiera podstawowy model dodawania do strony internetowej elementów Wyszukiwarki niestandardowej oraz opis konfigurowalnych komponentów tego elementu oraz elastycznego interfejsu JavaScript API.

Zakres

W tym dokumencie opisujemy, jak korzystać z funkcji i właściwości charakterystycznych dla interfejsu Programmable Search Engine Control API.

Zgodność z przeglądarką

Listę przeglądarek obsługiwanych przez Wyszukiwarka niestandardowa znajdziesz tutaj.

Odbiorcy

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

Elementy Wyszukiwarki niestandardowej

Za pomocą znaczników HTML możesz dodać do strony element Wyszukiwarki niestandardowej. 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 użytkownicy mogą wpisywać dane w jeden z tych sposobów:

• Zapytanie wpisane w polu do wprowadzania tekstu.
• Ciąg zapytania umieszczony w adresie URL
• Automatyzacja

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

• Ciąg zapytania umieszczony w adresie URL
• Automatyzacja

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

Do strony możesz dodać dowolną liczbę prawidłowych elementów wyszukiwania. W trybie 2 kolumn muszą znajdować się 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 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ą elementów Wyszukiwarki niestandardowej. Aby zobaczyć demonstrację dowolnej z tych opcji, kliknij link.

Więcej informacji o opcjach układu

Dostosowywanie elementów Wyszukiwarki niestandardowej

Aby dostosować kolory, czcionkę lub styl linków, otwórz stronę Wygląd i styl w wyszukiwarce niestandardowej.

Atrybuty opcjonalne pozwalają zastępować konfiguracje utworzone w panelu sterowania Wyszukiwarki niestandardowej. Dzięki temu możesz utworzyć środowisko wyszukiwania dostosowane do określonej 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 jest używana do tworzenia adresu URL wyników.

Pamiętaj, że atrybut queryParameterName jest poprzedzony znakiem 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 używasz takich funkcji jak autouzupełnianie lub udoskonalanie, możesz je dostosowywać za pomocą atrybutów. Wszelkie dostosowania wprowadzone za pomocą tych atrybutów zastąpią ustawienia wprowadzone w panelu sterowania. Poniższy 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
• Doprecyzowania 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 zapewniają szczegółową kontrolę nad procesami inicjowania i wyszukiwania elementu wyszukiwania. Są one rejestrowane w kodzie JavaScript elementu wyszukiwania za pomocą globalnego obiektu __gcse. Opcja Zarejestruj wywołania zwrotne pokazuje 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 inicjujące

Wywołanie zwrotne inicjowania jest wywoływane przed wyrenderowaniem przez kod JavaScript elementu wyszukiwania elementów wyszukiwania w DOM. Jeśli zasada parsetags w __gcse ma wartość explicit, kod JavaScript elementu wyszukiwania pozostawia w przypadku elementów wyszukiwania wywołanie zwrotne inicjowania do renderowania (jak widać w sekcji Zarejestruj wywołania zwrotne). Tej opcji można użyć do wyboru elementów do wyrenderowania lub do odroczenia renderowania elementów do momentu, gdy będą potrzebne. Może też zastępować atrybuty elementów, np. włączyć w polu wyszukiwania obrazów pole wyszukiwania skonfigurowane w panelu sterowania lub atrybuty HTML tak, aby wyszukiwanie w internecie domyślnie uwzględniało wyszukiwanie w internecie. Można też określić, że zapytania przesyłane za pomocą formularza Wyszukiwarki niestandardowej są wykonywane w elemencie występującym tylko w przypadku wyników wyszukiwania. Zobacz prezentację

Rola wywołania zwrotnego inicjowania zależy od wartości właściwości parsetags __gcse.

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

Poniższy kod pokazuje, jak renderować pole wyszukiwania razem z wynikami wyszukiwania w obiekcie div przy użyciu analizy i wywołania zwrotnego 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

Kod JavaScript elementu wyszukiwania obsługuje 6 wywołań zwrotnych, które działają w procesie sterowania wyszukiwaniem. Wywołania zwrotne w wyszukiwarce występują parami: są to wywołania zwrotne z wyszukiwarki Google i pasujące wywołanie zwrotne w wyszukiwarce grafiki:

• Rozpoczęcie wyszukiwania:
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie
• Wyniki są gotowe
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie
• Wyrenderowane wyniki
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie

Podobnie jak wywołanie zwrotne inicjowania,wywołania zwrotne wyszukiwania konfiguruje się przy użyciu wpisów w obiekcie __gcse. Dzieje się tak w trakcie uruchamiania kodu JavaScript elementu wyszukiwania. Modyfikacje wartości __gcse po uruchomieniu są ignorowane.

Każde z tych wywołań zwrotnych jest przekazywane jako argument gName elementu wyszukiwania. Parametr gname przydaje się, gdy strona zawiera więcej niż jedno wyszukiwanie. Za pomocą atrybutu data-gname nadaj elementowi wyszukiwania wartości gname:

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

Jeśli w kodzie HTML nie można zidentyfikować identyfikatora gname, kod JavaScript elementu wyszukiwania wygeneruje wartość, która pozostanie spójna do czasu modyfikacji kodu.

Wywołanie zwrotne rozpoczynające się od wyszukiwania grafiki/wyszukiwania w internecie

Początkowe wywołania zwrotne wyszukiwania są wywoływane bezpośrednio przed tym, jak skrypt JavaScript elementu wyszukiwania wysyła żądanie wyszukiwania do swojego serwera. Przykładowym przypadkiem użycia jest lokalna pora dnia do kontrolowania zmian w zapytaniu.

searchStartingCallback(gname, query)

gname

Ciąg identyfikujący element wyszukiwania

query

wartość wpisana przez użytkownika (prawdopodobnie zmodyfikowana przez kod JavaScript elementu wyszukiwania).

Wywołanie zwrotne zwraca wartość, która powinna zostać użyta jako zapytanie dla tego wyszukiwania. Jeśli zwraca pusty ciąg, zwracana 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 dodać wywołanie zwrotne do obiektu za pomocą JavaScriptu:

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

Przykładowe wyszukiwanie rozpoczynające wywołanie zwrotne

Przykładowe wyszukiwanie rozpoczynające wywołanie zwrotne w sekcji Przykładowe wywołanie zwrotne w ramach wyszukiwania dodaje do zapytania 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>

Gotowe wywołanie zwrotne w wynikach wyszukiwania grafiki/wyników wyszukiwania w internecie

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

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

gname

Ciąg identyfikujący element wyszukiwania

query

zapytanie, które wygenerowało te wyniki

promos

tablica obiektów promocji, które odpowiadają promocjom dopasowanym do zapytania użytkownika; Zobacz definicję obiektu promocji.

results

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

div

element div w kodzie HTML umieszczony w modelu DOM, w którym element wyszukiwania zwykle umieszcza promocje i wyniki wyszukiwania; Normalnie kod JavaScript elementu wyszukiwania obsługuje wypełnianie tego elementu div, ale to wywołanie zwrotne może zatrzymać automatyczne renderowanie wyników i wykorzystać ten element div do samych wyników.

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

Przykładowe wyniki gotowe – wywołanie zwrotne

Przykładowe wywołanie zwrotne resultsReady w Gotowe wywołanie zwrotne z przykładowymi wynikami zastępuje domyślną prezentację 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>

Wywołanie zwrotne wyrenderowane w wynikach wyszukiwania grafiki/wyszukiwania w internecie

Te wywołania zwrotne są wywoływane bezpośrednio przed wyrenderowaniem stopki strony przez kod JavaScript elementu wyszukiwania. Przykładowe przypadki użycia to m.in. wywołanie zwrotne dodające treść wyników, której nie wyświetla element wyszukiwania, np. pole wyboru zapisz to, informacje, które nie są renderowane automatycznie, albo wywołanie zwrotne dodające przyciski aby uzyskać więcej informacji.

Jeśli wyrenderowane wywołanie zwrotne w wynikach wymaga informacji, które znajdują się w parametrach promos i results wywołania zwrotnego gotowych wyników, może je przekazać między nimi w ten sposób:

callback(gname, query, promoElts, resultElts);

gname

Ciąg identyfikujący element wyszukiwania

query

wyszukiwany ciąg.

promoElts

tablica elementów DOM zawierających promocje.

resultElts

tablica elementów DOM zawierających wyniki.

Nie ma zwracanej wartości.

Przykładowe wywołanie zwrotne wyrenderowanego wyniku

Przykładowe wywołanie zwrotne resultsRendered w funkcji Wyrenderowane wyniki z przykładowego wywołania zwrotnego powoduje dodanie fikcyjnego pola wyboru Keep do 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 wyrenderowane wywołanie zwrotne w wynikach wymaga informacji, które zostały przekazane do wywołania zwrotnego gotowych wyników, może przekazać te dane między wywołaniami zwrotnymi. Przykład poniżej pokazuje jeden z wielu sposobów na przekazanie wartości oceny z richSnippet z wywołania zwrotnego gotowych wyników do wyrenderowanych wywołań zwrotnych.

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

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

To są właściwości obiektów promotion i result w notacji JSDoc. Tutaj znajdziesz listę wszystkich właściwości, które mogą być obecne. Obecność wielu właściwości zależy 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,
}

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

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

Interfejs 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');