Tworzenie interfejsu wyszukiwania za pomocą widżetu wyszukiwania

Widżet wyszukiwania udostępnia konfigurowalny interfejs wyszukiwania dla aplikacji internetowych. Wymaga minimalnej implementacji HTML i JavaScriptu oraz obsługuje typowe funkcje, takie jak aspekty i stronicowanie. Możesz też dostosować interfejs za pomocą CSS i JavaScriptu.

Jeśli potrzebujesz większej elastyczności, użyj interfejsu Query API. Zobacz Tworzenie interfejsu wyszukiwania za pomocą interfejsu Query API.

Tworzenie interfejsu wyszukiwania

Tworzenie interfejsu wyszukiwania wymaga wykonania tych czynności:

skonfigurowanie aplikacji do wyszukiwania.
Wygeneruj identyfikator klienta aplikacji.
Dodaj znaczniki HTML dla pola wyszukiwania i wyników.
Załaduj widżet na stronie.
Zainicjuj widżet.

Konfigurowanie wyszukiwarki

Każdy interfejs wyszukiwania wymaga aplikacji wyszukiwania zdefiniowanej w konsoli administracyjnej. Aplikacja udostępnia ustawienia zapytania, takie jak źródła danych, aspekty i parametry jakości wyszukiwania.

Aby utworzyć wyszukiwarkę, zapoznaj się z artykułem Tworzenie niestandardowego środowiska wyszukiwania.

Wygeneruj identyfikator klienta aplikacji.

Oprócz czynności opisanych w artykule Konfigurowanie dostępu do interfejsu Cloud Search API wygeneruj identyfikator klienta aplikacji internetowej.

Konfigurowanie projektu

Podczas konfigurowania projektu:

Wybierz typ klienta Przeglądarka.
Podaj adres URL pochodzenia aplikacji.
Zapisz identyfikator klienta. Widżet nie wymaga klucza klienta.

Więcej informacji znajdziesz w artykule OAuth 2.0 w przypadku internetowych aplikacji po stronie klienta.

Dodawanie znaczników HTML

Widżet wymaga tych elementów HTML:

Element input w polu wyszukiwania.
Element, do którego jest przypięte okno sugestii.
Element wyników wyszukiwania.
(Opcjonalnie) Element sterujący aspektami.

Ten fragment kodu pokazuje elementy zidentyfikowane za pomocą atrybutów id:

serving/widget/public/with_css/index.html

Wyświetl w GitHubie

<div id="search_bar">
  <div id="suggestions_anchor">
    <input type="text" id="search_input" placeholder="Search for...">
  </div>
</div>
<div id="facet_results"></div>
<div id="search_results"></div>

Wczytywanie widżetu

Dołącz moduł wczytujący za pomocą tagu <script>:

serving/widget/public/with_css/index.html

Wyświetl w GitHubie

<!-- Google API loader -->
<script src="https://apis.google.com/js/api.js?mods=enable_cloud_search_widget&onload=onLoad" async defer></script>

Podaj onload wywołanie zwrotne. Gdy moduł wczytujący będzie gotowy, wywołaj funkcję gapi.load(), aby wczytać klienta interfejsu API, logowanie przez Google i moduły Cloud Search.

serving/widget/public/with_css/app.js

Wyświetl w GitHubie

/**
* Load the cloud search widget & auth libraries. Runs after
* the initial gapi bootstrap library is ready.
*/
function onLoad() {
  gapi.load('client:auth2:cloudsearch-widget', initializeApp)
}

Inicjowanie widżetu

Zainicjuj bibliotekę klienta za pomocą funkcji gapi.client.init() lub gapi.auth2.init(), podając identyfikator klienta i zakres https://www.googleapis.com/auth/cloud_search.query. Użyj klas buildera, aby skonfigurować i powiązać widżet.

Przykładowa inicjalizacja:

serving/widget/public/with_css/app.js

Wyświetl w GitHubie

/**
 * Initialize the app after loading the Google API client &
 * Cloud Search widget.
 */
function initializeApp() {
  // Load client ID & search app.
  loadConfiguration().then(function() {
    // Set API version to v1.
    gapi.config.update('cloudsearch.config/apiVersion', 'v1');

    // Build the result container and bind to DOM elements.
    var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setSearchResultsContainerElement(document.getElementById('search_results'))
      .setFacetResultsContainerElement(document.getElementById('facet_results'))
      .build();

    // Build the search box and bind to DOM elements.
    var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setInput(document.getElementById('search_input'))
      .setAnchor(document.getElementById('suggestions_anchor'))
      .setResultsContainer(resultsContainer)
      .build();
  }).then(function() {
    // Init API/oauth client w/client ID.
    return gapi.auth2.init({
        'clientId': clientId,
        'scope': 'https://www.googleapis.com/auth/cloud_search.query'
    });
  });
}

