Programmable Search Element Control API

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

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

Wprowadzenie

Ten dokument zawiera podstawowy model dodawania elementów Wyszukiwarki niestandardowej wraz z objaśnieniami konfigurowanych elementów i elastycznym interfejsem API JavaScript.

Zakres

Ten dokument opisuje korzystanie z funkcji i właściwości związanych z interfejsem Programmable Search Engine Control API.

Zgodność z przeglądarką

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

Odbiorcy

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

Elementy wyszukiwarki z automatyzacją

Za pomocą znaczników HTML możesz dodać do swojej strony Wyszukiwarka niestandardowa. Każdy element składa się z co najmniej jednego komponentu: pola wyszukiwania, bloku wyników wyszukiwania lub obu tych elementów. Pole wyszukiwania akceptuje dane wejściowe użytkownika w dowolny z tych sposobów:

• Zapytanie wpisane w polu tekstowym
• Ciąg zapytania umieszczony w adresie URL
• Realizacja automatyczna

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

• Ciąg zapytania umieszczony w adresie URL
• Realizacja automatyczna

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

Do strony możesz dodać dowolną liczbę prawidłowych elementów wyszukiwania. W trybie dwukolumnowym 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>

Utwórz różne opcje układu za pomocą elementów Programmable Search Search

Na stronie Wygląd i styl 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ą elementów wyszukiwarki niestandardowej. Aby zobaczyć prezentację 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.

Za pomocą atrybutów opcjonalnych możesz zastąpić konfiguracje utworzone w panelu sterowania Wyszukiwarki niestandardowej. Dzięki temu możesz dostosować wyszukiwanie do konkretnej strony. Na przykład poniższy 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 utworzenia adresu URL wyników.

Pamiętaj, że atrybut queryParameterName jest poprzedzony ciągiem 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 zostały włączone takie funkcje jak autouzupełnianie lub doprecyzowywanie, 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 pokazuje utworzenie dwukolumnowego elementu w wyszukiwarce z tymi funkcjami:

• Zarządzanie historią jest włączone
• Maksymalna liczba wyświetlanych pozycji autouzupełniania to 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 elementów. Są one rejestrowane za pomocą kodu JavaScript elementu wyszukiwania za pomocą globalnego obiektu __gcse. Opcja Zarejestruj wywołania zwrotne pokazuje wszystkie 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 inicjujące

Inicjacja wywołania zwrotnego jest wywoływana przed wyrenderowaniem elementów wyszukiwania w DOM przez element JavaScript elementu wyszukiwania. Jeśli parsetags ma wartość explicit w __gcse, kod JavaScript elementu wyszukiwania pozostawia renderowanie elementów wyszukiwania dla wywołania zwrotnego inicjowania (jak pokazano w sekcji Rejestrowanie wywołań zwrotnych). Tego elementu można użyć do wybrania elementów do wyrenderowania lub do odroczenia elementów renderowania, dopóki nie będą potrzebne. Może też zastąpić atrybuty elementów. Na przykład może zmienić pole wyszukiwania skonfigurowane za pomocą panelu sterowania lub atrybuty HTML w domyślne miejsce na wyszukiwarkę grafiki albo określić, że zapytania przesyłane za pomocą Wyszukiwarki niestandardowej są wykonywane w elemencie przeznaczonym tylko do wyszukiwania. Obejrzyj prezentację.

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

• 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 jego 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()

Ten kod pokazuje, jak renderować pole wyszukiwania wraz z wynikami wyszukiwania w div za pomocą parstagu i wywołania inicjującego 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>

Wyszukaj wywołania zwrotne

JavaScript elementu Search obsługuje sześć wywołań zwrotnych, które działają w procesie kontroli wyszukiwania. Wywołania zwrotne w wyszukiwarce wyświetlają się w parych, wywołaniach wyszukiwania w internecie i pasujących wywołaniach wyszukiwania grafiki:

• Początek wyszukiwania
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie
• Wyniki są gotowe
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie
• Renderowanie wyników
  • Wyszukiwanie obrazów
  • Wyszukiwanie w internecie

Podobnie jak inicjowanie wywołania zwrotnego wywołania zwrotne wyszukiwania są konfigurowane z użyciem wpisów w obiekcie __gcse. Dzieje się tak w momencie uruchomienia JavaScriptu elementu wyszukiwania. Modyfikacje wartości __gcse po uruchomieniu są ignorowane.

Każde takie wywołanie zwrotne jest przekazywane jako gName dla elementu wyszukiwania jako argument. Pole gname jest przydatne, gdy strona zawiera kilka wyszukiwań. Dodaj do elementu wyszukiwania wartość gname za pomocą atrybutu data-gname:

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

