使用搜尋小工具建立搜尋介面

搜尋小工具可為網路應用程式提供可自訂的搜尋介面。這個小工具只需要少量 HTML 和 JavaScript 即可實作，並啟用常見的搜尋功能，例如面向和分頁。您也可以使用 CSS 和 JavaScript 自訂介面部分。

如果您需要比小工具提供的彈性更高的功能，請考慮使用 Query API。如要瞭解如何使用 Query API 建立搜尋介面，請參閱「使用 Query API 建立搜尋介面」一文。

建構搜尋介面

建構搜尋介面需要完成幾個步驟：

  1. 設定搜尋應用程式
  2. 為應用程式產生用戶端 ID
  3. 為搜尋框和搜尋結果新增 HTML 標記
  4. 在頁面上載入小工具
  5. 初始化小工具

設定搜尋應用程式

每個搜尋介面都必須在管理控制台中定義搜尋應用程式。搜尋應用程式會提供查詢的其他資訊，例如資料來源、商情項目和搜尋品質設定。

如要建立搜尋應用程式，請參閱「建立自訂搜尋功能」。

為應用程式產生用戶端 ID

除了設定 Google Cloud Search API 存取權中的步驟之外，您還必須為網頁應用程式產生用戶端 ID。

設定專案

設定專案時：

  • 選取「網路瀏覽器」用戶端類型
  • 提供應用程式的來源 URI。
  • 記下已建立的用戶端 ID。您需要用戶端 ID 才能完成後續步驟。小工具不需要用戶端密鑰。

如需更多資訊，請參閱「用於用戶端網頁應用程式的 OAuth 2.0」。

新增 HTML 標記

小工具需要少量 HTML 才能運作。您必須提供以下資訊：

  • 搜尋框的 input 元素。
  • 建議彈出式視窗的錨定元素。
  • 用於容納搜尋結果的元素。
  • (選用) 提供元素來容納切面控制項。

以下 HTML 程式碼片段顯示搜尋小工具的 HTML，其中要繫結的元素會透過 id 屬性識別：

serving/widget/public/with_css/index.html

載入小工具

小工具會透過載入器指令碼動態載入。如要納入載入器，請使用

您必須在指令碼標記中提供 onload 回呼。系統會在載入器就緒時呼叫此函式。載入器準備就緒後，請呼叫 gapi.load() 來載入 API 用戶端、Google 登入和 Cloud Search 模組，繼續載入小工具。

serving/widget/public/with_css/app.js
/**
* 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)
}

系統會在載入所有模組後呼叫 initializeApp() 函式。

初始化小工具

首先，請使用產生的用戶端 ID 和 https://www.googleapis.com/auth/cloud_search.query 範圍，呼叫 gapi.client.init() 或 gapi.auth2.init()，藉此初始化用戶端程式庫。接下來，請使用 gapi.cloudsearch.widget.resultscontainer.Builder 和 gapi.cloudsearch.widget.searchbox.Builder 類別設定小工具，並將其繫結至 HTML 元素。

以下範例說明如何初始化小工具：

serving/widget/public/with_css/app.js
/**
 * 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'
    });
  });
}

上述範例參照了兩個變數，其定義如下：

serving/widget/public/with_css/app.js
/**
* Client ID from OAuth credentials.
*/
var clientId = "...apps.googleusercontent.com";

/**
* Full resource name of the search application, such as
* "searchapplications/".
*/
var searchApplicationName = "searchapplications/...";

自訂登入體驗

根據預設，小工具會在使用者開始輸入查詢時，提示他們登入並授權應用程式。您可以使用 Google 網站登入，為使用者提供更貼近需求的登入體驗。

直接授權使用者

使用「使用 Google 帳戶登入」功能，監控使用者的登入狀態，並視需要登入或登出使用者。舉例來說，以下範例會觀察 isSignedIn 狀態，以監控登入變更，並使用 GoogleAuth.signIn() 方法，透過按下按鈕來啟動登入程序：

serving/widget/public/with_signin/app.js
// 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();
};

詳情請參閱「使用 Google 帳戶登入」。

自動登入使用者

您可以代表貴機構中的使用者預先授權應用程式，進一步簡化登入體驗。如果您使用 Cloud Identity-Aware Proxy 保護應用程式，這項技巧也非常實用。

詳情請參閱「在 IT 應用程式中使用 Google 登入」。

自訂介面

您可以透過多種技巧組合變更搜尋介面的外觀：

  • 使用 CSS 覆寫樣式
  • 使用轉接程式裝飾元素
  • 使用轉接器建立自訂元素

使用 CSS 覆寫樣式

搜尋小工具會提供專屬 CSS，用於設定建議和結果元素的樣式，以及分頁控制項。您可以視需要重新設定這些元素的樣式。

載入期間，搜尋小工具會動態載入預設樣式表。這會在應用程式樣式表載入後發生，並提高規則的優先順序。為確保您自訂的樣式優先於預設樣式，請使用祖系選取器來提高預設規則的特定性。

舉例來說，如果在文件中的靜態 link 或 style 標記中載入下列規則，就不會產生任何效果。

.cloudsearch_suggestion_container {
  font-size: 14px;
}

請改用頁面中宣告的祖系容器 ID 或類別來限定規則。

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

如需支援類別清單和小工具產生的 HTML 範例，請參閱「支援的 CSS 類別」參考資料。

使用轉接程式裝飾元素

如要在算繪前裝飾元素，請建立並註冊實作任一裝飾方法的轉接器，例如 decorateSuggestionElement 或 decorateSearchResultElement.

舉例來說，下列轉接器會在建議和結果元素中新增自訂類別。

serving/widget/public/with_decorated_element/app.js
/**
 * 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');
}

如要在初始化小工具時註冊轉接程式，請使用相應 Builder 類別的 setAdapter() 方法：

serving/widget/public/with_decorated_element/app.js
// 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();

裝飾子可能會修改容器元素和任何子元素的屬性。裝飾期間可能會新增或移除子元素。不過，如果要對元素進行結構性變更，建議您直接建立元素，而非裝飾元素。

使用轉接器建立自訂元素

如要為建議、切面容器或搜尋結果建立自訂元素，請分別建立並註冊實作 createSuggestionElement、createFacetResultElement 或 createSearchResultElement 的轉接器。

下列轉接器說明如何使用 HTML