Programmable Search Element Control API

您可以使用 HTML 標記,在網頁和其他網路應用程式中嵌入程式化搜尋引擎元件 (搜尋框和搜尋結果網頁)。這些程式化搜尋引擎元素是由元件組成,會根據程式化搜尋伺服器儲存的設定和您所做的任何自訂項目進行算繪。

所有 JavaScript 都會以非同步方式載入,因此瀏覽器擷取程式化搜尋引擎 JavaScript 時,網頁可以繼續載入。

簡介

本文提供基本模型,說明如何在網頁中新增 Programmable Search Engine 元素,並解釋元素的可設定元件和彈性 JavaScript API。

範圍

本文說明如何使用 Programmable Search Engine Control API 專屬的函式和屬性。

瀏覽器相容性

如要查看程式化搜尋引擎支援的瀏覽器清單,請按這裡

觀眾

這份文件適用於想在網頁中加入 Google 可程式化搜尋功能的開發人員。

程式化搜尋元素

您可以使用 HTML 標記,在網頁中加入可程式化搜尋元素。每個元素至少包含一個元件:搜尋框、一組搜尋結果,或兩者皆有。搜尋框接受使用者以任何下列方式輸入內容:

  • 在文字輸入欄位中輸入的搜尋查詢
  • 網址中內嵌的查詢字串
  • 程式輔助執行

此外,搜尋結果區塊接受以下輸入方式:

  • 網址中內嵌的查詢字串
  • 程式輔助執行

可用的程式化搜尋元素類型如下:

元素類型 元件 說明
standard <div class="gcse-search"> 搜尋框和搜尋結果,顯示在同一個 <div> 中。
兩欄 <div class="gcse-searchbox"><div class="gcse-searchresults"> 兩欄式版面配置,一側顯示搜尋結果,另一側顯示搜尋框。如果您打算在網頁的雙欄模式中插入多個元素,可以使用 gname 屬性將搜尋框與搜尋結果區塊配對。
searchbox-only <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 字串 (選用) Search Element 物件的名稱。名稱可用於依名稱擷取相關聯的元件,或將 searchbox 元件與 searchresults 元件配對。如未提供,程式化搜尋引擎會根據網頁上元件的順序,自動產生 gname。舉例來說,第一個未命名的 searchbox-only 具有 gname「searchbox-only0」,第二個具有 gname「seachbox-only1」,依此類推。請注意,在雙欄版面配置中,元件的自動產生 gname 會是 two-column。以下範例使用 gname storesearchsearchbox 元件連結至 searchresults 元件:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

擷取物件時,如果有多個元件具有相同的 gname,程式化搜尋引擎會使用網頁上的最後一個元件。

不限
autoSearchOnLoad 布林值 指定是否要依據載入網頁網址中嵌入的查詢執行搜尋。請注意,網址中必須有查詢字串,才能執行自動搜尋。預設:true 不限
enableHistory 布林值 如果為 true,則啟用瀏覽器「返回」和「前往」按鈕的記錄管理功能。觀看示範影片

搜尋框

searchbox-only

