您可以使用 HTML 標記,在網頁和其他網頁應用程式中嵌入程式化搜尋引擎元件 (搜尋框和搜尋結果網頁)。這些程式化搜尋引擎元素包含依據程式化搜尋伺服器儲存的設定轉譯的元件,以及您所做的任何自訂。
所有 JavaScript 都是以非同步方式載入,在瀏覽器擷取程式化搜尋引擎 JavaScript 時,還能繼續載入網頁。
簡介
本文件提供在網頁中新增程式化搜尋引擎元素的基本模型,以及該元素可設定元件和彈性 JavaScript API 的說明。
範圍
本文件說明如何使用 Programmable Search Engine Control API 專屬的函式和屬性。
瀏覽器相容性
如要查看程式化搜尋引擎支援的瀏覽器清單,請按這裡。
觀眾
開發人員可利用本文件,在網頁中加入 Google 程式化搜尋功能。
程式化搜尋元素
您可以使用 HTML 標記在網頁中加入程式化搜尋元素。每個元素都至少包含一個元件:搜尋框和搜尋結果區塊,或同時包含兩者。搜尋框接受使用者以下列任何方式輸入:
- 在文字輸入欄位中輸入的搜尋查詢
- 嵌入網址中的查詢字串
- 程式輔助執行作業
此外,搜尋結果區塊可接受下列輸入方式:
- 嵌入網址中的查詢字串
- 程式輔助執行作業
可用的程式化搜尋元素類型如下:
元素類型 | 元件 | 說明 |
---|---|---|
standard | <div class="gcse-search"> |
搜尋框和搜尋結果,以同一個 <div> 顯示。 |
雙欄 | 「<div class="gcse-searchbox"> 」和「<div class="gcse-searchresults"> 」 |
雙欄版面配置,其中一側顯示搜尋結果,另一側顯示搜尋框。如果您打算在網頁中以雙欄模式插入多個元素,可以使用 gname 屬性將搜尋框與搜尋結果區塊配對。 |
僅限搜尋框 | <div class="gcse-searchbox-only"> |
獨立的搜尋框。 |
僅限搜尋結果 | <div class="gcse-searchresults-only"> |
搜尋結果的獨立區塊。 |
您可以在網頁中新增任意數量的有效搜尋元素。如果是雙欄模式,所有必要元件 (搜尋框和搜尋結果區塊) 都必須存在。
以下是簡易搜尋元素的範例:
<!-- 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>
使用程式化搜尋元素撰寫不同的版面配置選項
「程式化搜尋引擎」控制台的「外觀」頁面有下列版面配置選項。以下是使用程式化搜尋元素撰寫版面配置選項的一些一般指南。如要查看這些選項的示範,請按一下該連結。
選項 | 元件 |
---|---|
全形 | <div class="gcse-search"> |
小巧 | <div class="gcse-search"> |
兩欄 | <div class="gcse-searchbox"> 、<div class="gcse-searchresults"> |
雙頁 | 第一頁為 <div class="gcse-searchbox-only"> ,第二頁的 <div class="gcse-searchresults-only"> (或其他元件) |
只顯示搜尋結果 | <div class="gcse-searchresults-only"> |
Google 代管 | <div class="gcse-searchbox-only"> |
自訂程式化搜尋元素
如要自訂顏色、字型或連結樣式,請前往程式化搜尋引擎的「外觀和風格」頁面。
您可以使用選用屬性覆寫在程式化搜尋引擎控制台中建立的設定。藉此打造專屬網頁的搜尋體驗。
舉例來說,以下程式碼會建立搜尋框,以便在新視窗中開啟結果網頁 (http://www.example.com?search=lady+gaga)。queryParameterName
屬性的值以及使用者查詢字串,會用來建立結果網址。
請注意,queryParameterName
屬性的前置字串是 data-
。所有屬性都必須包含這個前置字串。
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
如果您曾使用程式化搜尋引擎控制台啟用自動完成或修正等功能,就可以利用屬性來自訂這些功能。使用這些屬性指定的所有自訂設定,都會覆寫控制台中的設定。以下範例會建立兩個資料欄的搜尋元素,其中具備下列功能:
- 記錄管理已啟用
- 顯示的自動完成建議數量上限設為 5
- 分類標籤會以連結的形式顯示。
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
支援的屬性
屬性 | 類型 | 說明 | 元件 |
---|---|---|---|
一般 | |||
gname |
字串 | (選用) Search Element 物件的名稱。名稱可用來依名稱擷取相關元件,或將 searchbox 元件與 searchresults 元件配對。如未提供,程式化搜尋引擎會根據網頁上的元件順序自動產生 gname 。舉例來說,第一個未命名的 searchbox-only 含有 gname 「searchbox-only0」,第二個則含有「seachbox-only1」,以此類推。gname 請注意,針對雙欄版面配置中的元件自動產生的 gname 為 two-column 。以下範例使用 gname storesearch 將 searchbox 元件連結至 searchresults 元件:
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> 擷取物件時,如果有多個元件具有相同的 |
不限 |
autoSearchOnLoad |
布林值 | 指定是否要根據載入中網頁網址內嵌的查詢執行搜尋。請注意,網址必須含有查詢字串,才能執行自動搜尋。預設值:true 。 |
不限 |
enableHistory |
布林值 | 如果設為 true ,則會啟用瀏覽器的「返回」和「前進」按鈕記錄管理功能。查看示範。 |
searchbox 僅限搜尋框 |
queryParameterName |
字串 | 查詢參數名稱,例如 q (預設) 或 query 。這會嵌入網址 (例如 http://www.example.com?q=lady+gaga)。請注意,單獨指定查詢參數名稱並不會在載入時觸發自動搜尋。網址必須含有查詢字串,才能執行自動搜尋。 |
不限 |
resultsUrl |
網址 | 結果網頁的網址。(預設值為 Google 代管的網頁)。 | 僅限搜尋框 |
newWindow |
布林值 | 指定是否要在新視窗中開啟結果頁面。
預設值:false 。 |
僅限搜尋框 |
ivt |
布林值 |
您可以透過這個參數提供布林值,讓 Google 瞭解,您希望廣告能在同意和不同意的流量中,分別使用無效流量 Cookie 和本機儲存空間。
預設: 使用範例: |
搜尋結果 僅限搜尋結果 |
mobileLayout |
字串 |
指定是否應針對行動裝置使用行動裝置版面配置樣式。
預設: 使用範例: |
不限 |
自動完成 | |||
enableAutoComplete |
布林值 | 您必須先在程式化搜尋引擎控制台中啟用自動完成功能,才能使用這項功能。
true 可啟用自動完成功能。 |
不限 |
autoCompleteMaxCompletions |
整數 | 顯示的自動完成建議數量上限。 | searchbox 僅限搜尋框 |
autoCompleteMaxPromotions |
整數 | 自動完成功能顯示的促銷活動數量上限。 | searchbox 僅限搜尋框 |
autoCompleteValidLanguages |
字串 | 以半形逗號分隔的語言清單,表示應啟用自動完成功能的語言。 支援的語言。 | searchbox 僅限搜尋框 |
分類標籤 | |||
defaultToRefinement |
字串 | 必須在程式化搜尋引擎控制台中建立分類標籤時才能使用。指定要顯示的預設修正標籤。注意:Google 代管版面配置不支援這個屬性。 | 不限 |
refinementStyle |
字串 | 可接受的值為 tab (預設值) 和 link 。
只有在已停用圖片搜尋功能,或已啟用圖片搜尋功能但已停用網頁搜尋的情況下,才能使用 link 。 |
搜尋結果 僅限搜尋結果 |
圖片搜尋 | |||
enableImageSearch |
布林值 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 如果是 |
搜尋結果 僅限搜尋結果 |
defaultToImageSearch |
布林值 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 如果設為 |
不限 |
imageSearchLayout |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 指定圖片搜尋結果網頁的版面配置。可接受的值為 |
搜尋結果 僅限搜尋結果 |
imageSearchResultSetSize |
整數,字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 指定圖片搜尋搜尋結果集的大小上限。
例如 |
不限 |
image_as_filetype |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 限制系統只傳回指定擴充功能檔案的結果。 支援的擴充功能包括 | 不限 |
image_as_oq |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 使用邏輯 OR 篩選搜尋結果。 如果想要包含「term1」或「term2」的搜尋結果,則顯示範例: | 不限 |
image_as_rights |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 依授權建立的篩選器。 支援的值為 查看一般組合。 | 不限 |
image_as_sitesearch |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 限制系統只顯示特定網站的網頁。 使用範例: | 不限 |
image_colortype |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 僅搜尋黑白 (單聲道)、灰階或彩色圖片。支援的值為 | 不限 |
image_cr |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 限制顯示來自特定國家/地區的文件搜尋結果。 | 不限 |
image_dominantcolor |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 限制搜尋特定主色圖片。
支援的值為 | 不限 |
image_filter |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 自動篩選搜尋結果。 支援的值:0/1 使用範例: | 不限 |
image_gl |
字串 | 必須在程式化搜尋引擎控制台中啟用 圖片搜尋功能,才能使用這個值。提升來源國家/地區與參數值相符的搜尋結果。 | 不限 |
image_size |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 傳回指定大小的圖片,其中尺寸可以是下列其中一種: | 不限 |
image_sort_by |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 使用日期或其他結構化內容排序結果。 如要依關聯性排序,請使用空白字串 (image_sort_by=")。 使用範例: | 不限 |
image_type |
字串 | 必須在程式化搜尋引擎控制台中啟用
圖片搜尋功能,才能使用這個值。 僅搜尋特定類型的圖片。
支援的值為 | 不限 |
網頁搜尋 | |||
disableWebSearch |
布林值 | 如果設為 true ,則會停用網頁搜尋功能。通常只有在程式化搜尋引擎控制台中啟用
圖片搜尋功能時,才會使用。 |
搜尋結果 僅限搜尋結果 |
webSearchQueryAddition |
字串 | 使用邏輯 OR 在搜尋查詢中加入額外字詞。
用法範例: |
不限 |
webSearchResultSetSize |
整數,字串 | 結果集的大小上限。適用於圖片搜尋和網頁搜尋。預設選項取決於版面配置,以及程式化搜尋引擎是否設為搜尋整個網路或僅限指定的網站。可接受的值包括:
|
不限 |
webSearchSafesearch |
字串 |
指定網頁搜尋結果是否已啟用SafeSearch。可接受的值為 off 和 active 。 |
不限 |
as_filetype |
字串 | 限制系統只傳回指定擴充功能檔案的結果。你可以在 Search Console 說明中心找到一份 Google 可建立索引的檔案類型清單。 | 不限 |
as_oq |
字串 | 使用邏輯 OR 篩選搜尋結果。
如果想要包含「term1」或「term2」的搜尋結果,則顯示範例: |
不限 |
as_rights |
字串 | 依據授權建立的篩選器。
支援的值為 如需瞭解典型組合,請參閱 https://wiki.creativecommons.org/wiki/CC_Search_integration。 | 不限 |
as_sitesearch |
字串 | 限制系統只顯示特定網站的網頁。
用法範例: |
不限 |
cr |
字串 | 限制只顯示來自特定國家/地區的文件搜尋結果。
用法範例: |
不限 |
filter |
字串 | 自動篩選搜尋結果。
支援的值:0/1 用法範例: |
不限 |
gl |
字串 | 提升來源國家/地區與參數值相符的搜尋結果。 這個方法只能與 language value 設定搭配使用。 用法範例: |
不限 |
lr |
字串 | 限制只顯示特定語言的文件搜尋結果。
使用範例: |
不限 |
sort_by |
字串 | 使用日期或其他結構化內容排序結果。屬性值必須是可自訂搜尋「例如」的「結果排序」設定中提供的其中一個選項。
如要依關聯性排序,請使用空白字串 (sort_by=")。 用法範例: |
不限 |
搜尋結果 | |||
enableOrderBy |
布林值 | 按關聯性、日期或標籤排序結果。 | 不限 |
linkTarget |
字串 | 設定連結目標。預設值:_blank 。 |
搜尋結果 僅限搜尋結果 |
noResultsString |
字串 | 指定沒有與查詢相符的結果時顯示的預設文字。預設結果字串可用來顯示所有支援語言的本地化字串,而自訂結果字串則不需要。 | 搜尋結果 僅限搜尋結果 |
resultSetSize |
整數,字串 | 結果集的大小上限。例如 large 、small 、filtered_cse 、10 。預設值取決於版面配置,以及引擎是設定為搜尋整個網路還是僅限指定的網站。 |
不限 |
safeSearch |
字串 | 指定是否同時為網頁和圖片搜尋啟用
安全搜尋。可接受的值為 off 和 active 。 |
不限 |
回呼
回呼支援詳細控制搜尋元素初始化和搜尋程序。這些物件會透過全域 __gcse
物件向 Search Element JavaScript 註冊。註冊回呼說明所有支援的回呼的註冊作業。
初始化回呼
「搜尋元素」JavaScript 轉譯 DOM 中的搜尋元素前,系統會叫用初始化回呼。如果 __gcse
中的 parsetags
設為 explicit
,搜尋元素 JavaScript 會將轉譯搜尋元素留在初始化回呼中 (如「註冊回呼」所示)。這可用於選取要轉譯的元素,或延遲算繪元素,直到需要這些元素為止。此外,它也可以覆寫元素屬性;舉例來說,它可以將透過「控制台」或 HTML 屬性設定的搜尋框預設為「網頁搜尋」成為圖片搜尋框,或者指定透過程式化搜尋引擎表單提交的查詢,是在搜尋結果專用元素中執行。
查看示範。
初始化回呼的角色是由 __gcse
的 parsetags
屬性值控管。
- 如果值為
onload
,則搜尋元素 JavaScript 會自動轉譯網頁上的所有搜尋元素。系統仍會叫用初始化回呼,但不負責轉譯搜尋元素。 - 如果值為
explicit
,則搜尋元素 JavaScript 不會轉譯搜尋元素。回呼可能會使用render()
函式選擇性轉譯,或使用go()
函式轉譯所有搜尋元素
下列程式碼示範如何使用 explicit
剖析標記和初始化回呼,在 div
中算繪搜尋框和搜尋結果:
搜尋回呼
搜尋元素 JavaScript 支援在搜尋控制流程中運作的六個回呼。搜尋回呼分為兩組、網頁搜尋回呼和相符的圖片搜尋回呼:
- 開始搜尋
- 圖片搜尋
- 網頁搜尋
- 已有結果
- 圖片搜尋
- 網頁搜尋
- 已轉譯結果
- 圖片搜尋
- 網頁搜尋
與初始化回呼一樣,搜尋回呼會使用 __gcse
物件中的項目來設定。當 Search Element JavaScript 啟動時,這項功能就會隨之啟動。系統會在啟動後忽略 __gcse
的修改。
這些回呼的每個回呼都會以引數形式傳遞搜尋元素的 gName
。如果網頁含有多項搜尋條件,gname
就非常實用。請使用 data-gname
屬性為搜尋元素指定 gname
值:
<div class="gcse-searchbox" data-gname="storesearch"></div>
如果 HTML 無法辨識 gname,Search Element JavaScript 會產生一個一致的值,直到 HTML 修改為止。
圖片/網頁搜尋發起回呼
系統會在搜尋元素 JavaScript 向伺服器要求搜尋結果之前,立即叫用搜尋起始回呼。這類使用案例包括使用時段的當地時間控管查詢的變更。
searchStartingCallback(gname, query)
gname
- 搜尋元素的識別字串
query
- 值 (可能由搜尋元素 JavaScript 修改)。
回呼會傳回應做為這項搜尋查詢使用的值。如果傳回空字串,系統會忽略傳回值,並呼叫呼叫端使用未修改的查詢。
或者,您也可以將回呼函式放入 __gcse
物件中,或使用 JavaScript 將回呼動態新增至物件:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Google 搜尋啟動回呼範例
範例搜尋開始回呼中的搜尋起始回呼範例會根據時段,在查詢中新增 morning
或 afternoon
。
在 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>
圖片/網頁搜尋結果 - 回呼
系統會在搜尋元素 JavaScript 顯示置頂查詢和結果之前,立即叫用這些回呼。以下用途舉例說明可算繪促銷活動並產生的樣式,以無法透過一般自訂方式指定的樣式。
resultsReadyCallback(gname, query, promos, results, div)
gname
- 搜尋元素的識別字串
query
- 產生這些結果的查詢
promos
- 促銷物件陣列,對應至使用者查詢的相符促銷活動。請參閱促銷活動物件定義。
results
- 結果物件的陣列。請參閱結果物件定義。
div
- 在 DOM 中的 HTMLdiv 標記,Search Element 原本就會放置置頂查詢和搜尋結果。一般來說,搜尋元素 JavaScript 會處理填入這個 div,但這個回呼可能會選擇停止自動算繪結果,並使用此
div
自行算繪結果。
如果這個回呼傳回 true
值,搜尋元素 JavaScript 就會略過網頁頁尾的工作。
結果範例回呼
結果範例回呼中的 resultsReady
回呼範例會以「非常」簡易的取代項目,覆寫置頂查詢和結果的預設呈現方式。
圖片/網頁搜尋結果轉譯的回呼
系統會在「搜尋元素」JavaScript 轉譯網頁頁尾之前,立即叫用這些回呼。用途範例包括新增回呼,以新增搜尋元素未顯示的結果內容,例如「儲存這個」核取方塊或不會自動轉譯的資訊,或是新增更多資訊按鈕的回呼。
如果轉譯結果的回呼需要位於結果就緒回呼的 promos
和 results
參數中的資訊,可以在該回呼之間傳遞資訊,如下所示:
callback(gname, query, promoElts, resultElts);
gname
- 搜尋元素的識別字串
query
- 搜尋字串。
promoElts
- 內含促銷活動的 DOM 元素陣列。
resultElts
- 包含結果的 DOM 元素陣列。
沒有傳回值。
轉譯回呼範例
範例結果轉譯回呼中的 resultsRendered
回呼範例會在每個促銷活動和結果中加入虛擬的「Keep」核取方塊。
如果轉譯結果的回呼需要傳遞至結果就緒回呼的資訊,可以在回呼之間傳送該資料。以下範例顯示將評分值從richSnippet
從結果就緒回呼傳送至所轉譯結果回呼的其中一種方法。
更多回呼範例
如需其他回呼範例,請參閱「更多回呼範例」文件。
置頂查詢和結果屬性
使用 JSDoc 標記法時,這些是促銷和結果物件的屬性。這裡會列出可能出現的所有屬性。各項房源顯示的房源會因促銷活動或搜尋結果的詳細資料而異。
結果中的 richSnippet
具有物件陣列的概略類型。這個陣列中的項目值由系統針對每筆搜尋結果在網頁上找到的結構化資料控制。舉例來說,評論網站可能會包含結構化資料,將此陣列項目新增至 richSnippet
:
'review': { 'ratingstars': '3.0', 'ratingcount': '1024', },
Programmable Search Element Control API (第 2 版)
google.search.cse.element
物件會發布下列靜態函式:
功能 | 說明 | ||||||
---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
轉譯搜尋元素。
參數
|
||||||
.go(opt_container) |
轉譯指定容器中的所有搜尋元素標記/類別。
參數
|
||||||
.getElement(gname) |
取得 gname 的元素物件。如果找不到,則傳回空值。傳回的
下列程式碼會在搜尋元素「element1」中執行「news」: var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
傳回所有成功建立的元素物件的對應,鍵用 gname 做為索引鍵。 |