搜尋小工具提供網頁應用程式的可自訂搜尋介面。 加入小工具只需少量的 HTML 和 JavaScript 實作並啟用常見的搜尋功能,例如 facet 和分頁。個人中心 也可以使用 CSS 和 JavaScript 自訂介面的部分。
如果您需要比小工具提供的更多彈性,可以考慮使用 Query API。如要進一步瞭解如何使用 Query API 建立搜尋介面, 請參閱使用 Query API 建立搜尋介面。
建構搜尋介面
建構搜尋介面需要幾個步驟:
- 設定搜尋應用程式
- 產生應用程式的用戶端 ID
- 為搜尋框和結果新增 HTML 標記
- 在網頁上載入小工具
- 初始化小工具
設定搜尋應用程式
每個搜尋介面都必須在 管理控制台。搜尋應用程式會提供額外的 包括資料來源、商情項目 以及搜尋品質設定
如要建立搜尋應用程式,請參閱 建立自訂搜尋體驗。
產生應用程式的用戶端 ID
除了 設定 Google Cloud Search API 的存取權, 您也必須產生網頁應用程式的用戶端 ID。
設定專案時:
- 選取「網路瀏覽器」用戶端類型
- 提供來源 URI
- 記下建立的用戶端 ID。您需要用戶端 ID 才能 或完成後續步驟用戶端密碼不需要
如需詳細資訊,請參閲 用戶端網頁應用程式適用的 OAuth 2.0。
新增 HTML 標記
小工具需要少量 HTML 才能運作。個人中心 必須提供:
- 搜尋框的
input
元素。 - 將建議彈出式視窗固定到其中的元素。
- 用於包含搜尋結果的元素。
- (選用) 提供元素以包含 facet 控制項。
下列 HTML 程式碼片段顯示搜尋小工具的 HTML,其中
要繫結的元素以 id
屬性識別:
載入小工具
系統會透過載入器指令碼動態載入小工具。包含
載入器,請使用 <script>
標記,如下所示:
您必須在指令碼標記中提供 onload
回呼。這個函式稱為
並在載入器準備就緒時啟動載入器準備就緒後,繼續載入小工具
呼叫 gapi.load()
載入 API 用戶端、Google 登入和 Cloud Search 模組。
系統會在所有模組都呼叫完成後呼叫 initializeApp()
函式
就會引發這個事件。
初始化小工具
首先,請呼叫
將 gapi.client.init()
或 gapi.auth2.init()
替換為產生的用戶端 ID
以及 https://www.googleapis.com/auth/cloud_search.query
範圍接下來,請使用
《gapi.cloudsearch.widget.resultscontainer.Builder
》和
用於設定小工具的 gapi.cloudsearch.widget.searchbox.Builder
類別
並將其繫結至 HTML 元素
以下範例說明如何初始化小工具:
上述範例參照了定義如下的兩個設定變數:
自訂登入體驗
根據預設,小工具會提示使用者登入並授權應用程式 開始輸入查詢的同時別擔心!您可以使用 網站專用 Google 登入 為使用者提供更符合個人需求的登入體驗。
直接授權使用者
使用「使用 Google 帳戶登入」功能監控
使用者並視需求登入或登出帳戶例如,下列
範例:觀察 isSignedIn
以便監控登入變更
使用 GoogleAuth.signIn()
透過按鈕啟動登入的方法
點擊:
詳情請參閱「使用 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.
舉例來說,下列轉接器會在建議中加入自訂類別 。
如要在初始化小工具時註冊轉接程式,請使用 setAdapter()
各個 Builder
類別中的方法:
裝飾器可以修改容器元素的屬性,也可以修改任何 子元素。子元素可能會在裝飾時加入或移除。 不過,如果要變更元素結構,請考慮建立 元素,而不是裝飾元素。
使用轉接程式建立自訂元素
如要為建議、商情項目容器或搜尋結果建立自訂元素,
建立及註冊
createSuggestionElement
,
createFacetResultElement
,
或 createSearchResultElement
以回應表示
下列轉接程式說明如何建立自訂建議和搜尋結果
使用 HTML <template>
標記的元素。
如要在初始化小工具時註冊轉接程式,請使用 setAdapter()
各個 Builder
類別中的方法:
使用 createFacetResultElement
建立自訂 facet 元素
須遵守以下幾項限制:
- 您必須將 CSS 類別
cloudsearch_facet_bucket_clickable
附加至 元素:使用者點擊就能切換值區。 - 您必須使用 CSS 將每個值區納入包含的元素中
cloudsearch_facet_bucket_container
類別。 - 顯示值區的順序必須與其在 回應。
例如,下列程式碼片段會改用連結呈現 facet 勾選方塊。
自訂搜尋行為
「搜尋應用程式」設定代表預設值 都是靜態的。 篩選器或商情項目 (例如允許使用者切換資料來源) 攔截搜尋要求以覆寫搜尋應用程式設定 搭配轉接頭。
使用
interceptSearchRequest
方法來修改對
搜尋 API
執行的程式碼
舉例來說,下列轉接器會攔截限制查詢的要求 使用者選取的來源:
如要在初始化小工具時註冊轉接程式,請使用
setAdapter()
ResultsContainer
下列 HTML 可用於顯示篩選依據的選取框 資料來源:
下列程式碼會監聽變更、設定選擇及 會視需要重新執行查詢。
您也可以使用
interceptSearchResponse
。
固定 API 版本
根據預設,小工具會使用最新的 API 穩定版本。如要鎖定
指定版本,則請將 cloudsearch.config/apiVersion
設定參數
先改為偏好版本,再初始化小工具。
如果未設定或設為無效值,API 版本將預設為 1.0。
固定小工具版本
為避免搜尋介面發生非預期的變更,請將
cloudsearch.config/clientVersion
設定參數,如下所示:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
如果未設定或設為無效值,小工具版本會預設為 1.0。
保護搜尋介面
搜尋結果包含高度機密資訊。奉行最佳做法 強化網頁應用程式安全性,尤其是針對 點擊劫持攻擊。
詳情請參閱 OWASP Guide Project
啟用偵錯功能
使用 interceptSearchRequest
即可開啟搜尋小工具的偵錯功能。例如:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;