queryParameterName 字串 查詢參數名稱,例如 q (預設) 或 query。這會嵌入網址中 (例如 http://www.example.com?q=lady+gaga)。請注意,單獨指定查詢參數名稱不會在載入時觸發自動搜尋。網址中必須有查詢字串,才能執行自動搜尋。 不限
resultsUrl 網址 結果網頁的網址。(預設為 Google 代管的頁面)。 searchbox-only
newWindow 布林值 指定結果頁面是否在新視窗中開啟。 預設:false searchbox-only
ivt 布林值

這個參數可讓您提供布林值,通知 Google 只要是使用無效流量專用 Cookie 和本機儲存空間的廣告,都能向已取得和未取得同意聲明的流量放送。

true如果沒有這個參數,或是您將其設為「true」,我們只會針對已取得同意聲明的流量,設定無效流量專用 Cookie 並使用本機儲存空間。

false如果將這個參數設為「false」,系統會針對已取得和未取得同意聲明的流量,設定無效流量專用 Cookie 並使用本機儲存空間。

預設:false

範例用法:<div class="gcse-search" data-ivt="true"></div>

searchresults

searchresults-only

mobileLayout 字串

指定是否應在行動裝置上使用行動版面配置樣式。

enabled 僅在行動裝置上使用行動版面配置。

disabled 不會為任何裝置使用行動版面配置。

forced 所有裝置都使用行動版面配置。

預設:enabled

範例用法:<div class="gcse-search" data-mobileLayout="disabled"></div>

不限
自動完成
enableAutoComplete 布林值 只有在程式化搜尋引擎控制台中啟用自動完成功能時,才能使用這項功能。 true 啟用自動完成功能。 不限
autoCompleteMaxCompletions 整數 顯示的自動完成建議數量上限。

搜尋框

searchbox-only

autoCompleteMaxPromotions 整數 自動完成功能中顯示的促銷活動數量上限。

搜尋框

searchbox-only

autoCompleteValidLanguages 字串 以半形逗號分隔的語言清單,系統應為這些語言啟用自動完成功能。 支援的語言。

搜尋框

searchbox-only

微調
defaultToRefinement 字串 只有在程式化搜尋引擎控制台中建立精選內容後,才會顯示這類內容。指定要顯示的預設精選標籤。注意:Google 代管版面配置不支援這項屬性。 不限
refinementStyle 字串 可接受的值為 tab (預設) 和 link。 只有在停用圖片搜尋功能,或啟用圖片搜尋功能但停用網頁搜尋功能時,系統才會支援 link

searchresults

searchresults-only

圖片搜尋
enableImageSearch 布林值 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

如為 true,則啟用圖片搜尋。圖片搜尋結果會顯示在另一個分頁中。

searchresults

searchresults-only

defaultToImageSearch 布林值 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

如果 true,搜尋結果網頁預設會顯示圖片搜尋結果。網路結果會顯示在另一個分頁中。

不限
imageSearchLayout 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

指定圖片搜尋結果網頁的版面配置。可接受的值為 classiccolumnpopup

searchresults

searchresults-only

imageSearchResultSetSize 整數、字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

指定圖片搜尋的搜尋結果集大小上限。 例如:largesmallfiltered_cse10

不限
image_as_filetype 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

限制只顯示特定副檔名的檔案。

支援的副檔名為 jpggifpngbmpsvgwebpicoraw

不限

image_as_oq 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

使用邏輯 OR 篩選搜尋結果。

如要搜尋包含「term1」或「term2」的結果,請使用以下範例:<div class="gcse-search" data-image_as_oq="term1 term2"></div>

不限

image_as_rights 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

依授權篩選。

支援的值為 cc_publicdomaincc_attributecc_sharealikecc_noncommercialcc_nonderived,以及這些值的組合。

請參閱常見組合

不限

image_as_sitesearch 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

將結果限制為特定網站的網頁。

範例用法:<div class="gcse-search" data-image_as_sitesearch="example.com"></div>

不限

image_colortype 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

將搜尋範圍限制為黑白 (單色)、灰階或彩色圖片。支援的值為 monograycolor

不限

image_cr 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

限制顯示特定國家/地區的文件搜尋結果。

支援的值

不限

image_dominantcolor 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

限制搜尋特定主色的圖片。 支援的值為 redorangeyellowgreentealbluepurplepinkwhitegrayblackbrown

不限

image_filter 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

自動篩選搜尋結果。

支援的值:0/1

範例用法:<div class="gcse-search" data-image_filter="0"></div>

不限

image_gl 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。提升來源國家/地區與參數值相符的搜尋結果。

支援的值

不限

image_size 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

傳回指定大小的圖片,大小可以是:iconsmallmediumlargexlargexxlargehuge.

不限

image_sort_by 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

使用日期或其他結構化內容排序結果。

如要依相關性排序,請使用空白字串 (image_sort_by="")。

範例用法:<div class="gcse-search" data-image_sort_by="date"></div>

不限

image_type 字串 只有在程式化搜尋引擎控制台中啟用 圖片搜尋功能時,才會顯示這項設定。

將搜尋範圍限制在特定類型的圖片。 支援的值包括 clipart (插圖)、face (人臉)、lineart (線條藝術畫)、stock (圖庫相片)、photo (相片) 和 animated (動畫 GIF)。

不限

網頁搜尋
disableWebSearch 布林值 如果 true,則停用網頁搜尋。通常只在程式化搜尋引擎控制台中啟用 圖片搜尋時使用。

searchresults

searchresults-only

webSearchQueryAddition 字串 使用邏輯 OR 為搜尋查詢加入額外字詞。

範例用法:<div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

不限
webSearchResultSetSize 整數、字串 結果集的上限大小。適用於圖片搜尋和網頁搜尋。預設值取決於版面配置,以及程式化搜尋引擎是否設定為搜尋整個網路,或只搜尋特定網站。可接受的值包括:
  • 介於 1 到 20 之間的整數
  • small:要求小型結果集,通常每頁 4 個結果。
  • large:要求大型結果集,通常每頁 8 個結果。
  • filtered_cse:每頁最多可要求 10 個結果,最多 10 頁或 100 個結果。
不限
webSearchSafesearch 字串 指定是否要為網頁搜尋結果啟用SafeSearch功能。可接受的值為 offactive 不限
as_filetype 字串 將結果限制為特定副檔名的檔案。如要查看 Google 可建立索引的檔案類型清單,請前往 Search Console 說明中心

不限

as_oq 字串 使用邏輯 OR 篩選搜尋結果。

如要搜尋包含「term1」或「term2」的結果,請使用以下範例:<div class="gcse-search" data-as_oq="term1 term2"></div>

不限
as_rights 字串 依授權篩選。

支援的值為 cc_publicdomaincc_attributecc_sharealikecc_noncommercialcc_nonderived,以及這些值的組合。

如需常見組合,請參閱 https://wiki.creativecommons.org/wiki/CC_Search_integration

不限

as_sitesearch 字串 只顯示特定網站的網頁。

範例用法:<div class="gcse-search" data-as_sitesearch="example.com"></div>

不限
cr 字串 限制顯示來自特定國家/地區的文件搜尋結果。

支援的值

範例用法:<div class="gcse-search" data-cr="countryFR"></div>

不限
filter 字串 自動篩選搜尋結果。

支援的值:0/1

範例用法:<div class="gcse-search" data-filter="0"></div>

不限
gl 字串 提升來源國家/地區與參數值相符的搜尋結果。

這項功能僅適用於搭配語言值設定使用。

支援的值

範例用法:<div class="gcse-search" data-gl="fr"></div>

不限
lr 字串 限制顯示特定語言的文件搜尋結果。

支援的值

範例用法:<div class="gcse-search" data-lr="lang_fr"></div>

不限
sort_by 字串 使用日期或其他結構化內容排序結果。屬性值必須是可程式化搜尋引擎「結果排序」設定中提供的選項。

如要依關聯性排序,請使用空白字串 (sort_by="")。

範例用法:<div class="gcse-search" data-sort_by="date"></div>

不限
搜尋結果
enableOrderBy 布林值 可依關聯性、日期或標籤排序結果。 不限
linkTarget 字串 設定連結目標。預設:_blank

searchresults

searchresults-only

noResultsString 字串 指定沒有與查詢相符的結果時顯示的預設文字。 預設結果字串可用於以所有支援的語言顯示本地化字串,但自訂結果字串則無法。

searchresults

searchresults-only

resultSetSize 整數、字串 結果集的上限大小。例如:largesmallfiltered_cse10。預設值取決於版面配置,以及引擎是否設定為搜尋整個網路,或只搜尋特定網站。 不限
safeSearch 字串 指定是否同時為網頁和圖片搜尋啟用 安全搜尋。可接受的值為 offactive 不限

回呼

回呼序列圖
Search Element JavaScript 的回呼順序圖

回呼支援搜尋元素初始化和搜尋程序的詳細控制項。 這些事件是透過全域 __gcse 物件向 Search Element JavaScript 註冊。註冊回呼:說明如何註冊所有支援的回呼。

註冊回呼

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };
  

