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