Zmienne konfiguracji:

serving/widget/public/with_css/app.js

Wyświetl w GitHubie

/**
* Client ID from OAuth credentials.
*/
var clientId = "...apps.googleusercontent.com";

/**
* Full resource name of the search application, such as
* "searchapplications/<your-id>".
*/
var searchApplicationName = "searchapplications/...";

Dostosowywanie procesu logowania

Gdy użytkownik zacznie pisać, widżet poprosi go o zalogowanie się. Możesz użyć logowania przez Google w witrynach, aby dostosować usługi do swoich potrzeb.

Bezpośrednie autoryzowanie użytkowników

Używaj funkcji Zaloguj się przez Google, aby monitorować stany logowania i nimi zarządzać. W tym przykładzie używamy GoogleAuth.signIn() po kliknięciu przycisku:

serving/widget/public/with_signin/app.js

Wyświetl w GitHubie

// Handle sign-in/sign-out.
let auth = gapi.auth2.getAuthInstance();

// Watch for sign in status changes to update the UI appropriately.
let onSignInChanged = (isSignedIn) => {
  // Update UI to switch between signed in/out states
  // ...
}
auth.isSignedIn.listen(onSignInChanged);
onSignInChanged(auth.isSignedIn.get()); // Trigger with current status.

// Connect sign-in/sign-out buttons.
document.getElementById("sign-in").onclick = function(e) {
  auth.signIn();
};
document.getElementById("sign-out").onclick = function(e) {
  auth.signOut();
};

Automatyczne logowanie użytkowników

Wstępnie autoryzuj aplikację dla użytkowników w organizacji, aby uprościć proces logowania. Jest to przydatne również w przypadku Cloud Identity Aware Proxy. Zobacz Korzystanie z logowania przez Google w aplikacjach IT.

Dostosowywanie interfejsu

Wygląd widżetu możesz zmienić, wykonując te czynności:

Zastępowanie stylów za pomocą CSS.
dekorowanie elementów za pomocą adaptera,
Tworzenie elementów niestandardowych za pomocą adaptera.

Zastępowanie stylów za pomocą CSS

Widżet zawiera własny arkusz CSS. Aby go zastąpić, użyj selektorów elementów nadrzędnych, aby zwiększyć specyficzność:

#suggestions_anchor .cloudsearch_suggestion_container {
  font-size: 14px;
}

Zapoznaj się z informacjami o obsługiwanych klasach CSS.

Dekorowanie elementów za pomocą adaptera

Utwórz i zarejestruj adapter, aby modyfikować elementy przed renderowaniem. W tym przykładzie dodajemy niestandardową klasę CSS:

serving/widget/public/with_decorated_element/app.js

Wyświetl w GitHubie