初始化回呼

初始化回呼會在 Search Element JavaScript 於 DOM 中算繪搜尋元素前叫用。如果在 __gcse 中將 parsetags 設為 explicit,搜尋元素 JavaScript 會將搜尋元素的轉譯作業留給初始化回呼 (如「註冊回呼」所示)。這可能用於選取要算繪的元素,或延後算繪元素,直到需要時才算繪。此外,它也可以覆寫元素的屬性;舉例來說,它可以將透過控制台或 HTML 屬性設定的搜尋方塊,預設為網路搜尋,並轉換成圖片搜尋方塊,或是指定透過程式化搜尋引擎表單提交的查詢,只在搜尋結果元素中執行。 觀看示範。

初始化回呼的角色由 __gcseparsetags 屬性值控管。

  • 如果值為 onload,搜尋元素 JavaScript 會自動在網頁上算繪所有搜尋元素。初始化回呼仍會叫用,但不會負責算繪搜尋元素。
  • 如果值為 explicit,Search Element JavaScript 就不會轉譯 Search Element。回呼可使用 render() 函式選擇性地算繪這些元素,或使用 go() 函式算繪所有搜尋元素

以下程式碼示範如何在 div 中,使用 explicit parsetag 和初始化回呼,一併算繪搜尋方塊和搜尋結果:

初始化回呼範例

我們需要加入具有 ID 值的 <div>,以便放置搜尋元素程式碼:

    <div id="test"></div>
<div> 後方新增這段 JavaScript。請注意,這會參照 test,也就是我們用來識別 <div>id
const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};