Jeśli kod HTML nie identyfikuje elementu gname, kod JavaScript elementu wyszukiwania generuje wartość, która będzie taka sama do czasu zmodyfikowania tego kodu.

Początkowe wywołanie zwrotne wyszukiwarki grafiki lub wyszukiwarki

Początkowe wywołania zwrotne wyszukiwania są wywoływane bezpośrednio przed wywołaniem wyników wyszukiwania z pliku JavaScript elementu elementu. Może to być na przykład lokalna pora dnia w celu kontrolowania zmian w zapytaniu.

searchStartingCallback(gname, query)

gname

Ciąg znaków elementu wyszukiwania

query

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

Wywołanie zwrotne zwraca wartość, która powinna być użyta jako zapytanie w tym wyszukiwaniu. Jeśli jest pusty, 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 dodawać wywołanie zwrotne do obiektu za pomocą JavaScriptu:

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

Przykładowe wywołanie zwrotne rozpoczynające wyszukiwanie

W przypadku przykładowego wyszukiwania rozpoczynającego się wywołanie zwrotne w sekcji Przykładowe wywołanie zwrotne rozpoczyna się zapytanie 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 aplikacji 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 wyświetlenia w wyszukiwarce lub wyniku w wyszukiwarce

Te wywołania zwrotne są wywoływane bezpośrednio przed renderowaniem wyników i wyników JavaScriptu Elementu wyszukiwania. Przykładowe zastosowanie to wywołanie zwrotne, które renderuje promocje i tworzy styl, którego nie można określić przy normalnym dostosowywaniu.

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

gname

Ciąg znaków elementu wyszukiwania

query

zapytanie, które wygenerowało te wyniki

promos

Tablica obiektów promocji, która odpowiada promocjom zapytania użytkownika. Zobacz definicję obiektów promocyjnych.

results

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

div

div HTML umieszczony w elemencie DOM, w którym element wyszukiwania zwykle umieszcza promocje i wyniki wyszukiwania Normalnie element div z funkcją Search zaradziłby JavaScript JavaScript, ale może to spowodować zatrzymanie automatycznego renderowania wyników i wykorzystanie tego div do renderowania samych wyników.

Jeśli to wywołanie zwrotne zwraca wartość true, kod JavaScript elementu wyszukiwarki zostaje przekierowany do stopki strony.

Przykładowe gotowe wyniki wywołania

Przykładowe wywołanie zwrotne resultsReady w przykładowym wywołaniu wywołania zwrotnego zastępuje domyślną prezentację promocji i wyników przy użyciu bardzo prostej zmiany.

    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>

Renderowanie wywołania graficznego/wyników wyszukiwania w internecie

Te wywołania zwrotne są wywoływane bezpośrednio przed wyrenderowaniem stopki strony przez kod JavaScript elementu wyszukiwania. Może to być na przykład wywołanie zwrotne, które dodaje treść wynikową, której element wyszukiwania nie wyświetla, takie jak pole wyboru Zapisz ten wynik wyszukiwania, informacje, które nie są renderowane automatycznie, albo wywołanie zwrotne, które dodaje przycisk więcej informacji.

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

callback(gname, query, promoElts, resultElts);

gname

Ciąg znaków elementu wyszukiwania

query

ciąg znaków.

promoElts

tablica elementów DOM zawierających promocje.

resultElts

tablica elementów DOM z wynikami.

Nie ma wartości zwrotu.

Przykładowe wywołanie zwrotne

Przykładowe wywołanie zwrotne resultsRendered w przykładowym wywołanym wyniku wywołania dodaje charakterystyczne pole wyboru Zachowaj 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 wyników wymaga informacji, które zostały przekazane do wywołania gotowego do wywołania wyników, może przekazać te dane między wywołaniami zwrotnymi. Poniższy przykład pokazuje jeden ze sposobów przekazywania wartości oceny z pola richSnippet od wywołania gotowego do wyników do wyrenderowanego wywołania zwrotnego.

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ładowych połączeń

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

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

Korzystając z notacji JSDoc, są to właściwości obiektów promotion i result. Tutaj znajdziesz listę wszystkich dostępnych właściwości. Obecność wielu obiektów 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ściami w tej tablicy zarządza uporządkowane dane znalezione na stronie internetowej w przypadku każdego wyniku wyszukiwania. Na przykład witryna z opiniami może zawierać uporządkowane dane, które dodają do tablicy richSnippet ten wpis tablicy:

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