/**
 * Search box adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.decorateSuggestionElement = function(element) {
  element.classList.add('my-suggestion');
}

/**
 * Results container adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.decorateSearchResultElement = function(element) {
  element.classList.add('my-result');
}

Zarejestruj adapter podczas inicjalizacji:

serving/widget/public/with_decorated_element/app.js

Wyświetl w GitHubie

// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

Tworzenie elementów niestandardowych za pomocą adaptera

Wdróż createSuggestionElement, createFacetResultElement lub createSearchResultElement, aby utworzyć niestandardowe komponenty interfejsu. W tym przykładzie użyto tagów HTML <template>:

serving/widget/public/with_custom_element/app.js

Wyświetl w GitHubie

/**
 * Search box adapter that overrides creation of suggestion elements.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.createSuggestionElement = function(suggestion) {
  let template = document.querySelector('#suggestion_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.suggested_query').textContent = suggestion.suggestedQuery;
  return fragment.firstElementChild;
}

/**
 * Results container adapter that overrides creation of result elements.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.createSearchResultElement = function(result) {
  let template = document.querySelector('#result_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.title').textContent = result.title;
  fragment.querySelector('.title').href = result.url;
  let snippetText = result.snippet != null ?
    result.snippet.snippet : '';
  fragment.querySelector('.query_snippet').innerHTML = snippetText;
  return fragment.firstElementChild;
}

Zarejestruj adapter:

serving/widget/public/with_custom_element/app.js

Wyświetl w GitHubie

// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

Elementy niestandardowych aspektów muszą być zgodne z tymi regułami:

Dołącz cloudsearch_facet_bucket_clickable do elementów klikalnych.
Umieść każdy zasobnik w cloudsearch_facet_bucket_container.
Zachowaj kolejność segmentów z odpowiedzi.

Na przykład ten fragment kodu renderuje aspekty za pomocą linków zamiast pól wyboru.

serving/widget/public/with_custom_facet/app.js

Wyświetl w GitHubie

/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}

ResultsContainerAdapter.prototype.createFacetResultElement = function(result) {
  // container for the facet
  var container = document.createElement('div');

  // Add a label describing the facet (operator/property)
  var label = document.createElement('div')
  label.classList.add('facet_label');
  label.textContent = result.operatorName;
  container.appendChild(label);

  // Add each bucket
  for(var i in result.buckets) {
    var bucket = document.createElement('div');
    bucket.classList.add('cloudsearch_facet_bucket_container');

    // Extract & render value from structured value
    // Note: implementation of renderValue() not shown
    var bucketValue = this.renderValue(result.buckets[i].value)
    var link = document.createElement('a');
    link.classList.add('cloudsearch_facet_bucket_clickable');
    link.textContent = bucketValue;
    bucket.appendChild(link);
    container.appendChild(bucket);
  }
  return container;
}

// Renders a value for user display
ResultsContainerAdapter.prototype.renderValue = function(value) {
  // ...
}

Dostosowywanie zachowania wyszukiwania

Zastąp ustawienia aplikacji do wyszukiwania, przechwytując żądania za pomocą adaptera. Wdróż interceptSearchRequest, aby modyfikować żądania przed ich wykonaniem. Ten przykład ogranicza zapytania do wybranego źródła:

serving/widget/public/with_request_interceptor/app.js

Wyświetl w GitHubie

/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}
ResultsContainerAdapter.prototype.interceptSearchRequest = function(request) {
  if (!this.selectedSource || this.selectedSource == 'ALL') {
    // Everything selected, fall back to sources defined in the search
    // application.
    request.dataSourceRestrictions = null;
  } else {
    // Restrict to a single selected source.
    request.dataSourceRestrictions = [
      {
        source: {
          predefinedSource: this.selectedSource
        }
      }
    ];
  }
  return request;
}

Zarejestruj adapter:

serving/widget/public/with_request_interceptor/app.js

Wyświetl w GitHubie

var resultsContainerAdapter = new ResultsContainerAdapter();
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(resultsContainerAdapter)
  // ...
  .build();

Poniższy kod HTML służy do wyświetlania pola wyboru umożliwiającego filtrowanie według źródeł:

serving/widget/public/with_request_interceptor/index.html

Wyświetl w GitHubie

<div>
  <span>Source</span>
  <select id="sources">
    <option value="ALL">All</option>
    <option value="GOOGLE_GMAIL">Gmail</option>
    <option value="GOOGLE_DRIVE">Drive</option>
    <option value="GOOGLE_SITES">Sites</option>
    <option value="GOOGLE_GROUPS">Groups</option>
    <option value="GOOGLE_CALENDAR">Calendar</option>
    <option value="GOOGLE_KEEP">Keep</option>
  </select>
</div>

Poniższy kod nasłuchuje zmiany, ustawia wybór i w razie potrzeby ponownie wykonuje zapytanie.

serving/widget/public/with_request_interceptor/app.js

Wyświetl w GitHubie

// Handle source selection
document.getElementById('sources').onchange = (e) => {
  resultsContainerAdapter.selectedSource = e.target.value;
  let request = resultsContainer.getCurrentRequest();
  if (request.query) {
    // Re-execute if there's a valid query. The source selection
    // will be applied in the interceptor.
    resultsContainer.resetState();
    resultsContainer.executeRequest(request);
  }
}

Możesz też przechwycić odpowiedź wyszukiwania, implementując interceptSearchResponse w adapterze.

Przypinanie wersji

Wersja interfejsu API: ustaw wartość cloudsearch.config/apiVersion przed zainicjowaniem.
Wersja widżetu: użyj gapi.config.update('cloudsearch.config/clientVersion', 1.1).

Jeśli nie są ustawione, domyślnie przyjmują wartość 1,0.

Aby na przykład przypiąć widżet do wersji 1.1:

serving/widget/public/basic/app.js

Wyświetl w GitHubie

gapi.config.update('cloudsearch.config/apiVersion', 'v1');

Zabezpieczanie interfejsu wyszukiwania

Stosuj sprawdzone metody związane z bezpieczeństwem aplikacji internetowych, zwłaszcza aby zapobiegać kliknięciom.

Włączanie debugowania

Aby włączyć debugowanie, użyj interceptSearchRequest:

if (!request.requestOptions) {
  request.requestOptions = {};
}
request.requestOptions.debugOptions = {enableDebugging: true};
return request;

O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.

Ostatnia aktualizacja: 2026-02-24 UTC.

Blog
Przeczytaj bloga Google Workspace Developers
Omówienie stosu
Zadawanie pytań za pomocą tagu google-cloud-search
Próbki kodu
Przejrzyj nasze przykładowe aplikacje lub skopiuj je, aby stworzyć własne
Biblioteki klienta
Pobierz bibliotekę klienta dla wybranego języka