加入這段 HTML,即可開始載入搜尋元素。將 src 子句中的 cx 值替換為您自己的 cx

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

搜尋回呼

Search Element JavaScript 支援六個回呼,可在搜尋控制流程中運作。 搜尋回呼會成對出現,包括網頁搜尋回呼和相符的圖片搜尋回呼:

  • 開始搜尋
    • 圖片搜尋
    • 網頁搜尋
  • 結果已出爐
    • 圖片搜尋
    • 網頁搜尋
  • 顯示結果
    • 圖片搜尋
    • 網頁搜尋

初始化回呼類似,搜尋回呼也是使用 __gcse 物件中的項目設定。這是因為搜尋元素 JavaScript 會啟動。啟動後對 __gcse 的修改會遭到忽略。

每個回呼都會將 Search Element 的 gName 做為引數傳遞。如果網頁包含多個搜尋,gname 就非常實用。使用 data-gname 屬性為搜尋元素提供 gname 值:

<div class="gcse-searchbox" data-gname="storesearch"></div>

如果 HTML 未識別 gname,Search Element JavaScript 會產生值,且該值在 HTML 修改前會保持一致。

圖片/網頁搜尋啟動回呼

搜尋開始回呼會在 Search Element JavaScript 向伺服器要求搜尋結果前立即叫用。舉例來說,您可以使用當地時間來控管查詢的變更。

searchStartingCallback(gname, query)
gname
搜尋元素的識別字串
query
使用者輸入的值 (可能由搜尋元素 JavaScript 修改)。

回呼會傳回應做為這項搜尋查詢的值。如果傳回空字串,系統會忽略傳回值,呼叫端則會使用未修改的查詢。

或者,您也可以將回呼函式放在 __gcse 物件中,或使用 JavaScript 將回呼動態新增至物件:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
搜尋開始回呼範例

「Example Search Starting Callback」(範例搜尋開始回呼) 中的範例會根據一天中的時間,在查詢中加入 morningafternoon

搜尋開始回呼範例
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

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 中定位的 HTML div,搜尋元素通常會將促銷活動和搜尋結果放在這裡。通常,搜尋元素 JavaScript 會處理這個 div 的填入作業,但這個回呼可能會選擇停止自動顯示結果,並使用這個 div 自行顯示結果。

如果這個回呼傳回 true 值,Search Element JavaScript 會跳過,直接執行頁尾工作。

結果出爐回呼範例

「範例結果就緒回呼」中的 resultsReady 回呼範例會以非常簡單的替代項目,覆寫促銷活動和結果的預設呈現方式。

結果就緒回呼範例
    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

window.__gcse: 中安裝這個回呼:

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

與搜尋啟動回呼一樣,上述只是將回呼放入 __gcse 物件的其中一種方式。

圖片/網頁搜尋結果 - 顯示的回呼

系統會在搜尋元素 JavaScript 算繪網頁頁尾前,立即叫用這些回呼。用途範例包括:回呼會新增搜尋元素未顯示的結果內容,例如「儲存這個項目」核取方塊或未自動算繪的資訊;回呼會新增「瞭解詳情」按鈕。

如果結果顯示回呼需要結果就緒回呼promosresults 參數中的資訊,可以像這樣在兩者之間傳遞:

callback(gname, query, promoElts, resultElts);
gname
搜尋元素的識別字串
query
搜尋字串。
promoElts
:包含促銷活動的 DOM 元素陣列。
resultElts
:包含結果的 DOM 元素陣列。

不會傳回任何值。

範例結果算繪回呼

範例結果算繪回呼中的 resultsRendered 回呼,會為每項促銷活動和結果新增虛擬的「保留」核取方塊。

結果算繪回呼範例
myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

window.__gcse: 中安裝這個回呼:

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

如果結果算繪回呼需要傳遞至結果就緒回呼的資訊,可以在回呼之間傳遞該資料。以下範例說明如何將評分值從richSnippet結果就緒回呼傳遞至結果已算繪回呼,這只是其中一種做法。

與「結果已算繪」回呼合作的「結果已準備就緒」回呼範例
const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};
設定 __gcse 時,請使用類似下列內容的程式碼安裝這個回呼:
const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
範例:系統會在新分頁/視窗中開啟特定檔案類型

以下回呼範例可修改搜尋結果連結,在算繪後開啟新分頁/頁面中的特定檔案,而非目前視窗 (例如:PDF、Excel 或 Word)。如果使用者不想在同一個視窗中開啟檔案,並離開結果頁面,這項功能可提升瀏覽體驗。

這個回呼範例會找出搜尋結果中的 PDF 連結,並在 PDF 連結上設定 target="_blank" 屬性,以便在新分頁中開啟。如果網頁更新,系統會使用 MutationObserver 動態處理新結果。注意:您可以根據需求,將 handleSearchResults 中的 .pdf 替換成任何其他檔案類型。

這個回呼範例不適用於 Google 代管和重疊版面配置。

在新分頁/視窗中開啟特定檔案類型
function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

const myWebResultsRenderedCallback = () => {
  // Call handleSearchResults when results are rendered
  handleSearchResults();
  // Set up a MutationObserver to handle subsequent updates to the results
  const observer = new MutationObserver(handleSearchResults);
  const searchResultsContainer = document.querySelector('.gsc-results');
  if (searchResultsContainer) {
    observer.observe(searchResultsContainer, {
      childList: true,
      subtree: true
    });
  } else {
    console.log('No Results.');
  }
};

window.__gcse: 中安裝這個回呼:

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: myWebResultsRenderedCallback,
  },
};
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

更多回呼範例

如需其他回呼範例,請參閱「更多回呼範例」文件。

宣傳活動和結果屬性

使用 JSDoc 標記,這些是 promotionresult 物件的屬性。 我們在此列出所有可能存在的屬性。許多屬性是否會顯示,取決於宣傳活動或搜尋結果的詳細資料。

宣傳活動屬性
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
結果物件屬性
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

results 中的 richSnippet 具有物件陣列的寬鬆型別。這個陣列中的項目值是由每個搜尋結果網頁上找到的結構化資料所控管。舉例來說,評論網站可能會加入結構化資料,將這個陣列項目新增至 richSnippet

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

程式化搜尋元素控制項 API (V2)

google.search.cse.element 物件會發布下列靜態函式:

功能 說明
.render(componentConfig, opt_componentConfig) 顯示搜尋元素。

參數

名稱 說明
componentConfig 程式化搜尋元素元件的設定。指定下列項目:
  • div (字串|元素):<div>iddiv 元素,程式化搜尋元素會在此算繪。
  • tag (字串):要算繪的元件類型。(提供 opt_componentConfig 時,tag 屬性的值必須為 searchbox。) 允許的值如下:
    • search:搜尋框和搜尋結果會一併顯示
    • searchbox:可程式化搜尋元素的搜尋框元件。
    • searchbox-only:獨立搜尋方塊,會與兩欄式版面配置中 opt_componentConfig 指定的搜尋結果區塊配對。
    • searchresults-only:獨立的搜尋結果區塊。搜尋作業是由網址中嵌入的查詢參數或程式輔助執行所觸發。
  • gname (字串):(選用) 這個元件的專屬名稱。如未提供,程式化搜尋引擎會自動產生 gname
  • attributes (物件):以鍵/值組合形式呈現的選用屬性。支援的屬性
opt_componentConfig (選用步驟) 第二個元件設定引數。用於 TWO_COLUMN 模式,提供 searchresults 元件。指定下列項目:
  • div (字串):要算繪元素的 <div>div 元素的 id
  • tag (字串):要算繪的元件類型。提供 opt_componentConfig 時,tag 屬性的值必須為 searchresults。此外,componentConfig tag 屬性值必須為 searchbox
  • gname (字串):(選用) 這個元件的專屬名稱。如未提供,程式化搜尋引擎會自動為這個元件產生 gname。如果提供,則必須與 componentConfig 中的 gname 相符。
  • attributes (物件):選用屬性,格式為鍵/值組合。 支援的屬性。
.go(opt_container) 在指定容器中轉譯所有搜尋元素標記/類別。

參數

名稱 說明
opt_container 包含要轉譯的 Search Element 元件的容器。指定容器的 ID (字串) 或元素本身。如果省略,系統會顯示網頁 body 標記內的所有可程式化搜尋元素元件。
.getElement(gname) 透過 gname 取得元素物件。如果找不到,則傳回 null。

傳回的 element 物件具有下列屬性:

  • gname:元素物件的名稱。如未提供,程式化搜尋引擎會自動為物件產生 gname更多資訊
  • type:元素類型。
  • uiOptions:用於算繪元素的最終屬性。
  • execute - function(string):執行程式輔助查詢。
  • prefillQuery - function(string):在搜尋框中預先填入查詢字串,但不執行查詢。
  • getInputQuery - function():取得輸入方塊中顯示的目前值。
  • clearAllResults - function():清除控制項,隱藏搜尋方塊以外的所有項目 (如有)。

下列程式碼會在搜尋元素「element1」中執行「news」查詢:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() 傳回所有成功建立的元素物件對應地圖,並以 gname 做為鍵。